@vibesdotdev/mcp 0.0.0-stage → 1.0.0-rc.1

package/dist/adapters/mcp/server.js

@@ -0,0 +1,1423 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolRequestSchema, CallToolResultSchema, TextContentSchema, ResourceLinkSchema, CreateMessageResultSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import z from 'zod/v4';
+import { safeParseAsync } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+const registeredTools = new WeakMap();
+const explicitResumeInputSchema = z.object({
+    action: z.literal('resume'),
+    sessionId: z.string().trim().min(1)
+});
+const receiptRestoreInputSchema = z.object({
+    action: z.literal('status'),
+    receiptOnly: z.literal(true),
+    sessionId: z.string(),
+    participantId: z.string()
+});
+const explicitSessionTargetSchema = z.object({ sessionId: z.string().trim().min(1) });
+import { admitConnectionCaller } from "./connection-identity.js";
+import { PROMPTS_MANIFEST_DESCRIPTOR_PREFIX, PROMPTS_MANIFEST_KIND_ID, promptsManifestDescriptorSchema } from '@vibesdotdev/ai-schemas';
+import { resolvePromptText } from '@vibesdotdev/tools/prompts/manifests';
+import { isDiscriminatedUnion, getDiscriminator, getDiscriminatorOptions, flattenDiscriminatedUnionToObject, isPlainUnion, resolveMcpDescription } from "../zod-mcp.js";
+import { CapabilityError, CaughtFailureSchema, isCapabilityError, settle, settleNow, valueFreeFailure } from '@vibesdotdev/kernel';
+import { JsonObjectSchema } from '@vibesdotdev/kernel/schemas/json';
+import { redactedExcerpt } from '@vibesdotdev/shared/utils';
+import { requireMcpClient } from "../../client.js";
+import { resolveMcpTransportRegistry } from "./transport-registry.js";
+import { ToolError } from '@vibesdotdev/tools/errors/tool-error';
+import { getLogger } from '@vibesdotdev/logging';
+import { invokeTool } from '@vibesdotdev/tools/execution/invoke';
+import { ToolInputValidationError } from '@vibesdotdev/tools/execution/input-validation';
+import { buildDirectToolCallContext } from '@vibesdotdev/tools/execution/direct-context';
+import { DEFAULT_AGENT_CAPABILITY_CEILING, TOOL_AGENT_CONTEXT_METADATA_KEY } from '@vibesdotdev/tools/schemas/runtime/capability-tier';
+import { isLocalToolId, localToolsOf } from '@vibesdotdev/tools/local/node/ensure-local-tools';
+import { detectMcpClientId } from '@vibesdotdev/tools/schemas/presets/registry';
+import { loadMcpConfig } from "../../config/load.js";
+import { formatLocalMcpToolDescription, vibesToolOrigin } from "./local-origin.js";
+import { normalizeHarness } from "./serve-identity.js";
+import { missingRequiredTools, selectMcpTools } from "./tool-selection.js";
+import { deriveTrustTier, wrapToolOutputText } from "./trust-tag.js";
+import { createProjectionBirthResource, PROJECTION_BIRTH_RESOURCE_URI, projectionCatalogHash } from "./projection.js";
+import { createMcpWireNameMap, mcpWireToolName } from "./mcp-wire-name.js";
+import { ambientMeta, formatAmbientPrefix, liftAmbientEnvelope } from "./ambient-envelope.js";
+import { computeMcpToolCatalog, createMcpToolCatalogCache, formatRegistrationFailureInstructions } from "./tool-catalog.js";
+import { runWithMcpSamplingCallback } from "./sampling-context.js";
+/**
+ * Resolve the effective capability tier ceiling for an MCP connection from the
+ * runtime's `mcp` ConfigManifest (`clientCapabilityCeilings`).
+ *
+ * Verified transport harness identity (`admitConnectionCaller`) takes
+ * precedence over server-level `mcpClientId` and `preset`. Unconfigured
+ * profiles fall back to the tools default ceiling (`'1'`).
+ */
+export function resolveMcpClientCapabilityCeiling(config, input, source) {
+    const ceilings = config.clientCapabilityCeilings;
+    const candidates = [];
+    const pushCandidate = (raw) => {
+        const trimmed = raw?.trim().toLowerCase();
+        if (!trimmed)
+            return;
+        if (!candidates.includes(trimmed))
+            candidates.push(trimmed);
+        const normalized = (source ? normalizeHarness(source, trimmed) : undefined) ?? detectMcpClientId(trimmed) ?? undefined;
+        if (normalized && !candidates.includes(normalized))
+            candidates.push(normalized);
+    };
+    const verifiedHarness = input.admittedCaller?.harness;
+    if (verifiedHarness && verifiedHarness !== 'custom') {
+        pushCandidate(verifiedHarness);
+    }
+    pushCandidate(input.mcpClientId);
+    if (input.preset) {
+        pushCandidate(input.preset.replace(/^mcp:/i, ''));
+    }
+    if (verifiedHarness === 'custom') {
+        pushCandidate(verifiedHarness);
+    }
+    for (const candidate of candidates) {
+        const configured = ceilings[candidate];
+        if (configured !== undefined) {
+            return { profile: candidate, ceiling: configured };
+        }
+    }
+    return { profile: candidates[0], ceiling: DEFAULT_AGENT_CAPABILITY_CEILING };
+}
+/**
+ * Project-local catalog ids (CLI `list --source=local` parity). Explicit
+ * options win (tests, serve bootstrap); otherwise the tools this runtime's
+ * discovery pass registered from `.vibes/tools`.
+ *
+ * This is the one node-scoped read in the build path, so it lives here rather
+ * than in `tool-catalog.ts`, which stays isomorphic.
+ */
+export function resolveLocalToolIds(runtime, options) {
+    return options.localToolIds ?? localToolsOf(runtime).toolIds;
+}
+/**
+ * The catalog cache a serving surface should hold: one fold of the registry,
+ * shared by every connection, re-folded the moment the registry moves.
+ *
+ * `loaderSettlement` stays `'advisory'` unless the caller can name the
+ * registration bound for its serving surface (see {@link McpLoaderSettlement}).
+ * A settled cache excludes descriptors whose loader is unresolvable at fold
+ * time, and admits them on the next fold if one registers — the revision key
+ * is the guarantee.
+ */
+export function createMcpServerCatalogCache(runtime, options, logger, loaderSettlement = 'advisory') {
+    return createMcpToolCatalogCache(runtime, options, logger, () => resolveLocalToolIds(runtime, options), loaderSettlement);
+}
+function isStringValue(value) {
+    return typeof value === 'string';
+}
+function asJsonObject(value) {
+    const parsed = JsonObjectSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+const JsonTextSchema = z.string();
+/** Re-admit a JSON text: objects become structuredContent; arrays and null stay text. */
+function wireJsonText(text) {
+    const parsed = settleNow(() => JSON.parse(text));
+    if (!parsed.ok) {
+        throw new CapabilityError('the tool output is not JSON', 'INVALID_INPUT', {
+            reason: 'mcp-tool-output-not-json',
+            cause: parsed.cause
+        });
+    }
+    const structured = JsonObjectSchema.safeParse(parsed.value);
+    return structured.success ? { text, structured: structured.data } : { text };
+}
+const ZodIssueListSchema = z.object({
+    issues: z.array(z.object({
+        path: z.array(z.union([z.string(), z.number()])).optional(),
+        message: z.string().optional(),
+        values: z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional()
+    }))
+});
+const ToolHookFailureSchema = z.object({
+    code: z.string().optional(),
+    recoveryHint: z.string().optional(),
+    retryable: z.boolean().optional(),
+    metadata: JsonObjectSchema.optional(),
+    alternatives: z.array(z.string()).optional()
+});
+const SafetyReadOnlySchema = z.object({ readOnly: z.boolean().optional() });
+// SDK metadata and content contracts govern passthrough. Content stays required:
+// the SDK's default empty array must not classify ordinary domain output as MCP.
+const mcpToolResponseSchema = CallToolResultSchema.extend({
+    content: z.array(z.union([TextContentSchema, ResourceLinkSchema]))
+});
+function readMcpToolResponse(value) {
+    const parsed = mcpToolResponseSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function formatZodIssues(error) {
+    const parsed = ZodIssueListSchema.safeParse(error);
+    if (!parsed.success || parsed.data.issues.length === 0)
+        return 'Invalid input';
+    return parsed.data.issues
+        .slice(0, 4)
+        .map((issue) => {
+        const path = issue.path && issue.path.length > 0 ? issue.path.join('.') : '<root>';
+        const allowed = issue.values && issue.values.length > 0
+            ? ` (allowed: ${issue.values.map(String).join(', ')})`
+            : '';
+        const message = issue.message ?? 'Invalid input';
+        return `${path}: ${message}${allowed}`;
+    })
+        .join('; ');
+}
+/** The most characters of a typed failure's text the model sees. */
+const MODEL_FAILURE_TEXT_MAX_CHARS = 4000;
+/**
+ * The text a tool failure may put in the model's context. Typed failures
+ * (CapabilityError, input validation, ToolError) carry deliberate, value-free
+ * messages and pass the shared credential redactor; anything else is a fixed
+ * INTERNAL sentence naming only its value-free facts. The raw text goes to the
+ * log as a redacted excerpt, never to the model.
+ */
+function modelSafeFailureText(error) {
+    if (error instanceof ToolInputValidationError || error instanceof ToolError || isCapabilityError(error)) {
+        return redactedExcerpt(error.message, { maxChars: MODEL_FAILURE_TEXT_MAX_CHARS });
+    }
+    const facts = valueFreeFailure(error);
+    return `The tool failed with an internal error (${facts.name}${facts.code === undefined ? '' : ` ${facts.code}`}).`;
+}
+function projectMcpToolFailure(thrown) {
+    const error = CaughtFailureSchema.parse(thrown);
+    if (error instanceof ToolInputValidationError) {
+        const message = modelSafeFailureText(error);
+        const capability = new CapabilityError(message, 'INVALID_INPUT', {
+            recoveryHint: 'Fix the listed input issues and retry.',
+            details: { issues: error.issues }
+        });
+        return { message, code: 'INVALID_INPUT', envelope: { ...capability.toEnvelope() } };
+    }
+    if (isCapabilityError(error)) {
+        return { message: modelSafeFailureText(error), code: error.code, envelope: { ...error.toEnvelope() } };
+    }
+    const message = modelSafeFailureText(error);
+    // A timeout is read from the failure's own text but never copied out of it.
+    const timedOut = error instanceof Error && /timed out/i.test(error.message);
+    const code = timedOut ? 'TIMEOUT' : 'INTERNAL';
+    const failureOptions = { retryable: timedOut };
+    if (timedOut)
+        failureOptions.details = { timedOut: true };
+    const envelope = new CapabilityError(message, code, failureOptions).toEnvelope();
+    return { message, code, envelope };
+}
+function getSuggestedToolCallFromErrorMetadata(metadata) {
+    if (!metadata)
+        return undefined;
+    const containmentRequest = metadata.containmentRequest;
+    const containment = asJsonObject(containmentRequest);
+    if (!containment)
+        return undefined;
+    return {
+        toolId: 'workspace-fs',
+        input: {
+            action: 'write',
+            writeAction: 'request-access',
+            ...containment
+        }
+    };
+}
+function isZodLike(value) {
+    return value instanceof z.ZodType;
+}
+function isSafetyCategory(safety) {
+    return typeof safety === 'string';
+}
+function deriveMcpAnnotations(safety) {
+    if (!safety)
+        return undefined;
+    const category = isSafetyCategory(safety) ? safety : safety.category;
+    const hints = isSafetyCategory(safety) ? undefined : safety;
+    // Default values based on category
+    const defaults = {
+        read: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        },
+        write: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false
+        },
+        execute: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }[category] ?? {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+    };
+    // Apply explicit overrides. `readOnly` is read defensively (the
+    // SafetyField type does not declare it yet) so a descriptor that declares
+    // an explicit readOnly hint is honored instead of silently taking the
+    // category default.
+    const parsedReadOnly = hints ? SafetyReadOnlySchema.safeParse(hints) : undefined;
+    const readOnly = parsedReadOnly?.success ? parsedReadOnly.data.readOnly : undefined;
+    return {
+        readOnlyHint: readOnly ?? defaults.readOnlyHint,
+        destructiveHint: hints?.destructive ?? defaults.destructiveHint,
+        idempotentHint: hints?.idempotent ?? defaults.idempotentHint,
+        openWorldHint: hints?.openWorld ?? defaults.openWorldHint
+    };
+}
+function uniqueName(base, used) {
+    if (!used.has(base)) {
+        used.add(base);
+        return base;
+    }
+    let index = 2;
+    let candidate = `${base}.${index}`;
+    while (used.has(candidate)) {
+        index += 1;
+        candidate = `${base}.${index}`;
+    }
+    used.add(candidate);
+    return candidate;
+}
+function getDescriptorMcpDescription(descriptor) {
+    return resolveMcpDescription(descriptor);
+}
+function buildResourceText(descriptor, resourceName, uri, variables) {
+    const description = getDescriptorMcpDescription(descriptor);
+    return JSON.stringify({
+        kind: 'descriptor-metadata',
+        note: 'Descriptor metadata payload; not live resource data.',
+        tool: {
+            id: descriptor.id,
+            name: descriptor.name ?? descriptor.id,
+            description: description || null
+        },
+        resource: {
+            name: resourceName,
+            uri
+        },
+        variables
+    }, null, 2);
+}
+/** MCP prompt arguments arrive as strings; each manifest-declared argument becomes one. */
+function buildPromptArgsSchema(argumentsSchema) {
+    if (!argumentsSchema || argumentsSchema.length === 0)
+        return undefined;
+    const argumentSchemas = {};
+    for (const arg of argumentsSchema) {
+        // Describe the outer schema: the SDK lists an optional argument's own description.
+        const description = arg.description ?? `${arg.name} argument`;
+        argumentSchemas[arg.name] = arg.required ? z.string().describe(description) : z.string().optional().describe(description);
+    }
+    return argumentSchemas;
+}
+function registerDescriptorMcpDefinitions(server, descriptors, runtime, logger, options = { announce: true }) {
+    const resourceUris = new Set();
+    const resourceNames = new Set();
+    const promptNames = new Set();
+    const promptIds = new Set();
+    const mcpLog = logger.child('mcp-definitions');
+    const canResolvePromptIds = runtime.hasKind(PROMPTS_MANIFEST_KIND_ID);
+    for (const descriptor of descriptors) {
+        const mcp = descriptor.mcp;
+        if (!mcp)
+            continue;
+        const resources = [...(mcp.resource ? [mcp.resource] : []), ...(mcp.resources ?? [])];
+        for (const resource of resources) {
+            if (resource.uri === PROJECTION_BIRTH_RESOURCE_URI)
+                throw new Error('Reserved projection birth resource URI');
+            if (resourceUris.has(resource.uri))
+                continue;
+            resourceUris.add(resource.uri);
+            const name = uniqueName(resource.name || `${descriptor.id}.resource`, resourceNames);
+            server.registerResource(name, resource.uri, {
+                description: resource.description
+                    ? `${resource.description} (descriptor metadata)`
+                    : `Descriptor metadata for ${descriptor.id}`,
+                mimeType: resource.mimeType,
+                _meta: {
+                    vibes: {
+                        toolId: descriptor.id,
+                        cacheable: resource.cacheable,
+                        subscriptions: resource.subscriptions
+                    }
+                }
+            }, (uri) => ({
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: resource.mimeType ?? 'application/json',
+                        text: buildResourceText(descriptor, name, uri.href)
+                    }
+                ]
+            }));
+        }
+        for (const template of mcp.resourceTemplates ?? []) {
+            if (template.uriTemplate === PROJECTION_BIRTH_RESOURCE_URI)
+                throw new Error('Reserved projection birth resource URI');
+            const name = uniqueName(template.name || `${descriptor.id}.resource-template`, resourceNames);
+            const uriTemplate = new ResourceTemplate(template.uriTemplate, { list: undefined });
+            server.registerResource(name, uriTemplate, {
+                description: template.description
+                    ? `${template.description} (descriptor metadata)`
+                    : `Descriptor metadata template for ${descriptor.id}`,
+                mimeType: template.mimeType,
+                _meta: {
+                    vibes: {
+                        toolId: descriptor.id,
+                        cacheable: template.cacheable,
+                        subscriptions: template.subscriptions
+                    }
+                }
+            }, (uri, variables) => ({
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: template.mimeType ?? 'application/json',
+                        text: buildResourceText(descriptor, name, uri.href, variables)
+                    }
+                ]
+            }));
+        }
+        if (canResolvePromptIds) {
+            for (const promptId of mcp.promptIds ?? []) {
+                if (promptIds.has(promptId))
+                    continue;
+                promptIds.add(promptId);
+                const name = uniqueName(`ai.prompt.${promptId}`, promptNames);
+                const registered = runtime.query(PROMPTS_MANIFEST_KIND_ID)
+                    .withId(`${PROMPTS_MANIFEST_DESCRIPTOR_PREFIX}${promptId}`)
+                    .firstDescriptor();
+                const manifest = registered ? promptsManifestDescriptorSchema.parse(registered).manifest : undefined;
+                const promptDescription = manifest
+                    ? resolveMcpDescription({ id: promptId, name: manifest.name, description: manifest.description || undefined })
+                    : `Prompt descriptor ${promptId}`;
+                const argsSchema = buildPromptArgsSchema(manifest?.arguments) ?? {};
+                server.registerPrompt(name, {
+                    description: promptDescription,
+                    argsSchema
+                }, async (args) => {
+                    // THE prompts kind renders the prompt with its composition, declared defaults and the caller's arguments.
+                    const text = await resolvePromptText(runtime, promptId, { args });
+                    return {
+                        description: promptDescription,
+                        messages: [
+                            {
+                                role: 'user',
+                                content: {
+                                    type: 'text',
+                                    text: text || `Prompt '${promptId}' has no prompts/manifest content to expose.`
+                                }
+                            }
+                        ]
+                    };
+                });
+            }
+        }
+    }
+    // Announced once per catalog fold; identical on every later connection.
+    const summary = { resources: resourceUris.size, prompts: promptNames.size };
+    if (options.announce) {
+        mcpLog.info('Registered MCP descriptor definitions', summary);
+    }
+    else {
+        mcpLog.debug('Registered MCP descriptor definitions', summary);
+    }
+}
+/**
+ * Construct one `McpServer` for one connection.
+ *
+ * The catalog fold (discover → enable → select → instructions) is NOT done
+ * here: pass a `catalog` from `createMcpToolCatalogCache` so many connections
+ * share one fold. When omitted the fold happens inline, which keeps every
+ * single-server caller (stdio, tests) working exactly as before.
+ */
+export function buildServer(runtime, options, logger, catalog = computeMcpToolCatalog(runtime, options, logger, resolveLocalToolIds(runtime, options))) {
+    const buildLog = logger.child('build');
+    const serverName = options.serverName ?? 'vibes';
+    const serverVersion = options.serverVersion ?? '0.0.0';
+    if (catalog.degradedKind) {
+        // Constitution rule 13: empty tools/list must not look healthy. The
+        // banner was composed (and error-logged) by the catalog fold.
+        return new McpServer({ name: serverName, version: serverVersion }, {
+            capabilities: catalog.capabilities,
+            instructions: catalog.instructions
+        });
+    }
+    const selected = catalog.selected;
+    if (!selected) {
+        throw new Error('MCP tool catalog is non-degraded but carries no selection');
+    }
+    const enabledDescriptors = catalog.enabledDescriptors;
+    const localToolIds = catalog.localToolIds;
+    const descriptors = catalog.descriptors;
+    createMcpWireNameMap(descriptors.map(descriptor => descriptor.id), options.mcpClientId, catalog.purposePresets);
+    const capabilities = catalog.capabilities;
+    const instructions = catalog.instructions;
+    const preScanFailedTools = [...catalog.preScanFailedTools];
+    const failedTools = [...preScanFailedTools];
+    let registeredCount = 0;
+    const registeredToolIds = [];
+    const server = new McpServer({ name: serverName, version: serverVersion }, {
+        capabilities,
+        instructions: instructions || undefined
+    });
+    for (const descriptor of descriptors) {
+        if (!descriptor.schemas?.input) {
+            // Already counted in preFailed / instructions.
+            continue;
+        }
+        const registered = settleNow(() => registerTool(server, descriptor, runtime, { ...options, customPresets: catalog.purposePresets }, logger, localToolIds));
+        if (!registered.ok) {
+            const facts = valueFreeFailure(registered.cause);
+            failedTools.push(`${descriptor.id}: ${facts.name}`);
+            buildLog.error(`Failed to register tool: ${descriptor.id}`, { error: facts });
+            continue;
+        }
+        if (registered.value) {
+            registeredCount++;
+            registeredToolIds.push(descriptor.id);
+        }
+        else {
+            failedTools.push(`${descriptor.id}: schema conversion failed`);
+            buildLog.warn(`Tool registration returned false: ${descriptor.id}`);
+        }
+    }
+    // One INFO per catalog fold, DEBUG for every later connection served from the
+    // same fold: the work is identical, so repeating the line per connection is
+    // noise that hides real events (7,291 of these in 53 h of uptime).
+    const announce = !catalog.announced;
+    catalog.announced = true;
+    const registrationSummary = `Registered ${registeredCount}/${descriptors.length} tools with MCP server`;
+    if (announce) {
+        buildLog.info(registrationSummary, { descriptorRevision: catalog.revision });
+    }
+    else {
+        buildLog.debug(registrationSummary, { descriptorRevision: catalog.revision });
+    }
+    if (failedTools.length > 0) {
+        buildLog.error(`MCP tool registration incomplete: ${failedTools.length} tool(s) not advertised to agents`, { failedTools, registeredCount, selectedCount: descriptors.length });
+    }
+    // Late failures were not known at construct — patch `_instructions` so the
+    // host still sees DEGRADED TOOLSET at session start (rule 13).
+    const lateFailedTools = failedTools.slice(preScanFailedTools.length);
+    if (lateFailedTools.length > 0) {
+        appendMcpInstructions(server, formatRegistrationFailureInstructions(lateFailedTools));
+    }
+    // Continuity contract: required tools that were selected but lack schemas.input
+    // (pre-scan) fail closed — same injury class as missingRequired at selection.
+    const requiredSet = new Set(selected.preset?.requiredTools ?? []);
+    const requiredMissingSchema = descriptors
+        .filter((d) => requiredSet.has(d.id) && !d.schemas?.input)
+        .map((d) => d.id);
+    if (requiredMissingSchema.length > 0) {
+        const message = `REQUIRED MCP TOOLS CANNOT BE ADVERTISED for preset ${selected.presetId}: ` +
+            `${requiredMissingSchema.join(', ')} (no schemas.input). ` +
+            `These continuity tools must not silently vanish from tools/list.`;
+        buildLog.error(message, { requiredMissingSchema, failedTools });
+        throw new Error(message);
+    }
+    // Determinism gate (czar D2 / c198b7bc):
+    // Serve-time registry hash vs selected policy ids asserted equal every boot.
+    const selectedToolIds = descriptors.map((descriptor) => descriptor.id);
+    const selectedCatalogHash = projectionCatalogHash(selectedToolIds);
+    const registeredCatalogHash = projectionCatalogHash(registeredToolIds);
+    if (selectedCatalogHash !== registeredCatalogHash) {
+        const unregisteredIds = selectedToolIds.filter((id) => !registeredToolIds.includes(id));
+        buildLog.error(`MCP serve catalog indeterminism: registered toolset hash (${registeredCatalogHash}) differs from selected policy ids (${selectedCatalogHash})`, {
+            selectedCatalogHash,
+            registeredCatalogHash,
+            unregisteredIds
+        });
+    }
+    // Snapshot before client detection or generation changes can add served tools.
+    if (options.buildProvenance) {
+        const birth = createProjectionBirthResource({ provenance: options.buildProvenance, selectedToolIds, registeredToolIds });
+        server.registerResource('vibes-projection-birth', PROJECTION_BIRTH_RESOURCE_URI, { description: 'Immutable startup snapshot; not a host-visible catalog attestation.', mimeType: 'application/json' }, () => ({ contents: [{ uri: PROJECTION_BIRTH_RESOURCE_URI, mimeType: 'application/json', text: birth.text }] }));
+        const warning = options.buildProvenance.match(/^⚠ (?:EXECUTABLE SOURCE UNKNOWN|DIRTY BUILD|STALE BUILD):/);
+        if (warning)
+            appendMcpInstructions(server, `${warning[0]} Read ${PROJECTION_BIRTH_RESOURCE_URI} for source identity and recovery guidance.`);
+        appendMcpInstructions(server, birth.instructions);
+    }
+    registerDescriptorMcpDefinitions(server, descriptors, runtime, logger, { announce });
+    // Client auto-detection (2025-era scar tissue): when serve was spawned without
+    // --client, the base `mcp` preset applies and client-curated tools stay hidden.
+    // After initialize, we additive-register the detected preset and emit
+    // tools/listChanged.
+    //
+    // MCP 2026-07-28: tools/list MUST NOT vary per connection. This path mutates
+    // the catalog after initialize and is therefore gated behind an explicit
+    // opt-in (`allowClientAutoDetectUpgrade`, default OFF). Pass --client (or
+    // pack config) so the catalog is fixed at start.
+    // See docs/proposals/mcp-2026-07-28/FINDINGS.md.
+    if (!options.mcpClientId && options.allowClientAutoDetectUpgrade) {
+        const baselineIds = new Set(descriptors.map((descriptor) => descriptor.id));
+        server.server.oninitialized = () => {
+            const detected = settleNow(() => {
+                const clientName = server.server.getClientVersion()?.name;
+                const detectedClientId = detectMcpClientId(clientName, catalog.purposePresets);
+                if (!detectedClientId)
+                    return;
+                buildLog.warn('MCP catalog mutated after initialize (client auto-detect). ' +
+                    'Illegal under protocol 2026-07-28 — pass --client so the preset is fixed at start.', { clientName, detectedClientId });
+                // Same registration bound as the construct-time fold: a settled
+                // surface must not re-admit an unavailable descriptor through
+                // this opt-in mutation path. `zombieCandidates` is exactly the
+                // fold's unavailable set.
+                const settlementExcluded = catalog.loaderSettlement === 'settled' ? new Set(catalog.zombieCandidates) : null;
+                const upgraded = selectMcpTools(settlementExcluded
+                    ? enabledDescriptors.filter((descriptor) => !settlementExcluded.has(descriptor.id))
+                    : [...enabledDescriptors], { mcpClientId: detectedClientId, customPresets: catalog.purposePresets });
+                const additions = upgraded.descriptors.filter((descriptor) => !baselineIds.has(descriptor.id));
+                if (additions.length === 0)
+                    return;
+                let added = 0;
+                const upgradeFailures = [];
+                for (const descriptor of additions) {
+                    const registered = settleNow(() => registerTool(server, descriptor, runtime, { ...options, customPresets: catalog.purposePresets }, logger, localToolIds));
+                    if (!registered.ok) {
+                        const facts = valueFreeFailure(registered.cause);
+                        upgradeFailures.push(`${descriptor.id}: ${facts.name}`);
+                        // Error (not warn): continuity tools often land only via
+                        // this path when --client was omitted at serve start.
+                        buildLog.error(`Client-detected tool failed to register: ${descriptor.id}`, { error: facts });
+                        continue;
+                    }
+                    if (registered.value) {
+                        baselineIds.add(descriptor.id);
+                        added += 1;
+                    }
+                    else {
+                        upgradeFailures.push(`${descriptor.id}: schema conversion failed`);
+                        buildLog.error(`Client-detected tool failed to register: ${descriptor.id}`, { error: 'schema conversion failed' });
+                    }
+                }
+                // Initialize already returned construct-time instructions; patch
+                // so agents that re-read server state / later sessions see the gap.
+                // Hosts that only saw initialize may still miss this — error log
+                // remains load-bearing until listChanged + instructions re-push.
+                if (upgradeFailures.length > 0) {
+                    appendMcpInstructions(server, formatRegistrationFailureInstructions(upgradeFailures));
+                    buildLog.error(`Client-detected preset upgrade incomplete: ${upgradeFailures.length} tool(s) not advertised`, { upgradeFailures, added, detectedClientId });
+                }
+                // Required continuity tools for the detected client must not
+                // vanish silently (brain/presence class outage via auto-detect).
+                const stillMissingRequired = missingRequiredTools([...baselineIds], upgraded.preset);
+                if (stillMissingRequired.length > 0) {
+                    const section = `⚠ DEGRADED SURFACE: required tools missing after client auto-detect ` +
+                        `(${detectedClientId}): ${stillMissingRequired.join(', ')}. ` +
+                        `Report this to the user IMMEDIATELY; do NOT silently work around it.`;
+                    appendMcpInstructions(server, section);
+                    buildLog.error('REQUIRED MCP TOOLS MISSING after client auto-detect', {
+                        detectedClientId,
+                        stillMissingRequired
+                    });
+                }
+                buildLog.info('Client-detected preset upgrade', {
+                    clientName,
+                    detectedClientId,
+                    presetId: upgraded.presetId,
+                    added,
+                    addedTools: additions.map((descriptor) => descriptor.id),
+                    upgradeFailures
+                });
+            });
+            if (!detected.ok) {
+                const facts = valueFreeFailure(detected.cause);
+                // Whole-path failure (not per-tool): still a rule-13 injury —
+                // thin base preset can look healthy without continuity tools.
+                appendMcpInstructions(server, '⚠ DEGRADED SURFACE: client preset auto-detection failed after initialize. ' +
+                    'Continuity tools for the connected client may be missing. ' +
+                    'Report this to the user IMMEDIATELY; do NOT silently work around it. ' +
+                    'Diagnose: pass --client explicitly or check MCP initialize clientInfo.name.');
+                buildLog.error('Client preset auto-detection failed', { error: facts });
+            }
+        };
+    }
+    // Own admission before asynchronous SDK schema parsing. RegisteredTool is
+    // a public SDK handle; replacing it leaves admitted calls' schemas intact.
+    //
+    // Protocol shape: an unknown tool or unsupported task execution is a
+    // request error, not a tool-execution error — per MCP spec these are
+    // JSON-RPC -32602 responses, not HTTP-200 `isError` results. Validation
+    // failures stay tool-result-shaped but stamp `_meta.errorCode`
+    // (`INVALID_INPUT`), mirroring the execution path's capability-error
+    // projection below.
+    server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const invocation = runtime.acquireInvocation();
+        try {
+            const attempted = await settle(() => invocation.runtime.runInvocation(async () => {
+                const tool = registeredTools.get(server)?.get(request.params.name);
+                if (!tool?.registration.enabled)
+                    throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+                if (request.params.task)
+                    throw new McpError(ErrorCode.InvalidParams, 'This tool does not support task execution');
+                const parsed = tool.registration.inputSchema ? await safeParseAsync(tool.registration.inputSchema, request.params.arguments) : { success: true, data: request.params.arguments };
+                if (!parsed.success) {
+                    const issues = formatZodIssues(parsed.error);
+                    const text = `Invalid input for '${request.params.name}': ${issues}`;
+                    // Omit structuredContent on isError: MCP clients that kept
+                    // outputSchema validate it even on errors, and {ok:false,error}
+                    // does not match tool output schemas.
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text }],
+                        _meta: { errorCode: 'INVALID_INPUT' }
+                    };
+                }
+                return await tool.invoke(request.params.arguments, extra, invocation);
+            }));
+            if (attempted.ok)
+                return attempted.value;
+            // McpError must escape so the SDK answers with a JSON-RPC error
+            // response carrying its code and the request id.
+            if (attempted.cause instanceof McpError)
+                throw attempted.cause;
+            const failure = projectMcpToolFailure(attempted.cause);
+            return {
+                isError: true,
+                content: [{ type: 'text', text: failure.message }],
+                _meta: { errorCode: failure.code }
+            };
+        }
+        finally {
+            invocation.release();
+        }
+    });
+    const unsubscribe = runtime.onGenerationChange(() => {
+        // Same isolation contract as the initial registration loop above: one
+        // bad descriptor must not leave the server with its tools removed but
+        // not re-registered, skip sendToolListChanged(), or escape into the
+        // event subscription.
+        const refreshed = settleNow(() => {
+            // Same registration bound as the fold this server was built from:
+            // the refresh must not widen a settled surface with descriptors a
+            // fresh connection would still exclude.
+            const next = computeMcpToolCatalog(runtime, options, logger, resolveLocalToolIds(runtime, options), catalog.loaderSettlement);
+            // Validate the replacement before retracting the current, unambiguous catalog.
+            createMcpWireNameMap(next.descriptors.map(descriptor => descriptor.id), options.mcpClientId, next.purposePresets);
+            for (const entry of registeredTools.get(server)?.values() ?? [])
+                entry.registration.remove();
+            registeredTools.set(server, new Map());
+            const refreshFailures = [];
+            for (const descriptor of next.descriptors) {
+                const registered = settleNow(() => registerTool(server, descriptor, runtime, { ...options, customPresets: next.purposePresets }, logger, next.localToolIds));
+                if (!registered.ok) {
+                    const facts = valueFreeFailure(registered.cause);
+                    refreshFailures.push(`${descriptor.id}: ${facts.name}`);
+                    buildLog.error(`Failed to re-register tool on generation change: ${descriptor.id}`, { error: facts });
+                    continue;
+                }
+                if (!registered.value)
+                    refreshFailures.push(`${descriptor.id}: schema conversion failed`);
+            }
+            if (refreshFailures.length > 0) {
+                appendMcpInstructions(server, formatRegistrationFailureInstructions(refreshFailures));
+                buildLog.error(`MCP tool re-registration incomplete after generation change: ${refreshFailures.length} tool(s) not advertised`, { refreshFailures });
+            }
+            server.sendToolListChanged();
+        });
+        if (!refreshed.ok) {
+            const facts = valueFreeFailure(refreshed.cause);
+            appendMcpInstructions(server, '⚠ DEGRADED SURFACE: tool catalog refresh after a registry generation change failed. ' +
+                'The previously registered tool list may be stale or empty. ' +
+                'Report this to the user IMMEDIATELY; do NOT silently work around it.');
+            buildLog.error('MCP tool catalog refresh on generation change failed', { error: facts });
+        }
+    });
+    const onclose = server.server.onclose;
+    server.server.onclose = () => { unsubscribe(); onclose?.(); };
+    return server;
+}
+/**
+ * SDK keeps instructions on Server as private `_instructions` and reads that
+ * field on initialize. Construct-time options cannot list late registerTool
+ * failures — mutate the field after registration so rule 13 still holds.
+ */
+function appendMcpInstructions(server, section) {
+    const inner = server.server;
+    // The SDK Server constructor always assigns its own `_instructions`
+    // property (possibly undefined). If that own property disappears, the SDK
+    // renamed the private field and every degraded-toolset banner written here
+    // would be silently dropped — fail loudly instead of rotting.
+    if (!('_instructions' in inner) || !Object.prototype.hasOwnProperty.call(inner, '_instructions')) {
+        throw new Error('MCP SDK Server no longer declares the private `_instructions` field; ' +
+            'appendMcpInstructions cannot patch degraded-toolset instructions. ' +
+            'Upstream an SDK API for late instructions and update this adapter.');
+    }
+    const previousInstructions = z.object({ _instructions: z.string().optional() }).safeParse(inner);
+    const existing = previousInstructions.success ? previousInstructions.data._instructions ?? '' : '';
+    if (!Reflect.set(inner, '_instructions', existing ? `${existing}\n\n${section}` : section)) {
+        throw new Error('MCP SDK Server instructions are no longer writable.');
+    }
+}
+/**
+ * Zod introspection is pure in its schema, so it is cached against the schema
+ * OBJECT rather than the descriptor id or the registry revision. A WeakMap
+ * cannot go stale: a changed descriptor brings a different schema instance, and
+ * an unchanged instance cannot derive differently.
+ */
+const derivedInputSchemas = new WeakMap();
+const normalizableOutputSchemas = new WeakMap();
+function requireToolZodSchema(value, toolId) {
+    const parsed = z.custom((candidate) => candidate instanceof z.ZodType).safeParse(value);
+    if (!parsed.success)
+        throw new CapabilityError(`Tool '${toolId}' must supply a Zod schema`, 'INVALID_INPUT');
+    return parsed.data;
+}
+function deriveInputSchema(zodSchema) {
+    const cached = derivedInputSchemas.get(zodSchema);
+    if (cached)
+        return cached;
+    const isUnion = isDiscriminatedUnion(zodSchema);
+    const derived = {
+        isUnion,
+        discriminator: isUnion ? getDiscriminator(zodSchema) : null,
+        unionOptions: isUnion ? getDiscriminatorOptions(zodSchema) : [],
+        // The SDK's normalizeObjectSchema only handles z.object() — discriminated
+        // unions produce { type: "object", properties: {} } in tools/list.
+        // Flatten union variants into a merged z.object() so the SDK serializes all params.
+        inputSchema: flattenDiscriminatedUnionToObject(zodSchema)
+    };
+    derivedInputSchemas.set(zodSchema, derived);
+    return derived;
+}
+function normalizableOutputSchema(rawOutputSchema) {
+    const cached = normalizableOutputSchemas.get(rawOutputSchema);
+    if (cached)
+        return cached.schema;
+    const schema = !isPlainUnion(rawOutputSchema) && !isDiscriminatedUnion(rawOutputSchema)
+        ? rawOutputSchema
+        : undefined;
+    normalizableOutputSchemas.set(rawOutputSchema, { schema });
+    return schema;
+}
+// One fallback identity per server, shared by its tools and preserved across registration refresh.
+const serverConnectionKeys = new WeakMap();
+function registerTool(server, descriptor, runtime, options, logger, localToolIds = []) {
+    let serverConnectionKey = serverConnectionKeys.get(server);
+    if (!serverConnectionKey) {
+        serverConnectionKey = `mcp-server:${crypto.randomUUID()}`;
+        serverConnectionKeys.set(server, serverConnectionKey);
+    }
+    if (!descriptor.schemas?.input) {
+        logger.child('schema').error(`No input schema for ${descriptor.id} — skipping tool`);
+        return false;
+    }
+    const zodSchema = requireToolZodSchema(descriptor.schemas.input, descriptor.id);
+    // Pre-computed once per schema OBJECT, not once per connection. Every HTTP
+    // session builds its own McpServer and re-registers all ~89 tools, and the
+    // zod introspection below (union walk + variant merge) was the bulk of that
+    // work. Keying a WeakMap on the schema instance needs no invalidation: a
+    // re-registered descriptor arrives with a new schema object, and for the
+    // same object these are pure functions.
+    const derived = deriveInputSchema(zodSchema);
+    const inputSchema = derived.inputSchema;
+    // Output schema - pass only if it can be normalized by the SDK.
+    // The SDK's normalizeObjectSchema() only handles z.object() — unions cause
+    // safeParseAsync(undefined, ...) which throws "undefined is not an object (evaluating 's._zod')".
+    // Skip output schemas that are plain unions or discriminated unions to avoid this SDK bug.
+    const rawOutputSchema = descriptor.schemas.output === undefined ? undefined : requireToolZodSchema(descriptor.schemas.output, descriptor.id);
+    const outputSchema = rawOutputSchema ? normalizableOutputSchema(rawOutputSchema) : undefined;
+    // Derive MCP annotations from safety field
+    const annotations = deriveMcpAnnotations(descriptor.safety);
+    // Trust-tag tier is derived from `safety` until `descriptor.capability.tier`
+    // lands in the tier-spec PR (AI-SURFACE-2026-05.md §4.3 step 1). Captured
+    // once at registration so it composes with cache-stable system prompts.
+    const trustTier = deriveTrustTier(descriptor);
+    const toolAccessor = runtime.assets('tools/tool');
+    const isDiscriminated = toolAccessor.isDiscriminated(descriptor.id);
+    let variantSafety;
+    if (isDiscriminated) {
+        const discriminatedDescriptor = toolAccessor.getDiscriminatedDescriptor(descriptor.id);
+        if (discriminatedDescriptor) {
+            const entries = discriminatedDescriptor.variantNames
+                .map((variantName) => [variantName, discriminatedDescriptor.getVariantSafety(variantName)])
+                .filter((entry) => entry[1] !== undefined);
+            if (entries.length > 0) {
+                variantSafety = Object.fromEntries(entries);
+            }
+        }
+    }
+    const isLocal = isLocalToolId(descriptor.id, localToolIds);
+    const origin = vibesToolOrigin(isLocal);
+    const description = formatLocalMcpToolDescription(getDescriptorMcpDescription(descriptor), isLocal);
+    const dispatchRuntime = runtime;
+    const vibesRegistrationMeta = {
+        origin,
+        category: descriptor.category,
+        subcategory: descriptor.subcategory,
+        tags: descriptor.tags,
+        requiresApproval: descriptor.requiresApproval,
+        safety: descriptor.safety,
+        mcpClientId: options.mcpClientId
+    };
+    if (variantSafety)
+        vibesRegistrationMeta.variants = variantSafety;
+    const registrationOptions = {
+        title: descriptor.name ?? descriptor.id,
+        description,
+        inputSchema: inputSchema,
+        outputSchema: outputSchema,
+        annotations,
+        _meta: { vibes: vibesRegistrationMeta }
+    };
+    const handler = async (args, extra, boundInvocation) => {
+        const callId = `mcp_${Date.now()}_${crypto.randomUUID()}`;
+        // Per-call nonce for trust-tag wrapper (F4). Shared across all text items
+        // and error paths in this tool call so the model can verify boundary integrity.
+        const callNonce = crypto.randomUUID();
+        // A body whose executable was replaced on disk says so on EVERY result and
+        // error until it is respawned (stale-body.consumer.ts, handed in by the
+        // consumer serve impl) — the one channel an agent reads on every call.
+        // Computed before `try` so the error path shares it.
+        const stalePrefix = options.staleBodyBanner?.() ?? null;
+        let toolCallCtx;
+        const callStarted = Date.now();
+        const traceStage = (stage) => logger.info('MCP invocation stage', { callId, tool: descriptor.id, stage, elapsedMs: Date.now() - callStarted });
+        traceStage('start');
+        const invocation = boundInvocation?.retain() ?? dispatchRuntime.acquireInvocation();
+        const runtime = invocation.runtime;
+        let callDescriptor = descriptor;
+        try {
+            const attempted = await settle(async () => {
+                // SAFETY: This accessor belongs to the registered tools/tool kind, whose descriptor contract is ToolAssetDescriptor; AssetAccessor erases the descriptor type, not its owner.
+                const currentDescriptor = runtime.assets('tools/tool').descriptor(descriptor.id);
+                if (!currentDescriptor?.schemas?.input)
+                    throw new Error(`Tool '${descriptor.id}' is unavailable in this generation`);
+                callDescriptor = currentDescriptor;
+                const zodSchema = requireToolZodSchema(callDescriptor.schemas.input, callDescriptor.id);
+                const { isUnion, discriminator, unionOptions } = deriveInputSchema(zodSchema);
+                const defaultAction = callDescriptor.schemas.defaultAction;
+                await options.beforeToolCall?.();
+                // Tools parses these raw JSON arguments once with the owner schema.
+                // This handler does not parse them. A missing union discriminator
+                // still defaults only on an admitted object, for the session stamp.
+                const wire = JsonObjectSchema.safeParse(args);
+                if (isUnion && discriminator && !wire.success) {
+                    throw new CapabilityError('the tool arguments are invalid', 'INVALID_INPUT', {
+                        reason: 'mcp-tool-args-invalid'
+                    });
+                }
+                let resolvedArgs = wire.success ? wire.data : {};
+                if (isUnion && discriminator && wire.success && !(discriminator in resolvedArgs)) {
+                    if (defaultAction && unionOptions.includes(defaultAction)) {
+                        resolvedArgs = { [discriminator]: defaultAction, ...resolvedArgs };
+                    }
+                }
+                // The SDK callback does not currently populate `extra.sessionId` for
+                // WebStandard Streamable HTTP. The HTTP adapter therefore gives each
+                // connection a private identity cell when it builds the server. This is
+                // call data, never mutable process-global runtime scope.
+                const transportSessionId = extra.sessionId ?? options.resolveTransportSessionId?.();
+                // A session-family call may name the participant it continues as
+                // (the documented bind flow). That is a binding hint the session layer
+                // verifies, not identity: agent identity comes only from the connection.
+                const callMeta = '_meta' in extra ? asJsonObject(extra._meta) : undefined;
+                const metaParticipantId = (isStringValue(callMeta?.participantId) && callMeta.participantId) ||
+                    (isStringValue(callMeta?.['vibes/participantId']) &&
+                        callMeta['vibes/participantId']) ||
+                    undefined;
+                const connectionKey = transportSessionId ?? serverConnectionKey;
+                // Build context with progress/cancellation support
+                const baseToolCallCtx = {
+                    callId,
+                    logger: logger.child(callDescriptor.id)
+                };
+                if (extra.signal)
+                    baseToolCallCtx.signal = extra.signal;
+                if (extra.sendProgress)
+                    baseToolCallCtx.sendProgress = (progress) => {
+                        const update = { progress: progress.progress, total: progress.total };
+                        if (progress.message)
+                            update.message = progress.message;
+                        extra.sendProgress?.(update);
+                    };
+                // Stamp trusted identity from the runtime's `auth/identity` (the same
+                // builder the tools-cli surface uses). The MCP stdio surface runs as an
+                // authenticated local account; without this, owner-scoped tools
+                // (applet/knowledge/work) fell back to SYSTEM_OWNER and orphaned the
+                // user's artifacts. buildDirectToolCallContext strips any caller-supplied
+                // identity keys (anti-laundering) before stamping userId/actorUserId(+org).
+                traceStage('direct-auth');
+                const directContext = await buildDirectToolCallContext(runtime, baseToolCallCtx);
+                const caller = metaParticipantId && !directContext.caller?.participantId
+                    ? { ...directContext.caller, participantId: metaParticipantId }
+                    : { ...directContext.caller };
+                // Admission (RC08 U7): identity only from what this connection's
+                // transport verified, before the hook bus or any observer runs.
+                const admittedCaller = admitConnectionCaller({
+                    verified: options.resolveVerifiedConnectionIdentity?.() ?? options.verifiedConnectionIdentity,
+                    declared: options.resolveConnectionIdentity?.(),
+                    call: caller,
+                    principal: directContext.metadata
+                });
+                const mcpSettings = await loadMcpConfig(runtime);
+                const resolvedCeiling = resolveMcpClientCapabilityCeiling(mcpSettings, {
+                    admittedCaller,
+                    mcpClientId: options.mcpClientId,
+                    preset: options.preset
+                }, runtime);
+                const agentContext = {
+                    agentId: admittedCaller?.agentId ?? resolvedCeiling.profile ?? 'mcp-client',
+                    ceiling: resolvedCeiling.ceiling,
+                    callChain: []
+                };
+                const metadata = {
+                    ...directContext.metadata,
+                    'mcp.transportMode': options.mode,
+                    [TOOL_AGENT_CONTEXT_METADATA_KEY]: agentContext,
+                    agentCapabilityCeiling: resolvedCeiling.ceiling
+                };
+                if (transportSessionId)
+                    metadata['mcp.transportSessionId'] = transportSessionId;
+                if (connectionKey)
+                    metadata['mcp.connectionKey'] = connectionKey;
+                const directToolCallCtx = {
+                    ...directContext,
+                    caller: admittedCaller,
+                    metadata
+                };
+                traceStage('prepare-context');
+                const preparation = {
+                    context: directToolCallCtx, toolId: callDescriptor.id, input: resolvedArgs, descriptor: callDescriptor
+                };
+                if (transportSessionId)
+                    preparation.transportSessionId = transportSessionId;
+                const preparedToolCallCtx = options.prepareToolCallContext
+                    ? await options.prepareToolCallContext(preparation)
+                    : directToolCallCtx;
+                traceStage('stamp-session');
+                const sessionStampedCtx = await stampMcpSessionCaller(runtime, server, preparedToolCallCtx, transportSessionId ?? connectionKey, options.mode, callDescriptor.id, resolvedArgs, logger);
+                const stampedToolCallCtx = {
+                    ...sessionStampedCtx,
+                    metadata: {
+                        ...sessionStampedCtx.metadata,
+                        [TOOL_AGENT_CONTEXT_METADATA_KEY]: agentContext,
+                        agentCapabilityCeiling: resolvedCeiling.ceiling
+                    }
+                };
+                toolCallCtx = stampedToolCallCtx;
+                // Route through invokeTool so tools/tool hook bus events
+                // (contextBuild / beforeExecute / afterExecute / error) fire
+                // around execution. invokeTool handles discriminated dispatch
+                // internally and propagates hook-enriched error metadata.
+                traceStage('invoke');
+                const execution = {
+                    runtime, toolId: callDescriptor.id, input: args, ctx: stampedToolCallCtx
+                };
+                if (options.toolExecutionTimeoutMs !== undefined && options.toolExecutionTimeoutMs > 0) {
+                    execution.timeoutMs = options.toolExecutionTimeoutMs;
+                }
+                const detachAgentContextHook = runtime
+                    .hooks('tools/tool')
+                    .on('contextBuild', (event) => {
+                    if (event.callId === stampedToolCallCtx.callId) {
+                        event.metadata.set(TOOL_AGENT_CONTEXT_METADATA_KEY, agentContext);
+                    }
+                });
+                const rawOutput = await (async () => {
+                    try {
+                        return await runWithMcpSamplingCallback(options.scopedValues, (request) => server.server.request({ method: 'sampling/createMessage', params: request }, CreateMessageResultSchema, { relatedRequestId: extra.requestId }), () => invokeTool(execution));
+                    }
+                    finally {
+                        detachAgentContextHook();
+                    }
+                })();
+                traceStage('result');
+                const outputSchema = callDescriptor.schemas.output;
+                const lifted = liftAmbientEnvelope(rawOutput, isZodLike(outputSchema) ? outputSchema : undefined);
+                const output = lifted.output;
+                const ambientPrefix = formatAmbientPrefix(lifted);
+                const envelopeMeta = ambientMeta(lifted);
+                const unboundNotice = isStringValue(toolCallCtx.metadata?.['mcp.unboundSessionNotice'])
+                    ? toolCallCtx.metadata['mcp.unboundSessionNotice']
+                    : undefined;
+                if (isZodLike(callDescriptor.schemas.output)) {
+                    const res = callDescriptor.schemas.output.safeParse(output);
+                    if (!res.success) {
+                        const issues = (res.error?.issues ?? [])
+                            .slice(0, 4)
+                            .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+                            .join('; ');
+                        throw new Error(`Invalid output from '${callDescriptor.id}': ${issues}`);
+                    }
+                }
+                // Build content array
+                const content = [];
+                // Trust-tag wrapper (F4 / VIBA-34). Every text payload that reaches the
+                // model gets a nonce-randomized <tool_output> envelope so injected
+                // instructions inside tool output can't impersonate system content.
+                // One nonce per call: shared across all text items and error paths.
+                const resultPrefix = [stalePrefix, unboundNotice, ambientPrefix]
+                    .filter(Boolean)
+                    .join('\n');
+                const wrapText = (text) => wrapToolOutputText({
+                    toolId: callDescriptor.id,
+                    tier: trustTier,
+                    text: resultPrefix ? `${resultPrefix}\n${text}` : text,
+                    nonce: callNonce
+                }).text;
+                // Passthrough for tools that return MCP content directly
+                const mcpResponse = readMcpToolResponse(output);
+                if (mcpResponse) {
+                    const wrappedContent = mcpResponse.content.map((item) => item.type === 'text' ? { ...item, text: wrapText(item.text) } : item);
+                    const result = {
+                        ...mcpResponse,
+                        content: wrappedContent
+                    };
+                    if (envelopeMeta)
+                        result._meta = { ...mcpResponse._meta, ...envelopeMeta };
+                    return result;
+                }
+                // Handle string output
+                if (isStringValue(output)) {
+                    const result = {
+                        content: [{ type: 'text', text: wrapText(output) }]
+                    };
+                    if (envelopeMeta)
+                        result._meta = envelopeMeta;
+                    return result;
+                }
+                // JSON wire form: undefined fields omitted, arrays kept. Never String() an object or array.
+                const serialized = settleNow(() => JSON.stringify(output));
+                if (!serialized.ok) {
+                    throw new CapabilityError('the tool output is not JSON', 'INVALID_INPUT', {
+                        reason: 'mcp-tool-output-not-json',
+                        cause: serialized.cause
+                    });
+                }
+                const jsonText = JsonTextSchema.safeParse(serialized.value);
+                if (!jsonText.success) {
+                    throw new CapabilityError('the tool output is not JSON', 'INVALID_INPUT', {
+                        reason: 'mcp-tool-output-not-json'
+                    });
+                }
+                const wired = wireJsonText(jsonText.data);
+                content.push({
+                    type: 'text',
+                    text: wrapText(wired.text)
+                });
+                // Add resource links if present (must include required 'name' field per MCP ResourceSchema)
+                const resourceLinkValue = wired.structured?.resourceLinks;
+                const resourceLinks = Array.isArray(resourceLinkValue)
+                    ? z.array(ResourceLinkSchema.pick({ uri: true, mimeType: true })).parse(resourceLinkValue)
+                    : [];
+                if (resourceLinks.length > 0) {
+                    for (const link of resourceLinks) {
+                        if (link?.uri) {
+                            const resourceLink = {
+                                type: 'resource_link',
+                                name: link.uri.split('/').pop() || link.uri,
+                                uri: link.uri
+                            };
+                            if (link.mimeType)
+                                resourceLink.mimeType = link.mimeType;
+                            content.push(resourceLink);
+                        }
+                    }
+                }
+                const result = { content };
+                // Plain object outputs retain typed data without requiring clients to parse text.
+                if (wired.structured)
+                    result.structuredContent = wired.structured;
+                if (envelopeMeta)
+                    result._meta = envelopeMeta;
+                return result;
+            });
+            if (attempted.ok)
+                return attempted.value;
+            const error = attempted.cause;
+            const caught = error;
+            const message = modelSafeFailureText(caught);
+            logger.child('tool').error(`Execution failed: ${callDescriptor.id}`, {
+                failure: valueFreeFailure(caught),
+                excerpt: caught instanceof Error ? redactedExcerpt(caught.message) : undefined
+            });
+            // Format error with structured metadata for MCP
+            const parsedHookFailure = ToolHookFailureSchema.safeParse(error);
+            const toolError = parsedHookFailure.success ? parsedHookFailure.data : undefined;
+            const suggestedToolCall = getSuggestedToolCallFromErrorMetadata(toolError?.metadata);
+            // invokeTool attaches `recoveryHint` / `retryable` onto the
+            // thrown error after hook-bus `error` subscribers run. Surface
+            // them even when the error isn't a structured ToolError.
+            const hookRecoveryHint = toolError?.recoveryHint;
+            const hookRetryable = toolError?.retryable;
+            // Wrap error text in the same trust-tag envelope: error messages flow
+            // back into model context exactly like success output and so share the
+            // same prompt-injection surface. Uses the same per-call nonce for
+            // boundary integrity across success and error paths.
+            const unboundNotice = isStringValue(toolCallCtx?.metadata?.['mcp.unboundSessionNotice'])
+                ? toolCallCtx.metadata['mcp.unboundSessionNotice']
+                : undefined;
+            const errorPrefix = [stalePrefix, unboundNotice].filter(Boolean).join('\n');
+            const errorContent = {
+                type: 'text',
+                text: wrapToolOutputText({
+                    toolId: callDescriptor.id,
+                    tier: trustTier,
+                    text: errorPrefix ? `${errorPrefix}\n${message}` : message,
+                    nonce: callNonce
+                }).text
+            };
+            // CapabilityError is the runtime-owned cross-surface outcome contract
+            // (@vibesdotdev/kernel, outcome/capability-error.ts) — the harvested
+            // generalization of ToolError with the TOOL_ prefix dropped from the
+            // code vocabulary. The explicit naming correspondence between the two
+            // small enums (do NOT re-derive by string surgery):
+            //   NOT_FOUND ↔ TOOL_NOT_FOUND, PERMISSION_DENIED ↔ TOOL_PERMISSION_DENIED,
+            //   RATE_LIMITED ↔ TOOL_RATE_LIMITED, TIMEOUT ↔ TOOL_TIMEOUT,
+            //   CANCELLED ↔ TOOL_CANCELLED, INTERNAL ↔ TOOL_INTERNAL_ERROR,
+            //   INVALID_INPUT ↔ TOOL_VALIDATION_FAILED;
+            //   AUTH_REQUIRED / CONFLICT / UNAVAILABLE have no ToolError twin.
+            // Per the contract ("MCP → _meta.errorCode + retryable + recoveryHint")
+            // the stable capability code goes on the wire UNTRANSLATED — squashing
+            // the twin-less codes into a generic TOOL_* code would lose exactly the
+            // signal the contract exists to carry. Same _meta shape as ToolError.
+            // This branch runs FIRST: CapabilityError also has a truthy `.code`, so
+            // the ToolError duck-typed branch below would otherwise swallow it and
+            // drop the contract's `retryable`/`details` projection.
+            let structuredMeta;
+            if (error instanceof Error && isCapabilityError(error)) {
+                structuredMeta = {
+                    errorCode: error.code,
+                    recoveryHint: error.recoveryHint ?? hookRecoveryHint,
+                    retryable: error.retryable
+                };
+                if (error.details !== undefined)
+                    structuredMeta.errorMetadata = error.details;
+            }
+            else if (toolError?.code) {
+                structuredMeta = {
+                    errorCode: toolError.code,
+                    recoveryHint: toolError.recoveryHint ?? hookRecoveryHint,
+                    alternatives: toolError.alternatives,
+                    errorMetadata: toolError.metadata
+                };
+                if (hookRetryable !== undefined)
+                    structuredMeta.retryable = hookRetryable;
+            }
+            else if (hookRecoveryHint || hookRetryable !== undefined || suggestedToolCall) {
+                structuredMeta = {};
+                if (hookRecoveryHint)
+                    structuredMeta.recoveryHint = hookRecoveryHint;
+                if (hookRetryable !== undefined)
+                    structuredMeta.retryable = hookRetryable;
+            }
+            if (structuredMeta && suggestedToolCall)
+                structuredMeta.suggestedToolCall = suggestedToolCall;
+            const failure = projectMcpToolFailure(error);
+            const existingCode = structuredMeta && 'errorCode' in structuredMeta
+                ? structuredMeta.errorCode
+                : undefined;
+            const errorResponse = {
+                content: [errorContent],
+                isError: true,
+                _meta: { ...structuredMeta, errorCode: existingCode ?? failure.code }
+            };
+            return errorResponse;
+        }
+        finally {
+            invocation.release();
+        }
+    };
+    const registration = server.registerTool(mcpWireToolName(descriptor.id, options.mcpClientId, options.customPresets), registrationOptions, handler);
+    const entries = registeredTools.get(server) ?? new Map();
+    entries.set(mcpWireToolName(descriptor.id, options.mcpClientId, options.customPresets), { registration, invoke: handler });
+    registeredTools.set(server, entries);
+    return true;
+}
+/**
+ * Stamp MCP client + session-participant identity onto the tool ctx so
+ * session-collaborate send/mark-read can resolve the caller without
+ * fromParticipant / participantId.
+ */
+/** One unbound-session notice per MCP transport connection, per root (views and generations share it). */
+function takeUnboundSessionNoticeSlot(runtime, connectionId) {
+    const key = connectionId ?? 'stdio';
+    const issued = requireMcpClient(runtime).unboundSessionNotices;
+    if (issued.has(key))
+        return false;
+    issued.add(key);
+    if (issued.size > 256) {
+        const first = issued.values().next().value;
+        if (first)
+            issued.delete(first);
+    }
+    return true;
+}
+async function resolveWorkspacePath(runtime) {
+    const attempted = await settle(() => runtime.context('runtime/workspace-path'));
+    if (!attempted.ok) {
+        // An unbound workspace is a fact, not a failure; anything else is logged with its reason.
+        const error = attempted.cause;
+        if (!(error instanceof Error && isCapabilityError(error) && error.reason === 'workspace-unbound')) {
+            getLogger('mcp', runtime).debug('workspace path unavailable for the tool call', { failure: valueFreeFailure(error) });
+        }
+        return undefined;
+    }
+    return isStringValue(attempted.value) && attempted.value.length > 0 ? attempted.value : undefined;
+}
+async function stampMcpSessionCaller(runtime, server, ctx, transportSessionId, mode, toolId, input, logger) {
+    const mcpSessionId = transportSessionId ?? null;
+    let transportParticipantId;
+    let sessionUtils;
+    const stamped = await settle(async () => {
+        sessionUtils = await import('@vibesdotdev/session/mcp/utils/participant');
+        const mcpSessionRegistry = await resolveMcpTransportRegistry(runtime);
+        const clientVersion = server.server.getClientVersion?.();
+        const existing = mcpSessionRegistry.getClientInfo(mcpSessionId);
+        // The connection declares its harness session; a shared host never reads
+        // its own environment for it (that is whichever harness started the host).
+        const harnessSessionId = ctx.caller?.harnessSessionId ?? existing?.harnessSessionId;
+        const agentId = ctx.caller?.agentId ?? existing?.agentId;
+        if (clientVersion?.name || existing || harnessSessionId || agentId) {
+            const clientInfo = {
+                ...existing,
+                name: clientVersion?.name ?? existing?.name ?? 'mcp-client',
+                version: clientVersion?.version ?? existing?.version,
+                transport: mode === 'http' ? 'http' : 'stdio',
+                connectionId: mcpSessionId ?? existing?.connectionId
+            };
+            if (agentId)
+                clientInfo.agentId = agentId;
+            if (harnessSessionId)
+                clientInfo.harnessSessionId = harnessSessionId;
+            mcpSessionRegistry.setClientInfo(mcpSessionId, clientInfo);
+        }
+        if (mcpSessionId) {
+            const previous = mcpSessionRegistry.getConnectionState(mcpSessionId);
+            transportParticipantId =
+                (previous && 'participantId' in previous && isStringValue(previous.participantId) ? previous.participantId : undefined) ??
+                    previous?.agentId ??
+                    undefined;
+            mcpSessionRegistry.setConnectionState(mcpSessionId, {
+                ...previous,
+                transport: mode === 'http' ? 'http' : 'stdio',
+                connectionId: mcpSessionId,
+                sessionId: previous?.sessionId,
+                agentId: previous?.agentId ?? null,
+                agentSlug: previous?.agentSlug ?? null
+            });
+        }
+    });
+    if (!stamped.ok) {
+        // Session registry is optional for non-session MCP surfaces, but a real
+        // failure still degrades downstream participant resolution — leave a
+        // diagnostic instead of vanishing.
+        logger.warn('MCP session caller stamping failed; participant resolution may degrade', {
+            failure: valueFreeFailure(stamped.cause),
+            toolId
+        });
+    }
+    const isSessionFamilyTool = toolId === 'session' || toolId.startsWith('session-');
+    const { participantId: _hintParticipant, sessionId: _hintSession, ...unboundCaller } = ctx.caller ?? {};
+    if (!runtime.hasContext('session/manager')) {
+        return { ...ctx, caller: unboundCaller };
+    }
+    const receiptRestore = toolId === 'session' ? receiptRestoreInputSchema.safeParse(input) : undefined;
+    const receiptRestoreParticipantId = receiptRestore?.success
+        ? receiptRestore.data.participantId
+        : undefined;
+    let authoritativeParticipantId = ctx.caller?.participantId ?? transportParticipantId ?? receiptRestoreParticipantId;
+    // The session family is the only consumer of caller.sessionId stamping; the
+    // no-durable-session branch below exempted nothing, which gated stateless
+    // tools behind session-authority repair.
+    const reconciled = await settle(async () => {
+        const manager = await runtime.context('session/manager');
+        if (!isSessionFamilyTool) {
+            // Ordinary tools cannot self-identify as another seat through request metadata.
+            authoritativeParticipantId = await manager.resolveMcpParticipant({}, mcpSessionId);
+        }
+        else {
+            authoritativeParticipantId ??= await manager.resolveMcpParticipant({}, mcpSessionId, ctx.caller);
+        }
+        if (!authoritativeParticipantId) {
+            throw new Error('Session manager did not resolve an MCP participant');
+        }
+        const participantSession = await manager.ensureParticipantSession(authoritativeParticipantId);
+        if (!participantSession) {
+            // A brand-new MCP body has no session by definition. Permit discovery
+            // (list/search/status/get) and init so the caller can bind or create,
+            // and strip any stale prepared session so neither can inherit another
+            // body's custody.
+            const workspacePath = await resolveWorkspacePath(runtime);
+            if (!isSessionFamilyTool) {
+                // Tools outside the session family never consume
+                // caller.sessionId; failing them here gated stateless tools
+                // (calculate & co.) behind session-authority repair. Stamp the
+                // participant identity only, and tell the agent once per
+                // connection that it is unbound.
+                const { sessionId: _staleSessionId, ...caller } = ctx.caller ?? {};
+                let notice;
+                if (takeUnboundSessionNoticeSlot(runtime, mcpSessionId) && sessionUtils) {
+                    const guidance = await sessionUtils.buildUnboundSessionGuidance(manager, {
+                        workspacePath
+                    });
+                    notice = sessionUtils.renderUnboundSessionGuidance(guidance);
+                }
+                const metadata = { ...ctx.metadata };
+                if (notice)
+                    metadata['mcp.unboundSessionNotice'] = notice;
+                return {
+                    ...ctx,
+                    caller: { ...caller, participantId: authoritativeParticipantId },
+                    metadata
+                };
+            }
+            const getNeedsId = toolId === 'session' &&
+                input.action === 'get' &&
+                !explicitSessionTargetSchema.safeParse(input).success;
+            // Resume repairs an inactive binding. It must reach its owner with the
+            // participant identity, but without borrowing the closed session's custody.
+            const explicitResume = toolId === 'session' && explicitResumeInputSchema.safeParse(input).success;
+            if (!getNeedsId &&
+                (explicitResume || sessionUtils?.isSessionDiscoveryCall(toolId, input.action) ||
+                    (!sessionUtils &&
+                        toolId === 'session' &&
+                        (input.action === 'init' || input.action === 'status')))) {
+                const { sessionId: _staleSessionId, ...caller } = ctx.caller ?? {};
+                return {
+                    ...ctx,
+                    caller: { ...caller, participantId: authoritativeParticipantId }
+                };
+            }
+            if (sessionUtils) {
+                const fields = await sessionUtils.unboundSessionErrorFields(manager, { workspacePath });
+                throw sessionUtils.createSessionToolError('SESSION_NOT_ACTIVE', fields.message, fields.hint, fields.details);
+            }
+            throw new Error(`Participant ${authoritativeParticipantId} has no durable active session (call session { action: "init" } to bind one, or resume the archived session explicitly)`);
+        }
+        if (mcpSessionId) {
+            sessionUtils?.bindRuntimeConnectionReceipt(runtime, mcpSessionId, authoritativeParticipantId, participantSession.id);
+        }
+        return {
+            ...ctx,
+            caller: {
+                ...ctx.caller,
+                participantId: authoritativeParticipantId,
+                sessionId: participantSession.id
+            }
+        };
+    });
+    if (reconciled.ok)
+        return reconciled.value;
+    const error = reconciled.cause;
+    if (!isSessionFamilyTool) {
+        // Session-authority failures (storage unavailable, unreadable routing
+        // rows) must not take down tools that never touch session state. Run
+        // unqualified rather than wedging stateless tools behind identity
+        // repair.
+        logger.warn('MCP participant reconciliation failed; running non-session tool without session identity', { toolId, failure: valueFreeFailure(error) });
+        return { ...ctx, caller: unboundCaller };
+    }
+    if (sessionUtils?.isSessionToolError(error, 'SESSION_NOT_ACTIVE'))
+        throw error;
+    throw new Error(`Cannot reconcile MCP participant ${authoritativeParticipantId ?? 'from the session authority'} to a session`, { cause: error });
+}
+//# sourceMappingURL=server.js.map