Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { noteForwardProgress } from '../core/forward-progress.ts';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import type { BrainEngine } from '../core/engine.ts';
import { OperationError, opError, type OperationMeta } from '../core/ops/contract.ts';
import { transientDatabaseFailure } from '../core/persistence/transient-retry.ts';
import { OPERATION_MANIFEST } from '../core/operation-manifest.generated.ts';
import { isCallable, publishGatesFromDisabled } from '../core/ops/callable.ts';
import { VERSION } from '../version.ts';
import { buildToolDefs } from './tool-defs.ts';
import type { ToolResult } from './dispatch.ts';
import { findInvalidParam, normalizeOptionalParams, schemaInvalidParams, parseStrictParamsMode } from './validate-params.ts';
import { clampSurface, createStdioSurfaceState, resolveAdvertisedSurface, stdioToolListing, sessionWidenAllowed, surfaceEnvInvalidNotice, type McpAccess, type McpSurface, type SurfaceSource } from './surface.ts';
import { noticeBlock, renderNotice, type Notice } from '../core/agent-output.ts';
import { disabledOpsForPublishGates } from './publish-gates.ts';
import { parseResultRowsMode, resolveResultRowsMode } from './result-rows.ts';
import { loadConfig } from '../core/config.ts';
import { requestConfigRows, withRequestConfigSnapshot } from '../core/config-snapshot.ts';
import { gcSessionContextState } from '../core/context/session-state.ts';
import { installInstructionsResolver, MCP_SERVER_DESCRIPTION, readInstructionContent, resolveMcpInstructions } from './instructions.ts';
import { instructionReadiness, stdioCapabilityReadiness } from './initialize-context.ts';
import { STATUS_TOOL_DEF, STATUS_TOOL_NAME, attemptStatusRecovery, statusHeadline, statusInstructionLine, statusModeErrorResult, statusModeOf, statusPayload, statusToolResult } from './status-mode.ts';
import { installCapabilitiesResource, mcpAdministrationGuidance } from './capabilities.ts';
import { createSkillResources, type SkillResources } from './skill-resources.ts';
import { readLocalWriter, verifyLocalWriter } from '../core/persistence/identity.ts';
import { ambientOptsFrom, type WritebackConfig } from '../core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';
import { isEngineDegraded, onEngineRecovered } from '../core/degraded-marker.ts';
import { assertStdioSourceBindable } from './source-preflight.ts';
import { readOnlyServeSkipsResidentDuties } from '../core/direct-pool-profile.ts';
import { hookSessionCwd } from '../core/session-cwd.ts';
import { stdioMemberIdentity } from '../core/access/caller.ts';
// The sized stdio transport moved to the engine-free lifecycle module the thin-client bridge shares.
export { MCP_STDIO_MAX_MESSAGE_BYTES, mcpStdioTransport } from './stdio-lifecycle.ts';
import { MCP_STDIO_MAX_MESSAGE_BYTES, mcpStdioTransport } from './stdio-lifecycle.ts';
// initialize and tools/list read OPERATION_MANIFEST; the handler graph behind
// dispatch.ts (src/core/operations.ts, ~760 modules) loads with the deferred
// boot in startMcpServer, or on the first tools/call.
type DispatchModule = typeof import('./dispatch.ts');
const loadDispatch = (): Promise<DispatchModule> => import('./dispatch.ts');
const loadMetaHook = () => import('../core/facts/meta-hook.ts');
/**
* Engine-dependent boot waits for the handshake so initialize and the first
* tools/list don't queue behind its module loading. It starts when the first
* tools/list is answered, or BOOT_LIST_GRACE_MS after initialize is answered
* with no tools/list in flight (a client that calls without listing), or
* BOOT_WITHOUT_INITIALIZE_MS after connect for a client that never
* initializes (a supervisor probe, a test driver).
*/
export const BOOT_LIST_GRACE_MS = 25;
export const BOOT_WITHOUT_INITIALIZE_MS = 1000;
/** Skill resource reads dispatch ops, so they wait for the deferred boot; listing does not. */
function bootGatedReads(skills: SkillResources, awaitBoot: () => Promise<void>): SkillResources {
return { list: () => skills.list(), read: async uri => { await awaitBoot(); return skills.read(uri); } };
}
/**
* The stdio deferred-boot gate. `run` waits for a trigger (see
* BOOT_LIST_GRACE_MS, or `awaitBoot` from a call), then boots; calls await
* `awaitBoot`, so none dispatches against a half-booted server, and a boot
* failure rejects them with the boot error while `run` rethrows it to
* startMcpServer (the fatal serve exit it always was). The handler graph
* starts loading at the trigger, alongside the boot.
*/
function deferredBoot(opts: { degraded: boolean }) {
let listsInFlight = 0;
let request!: () => void;
const requested = new Promise<void>(resolve => { request = resolve; });
const booted = Promise.withResolvers<void>();
// Degraded serve defers engine-dependent boot to its recovery hook, as before: calls never wait for it.
if (opts.degraded) booted.resolve();
booted.promise.catch(() => { /* rethrown by awaitBoot and run */ });
void requested.then(() => Promise.all([loadDispatch(), loadMetaHook()])).catch(() => { /* the first call's import reports it */ });
const awaitBoot = (): Promise<void> => { request(); return booted.promise; };
return {
awaitBoot,
/** Boot, then the dispatch and hot-memory modules a tools/call needs. */
awaitCall: async () => { await awaitBoot(); return Promise.all([loadDispatch(), loadMetaHook()]); },
initializeAnswered: (): void => { setTimeout(() => { if (listsInFlight === 0) request(); }, BOOT_LIST_GRACE_MS); },
async list<T>(work: () => Promise<T>): Promise<T> {
listsInFlight++;
try { return await work(); } finally { listsInFlight--; setImmediate(request); }
},
async run(bootPhase: (phase: string) => void, boot: () => Promise<void>): Promise<void> {
bootPhase('initialize_wait');
const fallback = setTimeout(request, BOOT_WITHOUT_INITIALIZE_MS);
fallback.unref?.();
await requested;
clearTimeout(fallback);
try { await boot(); booted.resolve(); } catch (e) { booted.reject(e); throw e; }
},
};
}
export async function resolveMcpStdioSourceScope(
engine: BrainEngine,
cwd: string = hookSessionCwd(),
opts: { warmConfig?: boolean } = {},
): Promise<{
sourceId: string;
localFederatedSourceIds?: string[];
explicitReadBinding?: import('../core/ops/contract.ts').ExplicitReadBinding;
tier: import('../core/source-resolver.ts').SourceTier;
}> {
// Degraded mode (db-availability 4c): short-circuit WITHOUT touching the
// engine. This site runs before EVERY dispatch and its catch below
// swallows errors into sourceId 'default' — letting it hit a degraded
// engine would both consume the one reconnect attempt (before the handler
// whose classified envelope the agent needs) and eat the error silently.
// A well-formed GBRAIN_SOURCE binding is still honored (engine-free, same
// rule as the catch below); otherwise seed_default keeps --source-guard
// fail-closed on writes. No call ever EXECUTES under this fallback scope
// against a live engine: the degraded proxy throws while dead, and the
// one call whose access triggers a successful reconnect gets
// DegradedRecoveredRetryError instead of a result (see degraded-engine.ts).
if (isEngineDegraded(engine)) {
const { isValidSourceId } = await import('../core/source-id.ts');
const env = process.env.GBRAIN_SOURCE;
return env && isValidSourceId(env)
? { sourceId: env, tier: 'env' }
: { sourceId: 'default', tier: 'seed_default' };
}
try {
const { resolveSourceWithTier, localFederatedSourceIds, explicitReadBinding } = await import('../core/source-resolver.ts');
// GBRA-156: a tool call resolves inside the request's config snapshot (which dispatch reuses for a read op), so
// `warmConfig` reads the config table beside the source rows: one round trip before the op.
const [resolved] = await Promise.all([resolveSourceWithTier(engine, null, cwd), opts.warmConfig ? requestConfigRows(engine) : undefined]);
const federated = await localFederatedSourceIds(engine, resolved.source_id, resolved.tier);
// #5081: the admission set is optional; a failed lookup must not discard
// the resolved binding (the catch below would fall back to 'default').
const binding = await explicitReadBinding(engine, resolved.source_id, resolved.tier).catch(() => undefined);
return {
sourceId: resolved.source_id,
...(federated ? { localFederatedSourceIds: federated } : {}),
...(binding ? { explicitReadBinding: binding } : {}),
tier: resolved.tier,
};
} catch {
// Resolution failure. Report the tier truthfully so --source-guard makes
// the safe call. A MALFORMED GBRAIN_SOURCE can never be a real binding —
// launder it through as tier 'env' and the guard would pass the write,
// which then dies downstream on the sources FK with a raw error instead
// of the guard's actionable envelope. So a format-invalid env value falls
// back to the ambiguous seed tier (guard blocks with "set GBRAIN_SOURCE /
// --source"). A well-formed value keeps tier 'env': a nonexistent-source
// or a transient engine blit is a separate downstream concern, and
// blocking a valid binding on a blip is worse.
const { isValidSourceId } = await import('../core/source-id.ts');
const env = process.env.GBRAIN_SOURCE;
return env && isValidSourceId(env)
? { sourceId: env, tier: 'env' }
: { sourceId: 'default', tier: 'seed_default' };
}
}
/**
* #4583 rework + review fixes: once-per-process unscoped-default-write
* advisory for the stdio lane. The latch arms on the first SUCCESSFUL
* assessment whatever its verdict (warned, or no-guard) — pre-fix it armed
* only when a warning printed, so on a no-guard brain the assessment's
* unindexed full-`pages` aggregate ran on EVERY mutating stdio call. The
* inputs are process-stable (env escape hatch, the brain's page
* distribution), so one assessment decides for the process. A FAILED
* assessment does NOT latch: the write proceeds (fail-open) but the next
* mutating seed_default call retries, so a transient DB error cannot disable
* the advisory for the life of the serve process. Concurrent calls share one
* in-flight assessment. Cheap early-returns (non-mutating call, non-seed
* tier) do NOT latch either — a later mutating seed_default call still gets
* its assessment. Exported for tests; `write` is injectable (production
* writes stderr).
*/
export function createDefaultWriteAdvisory(
engine: BrainEngine,
opts: { enabled: boolean; write?: (line: string) => void },
): (tier: import('../core/source-resolver.ts').SourceTier, mutating: boolean) => Promise<void> {
let latched = false;
let inflight: Promise<void> | null = null;
const write = opts.write ?? ((line: string) => process.stderr.write(line + '\n'));
return async (tier, mutating) => {
if (latched || !opts.enabled) return;
if (!mutating || tier !== 'seed_default') return;
inflight ??= (async () => {
try {
const { assessUnscopedDefaultWrite } = await import('../core/source-resolver.ts');
const { warning, assessed } = await assessUnscopedDefaultWrite(engine, tier, mutating);
// Latch before writing so a throwing stderr writer still counts as
// assessed; never latch on a failed (fail-open) assessment.
if (assessed) latched = true;
if (warning) write(warning);
} catch { /* advisory; never block a write */ } finally {
inflight = null;
}
})();
await inflight;
};
}
/**
* Per-request stdio tools/list set: the surfaced ops minus publish-gated ops
* whose gate resolves off. stdio dispatches remote:true (agent-facing), and
* the gate enforcement (assertPublishEnabled, the advisor inline gate) exempts
* only ctx.remote === false — so listing gate-off ops here was the exact
* listed-but-denied class the honest-catalog wave exists to kill, surviving on
* the default transport. localOnly ops STAY listed: locality is the transport
* axis (stdio IS the local pipe, D7); publish gates are the owner-consent
* axis. Deliberately uncached (publish-gates.ts doctrine: the per-request read
* is what makes a config flip take effect without a restart; tools/list is
* rare). Fail-closed: a resolver failure hides every gated op rather than
* re-creating the listed-but-denied complaint.
*/
export async function stdioVisibleTools<T extends OperationMeta>(
engine: BrainEngine,
surfacedOps: T[],
): Promise<T[]> {
let scopes: readonly string[] = [];
if (surfacedOps.some(op => op.requiredScopes?.length) && !isEngineDegraded(engine)) {
try {
const verified = await verifyLocalWriter(engine, await readLocalWriter(engine, 'stdio'));
if (verified.remote) scopes = verified.grant.scopes;
} catch {}
}
// Degraded serve (db-availability 4c): fail-closed WITHOUT touching the
// engine. The gate read can hit engine.getConfig, which on the degraded
// wrapper would burn the one lazy reconnect attempt — and stall the
// client's INITIAL tools/list handshake behind the reconnect's wait cap.
// Recovery re-sends tools/list_changed, so the full catalog returns.
let gateDisabled: ReadonlySet<string> = new Set();
if (surfacedOps.some(op => op.publishGateKey)) {
if (isEngineDegraded(engine)) {
gateDisabled = new Set(surfacedOps.filter(o => o.publishGateKey).map(o => o.name));
} else {
try {
gateDisabled = await disabledOpsForPublishGates(engine, loadConfig(), { transport: 'stdio' });
} catch {
gateDisabled = new Set(surfacedOps.filter(o => o.publishGateKey).map(o => o.name));
}
}
}
// Agent contract v1 (A2): the one callability predicate. The surface was
// applied by the caller (surfacedOps), so 'full' here adds no filter.
const publishGates = publishGatesFromDisabled(surfacedOps, gateDisabled);
return surfacedOps.filter(op => isCallable(op, { transport: 'stdio', surface: 'full', scopes, publishGates }));
}
// ─── #4409: in-flight stdio RPC tracking ────────────────────────────────
// A one-shot MCP client can write a batch of frames and close stdin
// immediately; the SDK parses every frame during the 'data' events (handler
// start is queued as a microtask), so at stdin-'end' time requests can be
// in flight with no response written yet. serve.ts's EOF path consults this
// counter and drains before its graceful exit instead of dropping the
// response on the floor. Module-level because one process runs one stdio
// server (matches the serve-sync-runner singleton posture).
let _stdioRpcsInFlight = 0;
/** Live count of stdio JSON-RPC requests whose handlers have not settled. */
export function stdioRpcsInFlightCount(): number {
return _stdioRpcsInFlight;
}
/** Wrap one request handler invocation in the in-flight counter. @internal */
export async function trackStdioRpc<T>(work: () => Promise<T>): Promise<T> {
_stdioRpcsInFlight++;
try {
return await work();
} finally {
_stdioRpcsInFlight--;
// A completed request is forward progress: serve's boot deadline must not
// stop a server that is answering its client while a boot phase waits on
// the engine behind those requests.
noteForwardProgress();
}
}
/**
* The stdio session surface: one mutable allow-set per process that
* tools/list, dispatch, the capabilities resource, whoami and gbrain_status
* read. `request_tools {surface}` widens it for this session only (never past
* --access read-only); each widen writes a `surface_widened` stderr line and
* sends tools/list_changed. `finishResult` adds the once-per-process
* `surface_env_invalid` notice to the first successful result.
*/
function stdioSurfaceSession(
opts: { surface?: McpSurface; surfaceSource?: SurfaceSource; invalidSurfaceEnv?: string; access?: McpAccess },
server: () => Server | null,
) {
const session = createStdioSurfaceState(OPERATION_MANIFEST, {
surface: clampSurface(opts.surface ?? 'full'), source: opts.surfaceSource ?? (opts.surface ? 'flag' : 'default'), readOnly: opts.access === 'read-only',
onWiden: ({ from, to, added }) => {
process.stderr.write(`[gbrain-serve] surface_widened from=${from} to=${to} op=request_tools added=${added.length}\n`);
Promise.resolve(server()?.sendToolListChanged()).catch(() => { /* best-effort */ });
},
});
let pending: Notice | null = opts.invalidSurfaceEnv ? surfaceEnvInvalidNotice(opts.invalidSurfaceEnv, session.surface, session.source) : null;
const finishResult = (result: ToolResult, dispatchRenderContext: DispatchModule['dispatchRenderContext']): ToolResult => {
if (!pending || result.isError) return result;
const rendered = renderNotice(pending, dispatchRenderContext({ transport: 'stdio', remote: true, surface: session.surface, allowedOps: session.allowedOps }));
result.content.push({ type: 'text', text: noticeBlock(rendered) });
result._meta = { ...(result._meta ?? {}), gbrain_notices: [...((result._meta?.gbrain_notices as unknown[]) ?? []), rendered] };
pending = null;
return result;
};
const statusResult = (state: NonNullable<ReturnType<typeof statusModeOf>>) => {
const status = statusToolResult(state);
status.content[0].text = JSON.stringify({ ...JSON.parse(status.content[0].text), surface: session.surface, surface_source: session.source }, null, 2);
return status;
};
return { session, finishResult, statusResult };
}
/**
* #7599: a read-only stdio serve on Postgres runs no resident write duty: no persistence consumer, no delegated sync, nudge or
* sweep kinds, no session-cursor GC and no startup sweep (serve.ts also skips the idle sweep and the resident tickers, the
* on-commit watcher among them); only the onboarding cache refresher runs. The long-lived serve, worker or autopilot owns
* them; doctor's commit_notifier and two_consumers_on_host say when none runs. A PGLite serve keeps them (readOnlyServeSkipsResidentDuties).
*/
const READ_ONLY_SERVE_NOTE = '[gbrain-serve] read-only: no persistence consumer, on-commit sync or sweep runs here; a read-write serve, jobs work or autopilot owns them.\n';
/**
* The ambient writeback section's options for a stdio serve: what the session can call, and whether the stdio member (`--stdio-member`, else mcp.stdio_member) binds
* it to a member, whose writes stay private unless shared (GST-2243), so its rule never says "pass visibility: world". The lookup runs only when a
* member is named; one that fails with access_identity_unavailable or a transient database failure still reads as bound and serve starts, and any
* other error is thrown.
*/
export async function stdioAmbientOpts(engine: BrainEngine, writeback: WritebackConfig, allowedOps: ReadonlySet<string> | undefined, stdioMember?: string) {
return ambientOptsFrom(writeback, {
remember: allowedOps ? allowedOps.has('remember') : true,
extractFacts: allowedOps ? allowedOps.has('extract_facts') : true,
member: await stdioMemberIdentity(engine, stdioMember).then(identity => identity.some(p => p.startsWith('member:')), (error: unknown) => {
if ((error instanceof OperationError && error.code === 'access_identity_unavailable') || transientDatabaseFailure(error)) return true;
throw error;
}),
});
}
export async function startMcpServer(engine: BrainEngine, opts: { surface?: McpSurface; surfaceSource?: SurfaceSource; invalidSurfaceEnv?: string; sourceGuard?: boolean; onBootPhase?: (phase: string) => void; access?: McpAccess; advertise?: McpSurface; stdioMember?: string } = {}) {
const config = loadConfig();
const bootPhase = (phase: string) => { try { opts.onBootPhase?.(phase); } catch { /* diagnostic only */ } };
// Refuse to serve a well-formed GBRAIN_SOURCE that no active source row
// backs (see source-preflight.ts). Throws before any transport is attached.
bootPhase('source_preflight');
await assertStdioSourceBindable(engine);
// MEMORY_VERBS v1 surface mode: 'full' (default — every op, byte-identical
// to pre-surface behavior), 'starter' (WP4 daily-driver set), or 'verbs'
// (exactly the 7 protocol verbs). Enforced BOTH on the advertised list and
// in dispatch (fail-closed [c2]). WP4: the GBRAIN_MCP_FORCE_SURFACE kill
// switch min()s in (narrow-only, FOV-6a). Note stdio keeps localOnly ops
// on every surface tier that includes them — it IS the local surface (D7,
// the transport-LOCALITY axis). Publish gates are the separate owner-
// CONSENT axis keyed on ctx.remote === false only, and stdio dispatches
// remote:true — so gate-off ops are subtracted per tools/list below.
// (Resolved before Server construction: the initialize instructions need
// the allowed-op set to decide whether extract_facts may be advertised.)
let server: Server | null = null;
const { session, finishResult, statusResult } = stdioSurfaceSession(opts, () => server);
const gate = deferredBoot({ degraded: isEngineDegraded(engine) }); // engine-dependent boot waits for the handshake
// Ambient writeback (opt-in, default off): resolved ONCE at boot — a
// config flip needs a serve restart on this lane, the same posture as
// `mcp.strict_params` below. Uses the fail-closed dual-plane resolver
// rather than a file-only read (deliberate deviation from the file-plane
// boot rule): the visibility POSTURE lives in the DB plane, and a partial
// file-only resolve could embed a `world` posture against an explicitly
// private brain. Read failure here yields the OFF bundle — no section,
// never a wrong posture — and the engine is already connected by the time
// serve reaches this call.
bootPhase('writeback_config');
// F4 status-only mode: never touch the lazy engine at boot (its gated
// reconnect belongs to tool calls).
const statusMode = statusModeOf(engine);
const writeback = statusMode ? null : (await resolveAgentWriteback(engine, config)).bundle;
const writebackOpts = writeback ? await stdioAmbientOpts(engine, writeback, session.allowedOps, opts.stdioMember) : null;
server = new Server(
{ name: 'gbrain', version: VERSION, description: MCP_SERVER_DESCRIPTION },
// listChanged: a client that handshakes during DEGRADED mode receives the
// gate-hidden catalog (stdioVisibleTools fail-closes every publishGateKey
// op on engine failure) and caches it — recovery sends the notification
// so the full catalog comes back without a harness restart.
{
capabilities: { tools: { listChanged: true }, resources: {} },
// #4748: canonical contract (+ opt-in ambient-writeback section) plus the
// optional operator-set deployment identity, appended last.
instructions: resolveMcpInstructions(config, process.env, { writeback: writebackOpts }),
},
);
const listing = stdioToolListing(() => resolveAdvertisedSurface(isEngineDegraded(engine) ? null : engine, config, opts.advertise ?? null), session, server);
// F1: callable-set contract + readiness tail (or status-only line), resolved at client initialize.
installInstructionsResolver(server, async () => {
if (statusMode && isEngineDegraded(engine)) {
return resolveMcpInstructions(config, process.env, { tools: { callable: n => n === STATUS_TOOL_NAME, statusLine: statusInstructionLine(statusMode) } });
}
const visibleOps = await stdioVisibleTools(engine, session.surfacedOps), listedOps = await listing.listed(visibleOps), listed = new Set(listedOps.map(op => op.name));
return resolveMcpInstructions(config, process.env, {
writeback: writebackOpts, ...await readInstructionContent(engine),
tools: { callable: n => listed.has(n), readiness: await instructionReadiness(engine, config, 'stdio'), hiddenCallable: visibleOps.length - listedOps.length },
});
}, gate.initializeAnswered);
// WP3: strict-params schema emission, resolved ONCE at startup from the
installCapabilitiesResource(server, async () => {
if (statusMode && isEngineDegraded(engine)) return { transport: 'stdio', status_only: statusPayload(statusMode) };
const scope = await resolveMcpStdioSourceScope(engine);
const available = (await stdioVisibleTools(engine, session.surfacedOps)).map(op => op.name);
let scopes: readonly string[] = [];
if (!isEngineDegraded(engine)) {
try {
const verified = await verifyLocalWriter(engine, await readLocalWriter(engine, 'stdio'));
if (verified.remote) scopes = verified.grant.scopes;
} catch {}
}
return { transport: 'stdio', scopes, surface: session.surface, surface_source: session.source, access: session.readOnly ? 'read-only' : 'full', source_id: scope.sourceId,
available_operations: available,
administration: mcpAdministrationGuidance(),
shared_skills: { protocol_version: 2, catalog: available.includes('list_skills') && available.includes('get_skill'),
can_join: available.includes('join_brain'), can_edit: available.includes('put_skill') && available.includes('delete_skill'), native_activation: 'unverified' },
...await stdioCapabilityReadiness(engine, config),
note: 'This local MCP pipe has no OAuth profile; agent-facing operation restrictions still apply.' };
}, bootGatedReads(createSkillResources(engine, async () => {
const scope = await resolveMcpStdioSourceScope(engine);
return { remote: true, transport: 'stdio', sourceId: scope.sourceId,
localFederatedSourceIds: scope.localFederatedSourceIds, allowedOps: session.allowedOps, surface: session.surface, config: config ?? undefined, ...(opts.stdioMember !== undefined ? { stdioMember: opts.stdioMember } : {}) };
}), gate.awaitBoot));
// FILE config plane only — stdio has no per-request list cycle, so a
// `mcp.strict_params` flip needs a serve restart here (deliberate; the
// OAuth HTTP path re-reads dual-plane per request).
const strictParams = parseStrictParamsMode(config?.mcp?.strict_params) === 'reject';
// C1: row shape resolved once at boot like strict_params (stdio has no thin client; a degraded engine reads the file plane).
const resultRows = isEngineDegraded(engine)
? parseResultRowsMode(config?.mcp?.result_rows) ?? 'lean'
: await resolveResultRowsMode(engine, config);
session.widenAllowed = await sessionWidenAllowed(isEngineDegraded(engine) ? null : engine, config);
// Generate tool definitions from operations. Extracted to buildToolDefs so
// the subagent tool registry (v0.15+) can call the same mapper against a
// filtered OPERATIONS subset instead of duplicating this shape. Publish-gate
// subtraction happens per request (stdioVisibleTools) — no caching, so a
// `gbrain config set mcp.publish_skills true` takes effect on the next
// tools/list without a serve restart (matches the HTTP transports).
server.setRequestHandler(ListToolsRequestSchema, async () => trackStdioRpc(() => gate.list(async () => ({
tools: statusMode && isEngineDegraded(engine)
? [STATUS_TOOL_DEF]
: buildToolDefs(await listing.listed(await stdioVisibleTools(engine, session.surfacedOps)), { strictParams }),
}))));
// #4583 (fixes #4564's misrouted-write symptom): once-per-process advisory
// for unscoped default writes on a multi-source brain; latch semantics live
// in createDefaultWriteAdvisory above. Skipped under --source-guard (the
// opt-in fail-closed guard owns that lane).
const defaultWriteAdvisory = createDefaultWriteAdvisory(engine, { enabled: !opts.sourceGuard });
// Dispatch tool calls via shared dispatch.ts (parity with HTTP transport).
// MCP stdio callers are remote/untrusted; dispatch defaults remote=true.
// The MCP SDK's response type widened in 1.29 to allow a managed-task wrapper;
// gbrain ops are synchronous, so we return the legacy `{ content, isError? }`
// shape and cast through `any` (the SDK accepts it via the ServerResult union).
server.setRequestHandler(CallToolRequestSchema, async (request: any): Promise<any> => trackStdioRpc(() => withRequestConfigSnapshot(engine, async () => {
const { name, arguments: params } = request.params;
const [{ dispatchToolCall, dispatchRenderContext, requestMetaSessionId, hotMemoryOffIn }, { getBrainHotMemoryMeta }] = await gate.awaitCall();
// F4: status-only mode answers gbrain_status and refuses the rest until
// a tool call's re-probe finds the brain openable (then dispatch normally).
if (statusMode) {
const open = await attemptStatusRecovery(engine, statusMode);
if (name === STATUS_TOOL_NAME) return statusResult(statusMode);
if (!open) return statusModeErrorResult(statusMode, name);
}
// #3242 / #3906: stdio resolves its source through the same ambient chain
// as local CLI dispatch: GBRAIN_SOURCE, then .gbrain-source, then the
// non-explicit fallback tiers. Non-explicit tiers may widen to federated
// local reads; explicit/env/dotfile scopes stay scalar.
const sourceScope = await resolveMcpStdioSourceScope(engine, hookSessionCwd(), { warmConfig: OPERATION_MANIFEST.find(o => o.name === name)?.mutating === false });
// v0.28: stdio MCP has no per-token auth (local pipe). Default the
// takes-holder allow-list to ['world'] so agent-facing callers don't
// see private hunches via takes_list / takes_search / query. Operators
// who want stdio to see everything should call ops directly via
// `gbrain call <op>` (sets remote=false in src/cli.ts).
// CX2-11: MCP carries `_meta.session_id` as a sibling of `arguments` in
// request.params. Thread it (clamped in dispatch) into the typed
// OperationContext.sessionId so the hot-memory metaHook's cache keys per
// session instead of collapsing every caller onto the null-session key.
const sessionId = requestMetaSessionId(request.params);
// #4583 rework: warn (once per process) when a MUTATING call's RESOLVED
// source scope actually lands in 'default' (tier seed_default) on a
// bulk-non-default brain. Keyed on the already-computed resolution tier —
// NOT on raw GBRAIN_SOURCE presence — so dotfile / local_path /
// brain_default pins never false-positive. No `--source` flag exists on
// this transport, so warn instead of refusing the agent's write.
await defaultWriteAdvisory(
sourceScope.tier,
OPERATION_MANIFEST.find(o => o.name === name)?.mutating === true,
);
return finishResult(await dispatchToolCall(engine, name, params, {
remote: true, admissionOrigin: 'interactive',
// #1061: mark the transport so whoami can report {transport: 'stdio'}
// instead of throwing unknown_transport. Trust posture unchanged —
// stdio stays remote/untrusted.
transport: 'stdio', inboundFrameBytes: MCP_STDIO_MAX_MESSAGE_BYTES,
takesHoldersAllowList: ['world'],
...(sessionId ? { sessionId } : {}), ...(hotMemoryOffIn(request.params) ? { hotMemoryOff: true } : {}), onBehalfOf: { requestMeta: request.params?._meta }, room: { requestMeta: request.params?._meta }, guest: { requestMeta: request.params?._meta },
mcpCaller: { client: server?.getClientVersion()?.name, meta: request.params?._meta },
sourceId: sourceScope.sourceId,
...(sourceScope.localFederatedSourceIds
? { localFederatedSourceIds: sourceScope.localFederatedSourceIds }
: {}),
...(sourceScope.explicitReadBinding
? { explicitReadBinding: sourceScope.explicitReadBinding }
: {}),
// --source-guard (plugin lanes): thread the winning resolution tier so
// dispatch can fail-close ambient-tier writes. Off (undefined) unless
// the serve was started with the flag.
...(opts.sourceGuard ? { sourceGuardTier: sourceScope.tier } : {}), ...(opts.stdioMember !== undefined ? { stdioMember: opts.stdioMember } : {}),
// v0.31 (eD3): _meta.brain_hot_memory injection so Claude Desktop /
// Code see the brain's relevant hot memory automatically alongside
// every tool-call response. Best-effort; absorbs errors.
metaHook: getBrainHotMemoryMeta,
// MEMORY_VERBS v1: fail-closed surface enforcement + usage attribution.
...(session.allowedOps ? { allowedOps: session.allowedOps } : {}),
surface: session.surface,
// WP4 (D2): stdio has no per-client rows; its surface is the ceiling
// request_tools bounds its catalog by; its {surface} call widens the session.
surfaceCeiling: session.surface, stdioSurface: session, revealTools: listing.reveal, isListed: listing.isListed,
resultRows,
}), dispatchRenderContext);
})));
const transport = mcpStdioTransport();
bootPhase('mcp_connect');
await server.connect(transport);
// Engine-dependent boot: the resolve-IPC listener, session-cursor GC, and
// the startup maintenance sweep all touch the engine. In DEGRADED mode
// (db-availability 4c) they are DEFERRED until the first successful
// reconnect — running them against a dead engine would burn reconnect
// attempts on background work instead of tool calls.
let ipcBinding: { close: () => void } | null = null;
let startupSweep: { cancel: () => void } | null = null;
const bootEngineDependents = async (): Promise<void> => {
// Retrieval Reflex (#1981, D9=C): the resolve/turn_context/context_pack (+ delegated sync/sweep) IPC listener. Wiring
// shared with `serve --http` via bindResolveIpcForServe (#4474) — best-effort; failure to bind never blocks the MCP server.
const [{ createPersistenceIpcProvider, residentPersistenceConfig }, { bindResolveIpcForServe }] = await Promise.all([import('../core/persistence/provider.ts'), import('./resolve-ipc-binding.ts')]);
bootPhase('source_scope');
const { sourceId: ipcSourceId } = await resolveMcpStdioSourceScope(engine);
bootPhase('persistence_consumer');
const lean = readOnlyServeSkipsResidentDuties(!!session.readOnly, engine.kind);
const persistence = lean ? undefined : await createPersistenceIpcProvider(engine, residentPersistenceConfig(config) ?? { engine: engine.kind });
bootPhase('resolve_ipc_bind');
ipcBinding = await bindResolveIpcForServe(engine, ipcSourceId, persistence, { rememberCallable: () => !session.allowedOps || session.allowedOps.has('remember'), lean });
import('../core/onboard/mcp-onboarding.ts').then(m => m.startOnboardingRefresher(engine, { idle: () => _stdioRpcsInFlight === 0 })).catch(() => { /* coaching is best-effort */ });
if (lean) return void process.stderr.write(READ_ONLY_SERVE_NOTE);
// v0.45.7 ambient recall: age out stale session cursors once per serve boot (7-day TTL, indexed DELETE). Best-effort — GC failure never blocks serve.
gcSessionContextState(engine).catch(() => {});
// Startup maintenance sweep [ENG-5][CX-P0.1+P0.3]: the serve process is
// the lock owner, so it runs the bounded sweep that ingests the corpus +
// reconciles fences/links/timeline for recent workspace writes. Same
// best-effort shape as the resolve-IPC block above: fires once ~3s after
// connect, unref'd (can never hold the process open), all errors
// swallowed inside armStartupSweep. Kill switch: GBRAIN_SWEEP=0 (checked
// inside the helper). Lazy import keeps sweep code off the boot path.
bootPhase('startup_sweep');
try {
const { armStartupSweep } = await import('../core/sweep.ts');
const { sourceId } = await resolveMcpStdioSourceScope(engine);
startupSweep = armStartupSweep(engine, {
sourceId,
});
} catch {
/* startup sweep is best-effort; never block serve */
}
};
if (isEngineDegraded(engine)) {
// Structured enter/exit lines for harness-log forensics.
process.stderr.write(statusMode
? `[gbrain-serve] STATUS-ONLY: ${statusHeadline(statusMode)} Serving gbrain_status; the full tool list returns once a tool call finds the brain openable. Supervisors: --fail-fast exits instead.\n`
: '[gbrain-serve] DEGRADED: database unreachable at startup — tool calls return classified errors (GBRAIN_DB_ACCESS) and the server reconnects automatically. Fix: gbrain db-repair. Kill switch: GBRAIN_SERVE_DEGRADED=0.\n');
onEngineRecovered(engine, () => {
// A reconnect can complete while shutdown is already draining (stdin
// EOF during the attempt) — booting IPC/sweep on an exiting process
// would leak a socket binding past the shutdown close.
if (shuttingDown) return;
process.stderr.write('[gbrain-serve] RECOVERED: database reachable — full service restored.\n');
// Refresh clients holding the degraded (gate-hidden) tool catalog.
Promise.resolve(server.sendToolListChanged()).catch(() => { /* best-effort */ });
bootEngineDependents().catch(() => { /* deferred boot is best-effort */ });
});
} else {
await gate.run(bootPhase, bootEngineDependents);
}
// Exit cleanly when MCP client disconnects (stdin EOF) or on signals.
// Without this, orphaned serve processes accumulate and contend for the
// PGLite write lock, causing ingest jobs (email-sync) to time out.
let shuttingDown = false;
const shutdown = (reason: string, code = 0) => {
if (shuttingDown) return;
shuttingDown = true;
process.stderr.write(`[gbrain-serve] shutdown: ${reason}\n`);
try { startupSweep?.cancel(); } catch { /* noop */ }
ipcBinding?.close();
// Cathedral 5: abort the in-flight checkpoint harvest + drop its queue
// BEFORE engine.disconnect — the background-work registry's drain is
// CLI-exit-only by contract, and a fire-and-forget DB writer surviving
// disconnect busy-loops the single-writer lock (the #1762 hazard class).
import('../core/context/checkpoint-harvest.ts')
.then((m) => m.shutdownCheckpointHarvest())
.catch(() => {})
// Delegated-sync settle BEFORE disconnect (idempotent shared promise —
// serve.ts's beginShutdown races here on the same signals): the job's
// final checkpoint flush and row-lock release need the live engine.
.then(() => import('../core/serve-sync-runner.ts').then((m) => m.shutdownDelegatedSync()))
.catch(() => {})
.then(() => Promise.resolve(engine.disconnect?.()))
.catch(() => {})
.finally(() => process.exit(code));
};
// v0.34.1 (#870): when MCP_STDIO=1, the wrapping gateway (OpenClaw's
// bundle-mcp layer, others) often pipes the JSON-RPC handshake then
// closes its stdin half. Treating that as a permanent disconnect kills
// the server before the first tool call arrives. Signal handlers and
// transport.onclose still cover the legitimate shutdown paths.
if (process.env.MCP_STDIO !== '1') {
process.stdin.on('end', () => shutdown('stdin end'));
process.stdin.on('close', () => shutdown('stdin close'));
}
// @ts-ignore — SDK exposes onclose on transport
transport.onclose = () => shutdown('transport close');
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
process.on('SIGHUP', () => shutdown('SIGHUP'));
}
// Backward compat: used by `gbrain call` command (trusted local path).
// v0.31.8 (D22): accept opts.sourceId so `gbrain call --source X <op> <json>`
// can scope the op handler to that source. resolveSourceWithTier() in call.ts
// is the upstream resolver; this layer just passes the resolved id through.
// #3874: also accept opts.localFederatedSourceIds so an ambient-tier
// resolution widens unqualified reads across federated sources exactly like
// the direct CLI path (cli.ts makeContext) does.
export async function handleToolCall(
engine: BrainEngine,
tool: string,
params: Record<string, unknown>,
opts?: { sourceId?: string; localFederatedSourceIds?: string[]; writeWaitMs?: number },
): Promise<unknown> {
const [{ operations }, { buildOperationContext }] = await Promise.all([import('../core/operations.ts'), loadDispatch()]);
const op = operations.find(o => o.name === tool);
if (!op) throw opError('unknown_tool', `Unknown tool: ${tool}`, 'Run `gbrain --tools-json` to list the tool names.');
const safeParams = normalizeOptionalParams(op, params);
const validationFailure = findInvalidParam(op, safeParams);
if (validationFailure) throw schemaInvalidParams(op, validationFailure, {});
const ctx = buildOperationContext(engine, safeParams, {
remote: false,
admissionOrigin: 'interactive',
logger: { info: console.log, warn: console.warn, error: console.error },
...(opts?.sourceId ? { sourceId: opts.sourceId } : {}),
...(opts?.writeWaitMs !== undefined ? { writeWaitMs: opts.writeWaitMs } : {}),
...(opts?.localFederatedSourceIds
? { localFederatedSourceIds: opts.localFederatedSourceIds }
: {}),
});
return op.handler(ctx, safeParams);
}