Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
42.5 KB
Raw Blame
/**
 * MCP Streamable HTTP endpoint for `gbrain serve --http` (split out of
 * serve-http.ts by refactor wave 1): bearer auth with the resource-audience
 * verifier, the per-request effective surface, tools/list and tools/call
 * through the shared dispatcher, request logging and the admin SSE feed.
 */
import { createHash } from 'node:crypto';
import type { Express, NextFunction, Request, Response } from 'express';
import { buildDefaultLimiters, type RateLimiter } from '../mcp/rate-limit.ts';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { DEFAULT_MAX_REQUEST_BODY_SIZE } from '@modelcontextprotocol/sdk/server/requestBody.js';
import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ErrorCode, type CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
import { opAllowedForBoundClient } from '../core/operations.ts';
import { authTransport } from '../core/ops/contract.ts';
import type { AuthInfo, Operation } from '../core/operations.ts';
import { disabledOpsForPublishGates } from '../mcp/publish-gates.ts';
import { installInstructionsResolver, MCP_SERVER_DESCRIPTION, readInstructionContent, resolveMcpInstructions } from '../mcp/instructions.ts';
import { httpInstructionTools } from '../mcp/initialize-context.ts';
import { installCapabilitiesResource, mcpAdministrationGuidance } from '../mcp/capabilities.ts';
import { createSkillResources } from '../mcp/skill-resources.ts';
import { resolveAuthCapabilities } from '../core/harness/capabilities.ts';
import { ambientOptsFrom, writebackCaller, type WritebackConfig } from '../core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';
import { OWNER_MEMBER_KEY } from '../core/search/private-visibility.ts';
import { hasScope, operationScopesAllowed } from '../core/scope.ts';
import { summarizeMcpParams, dispatchToolCall, requestLogStatusForResult, requestMetaSessionId, hotMemoryOffIn, acceptedPendingReceipt, unknownToolEnvelope, errorResult, dispatchRenderContext, grantBlockedNotices, admitNotices, audienceRefusal, type ToolResult } from '../mcp/dispatch.ts';
import { toAgentError } from '../core/agent-output.ts';
import { STATUS_TOOL_NAME, statusModeOf, statusToolResult } from '../mcp/status-mode.ts';
import { isCallable, publishGatesFromDisabled } from '../core/ops/callable.ts';
import { scopeDeniedError } from '../core/ops/op-fix.ts';
import { resolveStrictParamsMode } from '../mcp/validate-params.ts';
import { GBRAIN_CLIENT_HEADER, isGbrainThinClient, resolveResultRowsMode, resultRowsForRequest, type ResultRowsMode } from '../mcp/result-rows.ts';
import { buildToolDefs } from '../mcp/tool-defs.ts';
import { withEngineScope } from '../core/engine-scope.ts';
import {
  filterOpsForSurface,
  advertisedOps,
  clientAdvertisedSurface,
  clampSurface,
  minSurface,
  resolveClientRowSurface,
  resolveDefaultClientSurface,
  type McpSurface,
} from '../mcp/surface.ts';
import { getBrainHotMemoryMeta } from '../core/facts/meta-hook.ts';
import { ON_BEHALF_OF_HEADER } from '../core/access/audience.ts';
import { ROOM_HEADER } from '../core/access/room.ts';
import { GUEST_HEADER } from '../core/guests/admission.ts';
import { ACTOR_HEADER, EXTERNAL_ID_RE, QM_AUDIENCE_HEADER } from '../core/access/actor-model.ts';
import { parseAgentLabel, AGENT_LABEL_HEADER } from '../core/persistence/attribution.ts';
import { qmMemoryToolResult } from '../core/ops/qm-memory.ts';
import { attestableOp } from '../core/access/actor.ts';

const actorResourceRefusal = () => new McpError(ErrorCode.InvalidRequest,
  `actor_not_attested: resources are never read as an attested person, so nothing was read. Read resources without ${ACTOR_HEADER}.`,
  { code: 'actor_not_attested', reason: 'op_not_attested' });
import { serializeError } from '../core/errors.ts';
import { VERSION } from '../version.ts';
import { executeRawJsonb } from '../core/sql-query.ts';
import { withRequestConfigSnapshot } from '../core/config-snapshot.ts';
import { withBearerScopeHint } from './serve-http-oauth.ts';
import { mcpForegroundMiddleware } from '../core/foreground-activity.ts';
import type { ServeHttpContext } from './serve-http.ts';

/** Per-request state shared by the tools/list and tools/call handlers of one POST /mcp. */
interface McpRequestState {
  authInfo: AuthInfo;
  agentName: string;
  startTime: number;
  mcpOperations: Operation[];
  surface: McpSurface;
  surfaceCeiling: McpSurface;
  surfaceAllowedOps: ReadonlySet<string> | undefined;
  /** C1: search/query row shape for this request (thin-client header, else host `mcp.result_rows`). */
  resultRows: ResultRowsMode;
  /** Large pages: the same header marks gbrain's thin client, whose default get_page mode stays whole. Never authority. */
  thinClient: boolean;
  /** GBRA-231: the X-Gbrain-On-Behalf-Of header (a shared agent's audience); bounded by the credential's may_act_for in dispatch. */
  onBehalfOfHeader: string | undefined;
  /** GBRA-498: the X-Gbrain-Room header (the room an answer goes into); it only marks results, never narrows or widens them. */
  roomHeader: string | undefined;
  /** GBRA-504: the X-Gbrain-Guest header (guest attribution); read only for a write to a guest source. */
  guestHeader: string | undefined;
  /** GST-359 C1: the x-qm-actor header (a trusted system names the person); honoured in dispatch only for an attest credential. */
  actorHeader: string | undefined;
  /** GST-359 D: the x-qm-audience header (QM's channel audience, wave 2); any request carrying it is refused before any work. */
  audienceHeader: string | undefined;
  /** Wakeshift: the request's User-Agent, which tells it some agent programs apart. Shape only. */
  userAgent: string | undefined;
  /** The caller's self-declared agent label (X-Gbrain-Agent-Label): recorded on its write requests, never authority. */
  agentLabel: string | undefined;
}

export function mountMcp(app: Express, ctx: ServeHttpContext): void {
  const { engine, config, resourceVerifier, resourceMetadataUrl, mcpOperationsBase } = ctx;
  // ---------------------------------------------------------------------------
  // MCP tool calls (bearer auth + scope enforcement)
  // ---------------------------------------------------------------------------
  // MEMORY_VERBS v1 + WP4 (D2): the server-resolved surface is the CEILING.
  // The per-REQUEST effective surface — min(ceiling, client row surface ??
  // config default), clamped by the GBRAIN_MCP_FORCE_SURFACE kill switch
  // (narrow-only, FOV-6a) — is resolved inside the /mcp handler so a rescope
  // or config flip takes effect on the client's next request without a
  // restart, and the dispatch allow-set is recomputed per request
  // (amendment 20). The surface filter applies AFTER the localOnly filter;
  // the same set feeds dispatch as allowedOps so hidden ops are uncallable,
  // not just unlisted [c2].
  const serverSurfaceCeiling: McpSurface = ctx.surface ?? 'full';

  /**
   * WP4 (D2): resolve this request's effective surface from the caller's
   * verified auth. A legacy bearer token has no client row to pre-seed, so it
   * keeps the (clamped) ceiling; its scope, source and operation grants still
   * bound it (#9266). The config default (`mcp.default_surface_dcr`) is read
   * dual-plane ONLY when an OAuth client row carries no usable surface — the
   * common full-surface path pays no extra config read. Unknown row values
   * are ignored with a warn-once per client (amendment 18). Never throws:
   * surface resolution must not take a request down. On a default-surface
   * read failure the LAST successfully read default (per process) still
   * applies, so a transient config outage cannot silently widen a client
   * that normally resolves narrower than the ceiling; with no prior read,
   * the ceiling is the only floor available (pre-WP4 behavior).
   */
  let lastKnownDefaultSurface: McpSurface | null = null;
  async function resolveEffectiveSurface(authInfo: AuthInfo): Promise<{ ceiling: McpSurface; effective: McpSurface }> {
    const ceiling = clampSurface(serverSurfaceCeiling);
    // min() can never go below the narrowest surface: a 'verbs' ceiling makes
    // the row/default resolution a no-op, so skip the awaited config read.
    if (ceiling === 'verbs') return { ceiling, effective: ceiling };
    if (authInfo.principal?.kind === 'legacy_token') return { ceiling, effective: ceiling };
    const rowSurface = resolveClientRowSurface(authInfo.surface, authInfo.clientId);
    if (rowSurface !== null) return { ceiling, effective: minSurface(ceiling, rowSurface) };
    try {
      const dflt = await resolveDefaultClientSurface(engine, config);
      lastKnownDefaultSurface = dflt ?? null;
      return { ceiling, effective: minSurface(ceiling, dflt ?? ceiling) };
    } catch {
      return { ceiling, effective: minSurface(ceiling, lastKnownDefaultSurface ?? ceiling) };
    }
  }

  // v0.36.x #1076: MCP Streamable HTTP spec — GET /mcp opens an optional SSE
  // backchannel for server-initiated messages. gbrain's transport is stateless
  // and doesn't push server-initiated messages, so per spec we MUST return 405
  // (not 404) so probing clients (claude.ai, etc.) recognize this as an MCP
  // endpoint, not a missing route. Without this, clients display "endpoint not
  // found" instead of "endpoint exists but no SSE channel."
  app.get('/mcp', (_req: Request, res: Response) => {
    res.set('Allow', 'POST, DELETE');
    res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed' }, id: null });
  });

  // #5277: hint every scope a connector may need. Clients that request exactly
  // the hinted scope and never step up (claude.ai connectors) otherwise stay
  // read-only; grantScopes still caps each grant to the client row's scope.
  // GBRA-431: the rate limits SECURITY.md documents for /mcp, applied when the operator sets them: the IP bucket before
  // the token lookup, the token bucket after it. Unset, serve --http keeps its unlimited default.
  const limiters = buildDefaultLimiters();
  const ipLimit = rateLimitStep('GBRAIN_HTTP_RATE_LIMIT_IP', limiters.ip, req => req.ip ?? req.socket.remoteAddress ?? 'unknown', 'Too many requests');
  const tokenLimit = rateLimitStep('GBRAIN_HTTP_RATE_LIMIT_TOKEN', limiters.token,
    req => createHash('sha256').update(((req as any).auth as AuthInfo).token).digest('hex'), 'Too many requests for this token');
  app.post('/mcp', ipLimit, withBearerScopeHint(
    requireBearerAuth({ verifier: resourceVerifier, resourceMetadataUrl }), ['read', 'write'],
  ), mcpForegroundMiddleware, tokenLimit, (req: Request, res: Response) => withEngineScope(engine, () => withRequestConfigSnapshot(engine, () => handleMcpPost(req, res))));

  // #6721: one config snapshot serves every config read of one POST /mcp (the
  // surface, row-shape and writeback reads below, tools/list and a read op's
  // dispatch); dispatch reads live for a write op (config-snapshot.ts).
  async function handleMcpPost(req: Request, res: Response): Promise<void> {
    const startTime = Date.now();
    const authInfo = (req as any).auth as AuthInfo;

    // Human-readable agent name is now threaded through AuthInfo by
    // verifyAccessToken (which JOINs oauth_clients in its existing token
    // SELECT). No per-request DB roundtrip needed. Falls back to clientId
    // for legacy tokens or when the JOIN row's client_name is NULL.
    const agentName = authInfo.clientName ?? authInfo.clientId;

    // WP4 (D2): per-request effective surface + fail-closed allow-set,
    // recomputed per request (amendment 20) so rescopes/request_tools
    // persists take effect on the next request with zero restart.
    // Ambient writeback (opt-in, default off) resolves CONCURRENTLY with the
    // surface read (performance review, this wave — the two independent DB
    // waits must not serialize; an initialize-only resolve is NOT possible
    // here because /mcp has no JSON middleware, so req.body is undefined
    // until the SDK transport reads the stream — verified by the OAuth
    // lifecycle test, which caught exactly that regression). Restart-free
    // like the publish gates, fail-closed with a per-engine last-known-good
    // bundle so a transient config blip serves the previous bundle instead
    // of silently dropping the section mid-session. OV-A5: a token without
    // write scope never receives the section (`remember` would be
    // uncallable — instructions must not order impossible calls); OV2-14:
    // extract_facts is advertised only when this token's ACTUAL visible set
    // can call it (surface + scope + bound-client fence — the same
    // predicates tools/list applies).
    const canWrite = hasScope(authInfo.scopes, 'write');
    const [{ ceiling: surfaceCeiling, effective: surface }, writeback, hostResultRows] = await Promise.all([
      resolveEffectiveSurface(authInfo),
      canWrite ? resolveAgentWriteback(engine, config).then(r => r.bundle) : Promise.resolve(null),
      resolveResultRowsMode(engine, config),
    ]);
    // C1: gbrain's thin client keeps full rows. The header is unverified and
    // selects a row shape only; it never gates anything security-relevant.
    const resultRows = resultRowsForRequest(req.get(GBRAIN_CLIENT_HEADER), hostResultRows);
    const mcpOperations = filterOpsForSurface(mcpOperationsBase, surface)
      .filter(op => authInfo.allowedOperations == null || authInfo.allowedOperations.includes(op.name));
    authInfo.effectiveSurface = surface;
    const surfaceAllowedOps: ReadonlySet<string> | undefined =
      surface === 'full' && authInfo.allowedOperations == null ? undefined : new Set(mcpOperations.map(o => o.name));
    const thinClient = isGbrainThinClient(req.get(GBRAIN_CLIENT_HEADER));
    const state: McpRequestState = { authInfo, agentName, startTime, mcpOperations, surface, surfaceCeiling, surfaceAllowedOps, resultRows, thinClient,
      onBehalfOfHeader: req.get(ON_BEHALF_OF_HEADER), roomHeader: req.get(ROOM_HEADER), guestHeader: req.get(GUEST_HEADER), actorHeader: req.get(ACTOR_HEADER), audienceHeader: req.get(QM_AUDIENCE_HEADER),
      userAgent: req.get('user-agent'), agentLabel: parseAgentLabel(req.get(AGENT_LABEL_HEADER)) };
    const server = createMcpRequestServer(ctx, state, writeback, writeback?.enabled ? await engine.getConfig(OWNER_MEMBER_KEY).catch(() => null) : null);
    await serveMcpRequest(server, req, res);
  }
}

function createMcpRequestServer(
  ctx: ServeHttpContext,
  state: McpRequestState,
  writeback: WritebackConfig | null,
  ownerMember: string | null,
): Server {
  const { engine, config, mcpResourceUrl } = ctx;
  const { authInfo, mcpOperations, surface, surfaceCeiling, surfaceAllowedOps } = state;
  // Create a fresh MCP server per request (stateless).
  let writebackOpts: ReturnType<typeof ambientOptsFrom> = null;
  if (writeback) {
    // Both availability probes apply the SAME predicates tools/list does
    // (surface filter + bound-client fence): a slug-bound client whose
    // fence denies `remember` receives NO ambient section at all —
    // instructions must never order calls dispatch will deny.
    const rememberOp = mcpOperations.find(o => o.name === 'remember');
    const extractFactsOp = mcpOperations.find(o => o.name === 'extract_facts');
    writebackOpts = ambientOptsFrom(writeback, {
      remember: rememberOp !== undefined && opAllowedForBoundClient(authInfo, rememberOp),
      extractFacts: extractFactsOp !== undefined && opAllowedForBoundClient(authInfo, extractFactsOp),
      ...writebackCaller(authInfo, ownerMember),
    });
  }
  const server = new Server(
    { name: 'gbrain', version: VERSION, description: MCP_SERVER_DESCRIPTION },
    {
      capabilities: { tools: {}, resources: {} },
      // #4748: contract (+ opt-in writeback section) + deployment identity.
      instructions: resolveMcpInstructions(config, process.env, { writeback: writebackOpts }),
    },
  );
  // F1: the contract for THIS token's callable set + readiness tail, resolved at initialize.
  installInstructionsResolver(server, async () => resolveMcpInstructions(config, process.env, {
    writeback: writebackOpts,
    tools: await httpInstructionTools(engine, config, { ops: mcpOperations, surface, auth: authInfo, allowedOps: surfaceAllowedOps, cache: ctx.readinessCache, advertise: ctx.advertise ?? null }),
    ...await readInstructionContent(engine),
  }));
  installCapabilitiesResource(server, async () => {
    return { transport: authTransport(authInfo), client_id: authInfo.clientId,
      ...await resolveAuthCapabilities(authInfo, engine, config), administration: mcpAdministrationGuidance(mcpResourceUrl.toString()) };
  }, state.actorHeader != null || state.audienceHeader !== undefined ? undefined : createSkillResources(engine, async () => {
    const sourceId = authInfo.sourceId ?? 'default';
    const { noGrantFederatedScope } = await import('../core/source-resolver.ts');
    return { remote: true, transport: 'http', sourceId, auth: authInfo, config,
      localFederatedSourceIds: await noGrantFederatedScope(engine, authInfo.hasSourceGrant, sourceId),
      allowedOps: surfaceAllowedOps, surface, surfaceCeiling };
  }));
  // GST-359 C1: resources are never read as an attested person, so a request naming one reads none.
  if (state.actorHeader != null) server.setRequestHandler(ReadResourceRequestSchema, async () => { throw actorResourceRefusal(); });
  // GST-359 D: a request carrying x-qm-audience is refused before any work, on every method that reads or runs a tool.
  if (state.audienceHeader !== undefined) {
    const refusal = (op: string) => audienceRefusal(op, { auth: authInfo, transport: 'http' });
    const rpcRefusal = (method: string) => { const { rpc } = refusal(method); return new McpError(ErrorCode.InvalidRequest, rpc.message, rpc.data); };
    for (const [schema, method] of [[ListResourcesRequestSchema, 'resources/list'], [ReadResourceRequestSchema, 'resources/read'], [ListToolsRequestSchema, 'tools/list']] as const) {
      server.setRequestHandler(schema, async () => { throw rpcRefusal(method); });
    }
    server.setRequestHandler(CallToolRequestSchema, async (request) => refusal(request.params.name).result);
    return server;
  }
  server.setRequestHandler(ListToolsRequestSchema, async () => listMcpTools(ctx, state));
  server.setRequestHandler(CallToolRequestSchema, async (request) => callMcpTool(ctx, state, request));
  return server;
}

async function listMcpTools(ctx: ServeHttpContext, state: McpRequestState) {
  const { engine, config, broadcastEvent } = ctx;
  const { authInfo, agentName, startTime, mcpOperations, surface, surfaceAllowedOps } = state;
  // WP1 honest catalog: the advertised list is exactly what THIS token
  // can call. Three per-request filters, cheapest first:
  //   1. token scope — a read-only token never sees admin/write tools;
  //   2. bound-client fence — a slug-bound client never sees ops the
  //      dispatch fence would deny (same predicate, cannot drift);
  //   3. publish gates — gated ops (skills/advisor) are hidden while
  //      their gate is off; the resolver never throws (read failure =
  //      hidden, matching the default-off consent posture) so a config
  //      hiccup costs at most the 4 gated tools, never the whole list.
  // Call-time enforcement (hasScope / fence / assertPublishEnabled)
  // stays as the fail-closed backstop for all three layers.
  // Both per-request config reads are independent — issue them
  // concurrently (one RTT of latency on network Postgres, not two).
  const [gateDisabled, strictParamsMode, advertised] = await Promise.all([
    disabledOpsForPublishGates(engine, config),
    resolveStrictParamsMode(engine, config),
    clientAdvertisedSurface(authInfo, engine, config, ctx.advertise ?? null),
  ]);
  // FOV-4: `agent` deliberately implies only itself, which would strand
  // agent-only tokens with ZERO discovery — ops flagged `agentCallable`
  // (request_tools) are visible to (and callable by, below) agent scope
  // in addition to their declared scope.
  // Agent contract v1 (A2): the one callability predicate (isCallable) plus
  // the bound-client op fence.
  const publishGates = publishGatesFromDisabled(mcpOperations, gateDisabled);
  // GST-359 C1: under a valid x-qm-actor header from an attest credential, only the operations it may run as the person.
  const attest = state.actorHeader != null && EXTERNAL_ID_RE.test(state.actorHeader) ? authInfo.attest : null;
  const visibleOps = mcpOperations.filter(op =>
    isCallable(op, { transport: 'http', surface, scopes: authInfo.scopes, publishGates, allowedOps: surfaceAllowedOps })
    && opAllowedForBoundClient(authInfo, op) && (!attest || (attest.ops.includes(op.name) && attestableOp(op.name, op))),
  );
  // WP3 (amendment 14): ONE schema mapper — the inline map this handler
  // carried is unified onto buildToolDefs so the byte-pin test covers the
  // transport consumers actually use. strict_params is read dual-plane
  // PER REQUEST (same restart-free property as the publish gates above):
  // 'reject' closes each schema with additionalProperties:false and
  // declares the _meta/dry_run passthrough keys (D14.1).
  const strictParams = strictParamsMode === 'reject';
  // mcp.advertised_surface narrows the list only; dispatch below keeps the callable set (request_tools reaches the rest).
  // A client that chose its own surface (request_tools {surface}, an operator rescope) gets that surface listed in full.
  const tools = buildToolDefs(advertisedOps(visibleOps, surface, advertised), { strictParams });
  // v0.28.10: log every JSON-RPC method, not just successful tools/call.
  // Pre-fix, /admin/api/requests showed nothing for clients that only
  // ever called tools/list, and the v0.26.3 persistence regression test
  // asserting >= 2 rows after tools/list + tools/call was unreachable.
  // Amendment 23 stopgap (full list-size telemetry deferred): the row's
  // params carry the listed-tool count so per-token-class list sizes are
  // queryable (`params->>'tool_count'`) without new telemetry plumbing.
  const latency = Date.now() - startTime;
  try {
    await executeRawJsonb(
      engine,
      `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, params)
       VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
      [authInfo.clientId, agentName, 'tools/list', latency, 'success'],
      [{ tool_count: tools.length }],
    );
  } catch { /* best effort */ }
  broadcastEvent({
    agent: agentName,
    operation: 'tools/list',
    scopes: authInfo.scopes.join(','),
    latency_ms: latency,
    status: 'success',
    timestamp: new Date().toISOString(),
  });
  return { tools };
}

async function callMcpTool(ctx: ServeHttpContext, state: McpRequestState, request: CallToolRequest): Promise<ToolResult> {
  const { engine, broadcastEvent, logFullParams } = ctx;
  const { authInfo, agentName, startTime, mcpOperations, surface, surfaceCeiling, surfaceAllowedOps, resultRows, thinClient } = state;
  const { name, arguments: params } = request.params;
  // A server that recovered from status-only mode answers clients still holding the status tool list (never listed).
  const statusMode = name === STATUS_TOOL_NAME ? statusModeOf(engine) : null;
  if (statusMode && hasScope(authInfo.scopes, 'read')) return statusToolResult(statusMode, 'http');
  const op = mcpOperations.find(o => o.name === name);
  if (!op) {
    return qmMemoryToolResult(name, await rejectUnknownMcpOperation(ctx, state, name, requestMetaSessionId(request.params)), state.actorHeader != null);
  }

  // Scope enforcement (v0.28: hasScope replaces exact-string-match so
  // admin tokens satisfy any scope, write satisfies read, and the new
  // sources_admin / users_admin scopes resolve through the same
  // hierarchy. Plain string includes() at this site would have made
  // sources_admin tokens look like they couldn't even read.)
  const requiredScope = op.scope || 'read';
  // FOV-4: agentCallable carve-out mirrors the tools/list filter above —
  // an op listed for an agent-only token must not scope-deny at call time.
  // #5575: an owner-only (cliOnly) op is refused for every remote caller by the
  // shared dispatcher with `trusted_local_only` and the host command; a scope
  // denial first would tell the operator to widen the grant for nothing.
  const scopeSatisfied = op.cliOnly !== undefined || operationScopesAllowed(authInfo.scopes, op);
  if (!scopeSatisfied) {
    return qmMemoryToolResult(name, await rejectInsufficientMcpScope(ctx, state, name, requiredScope, requestMetaSessionId(request.params)), state.actorHeader != null);
  }

  // F8: redact request payload by default (declared keys only via the
  // op's `params` allow-list; values + attacker-controlled key names
  // never written to mcp_request_log or the SSE feed). --log-full-params
  // bypasses this for operators debugging on their own laptop, with the
  // startup warning printed earlier.
  //
  // D1 (v0.31 wave): mcp_request_log.params is JSONB. Pre-v0.31 wrote
  // a JSON-string into that JSONB column via the postgres.js template
  // tag's loose typing — readable but semantically wrong (params->>'op'
  // would return the encoded string, not the value). Post-v0.31 we
  // pass the OBJECT through executeRawJsonb with an explicit ::jsonb
  // cast, so reads return real objects and `params->>'op'` returns
  // 'tools/list'. Pre-existing string-shaped rows are normalized by
  // migration v41 in src/core/migrate.ts.
  const safeParamsSummary = summarizeMcpParams(name, params);
  // Wakeshift's session_key is a conversation credential: never logged, even under --log-full-params.
  const fullParams = params && typeof params === 'object' && 'session_key' in params ? { ...params, session_key: '[redacted]' } : params;
  const logParamsObj: unknown = logFullParams
    ? (fullParams || null)
    : (safeParamsSummary || null);
  const broadcastParams = logFullParams ? (fullParams || {}) : safeParamsSummary;

  // v0.31 (D12 / eE1): refactor the inlined op.handler call to go through
  // src/mcp/dispatch.ts so HTTP MCP shares the same dispatch path as
  // stdio MCP. The dispatcher does param validation, OperationContext
  // build, error envelope unification, and (new) `_meta.brain_hot_memory`
  // injection via the metaHook. HTTP-specific concerns (mcp_request_log
  // persistence + SSE broadcast) stay here; the dispatcher returns the
  // ToolResult and we read isError + _meta to pick the right branch.
  // #2529: takesHoldersAllowList is a typed AuthInfo field populated by
  // verifyAccessToken from access_tokens.permissions.takes_holders for
  // legacy bearer tokens ([] preserved as deny-all). The fail-closed
  // ['world'] default covers OAuth-client tokens (no per-client storage
  // yet — see TODOS.md) and pre-v29 brains (no permissions column →
  // isUndefinedColumnError fallback in verifyAccessToken).
  const tokenAllowList = authInfo.takesHoldersAllowList ?? ['world'];
  // v0.34.1 (#861, D13): AuthInfo.sourceId is now a real typed field
  // populated from oauth_clients.source_id (migration v60 backfilled
  // NULL → 'default'). Pre-fix this site cast through AuthInfo and
  // fell back to GBRAIN_SOURCE env / 'default' — the silent-fallback
  // path codex flagged in plan review. Post-v60, every OAuth client
  // has source_id set; legacy bearer tokens default to 'default' in
  // verifyAccessToken. The env-fallback is gone.
  const tokenSourceId = authInfo.sourceId ?? 'default';

  // #3242 parity: the legacy-transport and stdio dispatch sites widen a
  // no-grant caller's unqualified reads across the federated source set
  // (localFederatedSourceIds); this SDK-transport site never did, so the
  // same token saw federated pages over /mcp on one serve mode and scalar
  // 'default' on the other. hasSourceGrant === false is set ONLY for
  // legacy bearer tokens with no operator source grant (oauth-provider);
  // granted tokens and OAuth clients never widen. Best-effort: a resolver
  // failure keeps the scalar scope.
  const { noGrantFederatedScope } = await import('../core/source-resolver.ts');
  const localFederated = await noGrantFederatedScope(
    engine,
    authInfo.hasSourceGrant,
    tokenSourceId,
  );

  // #4817: written before dispatch, so a request that never returns (a spin
  // the stall watchdog later kills) still leaves its op name and an argument
  // digest behind. The digest identifies the request without logging content.
  let argsDigest = 'none';
  try { argsDigest = createHash('sha256').update(JSON.stringify(params ?? null)).digest('hex').slice(0, 16); } catch { /* unserializable */ }
  process.stderr.write(`[gbrain-serve] dispatch op=${name} args_sha256=${argsDigest}\n`);
  // CX2-11 parity with stdio: the request-level `_meta.session_id` (a sibling
  // of `arguments`) becomes OperationContext.sessionId, so the hot-memory
  // metaHook and every other session consumer key per remote session. Identity
  // only, never a trust surface.
  const sessionId = requestMetaSessionId(request.params);
  let toolResult: Awaited<ReturnType<typeof dispatchToolCall>>;
  try {
    toolResult = await dispatchToolCall(engine, name, params as Record<string, unknown> | undefined, {
      remote: true,
      admissionOrigin: 'interactive',
      config: ctx.config,
      // WP1/D7: network transport — the dispatch-layer localOnly
      // backstop keys off this marker.
      transport: 'http',
      inboundFrameBytes: mcpBodyCap(),
      ...(sessionId ? { sessionId } : {}),
      ...(hotMemoryOffIn(request.params) ? { hotMemoryOff: true } : {}),
      onBehalfOf: { header: state.onBehalfOfHeader, requestMeta: (request.params as { _meta?: unknown })._meta },
      room: { header: state.roomHeader, requestMeta: (request.params as { _meta?: unknown })._meta },
      guest: { header: state.guestHeader, requestMeta: (request.params as { _meta?: unknown })._meta },
      mcpCaller: { client: authInfo.clientName, userAgent: state.userAgent, meta: (request.params as { _meta?: Record<string, unknown> })._meta },
      actor: { header: state.actorHeader, audience: state.audienceHeader },
      ...(state.agentLabel ? { agentLabel: state.agentLabel } : {}),
      takesHoldersAllowList: tokenAllowList,
      sourceId: tokenSourceId,
      ...(localFederated ? { localFederatedSourceIds: localFederated } : {}),
      metaHook: getBrainHotMemoryMeta,
      ...(ctx.noticeLedger ? { noticeLedger: ctx.noticeLedger } : {}),
      // MEMORY_VERBS v1: fail-closed surface enforcement + usage attribution.
      ...(surfaceAllowedOps ? { allowedOps: surfaceAllowedOps } : {}),
      surface,
      // WP4 (D2): request_tools bounds its catalog + persist by this.
      surfaceCeiling,
      // D2: a callable tool the advertised surface leaves out of tools/list (same rule as listMcpTools).
      isListed: async op => advertisedOps([op], surface, await clientAdvertisedSurface(authInfo, engine, ctx.config, ctx.advertise ?? null)).length > 0,
      resultRows,
      ...(thinClient ? { thinClient: true } : {}),
      // v0.31 follow-up fix: thread auth so the whoami op (and any
      // future scope-aware handlers) can introspect the caller. The
      // original D12/eE1 refactor moved dispatch into dispatchToolCall
      // but forgot to pass authInfo; whoami fell through to the
      // unknown_transport throw because ctx.auth was undefined.
      auth: authInfo,
      logger: {
        info: (msg: string) => console.error(`[INFO] ${msg}`),
        warn: (msg: string) => console.error(`[WARN] ${msg}`),
        error: (msg: string) => console.error(`[ERROR] ${msg}`),
      },
    });
  } catch (e) {
    // dispatchToolCall absorbs OperationError + Error and returns
    // isError:true; only an unexpected throw lands here. Treat as the
    // F15 unified envelope. v0.31 wave (D1): mcp_request_log.params is
    // JSONB — write the object via executeRawJsonb so reads return a
    // real object, not a JSON-encoded string.
    const latency = Date.now() - startTime;
    const errorPayload = serializeError(e);
    try {
      await executeRawJsonb(
        engine,
        `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
         VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
        [authInfo.clientId, agentName, name, latency, 'error', errorPayload.message],
        [logParamsObj],
      );
    } catch { /* best effort */ }
    broadcastEvent({
      agent: agentName,
      operation: name,
      params: broadcastParams,
      scopes: authInfo.scopes.join(','),
      latency_ms: latency,
      status: 'error',
      error: errorPayload,
      timestamp: new Date().toISOString(),
    });
    // Agent contract v1 (A1): the one envelope, not the nested legacy StructuredError.
    return errorResult(e, { remote: true, transport: 'http', auth: authInfo, surface, ...(surfaceAllowedOps ? { allowedOps: surfaceAllowedOps } : {}) }, { op: name });
  }

  return recordMcpToolResult(ctx, state, name, toolResult, logParamsObj, broadcastParams);
}

async function rejectUnknownMcpOperation(ctx: ServeHttpContext, state: McpRequestState, name: string, sessionId?: string): Promise<ToolResult> {
  const { engine, broadcastEvent } = ctx;
  const { authInfo, agentName, startTime } = state;
  // v0.28.10: persist unknown-op attempts. Operators investigating
  // misbehaving agents need to see the full attempt log, not just
  // valid-op success/error.
  const latency = Date.now() - startTime;
  try {
    await executeRawJsonb(
      engine,
      `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
       VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
      [authInfo.clientId, agentName, name, latency, 'error', `unknown_operation: ${name}`],
      [null],
    );
  } catch { /* best effort */ }
  broadcastEvent({
    agent: agentName,
    operation: name,
    scopes: authInfo.scopes.join(','),
    latency_ms: latency,
    status: 'error',
    error: { code: 'unknown_operation', message: `Unknown: ${name}` },
    timestamp: new Date().toISOString(),
  });
  // Frozen v1 pair: `error: unknown_operation` stays; `code: unknown_tool`.
  const opts = { remote: true, transport: 'http' as const, auth: authInfo, surface: state.surface, config: ctx.config, surfaceCeiling: state.surfaceCeiling,
    ...(sessionId ? { sessionId } : {}), ...(ctx.noticeLedger ? { noticeLedger: ctx.noticeLedger } : {}),
    ...(state.surfaceAllowedOps ? { allowedOps: state.surfaceAllowedOps } : {}) };
  return unknownToolEnvelope(name, opts, 'unknown_operation', await grantBlockedNotices(engine, opts, true));
}

async function rejectInsufficientMcpScope(
  ctx: ServeHttpContext,
  state: McpRequestState,
  name: string,
  requiredScope: string,
  sessionId?: string,
): Promise<ToolResult> {
  const { engine, broadcastEvent } = ctx;
  const { authInfo, agentName, startTime } = state;
  // v0.28.10: persist scope-rejected attempts. Same operator-visibility
  // motivation as the unknown-op path — and it makes the v0.26.3
  // persistence regression test reliable across both rejection paths.
  // Amendment 33: a call-time scope deny is a LIST-LEVEL denial (the
  // tools/list filter uses this same hasScope predicate, so the op was
  // never advertised to this token — the client ignored or staled its
  // list, or list/call drifted). status='denied_after_list' makes the
  // honest-catalog metric a one-line count that trends to zero.
  const latency = Date.now() - startTime;
  try {
    await executeRawJsonb(
      engine,
      `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
       VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
      [authInfo.clientId, agentName, name, latency, 'denied_after_list', `insufficient_scope: requires '${requiredScope}'`],
      [null],
    );
  } catch { /* best effort */ }
  broadcastEvent({
    agent: agentName,
    operation: name,
    scopes: authInfo.scopes.join(','),
    latency_ms: latency,
    status: 'denied_after_list',
    error: { code: 'insufficient_scope', message: `requires '${requiredScope}'` },
    timestamp: new Date().toISOString(),
  });
  const denial = scopeDeniedError({ op: name, required: [requiredScope], auth: authInfo, transport: 'http' });
  const opts = { remote: true, transport: 'http' as const, auth: authInfo, config: ctx.config, surfaceCeiling: state.surfaceCeiling,
    ...(sessionId ? { sessionId } : {}), ...(ctx.noticeLedger ? { noticeLedger: ctx.noticeLedger } : {}) };
  const notices = await grantBlockedNotices(engine, opts, true);
  if (notices.length) denial.notices = admitNotices(notices, opts);
  const envelope = toAgentError(denial, { transport: 'http', op: name, render: dispatchRenderContext(opts) });
  return { content: [{ type: 'text', text: JSON.stringify({ ...envelope, your_scopes: authInfo.scopes }) }], isError: true };
}

async function recordMcpToolResult(
  ctx: ServeHttpContext,
  state: McpRequestState,
  name: string,
  toolResult: ToolResult,
  logParamsObj: unknown,
  broadcastParams: unknown,
): Promise<ToolResult> {
  const { engine, broadcastEvent } = ctx;
  const { authInfo, agentName, startTime } = state;
  const latency = Date.now() - startTime;
  if (toolResult.isError) {
    // dispatchToolCall serializes the error into the content text;
    // for the audit log we re-extract a message string for the
    // mcp_request_log error_message column. Best-effort parse.
    // Amendment 33 / D10: op-level denials the list should have
    // prevented (publish-gate backstop `config_key=...`, bound-client
    // fence op-level deny `fence=op`) log status='denied_after_list'
    // instead of plain 'error' — the honest-catalog trend-to-zero
    // metric. Argument-level fence denials carry no marker and stay
    // 'error' (legitimate for a listed op).
    let errMsg = 'unknown_error';
    try {
      const parsed = JSON.parse(toolResult.content[0]?.text ?? '{}');
      errMsg = parsed.error?.message ?? parsed.message ?? errMsg;
    } catch { /* ignore */ }
    const errStatus = requestLogStatusForResult(toolResult);
    // #5249: the opaque request id lets admin stats count pending writes that later fail.
    const pending = errStatus === 'accepted_pending' ? acceptedPendingReceipt(toolResult) : null;
    try {
      await executeRawJsonb(
        engine,
        `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
         VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
        [authInfo.clientId, agentName, name, latency, errStatus, errMsg],
        [pending ? { ...(logParamsObj && typeof logParamsObj === 'object' ? logParamsObj : {}), write_request_id: pending.request_id } : logParamsObj],
      );
    } catch { /* best effort */ }
    broadcastEvent({
      agent: agentName,
      operation: name,
      params: broadcastParams,
      scopes: authInfo.scopes.join(','),
      latency_ms: latency,
      status: errStatus,
      error: { code: 'op_error', message: errMsg },
      timestamp: new Date().toISOString(),
    });
    return toolResult;
  }

  // WP3 (amendment 13): warn-mode observability. A success whose _meta
  // carries a non-empty warnings array logs as 'success_with_warnings' so
  // the reject-flip decision is evidence-based (count per client via the
  // status column). Warn CONTENTS (the raw unknown keys) are never logged.
  const successStatus = requestLogStatusForResult(toolResult);
  try {
    await executeRawJsonb(
      engine,
      `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, params)
       VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
      [authInfo.clientId, agentName, name, latency, successStatus],
      [successStatus === 'accepted_pending' ? { ...(logParamsObj && typeof logParamsObj === 'object' ? logParamsObj : {}), write_request_id: acceptedPendingReceipt(toolResult)?.request_id } : logParamsObj],
    );
  } catch { /* best effort */ }
  broadcastEvent({
    agent: agentName,
    operation: name,
    params: broadcastParams,
    scopes: authInfo.scopes.join(','),
    latency_ms: latency,
    status: successStatus,
    timestamp: new Date().toISOString(),
  });
  return toolResult;
}

/** A positive integer env var, or undefined when unset or not one. */
function positiveEnvInt(name: string): number | undefined {
  const raw = process.env[name]?.trim();
  if (!raw) return undefined;
  const n = /^\d+$/.test(raw) ? Number(raw) : NaN;
  if (Number.isSafeInteger(n) && n > 0) return n;
  console.error(`[serve-http] ${name}=${JSON.stringify(raw)} is not a positive whole number; ignoring it.`);
  return undefined;
}

/** GBRA-431: the POST /mcp body cap, GBRAIN_HTTP_MAX_BODY_BYTES when the operator sets it, else the SDK's 4 MiB. Over it the SDK answers 413 before the body is read. */
function mcpBodyCap(): number {
  return positiveEnvInt('GBRAIN_HTTP_MAX_BODY_BYTES') ?? DEFAULT_MAX_REQUEST_BODY_SIZE;
}

/** One rate-limit bucket as an Express step: a no-op while `envName` is unset, else 429 with Retry-After once the key's bucket is empty. */
function rateLimitStep(envName: string, limiter: RateLimiter, key: (req: Request) => string, message: string) {
  const enabled = positiveEnvInt(envName) !== undefined;
  return (req: Request, res: Response, next: NextFunction) => {
    if (!enabled) return next();
    const check = limiter.check(key(req));
    if (check.allowed) return next();
    res.set('Retry-After', String(check.retryAfter ?? 60)).status(429).json({ error: 'rate_limited', message });
  };
}

async function serveMcpRequest(server: Server, req: Request, res: Response): Promise<void> {
  // F14: wrap transport setup + handleRequest in try/catch. Without this,
  // an SDK-level throw (e.g., schema parse failure on a malformed request)
  // propagates to express's default error handler, which renders an HTML
  // error page — clients expecting JSON-RPC envelopes break. On
  // !res.headersSent we emit a minimal JSON 500 so the client at least
  // gets parseable JSON back.
  try {
    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined as any, maxRequestBodySize: mcpBodyCap() });
    // #2844: per-request teardown (SDK stateless pattern) — without it every POST /mcp leaks the transport+Server pair (~3GB/day RSS). Registered BEFORE connect/handleRequest so early disconnects and handleRequest throws still clean up; best-effort catches so cleanup never surfaces an unhandledRejection.
    res.on('close', () => { transport.close().catch(() => {}); server.close().catch(() => {}); });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  } catch (e) {
    console.error('MCP request handler error:', e instanceof Error ? e.message : e);
    if (!res.headersSent) {
      res.status(500).json(toAgentError(e, { transport: 'http', render: dispatchRenderContext({ remote: true, transport: 'http' }) }));
    }
  }
}