Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
89.6 KB
Raw Blame
/**
 * Shared MCP tool-call dispatch — single source of truth for stdio + HTTP transports.
 *
 * Both transports validate the same params, build the same OperationContext shape,
 * and serialize errors identically. Drift between transports caused PR #483's reversed-args
 * + missing-context bugs; this module exists to prevent that recurring.
 */

import { writeReceiptCapacityNotices } from '../core/persistence/capacity-snapshot.ts';
import { affectsRecall } from '../core/types.ts';
import type { BrainEngine } from '../core/engine.ts';
import { operations, OperationError, enforceBoundClientOpAllowList, opError } from '../core/operations.ts';
import type { OperationContext, AuthInfo } from '../core/operations.ts';
import { asSegmentedWriteRefusal } from '../core/page-body/page-shape.ts';
import type { Operation, OperationMeta } from '../core/ops/contract.ts';
import { loadConfig } from '../core/config.ts';
import { withRequestConfigSnapshot, withoutRequestConfigSnapshot } from '../core/config-snapshot.ts';
import { currentCallerAccess, withCallerAccess } from '../core/search/private-visibility.ts';
import { appliedAccessSummary, identityLookupUnavailable, remoteCallerAccess } from '../core/access/caller.ts';
import { credentialScopeFor, requesterScopeGate, requesterScopeRefuses, requiresRequesterScope, withServesReread, type RequesterScopeNotice } from '../core/access/requester-scope.ts';
import type { GuestChannels } from '../core/guests/admission.ts';
import { assessRoom, readRoomDeclaration, roomResponseCapNotice, type RoomChannels, type RoomDeclaration } from '../core/access/room.ts';
import { audienceInArguments, audienceInArgumentsError, logAudienceAssertion, parseAudience, type AudienceAuditEvent, type AudienceChannels, type AudiencePrincipal } from '../core/access/audience.ts';
import { ACTOR_ARGUMENT, actorNotAttested, EXTERNAL_ID_RE, resolveAttestedActor, type ActorChannels } from '../core/access/actor.ts';
import { attestedReadMode, scopeReadAccess, scopeReadLabelledOnlyRefused, withReadMode, type ReadMode } from '../core/access/scope-read.ts';
import { attestedReadScope } from '../core/access/member-sources.ts';
import { QM_PERSONAL_OPS, qmMemoryToolResult, recallArguments, unlinkedRecallResult } from '../core/ops/qm-memory.ts';
import { resolveBrainId } from '../core/brain-resolver.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { VERB_NAMES, MEMORY_VERBS_VERSION } from '../core/verbs.ts';
import { cliRenderContext, orderNotices, redactForTransport, renderAction, renderNotice, toAgentError, toolErrorResult, toolResultWithNotices, type Notice, type RenderContext } from '../core/agent-output.ts';
import { cliOnlyRefusal, isCallable } from '../core/ops/callable.ts';
import { hostFix, scopeDeniedError } from '../core/ops/op-fix.ts';
import { mutedNoticeCodes, processNoticeLedger, __resetProcessNoticeLedgerForTests, type NoticeLedger, type NoticeAudience } from '../core/notice-ledger.ts';
import { logVerbUsage, recordsFiring, type RecordsFiring } from '../core/verbs/usage-log.ts';
import { searchCountLine } from '../core/search/keyword-paging.ts';
import { pageCapLine } from '../core/search/remote-page-cap.ts';
import { dateLabelLine } from '../core/search/date-labels.ts';
import { emptyRead, hiddenTakesNotice, localTranscriptsNotice, recallInteropNotices, wantsTranscriptHint } from '../core/interop-notices.ts';
import { degradedStampFor, degradedStampLine, type DegradedStamp } from '../core/degraded-stamp.ts';
import { assertUnscopedReadReachesPages } from '../core/sources-not-readable.ts';
import { accessPolicyNotices } from '../core/access/policy-notice.ts';
import { hiddenToolHint, hiddenToolNext, hiddenToolRoute, type ToolConnection } from './hidden-tool-hint.ts';
import { opAllowedForBoundClient } from '../core/ops/context.ts';
import { takePostUpgradeMcpNotice } from '../core/post-upgrade-notice.ts';
import { takeHttpBehaviorNotice, takeLocalBehaviorNotice } from '../core/behavior-change-notice.ts';
import { takeChatFallbackHopNotices } from '../core/ai/fallback-hop-queue.ts';
import { mcpOnboardingNotices } from '../core/onboard/mcp-onboarding.ts';
import { takeFactsDrainNotice } from '../core/facts/drain.ts';
import { sourceGuardBlocksWrite } from '../core/source-resolver.ts';
import { suggestNearest } from '../core/levenshtein.ts';
import {
  normalizeOptionalParams,
  findInvalidParam,
  schemaInvalidParams,
  findUnknownParams,
  narrowingUnknownParams,
  resolveStrictParamsMode,
} from './validate-params.ts';
import { backupCheckDisabled, backupNagGate, backupNoticeText, loadBackupStatus } from '../core/backup/status-file.ts';
import { maybeRefreshBackupStatusInProcess } from '../core/backup/coverage.ts';
import { operationScopesAllowed } from '../core/scope.ts';
import { enforceReadTrustFloor } from '../core/eligibility/registry.ts';
import { invalidateHotMemoryForEngine } from '../core/facts/meta-hook.ts';
import { withSearchConnectionBudget } from '../core/search/connection-budget.ts';
import { isEngineDegraded } from '../core/degraded-marker.ts';
import { admittedPendingReceipt, isWriteReceipt, publicWriteReceipt, type WriteReceipt } from '../core/persistence/types.ts';
import { currentVerifiedLocalWriter, readLocalWriter, verifyLocalWriter, withRequestIdentityMemo, withVerifiedLocalRegistration } from '../core/persistence/identity.ts';
import { frameOverCap, resultTooLargeError } from '../core/egress-budget.ts';
import { isAIInvocationPolicyError } from '../core/ai/invocation-guard.ts';

// WP3: normalization + validation moved to validate-params.ts (direct unit
// surface). Re-exported here so existing imports/tests keep working.
export { normalizeOptionalParams, validateParams } from './validate-params.ts';

// db-availability loop: the classifier only needs the CONFIGURED url as
// context (supabase enrichment; fix derivation) plus the resolved brain id
// (a MOUNT's failure must never read as a host failure — the id rides into
// the marker). Read once per process — the uncaught-error path must not add
// disk reads per failure, and serve's routing is fixed for its lifetime.
let cachedClassifyUrl: string | null | undefined;
function configuredDbUrlForClassify(): string | null {
  if (cachedClassifyUrl === undefined) {
    try {
      cachedClassifyUrl = loadConfig()?.database_url ?? null;
    } catch {
      cachedClassifyUrl = null;
    }
  }
  return cachedClassifyUrl;
}
/** The brain this process serves: `serve --brain` / GBRAIN_BRAIN_ID / .gbrain-mount / host. */
function servedBrainId(): string | undefined {
  try {
    return resolveBrainId(getCliOptions().brain);
  } catch {
    return undefined;
  }
}
let cachedClassifyBrainId: string | null | undefined;
function brainIdForClassify(): string | undefined {
  if (cachedClassifyBrainId === undefined) {
    try {
      cachedClassifyBrainId = resolveBrainId(null);
    } catch {
      cachedClassifyBrainId = null;
    }
  }
  return cachedClassifyBrainId ?? undefined;
}

const VERB_NAME_SET: ReadonlySet<string> = new Set(VERB_NAMES);

// ── monthly backup-coverage notice (once per process, agent-facing only) ────

let backupNoticeShown = false;
let backupNoticeCheckedMs = 0;

/** Test seam: re-arm the once-per-process backup notice. */
export function __resetBackupNoticeForTests(): void {
  backupNoticeShown = false;
  backupNoticeCheckedMs = 0;
  __resetProcessNoticeLedgerForTests();
}

/**
 * Attach the aggregate backup warning as an extra content block. Fail-open:
 * a notice bug must never break a tool call.
 *
 * STDIO transport only: the notice targets local-harness installs (Claude
 * Code/Codex/OpenClaw/plugin serves are all stdio). HTTP callers are remote
 * thin clients — the host's backup posture is operational metadata their
 * token scope doesn't grant (the mcp.publish_advisor discipline), and a
 * remote-triggered record() must not spend the LOCAL notice budget. Local CLI
 * callers (`gbrain call`, opts.remote === false) are excluded too — the
 * cli.ts startup rail owns that surface. The hourly recheck latch keeps the
 * healthy steady state at zero file reads per tool call.
 */
function maybeBackupNotice(notices: Notice[], opts: DispatchOpts): void {
  try {
    if (backupNoticeShown || opts.remote === false || opts.transport !== 'stdio') return;
    const now = Date.now();
    if (now - backupNoticeCheckedMs < 60 * 60 * 1000) return;
    backupNoticeCheckedMs = now;
    if (backupCheckDisabled()) return;
    const s = loadBackupStatus();
    if (!s || s.overall !== 'warn') return;
    const gate = backupNagGate('mcp', s);
    if (!gate.show) return;
    const text = backupNoticeText(s, 'aggregate');
    if (!text) return;
    notices.push({
      code: 'backup_coverage', kind: 'coaching', why: text,
      fix: { argv: ['gbrain', 'backup', 'status'], consent: [], actor: 'user', why: 'Lists each asset without a git remote and its fix command.', requires_exclusive: false },
    });
    backupNoticeShown = true;
    gate.record();
  } catch {
    /* never break dispatch over a notice */
  }
}

export interface ToolResult {
  content: { type: 'text'; text: string }[];
  isError?: boolean;
  /**
   * v0.31 (eD3): MCP spec-blessed metadata slot for server-supplied data.
   * The dispatcher injects `_meta.brain_hot_memory` here when an op succeeds
   * and the configured `metaHook` returns a payload.
   *
   * Structured data for programmatic consumers only: MCP hosts generally do
   * NOT show `_meta` to the model, so anything the agent must act on also
   * rides a model-visible channel (the notice blocks; agent contract v1).
   * NOT a wrapper around the result body — `content` stays the same shape it
   * always had. Best-effort: any error in the meta hook is absorbed and the
   * tool call still succeeds.
   */
  _meta?: Record<string, unknown>;
  /** GST-359 C1: set only on refusals of a call that named an attested actor (`{ error: { code, message, reason, fix } }`). */
  structuredContent?: Record<string, unknown>;
}

export interface DispatchOpts {
  /** Wakeshift: the MCP caller as the transport saw it (OperationContext.mcpCaller); never from tool arguments. */
  mcpCaller?: OperationContext['mcpCaller'];
  /** GST-359 C1: the x-qm-actor header the HTTP transport read (a trusted system names the person); stdio never sets it. */
  actor?: ActorChannels;
  /**
   * GBRA-231: the shared-agent audience channels the transport read from the request (the X-Gbrain-On-Behalf-Of
   * header, request-level `_meta`), set by harness code. Never populated from tool arguments, which are refused.
   */
  onBehalfOf?: AudienceChannels;
  /**
   * GBRA-498: the room channels the transport read (the X-Gbrain-Room header, request-level _meta.room), set by harness
   * code. A `room` tool argument is read too, and can only add people (access/room.ts).
   */
  room?: RoomChannels;
  /** GBRA-504: the guest attribution channels the transport read (the X-Gbrain-Guest header, request-level _meta.guest). */
  guest?: GuestChannels;
  /** GBRA-498 (internal): the room this call declared, resolved by dispatchToolCall; never set by a transport. */
  roomDeclaration?: RoomDeclaration;
  /** GBRA-498 (internal): the call named an attested actor, so its answer is never marked for a room. */
  roomAttested?: boolean;
  /** #6696 (A5): set by the trusted transport for the user's own agent calls; never from wire params. */
  admissionOrigin?: OperationContext['admissionOrigin'];
  /** The caller's self-declared agent label (X-Gbrain-Agent-Label), parsed by the transport; recorded only, never authority. */
  agentLabel?: string;
  /** Configuration selected by the resident transport, never populated from wire params. */
  config?: OperationContext['config'];
  /** Defaults to true (remote/untrusted). Local CLI callers (`gbrain call`) pass false. */
  remote?: boolean;
  /** Override the default stderr logger (e.g. CLI uses console.* directly). */
  logger?: OperationContext['logger'];
  /**
   * #1061: transport marker for auth-less remote surfaces. The stdio MCP
   * server passes 'stdio' so identity ops (whoami) can report the transport
   * instead of throwing unknown_transport. Never used for TRUST decisions
   * (that is `remote`), but it IS the transport-LOCALITY axis: localOnly
   * ops dispatch only when this is 'stdio' (WP1/D7) — HTTP transports pass
   * 'http', and an unset marker is treated as non-local, fail-closed.
   */
  transport?: OperationContext['transport'];
  /** The transport's inbound frame cap (OperationContext.inboundFrameBytes). */
  inboundFrameBytes?: number;
  /**
   * v0.28: per-token allow-list for the takes.holder field. Threaded by
   * the HTTP/stdio transport from `access_tokens.permissions.takes_holders`.
   * When set, takes_list / takes_search / query (when it returns takes)
   * MUST filter `WHERE holder = ANY($takesHoldersAllowList)`. Local CLI
   * callers leave this unset (no filter — they own the brain).
   */
  takesHoldersAllowList?: string[];
  /**
   * v0.31 (eD4): tenancy axis for facts hot memory ops (extract_facts,
   * recall, forget_fact). When set, the OperationContext receives a
   * matching `sourceId`. CLI dispatch resolves this from --source flag /
   * GBRAIN_SOURCE / .gbrain-source / 'default'; HTTP MCP transport
   * resolves it from the per-token allow-list (eE3).
   */
  sourceId?: string;
  /**
   * #3242: federated read set for callers with NO explicit source scope
   * (stdio without GBRAIN_SOURCE; legacy HTTP tokens without an operator-set
   * `permissions.source_id` grant). Transport-computed, never derived from
   * caller params. See OperationContext.localFederatedSourceIds.
   */
  localFederatedSourceIds?: string[];
  /** GBRA-585: the trusted local CLI named no source (OperationContext.localSourceImplicit); ignored unless remote is false. */
  localSourceImplicit?: boolean;
  /**
   * #5081: explicit-read admission for a stdio connection bound by
   * GBRAIN_SOURCE or a .gbrain-source pin. Stdio transport only; see
   * OperationContext.explicitReadBinding.
   */
  explicitReadBinding?: OperationContext['explicitReadBinding'];
  /**
   * `gbrain serve --source-guard` (plugin lanes): when set, write/admin ops
   * are blocked unless the source resolution tier proves the binding is
   * deliberate or unambiguous (see WRITE_SAFE_SOURCE_TIERS in
   * source-resolver.ts). The transport passes the tier that WON the
   * resolution for this call; unset means the guard is off (default —
   * existing serves are untouched). Reads always pass.
   */
  sourceGuardTier?: import('../core/source-resolver.ts').SourceTier;
  /**
   * CX2-11: opaque session identity resolved by the transport (e.g. from the
   * MCP request-level `_meta.session_id`). Clamped to 256 chars before it
   * reaches OperationContext. When unset, buildOperationContext falls back to
   * a `_meta.session_id` carried INSIDE the tool arguments (some clients put
   * it there). Cache/telemetry identity only — never a trust surface.
   */
  sessionId?: string;
  /**
   * GBRA-156: the request asked for no `_meta.brain_hot_memory` block (MCP request-level
   * `_meta.hot_memory: "off"`, resolved by the transport). The same value inside the tool
   * arguments' `_meta` works too. A channel or shared session sets it so a requester's own
   * facts never ride into a reply other people read.
   */
  hotMemoryOff?: boolean;
  /**
   * v0.31 (eD3): hook called by the dispatcher AFTER op.handler succeeds
   * to compute `_meta.brain_hot_memory` for the response. Wrapped in its
   * own try/catch (eE4) so a DB blip in the helper degrades to no _meta
   * rather than flipping the whole tool call to error.
   *
   * Returning undefined means "no _meta to inject"; the dispatcher
   * preserves the existing response shape.
   */
  metaHook?: (
    name: string,
    ctx: OperationContext,
  ) => Promise<Record<string, unknown> | undefined>;
  /**
   * OAuth auth info threaded through from the HTTP MCP transport. Set so
   * the whoami op (and any future scope-aware op handlers) can introspect
   * the calling identity. Without this, every whoami call from HTTP
   * transports throws unknown_transport — the v0.31 D12 / eE1 refactor
   * silently dropped this field when the inlined OperationContext literal
   * was replaced by dispatchToolCall.
   */
  auth?: AuthInfo;
  /** Agent contract v1 (A6): HTTP's per-server notice ledger (ServeHttpContext); stdio uses the process ledger. */
  noticeLedger?: NoticeLedger;
  /**
   * MEMORY_VERBS v1 surface enforcement [c2]. When set, a tool name outside
   * the set returns the unknown_tool envelope BEFORE resolution — fail-closed
   * at the SHARED layer, so a hidden op stays uncallable on every transport
   * even when only the tool LIST was filtered. Unset = full catalog
   * (pre-existing behavior, all current callers).
   */
  allowedOps?: ReadonlySet<string>;
  /**
   * Which surface this transport is serving — recorded on the verb usage
   * sidecar so adoption stats can split quickstart installs from full
   * surfaces. Defaults to 'full'. On the OAuth HTTP transport this is the
   * per-request EFFECTIVE surface (D2 ceiling resolution, recomputed per
   * request — amendment 20).
   */
  surface?: 'verbs' | 'starter' | 'full';
  /**
   * WP4 (D2): the SERVER surface ceiling for this transport (force-clamped),
   * threaded into `OperationContext.surfaceCeiling` for the request_tools
   * meta-op — its catalog never names ops above the ceiling and its persist
   * branch rejects widening past it. Unset (local CLI / direct dispatch) is
   * treated as 'full'.
   */
  surfaceCeiling?: 'verbs' | 'starter' | 'full';
  /** The stdio session surface (OperationContext.stdioSurface); its allow-set is the one `allowedOps` mirrors. */
  stdioSurface?: OperationContext['stdioSurface'];
  /** GST-363: OperationContext.stdioMember, from the stdio server's own argv (serve --stdio-member); no other transport sets it. */
  stdioMember?: string;
  /** GST-2476 G2: an enforced member CLI read (cli/enforced-member.ts): privacy stays hidden whatever the hatches say, and no owner relaxation. */
  enforcedMember?: true;
  /** Threaded into OperationContext.revealTools (stdio session tool reveal). */
  revealTools?: (names: string[]) => void;
  /**
   * D2: whether this connection's tools/list shows a callable tool (the
   * advertised surface can list fewer tools than the callable set). Unset =
   * every callable tool counts as listed.
   */
  isListed?: (op: OperationMeta) => Promise<boolean>;
  /** #5232: commit wait for coordinated writes (OperationContext.writeWaitMs); unset = agent default. */
  writeWaitMs?: number;
  /** PR B: the owner socket answers a write deferred behind a refresh as the write_pending error, so its CLI exits 10 and polls. */
  pendingAsError?: boolean;
  /** Large pages: the caller sent X-Gbrain-Client (OperationContext.thinClient). Shape only, never authority. */
  thinClient?: boolean;
  /** C1: search/query row shape chosen by the transport (OperationContext.resultRows); unset = lean for remote callers. */
  resultRows?: OperationContext['resultRows'];
}

/**
 * Build a privacy-safe summary of MCP request params for logging + the admin
 * SSE feed.
 *
 * The previous default of `JSON.stringify(params)` wrote raw payloads —
 * page bodies, search queries, file paths — into `mcp_request_log` and
 * broadcast them to every connected admin browser. For a personal-knowledge
 * brain those payloads include private notes about real people / deals /
 * companies, retained indefinitely.
 *
 * The redactor returns the SHAPE of the request (what op was called, which
 * declared params were passed, approximate size) without any of the values.
 *
 * Hardening note (codex C8): a naive "dump all submitted keys" summary still
 * leaks via attacker-controlled key names — a caller can submit
 * `put_page {"wiki/people/sensitive_name": "..."}` and the key becomes a
 * persistent log entry. To prevent this, we intersect submitted keys
 * against the operation's declared `params` allow-list (the same definition
 * `validateParams` reads). Anything outside the allow-list is counted but
 * not named.
 *
 * Operators who want full payloads for debugging set `--log-full-params` on
 * `gbrain serve --http`; that path bypasses this helper and writes the raw
 * JSON, with a loud startup warning.
 */
export interface ParamSummary {
  redacted: true;
  kind: 'array' | 'object' | string;
  declared_keys?: string[];
  unknown_key_count?: number;
  length?: number;
  approx_bytes?: number;
}

/**
 * Round a byte count UP to the nearest 1KB so the redacted summary keeps a
 * coarse size signal without enabling a size-based side channel.
 *
 * Why bucketing matters: the previous shape published `approx_bytes` as the
 * exact JSON.stringify(params).length. An attacker who can submit
 * `put_page` with a known prefix and observe the resulting log entry
 * could binary-search the byte length of secret content (the body the
 * legitimate user just wrote) via repeated probes. Bucketing to 1KB
 * resolution destroys that channel while preserving the operator-useful
 * "roughly how large was the request" signal.
 */
function bucketBytes(n: number | undefined): number | undefined {
  if (n === undefined || !Number.isFinite(n)) return undefined;
  if (n <= 0) return 0;
  const KB = 1024;
  return Math.ceil(n / KB) * KB;
}

export function summarizeMcpParams(opName: string, params: unknown): ParamSummary | null {
  if (params == null) return null;

  let approxBytes: number | undefined;
  try { approxBytes = bucketBytes(JSON.stringify(params).length); } catch { approxBytes = undefined; }

  if (Array.isArray(params)) {
    return {
      redacted: true,
      kind: 'array',
      length: params.length,
      ...(approxBytes !== undefined ? { approx_bytes: approxBytes } : {}),
    };
  }

  if (typeof params === 'object') {
    const submittedKeys = Object.keys(params as Record<string, unknown>);
    const op = operations.find(o => o.name === opName);
    const allowList = op ? new Set(Object.keys(op.params)) : new Set<string>();
    const declared: string[] = [];
    let unknown = 0;
    for (const k of submittedKeys) {
      if (allowList.has(k)) declared.push(k);
      else unknown += 1;
    }
    declared.sort();
    return {
      redacted: true,
      kind: 'object',
      declared_keys: declared,
      unknown_key_count: unknown,
      ...(approxBytes !== undefined ? { approx_bytes: approxBytes } : {}),
    };
  }

  return {
    redacted: true,
    kind: typeof params,
    ...(approxBytes !== undefined ? { approx_bytes: approxBytes } : {}),
  };
}

/**
 * Model-visible notices the search/query ops attach to `_meta.retrieval`: the
 * D8 empty-retrieval diagnosis, a reconciled type filter, other names declared in the evidence, and saved
 * facts that match the query, search's keyword count line, the remote page cap line and the row-date label. Each rides as its own text block after the
 * results (content[0] stays the bare result array for thin clients).
 */
export function retrievalNoticeBlocks(result: unknown, retrieval: unknown): string[] {
  if (retrieval === null || typeof retrieval !== 'object') return [];
  const empty = Array.isArray(result) && result.length === 0 ? buildEmptyRetrievalBlock(retrieval) : null;
  const r = retrieval as {
    type_filter_notice?: unknown;
    other_names?: Array<{ name: string; alias: string; slug: string }>;
    saved_facts?: Array<{ fact: string; entity_slug: string | null; valid_from: string; source: string; linked_from?: string; corrected_by?: number; quoted?: string; room_access?: { readable: unknown; reason?: string } }>;
    answer_id?: unknown;
    feedback?: { rateable?: boolean; how_to_rate?: string };
  };
  const blocks: string[] = empty ? [empty] : [];
  if (typeof r.type_filter_notice === 'string') blocks.push(r.type_filter_notice);
  if (r.other_names?.length) {
    const { text, more } = wholeItemsWithin('Other names in these results (documents may use either; search the one you have not tried): ',
      r.other_names.map(n => `${n.alias} = ${n.name} (declared in ${n.slug})`), '; ', OTHER_NAMES_NOTICE_MAX_CHARS);
    blocks.push(`${text}${more ? ` (+${more} more)` : ''}.`);
  }
  if (r.saved_facts?.length) {
    const { text, more } = wholeItemsWithin('Saved facts (remember): about the entity this query names (newest first), then facts those point to, then matches for its words; recall returns more:\n',
      r.saved_facts.map(f => `- ${f.fact}${f.quoted ? '\n' : ''} [entity: ${f.entity_slug ?? 'none'}; saved ${String(f.valid_from).slice(0, 10)}; provenance: ${f.source}${f.linked_from ? `; named in a saved fact about ${f.linked_from}` : ''}${f.corrected_by ? '; corrected by a newer saved fact above' : ''}${f.room_access ? `; room: ${f.room_access.readable === true ? 'readable' : f.room_access.readable === false ? `not readable (${f.room_access.reason})` : `unknown (${f.room_access.reason})`}` : ''}]`),
      '\n', SAVED_FACTS_NOTICE_MAX_CHARS);
    blocks.push(more ? `${text}\n(+${more} more; recall returns them)` : text);
  }
  // F2: which set the rows are and which set the keyword count covers, on every search call.
  const countLine = searchCountLine(result, retrieval);
  if (countLine) blocks.push(countLine);
  const capLine = pageCapLine(retrieval);
  if (capLine) blocks.push(capLine);
  // F4: what each row's effective_date is (document, event or fallback date), never contractual validity.
  const dateLine = dateLabelLine(result);
  if (dateLine) blocks.push(dateLine);
  if (typeof r.answer_id === 'string' && r.feedback?.rateable === true) blocks.push(rateLine(r.answer_id, typeof r.feedback.how_to_rate === 'string'));
  return blocks;
}

/**
 * #6192: the rateable answer's id on the model-visible channel (hosts that
 * show only `content[]` never see `_meta`). Short on every rateable answer;
 * the fuller wording on the answers where the `how_to_rate` cadence fires.
 */
function rateLine(answerId: string, coach: boolean): string {
  const call = `rate_answer { answer_id: "${answerId}", rating: 1-5 }`;
  return (coach ? `Rate this answer after you use it: ${call}. Ratings tune this brain's ranking.` : `Rate after use: ${call}`).slice(0, RATE_LINE_MAX_CHARS);
}

/** C4: character ceilings for the model-visible notice blocks (header included). */
export const SAVED_FACTS_NOTICE_MAX_CHARS = 1_500;
export const OTHER_NAMES_NOTICE_MAX_CHARS = 400;
export const RATE_LINE_MAX_CHARS = 160;

/**
 * Whole items after `head` while the block stays within `max` characters;
 * an item is never cut, so its provenance stays intact. The first item is
 * always shown, even alone over the ceiling. `more` counts the items left out.
 */
function wholeItemsWithin(head: string, items: string[], sep: string, max: number): { text: string; more: number } {
  let text = head + items[0];
  let shown = 1;
  while (shown < items.length && text.length + sep.length + items[shown].length <= max) text += sep + items[shown++];
  return { text, more: items.length - shown };
}

/**
 * D8: render the second (model-visible) content block for an empty retrieval
 * result from the handler-emitted `retrieval` meta. Returns null when the
 * meta doesn't carry the expected shape — the block is best-effort loudness,
 * never a failure source. Reason codes come from the closed degradation
 * vocabulary (D6); raw exception text never reaches this string.
 */
export function buildEmptyRetrievalBlock(retrieval: unknown): string | null {
  if (retrieval === null || typeof retrieval !== 'object') return null;
  const r = retrieval as {
    retrieved_count?: number;
    degraded?: Array<{ stage?: string; reason?: string }>;
    hint?: string;
  };
  const parts: string[] = ['0 results.'];
  if (typeof r.retrieved_count === 'number') parts.push(`retrieved ${r.retrieved_count} before trimming.`);
  // Ranking-only stages (a skipped reranker) cannot cause a miss — the model
  // must not be told recall was impaired when only ordering was.
  const stages = (r.degraded ?? [])
    .filter(affectsRecall)
    .map(d => d?.stage)
    .filter((s): s is string => typeof s === 'string' && s.length > 0);
  parts.push(stages.length > 0
    ? `degraded: ${[...new Set(stages)].join(', ')}.`
    : 'retrieval healthy (no recall-impairing stage). Try the display name, a synonym or hybrid match (the default) before concluding the brain has nothing.');
  if (typeof r.hint === 'string' && r.hint.length > 0) parts.push(`hint: ${r.hint}`);
  return parts.join(' ');
}

/**
 * Amendment 33 / D10 — honest-catalog metric classifier. True when a parsed
 * error envelope is an OP-LEVEL denial the tools/list filter SHOULD have
 * prevented (the same predicates gate list and call time, so in a correct
 * world these trend to zero):
 *   - publish-gate call-time backstop (`detail: 'config_key=...'` — WP1's
 *     machine-readable denial grammar)
 *   - bound-client fence OP-level deny (`detail: 'fence=op'` —
 *     enforceBoundClientOpAllowList; the tools/list filter consumes the
 *     identical predicate, ENG-3)
 *
 * Argument-level fence denials (slug-prefix rejections inside handlers) are
 * legitimate for a LISTED op and deliberately excluded (D10) — they carry no
 * marker. serve-http logs matching rows with status='denied_after_list' so
 * `SELECT count(*) FROM mcp_request_log WHERE status='denied_after_list'`
 * is the wave's trend-to-zero working metric (the scope-deny path in
 * serve-http is the third list-level class; it logs the status directly).
 */
export function isListLevelDenialEnvelope(parsed: unknown): boolean {
  if (parsed === null || typeof parsed !== 'object') return false;
  const p = parsed as { error?: unknown; detail?: unknown };
  if (p.error !== 'permission_denied') return false;
  if (typeof p.detail !== 'string') return false;
  return p.detail.startsWith('config_key=') || p.detail === 'fence=op';
}

/** The mcp_request_log status classes a dispatched tool result maps onto. */
export type RequestLogStatus = 'success' | 'success_with_warnings' | 'accepted_pending' | 'denied_after_list' | 'error';

/** #5249: the receipt of a write the dispatcher returned as accepted but not yet committed. */
export function acceptedPendingReceipt(result: ToolResult): WriteReceipt | null {
  const text = result.content[0]?.text ?? '{}';
  if (!result.isError && !/^\s*\{\s*"status"\s*:\s*"pending"/.test(text.slice(0, 64))) return null;
  try {
    const parsed: unknown = JSON.parse(text);
    return result.isError ? admittedPendingReceipt(parsed) : deferredPendingReceipt(parsed);
  } catch { return null; }
}

/** PR B: the receipt of a successful `status: "pending"` result, a write deferred behind a refresh. */
function deferredPendingReceipt(parsed: unknown): WriteReceipt | null {
  const body = parsed as { status?: unknown; receipt?: unknown } | null;
  return body?.status === 'pending' && isWriteReceipt(body.receipt) ? body.receipt : null;
}

/**
 * PR B (docs/designs/REFRESH_WRITE_BARRIER.md): a write deferred behind a worktree refresh was accepted and publishes after
 * it, so MCP answers it as a pending success instead of an error. Any other `write_pending` stays an error.
 */
export function deferredWriteResult(e: unknown, notices: Notice[], opts: DispatchOpts): ToolResult | null {
  if (opts.pendingAsError || !(e instanceof OperationError) || (e.code !== 'write_pending' && e.writeError !== 'write_pending') || !e.writeRequest?.deferred) return null;
  const receipt = publicWriteReceipt(e.writeRequest);
  return toolResultWithNotices({ status: 'pending', request_id: receipt.request_id, receipt, deferred: e.writeRequest.deferred,
    next: { tool: 'get_write_request', arguments: { request_id: receipt.request_id }, cli: `gbrain write-request ${receipt.request_id}`, retry_after_ms: receipt.retry_after_ms } },
  admitNotices(notices, opts), dispatchRenderContext(opts));
}

/**
 * The ONE `mcp_request_log.status` decision for a dispatched tool result
 * (serve-http's tools/call persistence + SSE broadcast both consume this):
 *   - errors whose envelope is a list-level denial (isListLevelDenialEnvelope
 *     above) → 'denied_after_list' (amendment 33 / D10 trend-to-zero metric);
 *   - `write_pending` carrying a non-terminal receipt → 'accepted_pending'
 *     (#5249: admitted work still in flight, not a failure);
 *     other errors (including unparseable content) → 'error';
 *   - successes whose `_meta.warnings` is a non-empty array →
 *     'success_with_warnings' (WP3 amendment 13 warn-mode observability;
 *     warn CONTENTS are never logged); otherwise → 'success'.
 * The scope-deny and unknown-op paths in serve-http log their statuses
 * directly — they never produce a ToolResult through the dispatcher.
 */
export function requestLogStatusForResult(result: ToolResult): RequestLogStatus {
  if (result.isError) {
    try {
      const parsed: unknown = JSON.parse(result.content[0]?.text ?? '{}');
      if (isListLevelDenialEnvelope(parsed)) return 'denied_after_list';
      if (admittedPendingReceipt(parsed)) return 'accepted_pending';
    } catch { /* unparseable error content stays plain 'error' */ }
    return 'error';
  }
  if (acceptedPendingReceipt(result)) return 'accepted_pending';
  const warnings = result._meta?.warnings;
  return Array.isArray(warnings) && warnings.length > 0 ? 'success_with_warnings' : 'success';
}

/**
 * WP3: the ONE unknown_tool envelope builder, shared by all three deny paths
 * (surface-hidden via allowedOps, nonexistent op, localOnly over a network
 * transport) so they stay byte-identical for the same input name — a hidden
 * op must remain indistinguishable from a nonexistent one.
 *
 * The did-you-mean candidates are the caller's VISIBLE surface only
 * (amendment 11): (allowedOps if set, else the full catalog) MINUS localOnly
 * ops MINUS publish-gated ops. Gated names are excluded unconditionally —
 * gate state is unknown here, and a suggestion naming a hidden/gated op
 * would be the exact existence oracle this envelope exists to prevent.
 */
export function unknownToolEnvelope(name: string, opts: DispatchOpts, legacyError?: 'unknown_operation', notices: Notice[] = []): ToolResult {
  const allowedOps = opts.allowedOps;
  const candidates = operations
    .filter(op => !op.localOnly && !op.publishGateKey && (allowedOps ? allowedOps.has(op.name) : true))
    .map(op => op.name);
  const nearest = suggestNearest(name, candidates);
  const hint = hiddenToolHint(operations.find(o => o.name === name), { ...opts, readOnly: opts.stdioSurface?.readOnly }, toolConnection(opts).canWiden); // F6: owner's stdio pipe only
  const suggestion = hint?.suggestion ?? (nearest
    ? `Did you mean "${nearest}"?`
    : 'List the tools this connection can call (tools/list) and use one of those names.');
  return errorResult(opError('unknown_tool', legacyError ? `Unknown: ${name}` : `Unknown tool: ${name}`, suggestion,
    { ...(legacyError ? { legacy_error: legacyError } : {}), ...(hint ? { fix: hint.fix } : {}) }), opts, { notices: admitNotices(notices, opts) });
}

/**
 * Agent contract v1 render context for a dispatch caller: a fix names an MCP
 * tool only when the same predicate behind tools/list says this caller can
 * call it. Preapprovals never apply over MCP (they are a CLI consent path).
 */
export function dispatchRenderContext(opts: DispatchOpts): RenderContext {
  const transport = opts.transport === 'stdio' ? 'stdio' : opts.remote === false ? 'cli' : 'http';
  const surface = opts.surface ?? 'full';
  const byName = new Map(operations.map(op => [op.name, op]));
  // A1: CLI fixes name the served brain and the request's source (ids only; the HTTP pass strips paths).
  const brain = servedBrainId();
  const routing = { ...(brain ? { brain } : {}), ...(opts.sourceId ? { source: opts.sourceId } : {}) };
  return {
    routing,
    transport,
    surface,
    isCallable: (opName: string) => {
      const op = byName.get(opName);
      return !!op && isCallable(op, {
        transport, surface, scopes: opts.auth?.scopes ?? [], publishGates: {}, allowedOps: opts.allowedOps,
      }) && (transport === 'cli' || opAllowedForBoundClient(opts.auth, op));
    },
    preapproved: () => false,
    ...(opts.auth?.clientId ? { principal: opts.auth.clientId } : {}),
  };
}

/** `gbrain call`'s failure envelope: same normaliser, CLI render context, the op's own effect tags. */
export function localCallErrorEnvelope(tool: string, e: unknown) {
  const op = operations.find(o => o.name === tool);
  return toAgentError(e, {
    transport: 'cli', op: tool, mutating: op?.mutating === true, idempotent: op?.idempotent === true,
    outcome: op?.mutating ? 'unknown' : 'failed', render: cliRenderContext(),
    db: { url: configuredDbUrlForClassify(), brainId: brainIdForClassify() },
  });
}

/**
 * A6 dedupe/budget/mute: the stdio ledger is per process; HTTP passes its
 * ServeHttpContext ledger. Session identity is the transport-resolved id only.
 * Fail-open: a ledger fault delivers every notice.
 */
function noticeAudience(opts: DispatchOpts): NoticeAudience {
  return { transport: opts.transport === 'stdio' ? 'stdio' : opts.remote === false ? 'cli' : 'http', principal: opts.auth?.clientId, sessionId: opts.sessionId };
}

export function admitNotices(notices: Notice[], opts: DispatchOpts): Notice[] {
  if (notices.length === 0) return notices;
  try {
    const audience = noticeAudience(opts);
    return (opts.noticeLedger ?? processNoticeLedger()).admit(notices, audience,
      mutedNoticeCodes(audience.principal ?? (audience.transport === 'stdio' ? 'stdio' : undefined)));
  } catch {
    return notices;
  }
}

/**
 * The hidden-tool route inputs for one dispatch caller (F6 and D2 share
 * them): stdio widens its own session when widening is on; an HTTP OAuth
 * client widens its own surface up to the server ceiling unless the brain
 * owner pinned it; the grant (scopes, snapshot, fence) bounds both.
 */
export function toolConnection(opts: DispatchOpts): ToolConnection {
  const render = dispatchRenderContext(opts);
  const http = render.transport === 'http';
  const auth = opts.auth;
  return {
    transport: render.transport,
    surface: opts.surface ?? 'full',
    readOnly: opts.stdioSurface?.readOnly,
    ceiling: http ? opts.surfaceCeiling ?? opts.surface ?? 'full' : 'full',
    canWiden: render.isCallable('request_tools') && (http
      ? auth?.principal?.kind === 'oauth_client' && auth.surfaceSetBy !== 'operator'
      : opts.stdioSurface?.widenAllowed !== false),
    isCallable: render.isCallable,
    grantAllows: op => opAllowedForBoundClient(auth, op) && (!http || operationScopesAllowed(auth?.scopes ?? [], op)),
  };
}

/** Reads whose result never shows the takes table to an agent-facing reader. */
const HIDDEN_TAKES_OPS: ReadonlySet<string> = new Set(['get_page', 'search', 'query']);

/**
 * D2 `hidden_tool_content`: a page read or search that left out takes says
 * so, with the next step this connection can actually take (the
 * hidden-tool route): call takes_list (stdio also lists it), widen with
 * request_tools, or the brain owner's repair. Silent when takes_list is
 * already in this connection's tool list. Never throws.
 */
async function hiddenContentNotices(engine: BrainEngine, name: string, result: unknown, ctx: OperationContext, opts: DispatchOpts): Promise<Notice[]> {
  if (opts.remote === false || !HIDDEN_TAKES_OPS.has(name)) return [];
  try {
    const op = operations.find(o => o.name === 'takes_list');
    const conn = toolConnection(opts);
    const route = hiddenToolRoute(op, conn);
    if (!op || !route) return [];
    if (route.kind === 'callable' && (!opts.isListed || await opts.isListed(op))) return [];
    const { takesHiddenFromResult } = await import('../core/ops/takes.ts');
    const hidden = await takesHiddenFromResult(ctx, name, result);
    if (!hidden) return [];
    const host = route.kind === 'host' && conn.transport === 'http' && opts.auth
      ? (await import('../core/harness/capabilities.ts')).grantRepairAction(await sessionGrantDiagnosis(engine, opts)) : null;
    const what = `the takes on ${hidden.pages[0]}`;
    const fix = hiddenToolNext(op, { tool: op.name, arguments: { page_slug: hidden.pages[0] } }, route, conn, what, host);
    if (route.kind === 'callable') opts.revealTools?.([op.name]);
    return [hiddenTakesNotice(hidden, route.kind, fix)];
  } catch {
    return [];
  }
}

/**
 * GST-2353: a refusal safe to retry carries the call to repeat (next: wait) in the id parameter the tool takes: its
 * request_id with the id it was refused under, or the same arguments when the tool replays by its idempotency_key.
 */
function attachRetryCall(op: Pick<Operation, 'mutating' | 'params'>, name: string, params: Record<string, unknown>, e: unknown): void {
  if (!op.mutating || !(e instanceof OperationError) || e.retryable !== true || !e.fix || e.fix.mcp) return;
  const retry = op.params.request_id ? (e.requestId ? { ...params, request_id: e.requestId } : null)
    : op.params.idempotency_key && typeof params.idempotency_key === 'string' ? params : null;
  if (retry) e.fix = { ...e.fix, mcp: { tool: name, arguments: retry } };
}

/** A refusal a grant explains: a missing scope or an operation outside the grant's snapshot or fence. */
function refusedByGrant(e: unknown): boolean {
  return e instanceof OperationError && (e.code === 'insufficient_scope' || e.code === 'permission_denied');
}

/**
 * D4 `grant_blocked_operations` on the connection's own authenticated path:
 * the shared capabilities resolver diagnoses the verifier's principal
 * (never a display name) and the notice reaches it once per (principal,
 * transport session); a stateless call with no session id counts once per
 * (principal, grant revision), so three stateless calls get one notice and a
 * rescoped grant is diagnosed afresh. A missing scope is reported only on a
 * refused call. Never throws; a failure delivers nothing.
 */
export async function grantBlockedNotices(engine: BrainEngine, opts: DispatchOpts, refused: boolean): Promise<Notice[]> {
  const auth = opts.auth;
  const principal = auth?.principal;
  if (!auth || !principal || opts.remote === false) return [];
  try {
    const { grantBlockedNotice } = await import('../core/harness/capabilities.ts');
    const notice = grantBlockedNotice(await sessionGrantDiagnosis(engine, opts), { refused });
    return notice && (opts.noticeLedger ?? processNoticeLedger()).claim(`grant_blocked_operations|${grantSessionKey(auth, principal, opts.sessionId)}`) ? [notice] : [];
  } catch {
    return [];
  }
}

/** The D4 session: (principal, transport session), or (principal, grant revision) for a stateless call. */
function grantSessionKey(auth: AuthInfo, principal: NonNullable<AuthInfo['principal']>, sessionId: string | undefined): string {
  const revision = Number.isSafeInteger(auth.grantRevision) ? String(auth.grantRevision) : 'none';
  return `${principal.kind}:${principal.id}|${sessionId ? `session:${sessionId.slice(0, SESSION_ID_MAX_CHARS)}` : `revision:${revision}`}`;
}

/** The shared capabilities resolver's diagnosis for this caller, computed once per D4 session and grant revision. */
async function sessionGrantDiagnosis(engine: BrainEngine, opts: DispatchOpts) {
  const auth = opts.auth!;
  const { resolveGrantDiagnosis } = await import('../core/harness/capabilities.ts');
  const revision = Number.isSafeInteger(auth.grantRevision) ? String(auth.grantRevision) : 'none';
  const compute = () => resolveGrantDiagnosis(auth, engine, opts.config ?? loadConfig() ?? { engine: 'postgres' }, { surfaceCeiling: opts.surfaceCeiling });
  if (!auth.principal) return compute();
  return (opts.noticeLedger ?? processNoticeLedger()).memoize(`grant_diagnosis|${grantSessionKey(auth, auth.principal, opts.sessionId)}|${revision}`, compute);
}

/**
 * Cat 40 R0: a search/query whose reranker failed counts toward this
 * session's reranker-degraded calls, and its own `_meta.retrieval` records
 * the reason, the fallback and that count (no `fields: "full"` needed).
 * Returns the session count, or undefined when the reranker did not fail.
 */
function recordRerankDegradation(responseMeta: Record<string, unknown>, opts: DispatchOpts): number | undefined {
  try {
    const retrieval = responseMeta.retrieval as { degraded?: Array<{ stage?: string; reason?: string }> } | undefined;
    const failed = retrieval?.degraded?.find(d => d.stage === 'rerank_failed');
    if (!retrieval || !failed) return undefined;
    const calls = (opts.noticeLedger ?? processNoticeLedger()).tally(noticeAudience(opts), 'rerank_failed');
    responseMeta.retrieval = { ...retrieval, rerank_degraded: { reason: failed.reason ?? 'provider_error', fallback: 'fused_order', calls_this_session: calls } };
    return calls;
  } catch {
    return undefined;
  }
}

/**
 * The one-time `behavior_changes` disclosure (stdio: once per brain; HTTP:
 * once per authenticated client, remote view) and the first
 * `chat_fallback_hop` of this process (stdio only: it names models). Rides
 * success and failure results alike. Never throws.
 */
async function sessionSafetyNotices(engine: BrainEngine, opts: DispatchOpts, config: OperationContext['config']): Promise<Notice[]> {
  const out: Notice[] = [];
  try {
    if (opts.transport === 'stdio' && opts.remote !== false) {
      const behavior = await takeLocalBehaviorNotice(engine, 'stdio', { cfg: config ?? null });
      if (behavior) out.push(behavior);
      out.push(...takeChatFallbackHopNotices());
    } else if (opts.transport === 'http') {
      const behavior = await takeHttpBehaviorNotice(engine, opts.auth?.clientId, { cfg: config ?? null });
      if (behavior) out.push(behavior);
    }
  } catch { /* a notice never breaks a tool call */ }
  return out;
}

/**
 * Merges the handler-emitted response meta into a success result, then the GBRA-200 degraded stamp:
 * `_meta.degraded` and one text block after every other block. The stamp is derived from every notice
 * the call produced, before dedupe, so it rides every degraded call.
 */
function attachResponseMeta(out: ToolResult, responseMeta: Record<string, unknown>, stamp: DegradedStamp | null): void {
  if (Object.keys(responseMeta).length > 0) out._meta = { ...(out._meta ?? {}), ...responseMeta };
  if (!stamp) return;
  out.content.push({ type: 'text', text: degradedStampLine(stamp) });
  out._meta = { ...(out._meta ?? {}), degraded: stamp };
}

type ToolTail = Parameters<NonNullable<OperationContext['emitToolTail']>>[0];

/**
 * Wakeshift's addition: its text (at most 2,000 characters) as the LAST text block, its meta merged into `_meta`
 * under gbrain's own keys, which it never replaces (a conversation credential: never logged).
 */
function appendToolTail(out: ToolResult, tail: ToolTail): void {
  if (tail.text) out.content.push({ type: 'text', text: tail.text.slice(0, 16_000) });
  if (tail.meta && typeof tail.meta === 'object') out._meta = { ...tail.meta, ...(out._meta ?? {}) };
}

/** The one error result path: toAgentError → exactly one content block. */
export function errorResult(e: unknown, opts: DispatchOpts, extra: { op?: string; mutating?: boolean; idempotent?: boolean; notices?: Notice[] } = {}): ToolResult {
  const carried = !!extra.notices?.length && e instanceof OperationError;
  if (carried) e.notices = [...(e.notices ?? []), ...extra.notices!];
  const render = dispatchRenderContext(opts);
  const envelope = toAgentError(e, {
    transport: render.transport, op: extra.op, mutating: extra.mutating, idempotent: extra.idempotent,
    outcome: extra.mutating ? 'unknown' : 'failed', render,
    db: { url: configuredDbUrlForClassify(), brainId: brainIdForClassify() },
  });
  if (!extra.notices?.length || carried) return toolErrorResult(envelope);
  // Any other throw (a plain Error, a DB fault) still carries the notices the call collected (A6: one block, `notices` key).
  const { contract_version, ...rest } = envelope;
  const added = extra.notices.map(n => redactForTransport(renderNotice(n, render), render.transport));
  return toolErrorResult({ ...rest, notices: orderNotices([...(envelope.notices ?? []), ...added]), contract_version });
}

/**
 * GST-1054: SkillOpt's tool loops hand the model a thrown error's message, so their read handlers throw this: the
 * error text an MCP caller reads for the same failed read (code, message, suggestion, fix), with `code` kept for
 * callers that branch on it. It renders for the caller's grant (a read-scope reader when the loop has none) and the
 * loop's own tools, so a fix names a tool call the model can make. An AI invocation policy stop passes through
 * unchanged, because the loop rethrows it.
 */
export function asAgentToolError(e: unknown, op: string, ctx: Pick<OperationContext, 'sourceId' | 'auth'>, allowedOps: ReadonlySet<string>): unknown {
  if (isAIInvocationPolicyError(e)) return e;
  const auth: AuthInfo = ctx.auth ?? { token: '', clientId: '', scopes: ['read'] };
  const text = errorResult(e, { remote: true, transport: 'http', sourceId: ctx.sourceId, auth, allowedOps }, { op, mutating: false, idempotent: true }).content[0]!.text;
  const err: Error & { code?: string } = new Error(text);
  err.code = (JSON.parse(text) as { code?: string }).code;
  return err;
}

const stderrLogger: OperationContext['logger'] = {
  info: (msg: string) => process.stderr.write(`[info] ${msg}\n`),
  warn: (msg: string) => process.stderr.write(`[warn] ${msg}\n`),
  error: (msg: string) => process.stderr.write(`[error] ${msg}\n`),
};

/** CX2-11: clamp an opaque session id to 256 chars (cache-key hygiene). */
const SESSION_ID_MAX_CHARS = 256;

/**
 * CX2-11: the request-level session — MCP carries `_meta.session_id` as a sibling of `arguments` in
 * `request.params`. Every transport threads it the same way, so a fact `remember`s the session over
 * HTTP exactly as over stdio. Non-string / empty values are ignored; dispatch clamps the length.
 */
export function requestMetaSessionId(requestParams: unknown): string | undefined {
  const raw = (requestParams as { _meta?: { session_id?: unknown } } | undefined)?._meta?.session_id;
  return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
}

/** GBRA-156: `_meta.hot_memory: "off"` on the request (pass `request.params`) or inside the tool arguments (pass the arguments). */
export function hotMemoryOffIn(params: unknown): boolean {
  return (params as { _meta?: { hot_memory?: unknown } } | undefined)?._meta?.hot_memory === 'off';
}

/**
 * Read `_meta.session_id` out of the tool arguments when present. The MCP
 * spec carries `_meta` as a sibling of `arguments`, but several clients (and
 * proxies) fold it into the arguments object — this is the dispatch-level
 * fallback for those. Non-string / empty values are ignored.
 */
function metaSessionIdFrom(params: Record<string, unknown>): string | undefined {
  const meta = params._meta;
  if (meta && typeof meta === 'object' && !Array.isArray(meta)) {
    const sid = (meta as Record<string, unknown>).session_id;
    if (typeof sid === 'string' && sid.length > 0) return sid.slice(0, SESSION_ID_MAX_CHARS);
  }
  return undefined;
}

export function buildOperationContext(
  engine: BrainEngine,
  params: Record<string, unknown>,
  opts: DispatchOpts = {},
): OperationContext {
  // CX2-11: transport-resolved session id wins; arguments-level _meta is the
  // fallback. Both clamped. Typed field — the meta-hook cache key reads it.
  const sessionId =
    (typeof opts.sessionId === 'string' && opts.sessionId.length > 0
      ? opts.sessionId.slice(0, SESSION_ID_MAX_CHARS)
      : undefined) ?? metaSessionIdFrom(params);
  let render: RenderContext | undefined;
  return {
    engine,
    config: opts.config ?? loadConfig() ?? { engine: 'postgres' },
    logger: opts.logger || stderrLogger,
    dryRun: !!params.dry_run,
    remote: opts.remote ?? true,
    transport: opts.transport,
    ...(opts.inboundFrameBytes !== undefined ? { inboundFrameBytes: opts.inboundFrameBytes } : {}),
    takesHoldersAllowList: opts.takesHoldersAllowList,
    // v0.34 D4: sourceId is REQUIRED at the type level. Auto-fill 'default'
    // for single-source brains and any caller who didn't resolve a sourceId.
    // CLI / HTTP / stdio transports SHOULD pass an explicit sourceId via opts;
    // this fallback covers code paths that historically passed undefined.
    sourceId: opts.sourceId ?? 'default',
    ...(sessionId ? { sessionId } : {}),
    ...(opts.localFederatedSourceIds ? { localFederatedSourceIds: opts.localFederatedSourceIds } : {}),
    ...(opts.localSourceImplicit && opts.remote === false ? { localSourceImplicit: true } : {}),
    ...(opts.explicitReadBinding ? { explicitReadBinding: opts.explicitReadBinding } : {}),
    ...(opts.surfaceCeiling ? { surfaceCeiling: opts.surfaceCeiling } : {}),
    ...(opts.stdioSurface ? { stdioSurface: opts.stdioSurface } : {}),
    ...(opts.stdioMember !== undefined && opts.transport === 'stdio' && !opts.auth ? { stdioMember: opts.stdioMember } : {}),
    ...(opts.guest && opts.remote !== false ? { guestChannels: opts.guest } : {}),
    ...(opts.revealTools ? { revealTools: opts.revealTools } : {}),
    ...(opts.writeWaitMs !== undefined ? { writeWaitMs: opts.writeWaitMs } : {}),
    ...(opts.admissionOrigin ? { admissionOrigin: opts.admissionOrigin } : {}),
    ...(opts.agentLabel ? { agentLabel: opts.agentLabel } : {}),
    ...(opts.resultRows ? { resultRows: opts.resultRows } : {}),
    ...(opts.thinClient ? { thinClient: true } : {}),
    ...(opts.mcpCaller ? { mcpCaller: opts.mcpCaller } : {}),
    isCallable: (opName: string) => (render ??= dispatchRenderContext(opts)).isCallable(opName),
    auth: opts.auth,
  };
}

const WORLD_ONLY_PACK_OPS = new Set(['context_pack', 'delta']);

/**
 * Resolve operation, validate params, build context, invoke handler, format result.
 *
 * Returns a `ToolResult` with the same shape both MCP transports need:
 * `{ content: [{ type: 'text', text }], isError?: boolean }`.
 */
export async function dispatchToolCall(
  engine: BrainEngine,
  name: string,
  params: Record<string, unknown> | undefined,
  opts: DispatchOpts = {},
): Promise<ToolResult> {
  // #6721: a read op answers every config read from one snapshot of the table
  // (config-snapshot.ts); a write reads config live, so it sees its own writes.
  // GBRA-156: and reads the brain identity and each local writer's credential once for its pre-submission checks.
  // GBRA-156: a remote read sees private pages only in the sources its grant names under private_pages: granted_sources; GBRA-575: private facts under private_facts, only on a credential's own read (no audience, actor, scope read or enforced member).
  // Writes, local callers and every path outside this call keep the empty set, so they hide or see exactly what they did.
  // context_pack and delta stay world-only for every caller unless a trusted local one passes include_private, so no grant widens them.
  // GBRA-498: a room declaration only marks the answer; its argument is taken out here, before any validation,
  // handler, cache, retry call or stored write intent sees it, and a trusted local caller's is ignored.
  const roomRead = readRoomDeclaration(opts.remote === false ? undefined : opts.room, params);
  params = roomRead.args;
  const roomDeclaration = opts.remote === false ? undefined : roomRead.declaration ?? undefined;
  const op = operations.find(o => o.name === name);
  const readOnly = op?.mutating === false;
  const args = op && params ? normalizeOptionalParams(op, params) : params;
  const [privateSources, privateFactSources] = readOnly && opts.remote !== false && !WORLD_ONLY_PACK_OPS.has(name) ? [opts.auth?.privatePages?.sources, opts.auth?.privateFacts?.sources] : [];
  const resolved = opts.metaHook && (opts.hotMemoryOff === true || hotMemoryOffIn(params)) ? { ...opts, metaHook: undefined } : opts;
  // GBRA-218: a remote call also carries its credential's member identity, which every caller-aware read checks page readers against.
  // GBRA-231: or the audience a shared agent's harness asserts, resolved (and refused) on every call before any work.
  const run = async () => {
    if (opts.remote === false) return qmMemoryToolResult(name, await withCallerAccess({ privateReadableSources: [], privateFactSources: [] }, () => withRequestIdentityMemo(() => dispatchResolvedCall(engine, name, params, resolved))));
    // GST-359 C1: or the person a trusted system attests (x-qm-actor), decided here too, before any work (access/actor.ts).
    let audience: AudiencePrincipal[] | null = null;
    let attested: Awaited<ReturnType<typeof resolveAttestedActor>> = null;
    let access: Awaited<ReturnType<typeof remoteCallerAccess>>;
    let readMode: ReadMode | null = null;
    let scoped = resolved;
    let scopeNotice: RequesterScopeNotice | null = null;
    const header = opts.actor?.header ?? undefined;
    const actorNamed = header !== undefined || opts.actor?.audience != null || (!!args && Object.prototype.hasOwnProperty.call(args, ACTOR_ARGUMENT));
    const assertion = (outcome: AudienceAuditEvent['outcome'], reason?: string) => logAudienceAssertion({ outcome, op: name,
      audience: [...(attested?.access?.audience ?? audience ?? [])], transport: opts.transport ?? 'unknown',
      principal: opts.auth?.principal ? `${opts.auth.principal.kind}:${opts.auth.principal.id}` : opts.transport === 'stdio' ? 'local_stdio' : 'unknown',
      ...(actorNamed ? { actor: { system: 'qm', ...(header && EXTERNAL_ID_RE.test(header) ? { external_id: header } : {}), ...(reason ? { reason } : {}) } } : {}) });
    try {
      if (audienceInArguments(args)) throw audienceInArgumentsError();
      audience = parseAudience(opts.onBehalfOf);
      attested = await resolveAttestedActor(engine, { channels: opts.actor, params: args, op: name, opShape: op,
        auth: opts.auth, transport: opts.transport, audienceAsserted: audience !== null });
      // GST-1158 E1: an attested read that names sources reads as the scope (access/scope-read.ts), or as the person on an attest_read person credential.
      readMode = attested?.actor ? attestedReadMode(name, attested.params, attested.read) : null;
      if (readMode === 'scope' && attested?.access?.labelledOnly) throw scopeReadLabelledOnlyRefused(name);
      access = readMode === 'scope' ? await scopeReadAccess(engine) : attested?.access ?? await remoteCallerAccess(engine, opts.auth, privateSources, opts.transport, audience, opts.transport === 'stdio' && !opts.auth ? opts.stdioMember : undefined, readOnly);
      // GBRA-284: an attested call reads its grant minus other members' personal sources, a scope read minus every personal source (access/member-sources.ts).
      if (attested?.actor) scoped = await attestedReadScope(engine, resolved, attested.actor.member, readMode === 'scope');
      if (roomDeclaration) scoped = { ...scoped, roomDeclaration, roomAttested: !!attested?.actor };
      if (opts.enforcedMember) access = { ...access, hidePrivate: true, owner: false, privateReadableSources: [] };
      // GST-363: on a brain that serves several people, a read from a connection bound to nobody is refused (or, in its grace, noticed) before any work.
      // An op this connection cannot reach (hidden by its surface, localOnly off stdio, or cliOnly over MCP) keeps its own refusal instead.
      const reachable = !!op && (!opts.allowedOps || opts.allowedOps.has(name)) && (!op.localOnly || opts.transport === 'stdio') && !op.cliOnly;
      try {
        if (!attested?.actor && reachable && requiresRequesterScope(op, opts.auth)) {
          const credential = opts.auth ? await credentialScopeFor(engine, opts.auth) : undefined;
          access = await withServesReread(engine, access, credential);
          scopeNotice = requesterScopeGate(op, access, credential, opts.transport);
        } else if (!attested?.actor && reachable && scoped.metaHook) {
          // GST-363: the ops the gate lets through (exempt reads, writes) carry no hot memory to a connection whose reads it refuses.
          const credential = opts.auth ? await credentialScopeFor(engine, opts.auth) : undefined;
          if (requesterScopeRefuses(await withServesReread(engine, access, credential), credential, opts.transport)) scoped = { ...scoped, metaHook: undefined };
        }
      } catch (dbFailure) {
        // The serves re-read met a database that is unreachable or missing its schema: its own envelope, nothing read.
        if (dbFailure instanceof OperationError) throw dbFailure;
        return errorResult(dbFailure, opts, { op: name });
      }
    } catch (thrown) {
      const e = identityLookupUnavailable(thrown) ?? thrown;
      // GST-359: a call that names a person gets every failure here (a lock timeout reading its link included) in the
      // envelope QM reads, never a thrown call; a coded refusal (access_identity_unavailable) is an error result, before
      // anything is admitted; anything else keeps the caller's own error path.
      if (!(e instanceof OperationError) || !/^(on_behalf_of_|actor_|requester_scope_(required|unknown)$)/.test(String(e.code))) {
        if (actorNamed) return withStructuredError(errorResult(e, opts, { op: name }));
        if (e instanceof OperationError) return errorResult(e, opts, { op: name });
        throw e;
      }
      assertion(e.code as AudienceAuditEvent['outcome'], e.reason);
      if (e.code === 'requester_scope_required' || e.code === 'requester_scope_unknown') return qmMemoryToolResult(name, withStructuredError(errorResult(e, opts, { op: name })));
      return qmMemoryToolResult(name, actorNamed ? actorRefusal(e, opts, name, header, args) : errorResult(e, opts, { op: name }));
    }
    if (audience || attested?.actor) assertion('accepted');
    const callParams = attested ? attested.params : args;
    return withCallerAccess({ ...access, privateFactSources: privateFactSources && !audience && !attested?.actor && readMode === null && !opts.enforcedMember ? privateFactSources : [] }, async () => {
      const out = await withRequestIdentityMemo(() => withReadMode(readMode, () => dispatchResolvedCall(engine, name, callParams, scoped)));
      // _meta.access (MCP_META_CHANNELS.md): the view this call was answered under, for the harness; own producer, isolated.
      try { out._meta = { ...(out._meta ?? {}), access: await appliedAccessSummary(engine, scoped.auth, [scoped.sourceId, ...(scoped.localFederatedSourceIds ?? [])]) }; } catch { /* the key is absent */ }
      if (scopeNotice) {
        const applied = (out._meta?.access ?? {}) as Record<string, unknown>;
        out._meta = { ...(out._meta ?? {}), access: { ...applied, requester_scope: { ...scopeNotice, fix: renderAction(scopeNotice.fix, dispatchRenderContext(opts)) } } };
      }
      const personal = !!attested?.actor;
      const shaped = qmMemoryToolResult(name, out, personal);
      // GST-1158 F2: a personal read's structuredContent repeats its JSON, so the final frame is measured again.
      if (!personal || shaped === out || shaped.isError || !QM_PERSONAL_OPS.has(name) || op?.mutating !== false) return shaped;
      const over = await frameOverCap(shaped, { remote: true, transport: opts.transport === 'stdio' ? 'stdio' : 'http', engine, config: opts.config ?? loadConfig() });
      return over ? qmMemoryToolResult(name, errorResult(resultTooLargeError(name, callParams ?? {}, over), opts, { op: name, mutating: false, idempotent: op.idempotent === true }), true) : shaped;
    });
  };
  if (name === 'search' || name === 'query') return withSearchConnectionBudget(() => withRequestConfigSnapshot(engine, run));
  return readOnly
    ? withRequestConfigSnapshot(engine, run)
    : withoutRequestConfigSnapshot(run);
}

/**
 * GST-359 C1: the refusal of a call that named an attested actor: gbrain's envelope (top-level `code` in the JSON text
 * block) plus `structuredContent.error`, both of which QM reads. The single seam where memory_recall answers
 * actor_unlinked as a success instead (GST-359 D): empty content and structuredContent {facts: [], truncated: false,
 * code: 'actor_unlinked'}, the code also in `_meta.access`, so a person not yet linked reads nothing and QM's turn goes on.
 */
function actorRefusal(e: OperationError, opts: DispatchOpts, op: string, header: string | undefined, params: Record<string, unknown> | undefined): ToolResult {
  if (op === 'memory_recall' && e.code === 'actor_unlinked') {
    try { recallArguments(params); } catch (invalid) { if (invalid instanceof OperationError) return actorRefusal(invalid, opts, op, header, params); throw invalid; }
    return { ...unlinkedRecallResult(), _meta: { access: { code: 'actor_unlinked', member: null, groups: [], audience: null, actor: { system: 'qm', external_id: header } } } };
  }
  return withStructuredError(errorResult(e, opts, { op }));
}

/** An error result with its JSON envelope's code, message, reason, detail and fix also in `structuredContent.error`, which QM reads. */
function withStructuredError(out: ToolResult): ToolResult {
  try {
    const env = JSON.parse(out.content[0]!.text) as Record<string, unknown>;
    out.structuredContent = { error: { code: env.code, message: env.message, ...(env.reason ? { reason: env.reason } : {}), ...(env.detail ? { detail: env.detail } : {}), ...(env.fix ? { fix: env.fix } : {}) } };
  } catch { /* the text block still carries the code */ }
  return out;
}

/**
 * GST-359 D: the refusal both HTTP transports give a request carrying x-qm-audience (a channel audience gbrain does
 * not serve yet), before any work: the tools/call result (with structuredContent.error) and the JSON-RPC error for
 * every other method that would read (tools/list, resources).
 */
export function audienceRefusal(op: string, opts: Pick<DispatchOpts, 'auth' | 'transport'>): { result: ToolResult; rpc: { code: number; message: string; data: Record<string, unknown> } } {
  const e = actorNotAttested('audience_not_supported', { auth: opts.auth }, { op, transport: opts.transport });
  return { result: actorRefusal(e, { remote: true, ...opts }, op, undefined, undefined),
    rpc: { code: -32600, message: `actor_not_attested: ${e.message}`, data: { code: 'actor_not_attested', reason: 'audience_not_supported', message: e.message } } };
}

/** The response-meta hook's keys, or its failure message; never rejects (a hook failure degrades to no keys). */
// The hot-memory hook reads ctx.sourceId only, so a call that names its own sources gets no ambient-source payload.
function namesOwnSources(params: Record<string, unknown>, sourceId: string | undefined): boolean {
  const ids = params.source_ids;
  if (Array.isArray(ids) ? ids.length > 0 : typeof ids === 'string' && ids.trim() !== '') return true;
  return typeof params.source_id === 'string' && params.source_id !== '' && params.source_id !== sourceId;
}

async function runMetaHook(hook: NonNullable<DispatchOpts['metaHook']>, name: string, ctx: OperationContext): Promise<{ meta?: Record<string, unknown>; failure?: string }> {
  try { return { meta: await hook(name, ctx) }; }
  catch (metaErr) { return { failure: metaErr instanceof Error ? metaErr.message : String(metaErr) }; }
}

/**
 * GBRA-498: an answer going into a room is marked for it on a detached copy (hot memory too, so the hook runs first),
 * before the notices, the degraded stamp and the frame are built. Marking never fails the call.
 */
async function markForRoom(engine: BrainEngine, opts: DispatchOpts, name: string, result: unknown, retrieval: unknown, ctx: OperationContext, hook: ReturnType<typeof runMetaHook> | undefined) {
  const hookOut = hook ? await hook : undefined;
  const room = await assessRoom(engine, { op: name, result, hotMemory: hookOut?.meta, retrieval, declaration: opts.roomDeclaration!, sourceId: ctx.sourceId,
    caller: { access: currentCallerAccess(), auth: ctx.auth, transport: ctx.transport, stdioMember: opts.stdioMember, attested: opts.roomAttested } });
  return { hookOut, room: room as Awaited<ReturnType<typeof assessRoom>> | null };
}

/**
 * GBRA-498: room marks never cost a read. Over the cap, the unmarked answer goes out with the room_hints_unavailable
 * notice (reason response_cap) and a one-key _meta.room note, then with the notice alone, then bare.
 */
async function roomCapFallback(build: (meta: Record<string, unknown>, extra: Notice[]) => ToolResult, cap: (built: ToolResult) => Promise<unknown>, responseMeta: Record<string, unknown>): Promise<ToolResult | null> {
  const note = [roomResponseCapNotice()];
  const tries: Array<[Record<string, unknown>, Notice[]]> = [[{ ...responseMeta, room: { complete: false, unavailable: 'response_cap' } }, note], [responseMeta, note], [responseMeta, []]];
  for (const [meta, extra] of tries) {
    const fallback = build(meta, extra);
    if (!await cap(fallback)) return fallback;
  }
  return null;
}

function assembleToolResult(
  call: { name: string; result: unknown; batchError: boolean; evidence: (retrieval: unknown) => string[]; tail: ToolTail | undefined; opts: DispatchOpts },
  body: unknown, shown: Notice[], stamped: Notice[], meta: Record<string, unknown>, hook: Record<string, unknown> | undefined,
): ToolResult {
  const built: ToolResult = call.batchError ? toolErrorResult(body as never) : toolResultWithNotices(body, shown, dispatchRenderContext(call.opts));
  const evidenceBlocks = call.evidence(meta.retrieval);
  if (evidenceBlocks.length > 0) built.content.splice(1, 0, ...evidenceBlocks.map(text => ({ type: 'text' as const, text })));
  // _meta assembly (WP2 amendment 9): one producer per top-level key,
  // each isolated — handler-emitted keys (retrieval, warnings) attach
  // BEFORE and independently of the metaHook, so a hot-memory hook
  // failure can never drop the retrieval channel. Per-key merge, never
  // wholesale assignment. See docs/protocol/MCP_META_CHANNELS.md.
  attachResponseMeta(built, meta, degradedStampFor(call.name, call.result, meta, stamped)); if (call.tail) appendToolTail(built, call.tail);
  if (hook && Object.keys(hook).length > 0) built._meta = { ...(built._meta ?? {}), ...hook };
  return built;
}

async function dispatchResolvedCall(
  engine: BrainEngine,
  name: string,
  params: Record<string, unknown> | undefined,
  opts: DispatchOpts,
): Promise<ToolResult> {
  const startedMs = Date.now();
  const isVerb = VERB_NAME_SET.has(name);
  // [c11] dispatch-layer usage sidecar for the five verbs — counts validation
  // failures too. Fire-and-forget; never awaited, never throws.
  const logVerb = (ok: boolean, extra?: { budget_dropped?: number; entity_found?: boolean; remember_status?: string; records_firing?: RecordsFiring }) => {
    if (!isVerb) return;
    logVerbUsage({
      verb: name,
      surface: opts.surface ?? 'full',
      remote: opts.remote ?? true,
      ok,
      latency_ms: Date.now() - startedMs,
      source_id: opts.sourceId ?? 'default',
      ...(extra ?? {}),
    });
  };

  // [c2] surface enforcement at the SHARED layer: a hidden op is uncallable
  // on every transport, not just unlisted. Same envelope as unknown ops so
  // the surface doesn't leak which names exist.
  if (opts.allowedOps && !opts.allowedOps.has(name)) {
    return unknownToolEnvelope(name, opts, undefined, await grantBlockedNotices(engine, opts, true));
  }

  const op = operations.find(o => o.name === name);
  if (!op) {
    // Always return JSON-shaped error content. v0.31 e2e tests
    // (sources-remote-mcp.test.ts) parse content via JSON.parse so a
    // plain `Error: ...` string here breaks the contract on every
    // unknown-op path and the resulting test failure looked like a
    // transport bug.
    return unknownToolEnvelope(name, opts, undefined, await grantBlockedNotices(engine, opts, true));
  }

  // localOnly backstop at the SHARED layer (WP1/D7): localOnly ops reach the
  // operator's filesystem, so they dispatch only on the local stdio pipe.
  // Any non-stdio transport — both HTTP servers, and any future caller that
  // forgets to mark its transport — is denied fail-closed. Same envelope as
  // a nonexistent op so the catalog doesn't leak which names exist. The
  // serve-http path also filters these at list time; the legacy bearer
  // transport at surface 'full' had no gate at all before this line.
  if (op.localOnly && opts.transport !== 'stdio') {
    return unknownToolEnvelope(name, opts, undefined, await grantBlockedNotices(engine, opts, true));
  }
  // F5: an owner-only op is never listed on MCP; a call gets the exact CLI command.
  if (op.cliOnly && opts.remote !== false) return errorResult(cliOnlyRefusal(op), opts, { op: name });

  // --source-guard (plugin lanes): fail-closed write routing. A user-global
  // plugin serve has no per-workspace source binding, so an ambient-tier
  // resolution must not be allowed to WRITE into whatever source it happened
  // to fall through to. Enforced before validation so a blocked caller
  // learns the routing rule, not the op's parameter shape.
  if (opts.sourceGuardTier && op.scope !== 'read') {
    // The `__all__` read-span sentinel can never be a valid WRITE target (no
    // source has that id — the write would die downstream on the FK). Under
    // the guard, block it with a sentinel-specific hint rather than the
    // generic ambiguity copy. This is independent of the tier probe below.
    const sentinelWrite = opts.sourceId === '__all__';
    if (sentinelWrite || (await sourceGuardBlocksWrite(engine, opts.sourceGuardTier))) {
      logVerb(false);
      const refusal = opError('source_binding_required', sentinelWrite
          ? 'GBRAIN_SOURCE=__all__ is a read-span sentinel, not a write target — a write cannot resolve to "all sources". ' +
            'Set GBRAIN_SOURCE to a concrete source id for writes.'
          : 'This brain has more than one source to choose from and the MCP server runs with --source-guard: ' +
          `write/admin operations need an explicit source binding so they cannot land in the wrong source (resolution tier: ${opts.sourceGuardTier}).`,
        'Set GBRAIN_SOURCE=<source-id> in the environment that launches this MCP server ' +
          '(plugin installs pass it through — the user-global stdio serve binds the source from the env, not a flag). ' +
          'List sources with `gbrain sources list`. Reads are unaffected.',
        { fix: { argv: ['gbrain', 'sources', 'list'], consent: [], actor: 'user', why: 'Names the source id to bind with GBRAIN_SOURCE.', requires_exclusive: false } });
      if (isVerb) refusal.protocolVersion = MEMORY_VERBS_VERSION;
      return errorResult(refusal, opts, { op: name });
    }
  }

  const safeParams = normalizeOptionalParams(op, params || {});
  const validationFailure = findInvalidParam(op, safeParams);
  if (validationFailure) {
    logVerb(false);
    // [c7] verb validation errors speak the protocol envelope (protocol_version);
    // B3: every op's suggestion names the param's type, choices and an example.
    const invalid = schemaInvalidParams(op, validationFailure, { remote: opts.remote, transport: dispatchRenderContext(opts).transport === 'http' ? 'http' : 'stdio' }, safeParams);
    if (isVerb) invalid.protocolVersion = MEMORY_VERBS_VERSION;
    return errorResult(invalid, opts, { op: name });
  }

  // WP3 strict/warn unknown-argument validation. Runs on the NORMALIZED
  // object (a null/'' optional idiom is never an unknown key). `_meta` and
  // `dry_run` are allowlisted inside findUnknownParams. The mode resolves
  // dual-plane (DB > file > 'warn') once per dispatch, and only when an
  // unknown key actually exists — the all-declared common case pays no
  // config read. #5970: a write (`op.mutating`) rejects in every mode; the
  // warn grace period would commit a row with the misnamed field dropped.
  const unknownParamWarnings = findUnknownParams(op, safeParams);
  if (unknownParamWarnings.length > 0) {
    const strictMode = op.mutating === true ? 'reject' : await resolveStrictParamsMode(engine, opts.config ?? loadConfig());
    // GBRA-431: a misspelled scope or filter on a read would answer unnarrowed, so it rejects in every mode.
    const narrowing = strictMode === 'reject' ? [] : narrowingUnknownParams(unknownParamWarnings, Object.keys(op.params));
    if (strictMode === 'reject' || narrowing.length > 0) {
      logVerb(false);
      // Privacy (amendment 11): the raw unknown key rides `suggestion` ONLY.
      // serve-http persists the envelope's `message` into
      // mcp_request_log.error_message — the message therefore counts, never
      // names (same posture as the redacted params summarizer).
      const n = unknownParamWarnings.length;
      const suggestion = unknownParamWarnings
        .map(w => w.suggestion
          ? `Unknown parameter "${w.param}" — did you mean "${w.suggestion}"?`
          : `Unknown parameter "${w.param}".`)
        .join(' ') + (op.callShape ? ` ${op.callShape}` : '');
      const strict = new OperationError('invalid_params',
        `${n} unknown parameter${n === 1 ? '' : 's'} not declared in the ${name} tool schema (${op.mutating === true ? 'write operations always reject unknown parameters; nothing was written' : narrowing.length > 0 ? 'a read rejects an unknown scope or filter parameter, which would otherwise return unnarrowed results; nothing was read' : 'mcp.strict_params=reject'}). See suggestion for the submitted name${n === 1 ? '' : 's'}.`,
        suggestion);
      if (isVerb) strict.protocolVersion = MEMORY_VERBS_VERSION;
      return errorResult(strict, opts, { op: name });
    }
  }

  // Remote callers must arrive with a resolved source scope. Every shipped
  // transport passes sourceId explicitly (serve-http from the OAuth client
  // row, http-transport from the legacy token grant, stdio from
  // GBRAIN_SOURCE); a remote call reaching the 'default' fallback means a
  // programmatic caller skipped scope resolution, and silently landing in
  // the shared 'default' source is the cross-source leak class behind
  // #1924 / #1371. Trusted local callers (remote === false) keep the
  // historical fallback via buildOperationContext.
  if ((opts.remote ?? true) && !opts.sourceId) {
    const viaClient = opts.transport !== 'stdio' && !!opts.auth?.clientId;
    return errorResult(opError('missing_source_scope',
      `Remote tool call '${name}' carries no resolved sourceId; refusing the shared 'default' source fallback. Pass an explicit sourceId resolved from the caller's grant.`,
      viaClient
        ? `This connection has no source grant. The brain host operator binds one to this client (gbrain auth rescope-client ${opts.auth!.clientId} --source <source-id>), then the call works.`
        : 'This MCP server resolved no source. Set GBRAIN_SOURCE to a registered source id in the environment that launches it, then restart it.',
      { fix: hostFix({ remote: true, transport: viaClient ? 'http' : 'stdio' },
        viaClient ? ['gbrain', 'auth', 'clients', '--json'] : ['gbrain', 'sources', 'list'],
        viaClient ? 'Shows each OAuth client\'s write source; the operator binds this client to one with `gbrain auth rescope-client`.'
          : 'Lists the source ids GBRAIN_SOURCE can name.') }), opts, { op: name });
  }

  const ctx = buildOperationContext(engine, safeParams, opts);

  // WP2/D3: response-meta side channel. Handlers publish namespaced
  // out-of-band metadata (retrieval degradation, strict-mode warnings) here;
  // the success path below merges the collected keys into ToolResult._meta.
  // Last write per key wins within one call; the collector never throws.
  const responseMeta: Record<string, unknown> = {};
  ctx.emitResponseMeta = (key, value) => {
    if (value !== undefined) responseMeta[key] = value;
  };

  // WP3 warn mode: unknown keys were accepted above — surface them on the
  // structured channel (`_meta.warnings`, amendment 13 shape) so operators
  // and capable clients see the grace-period signal per call.
  if (unknownParamWarnings.length > 0) {
    ctx.emitResponseMeta('warnings', unknownParamWarnings);
  }

  // Agent contract v1 (A6): the model-visible notice channel. Producers call
  // ctx.emitNotice; success renders prefixed extra blocks + _meta.gbrain_notices,
  // failure renders the envelope's `notices` key (one block).
  const notices: Notice[] = [];
  ctx.emitNotice = (n) => { if (n) notices.push(n); };
  let tail: ToolTail | undefined; ctx.emitToolTail = (t) => { tail = t; }; // Wakeshift's addition, appended last on success

  try {
    if (ctx.remote !== false && op.requiredScopes?.length) {
      let scopes = ctx.auth?.scopes;
      if (!scopes && ctx.transport === 'stdio') {
        const verified = currentVerifiedLocalWriter() ?? await verifyLocalWriter(engine, await readLocalWriter(engine, 'stdio'));
        scopes = verified.remote ? verified.grant.scopes : [];
      }
      if (!operationScopesAllowed(scopes ?? [], op)) {
        throw scopeDeniedError({ op: name, required: op.requiredScopes, auth: ctx.auth ? { ...ctx.auth, scopes: scopes ?? [] } : { clientId: '', scopes: scopes ?? [] },
          transport: ctx.transport === 'stdio' ? 'stdio' : 'http', message: 'This operation requires an explicit shared-skills grant.', legacy_error: 'permission_denied' });
      }
    }
    // Fail-closed gate for slug-bound OAuth clients, applied here because
    // this is the one path both MCP transports share. Per-op fences still
    // run inside the handlers; this stops an unfenced write op from being
    // a silent hole. See CLIENT_FENCED_WRITE_OPS in operations.ts.
    enforceBoundClientOpAllowList(ctx.auth, op);
    // #5575 CEO-18: a floored connection only reaches read ops that enforce its floor.
    enforceReadTrustFloor(ctx.auth, op);
    // GBRA-156: a read op does not change what the hook reads, so it runs beside the handler (a degraded engine's reconnect stays the handler's).
    const metaHook = namesOwnSources(safeParams, ctx.sourceId) ? undefined : opts.metaHook;
    const earlyMeta = metaHook && op.mutating === false && !isEngineDegraded(engine) ? runMetaHook(metaHook, name, ctx) : undefined;
    const sharedStdio = ctx.transport === 'stdio' && !ctx.auth &&
      (op.requiredScopes?.length || ['list_skills', 'get_skill', 'get_skill_asset', 'list_brain_skillpack'].includes(name));
    let registration: Awaited<ReturnType<typeof readLocalWriter>> | undefined;
    if (sharedStdio) {
      try { registration = await readLocalWriter(engine, 'stdio'); }
      catch (error) {
        if (!(error instanceof OperationError) || error.code !== 'writer_registration_required' || op.requiredScopes?.length) throw error;
      }
    }
    const result = registration
      ? await withVerifiedLocalRegistration(engine, registration, async verified => {
        if (!verified.remote) throw opError('permission_denied', 'This registration is not an agent-facing connection.',
          `${name} on this stdio connection needs the agent-facing stdio writer registration, which only the user can create in a terminal on the brain host.`,
          { fix: hostFix(ctx, ['gbrain', 'auth', 'local-writer', 'register', 'stdio', '--dry-run', '--json'],
            'Previews the agent-facing stdio registration; the user reruns it without --dry-run (with --replace and the complete grant when a registration exists).') });
        return op.handler(ctx, safeParams);
      })
      : await op.handler(ctx, safeParams);
    if (emptyRead(name, result)) await assertUnscopedReadReachesPages(name, safeParams, ctx);
    // Hot memory built before a write (forget, remember, …) is never served after it, on every transport;
    // #6696 (A4): the write's receipt carries the capacity notices (60 s snapshot, at most hourly per scope).
    if (op.mutating) { invalidateHotMemoryForEngine(engine); notices.push(...await writeReceiptCapacityNotices(engine, ctx)); }
    // [E4] verb success metrics: budget drops + entity hit/miss when present.
    {
      const r = result as { dropped_count?: number; found?: boolean; status?: string } | null;
      logVerb(true, {
        ...(typeof r?.dropped_count === 'number' ? { budget_dropped: r.dropped_count } : {}),
        ...(name === 'entity' && typeof r?.found === 'boolean' ? { entity_found: r.found } : {}),
        // remember's frozen status enum (inserted|duplicate|superseded) — the memory_writeback
        // doctor counters read this (all-MCP-callers semantics, labeled honestly there; OV-A11).
        ...(name === 'remember' && typeof r?.status === 'string' ? { remember_status: r.status } : {}),
        ...((name === 'entity' || name === 'context_pack') && recordsFiring(result) ? { records_firing: recordsFiring(result)! } : {}),
      });
    }
    // D8: model-visible loudness for empty retrievals. The body stays a bare
    // array (D3 — deployed thin-clients parse content[0] only); the diagnosis
    // rides the notice channel (its text kept as the `why:` line). Structured
    // consumers read the same facts from _meta.retrieval below.
    const emptyBlock = Array.isArray(result) && result.length === 0 && responseMeta.retrieval
      ? buildEmptyRetrievalBlock(responseMeta.retrieval) : null;
    if (emptyBlock) notices.push({ code: 'empty_retrieval', kind: emptyBlock.includes('degraded:') ? 'degraded' : 'info', why: emptyBlock });
    // Cat 40 (#5932) evidence blocks (type-filter notice, other names, saved facts) are retrieval
    // data, not advice: they stay plain extra text blocks right after content[0], as measured.
    const evidence = (retrieval: unknown) => retrievalNoticeBlocks(result, retrieval).slice(emptyBlock ? 1 : 0);
    // Lane F (F3): degraded recall and a source binding that narrowed an empty read.
    const rerankDegradedCalls = recordRerankDegradation(responseMeta, opts);
    notices.push(...recallInteropNotices(name, result, responseMeta, safeParams,
      { config: ctx.config, transport: dispatchRenderContext(opts).transport, binding: ctx.explicitReadBinding, rerankDegradedCalls }));
    notices.push(...accessPolicyNotices(name, ctx), ...await hiddenContentNotices(engine, name, result, ctx, opts));
    // Monthly backup-coverage: one AGGREGATE notice per process (counts only —
    // never a local path or source id). The refresher runs on the stdio
    // transport ONLY — the WP1/D7 locality axis localOnly ops use; 'http' or
    // an UNSET marker never probes (fail-closed).
    // F5 follow-up: local transcripts exist but their reader is not callable on this stdio connection.
    if (opts.transport === 'stdio' && opts.remote !== false && !dispatchRenderContext(opts).isCallable('get_recent_transcripts')
      && wantsTranscriptHint(name, safeParams, result)) {
      try {
        const { recentTranscriptPresence } = await import('../core/transcripts.ts');
        const hint = localTranscriptsNotice(await recentTranscriptPresence(engine));
        if (hint) notices.push(hint);
      } catch { /* a pointer, never a failure */ }
    }
    maybeBackupNotice(notices, opts);
    // GST-1387: a remember batch with a failed item is an MCP error; its body keeps every item's receipt.
    const batchError = name === 'remember' && typeof result === 'object' && result !== null && (result as { status?: unknown }).status === 'error' && Array.isArray((result as { items?: unknown }).items);
    if (opts.transport === 'stdio' && opts.remote !== false && !batchError) { const up = takePostUpgradeMcpNotice(); if (up) notices.push(up); } // F7
    if (opts.transport === 'stdio' && opts.remote !== false && !batchError) notices.push(...await mcpOnboardingNotices({ engine, op: name, result, meta: responseMeta, config: ctx.config, render: dispatchRenderContext(opts) }));
    if (opts.transport === 'stdio' && opts.remote !== false && !batchError) { const drain = takeFactsDrainNotice(); if (drain) notices.push(drain); } // Lane D facts drain
    if (!batchError) notices.push(...await sessionSafetyNotices(engine, opts, ctx.config), ...await grantBlockedNotices(engine, opts, false));
    let { hookOut, room } = opts.roomDeclaration && ctx.remote !== false && !batchError ? await markForRoom(engine, opts, name, result, responseMeta.retrieval, ctx, metaHook && (earlyMeta ?? runMetaHook(metaHook, name, ctx))) : { hookOut: undefined, room: null };
    const admitted = admitNotices(room ? [...notices, ...room.notices] : notices, opts);
    const assemble = (body: unknown, shown: Notice[], stamped: Notice[], meta: Record<string, unknown>, hook: Record<string, unknown> | undefined) =>
      assembleToolResult({ name, result, batchError, evidence, tail, opts }, body, shown, stamped, meta, hook);
    if (opts.transport === 'stdio') {
      maybeRefreshBackupStatusInProcess(engine);
    }
    // v0.31 (eD3 + eE4): best-effort _meta.brain_hot_memory injection.
    // The hook is wrapped in its own try/catch — any DB blip / cache miss /
    // helper crash degrades to no hook keys rather than flipping the whole
    // tool call to error.
    if (metaHook && !hookOut) hookOut = await (earlyMeta ?? runMetaHook(metaHook, name, ctx));
    if (hookOut?.failure !== undefined) ctx.logger.warn(`[mcp] _meta hook failed for ${name}: ${hookOut.failure}; degrading to no hook keys`);
    const cap = (built: ToolResult) => op.mutating ? Promise.resolve(null) : frameOverCap(built, { remote: ctx.remote, transport: ctx.transport, engine, config: ctx.config });
    const out = room
      ? assemble(room.result, admitted, [...notices, ...room.stamped], { ...responseMeta, ...(room.retrieval ? { retrieval: room.retrieval } : {}), room: room.meta }, (room.hotMemory ?? hookOut?.meta) as Record<string, unknown> | undefined)
      : assemble(result, admitted, notices, responseMeta, hookOut?.meta);
    // Large pages: the egress backstop measures the final frame; a read over the connection's cap is refused whole, never cut.
    const over = await cap(out);
    const fallback = over && room ? await roomCapFallback((meta, extra) => assemble(result, [...admitted.filter(n => !n.code.startsWith('room_')), ...extra], [...notices, ...extra], meta, hookOut?.meta), cap, responseMeta) : null;
    if (fallback) return fallback;
    if (over) return errorResult(resultTooLargeError(name, safeParams, over), opts, { op: name, mutating: false, idempotent: op.idempotent === true });
    return out;
  } catch (thrown: unknown) {
    // A transient failure of the member-identity lookup at submission is the retryable access_identity_unavailable.
    const e = identityLookupUnavailable(thrown) ?? thrown;
    logVerb(false);
    if (op.mutating) invalidateHotMemoryForEngine(engine); // a failed write may have committed part of its work
    // Agent contract v1 (A1): every failure — OperationError, classified DB
    // access errors, uncaught throws — goes through the one total normaliser,
    // which redacts raw messages, keeps verbs on their frozen v1 codes, and
    // never tells a mutating op with an unknown outcome to retry.
    notices.push(...await sessionSafetyNotices(engine, opts, ctx.config));
    notices.push(...await grantBlockedNotices(engine, opts, refusedByGrant(e)));
    attachRetryCall(op, name, safeParams, e);
    if (op.mutating) asSegmentedWriteRefusal(e);
    return deferredWriteResult(e, notices, opts) ?? errorResult(e, opts, { op: name, mutating: op.mutating === true, idempotent: op.idempotent === true, notices: admitNotices(notices, opts) });
  }
}