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

package/dist/adapters/mcp/tool-catalog.js

@@ -0,0 +1,330 @@
+/**
+ * The MCP tool catalog: what this runtime serves, computed once per registry
+ * revision instead of once per connection.
+ *
+ * WHY THIS IS A SEPARATE MODULE. `buildServer` used to do two unrelated things
+ * in one pass: (1) ask the runtime registry what tools exist, filter them to
+ * enabled, select by preset, and compose the `instructions` banner; and (2)
+ * construct an `McpServer` and register that selection on it. Only (2) is
+ * per-connection — an `McpServer` owns transport state and cannot be shared.
+ * (1) is a pure fold over the registry and is byte-identical for identical
+ * inputs, yet the HTTP session handler called it on every `initialize`. On this
+ * machine that ran 7,291 times in 53 hours of uptime, logging a full discovery
+ * block each time. `host-registry.ts` already documents the intended contract —
+ * "a host resolves its tool catalog ONCE at boot … and bakes it into a single
+ * McpServer" — and this module is what makes the HTTP path keep it.
+ *
+ * WHY A REVISION KEY AND NOT A TTL. A memoized catalog that serves a stale
+ * toolset is worse than no memo: an agent quietly holding the wrong tools is
+ * exactly the injury class this file's warnings exist to prevent, and a TTL
+ * guarantees a window where that is true. `runtime.descriptorRevision` is a
+ * monotonic counter the runtime bumps on every registration, retraction, kind
+ * change, plugin install and plugin retraction — so with hot reload landed
+ * (`retractPlugin`/`swapPlugin`), registry mutation is *observable* and the
+ * cache can be exact. If the revision has not moved, no descriptor, kind,
+ * plugin or enablement flag has moved either, and the fold cannot differ.
+ *
+ * The project-local tool ids (the tools discovery registered from
+ * `.vibes/tools`, or the caller's explicit set) are part of the key too —
+ * supplied by the caller, because reading them is a node-scoped import and
+ * this fold stays isomorphic.
+ */
+import { formatLocalToolsMcpInstructions } from "./local-origin.js";
+import { runtimePurposePresets, purposePresetPolicyKey } from '@vibesdotdev/tools/schemas/presets/registry';
+import { missingRequiredTools, selectMcpTools } from "./tool-selection.js";
+import { isolatedRuntimeInstructions } from "./isolated-notice.js";
+import { renderPromptManifest } from '@vibesdotdev/ai-schemas';
+// The banners are prompts/manifest descriptors; this fold is synchronous and
+// memoized, so it renders each descriptor's own manifest.
+import continuityWakePrompt from "./prompts/continuity-wake.prompt.descriptor.js";
+import emptyToolKindPrompt from "./prompts/empty-tool-kind.prompt.descriptor.js";
+import maxToolsPrompt from "./prompts/max-tools.prompt.descriptor.js";
+import registrationFailurePrompt from "./prompts/registration-failure.prompt.descriptor.js";
+import requiredChecklistPrompt from "./prompts/required-checklist.prompt.descriptor.js";
+import requiredToolsMissingPrompt from "./prompts/required-tools-missing.prompt.descriptor.js";
+import unknownClientPrompt from "./prompts/unknown-client.prompt.descriptor.js";
+function isToolAsset(descriptor) {
+    return descriptor.kind === 'tools/tool' && 'schemas' in descriptor;
+}
+export function hasMcpResources(descriptor) {
+    const mcp = descriptor.mcp;
+    return (!!mcp &&
+        (!!mcp.resource || (mcp.resources?.length ?? 0) > 0 || (mcp.resourceTemplates?.length ?? 0) > 0));
+}
+export function hasMcpPrompts(descriptor, options) {
+    const mcp = descriptor.mcp;
+    if (!mcp)
+        return false;
+    return options.canResolvePromptIds && (mcp.promptIds?.length ?? 0) > 0;
+}
+export function formatRegistrationFailureInstructions(failedTools) {
+    return renderPromptManifest(registrationFailurePrompt.manifest, {
+        count: failedTools.length,
+        failures: `${failedTools.slice(0, 12).join('; ')}${failedTools.length > 12 ? '…' : ''}`
+    });
+}
+/**
+ * Every input to the fold that `descriptorRevision` does not already cover.
+ *
+ * Keep this honest: anything read by `computeMcpToolCatalog` that can change
+ * without a registry mutation MUST appear here, or the cache serves stale.
+ */
+export function catalogCacheKey(runtime, localToolIds, configured) {
+    // Registry revisions already bind owner declarations; only configured input
+    // lies outside that journal. Cache hits need no Config-manifest enumeration.
+    return `${runtime.descriptorRevision}|local:${[...localToolIds].sort().join(',')}|policy:${purposePresetPolicyKey(configured ?? {})}`;
+}
+/**
+ * Fold the runtime registry into the catalog this surface serves.
+ *
+ * Pure with respect to the registry: no `McpServer`, no transport, no
+ * per-connection state. Logs the discovery block, so callers that memoize get
+ * one block per revision rather than one per connection.
+ */
+export function computeMcpToolCatalog(runtime, options, logger, 
+/** Project-local catalog ids (CLI list source=local parity), already resolved. */
+localToolIds, 
+/**
+ * The caller's registration bound for this fold. Defaults to `'advisory'`:
+ * unavailable descriptors stay selected and are warned about. Only a caller
+ * that can name the bound (see {@link McpLoaderSettlement}) passes
+ * `'settled'` to exclude them.
+ */
+loaderSettlement = 'advisory') {
+    const buildLog = logger.child('build');
+    const revision = runtime.descriptorRevision;
+    const key = catalogCacheKey(runtime, localToolIds, options.customPresets);
+    const purposePresets = runtimePurposePresets(runtime, options.customPresets);
+    buildLog.debug('Folding MCP tool catalog', {
+        hasToolKind: runtime.hasKind('tools/tool'),
+        scope: runtime.scope,
+        descriptorRevision: revision
+    });
+    if (!runtime.hasKind('tools/tool')) {
+        // Constitution rule 13: empty tools/list must not look healthy.
+        // Same continuity contract as missing requiredTools — ride MCP
+        // `instructions` so the host agent cannot miss the injury.
+        const emptyKindInstructions = renderPromptManifest(emptyToolKindPrompt.manifest, {
+            registeredKinds: runtime.kindIds().join(', ')
+        });
+        buildLog.error('tools/tool kind is not registered — surface degraded', {
+            registeredKinds: runtime.kindIds()
+        });
+        return {
+            revision,
+            purposePresets,
+            key,
+            loaderSettlement,
+            degradedKind: true,
+            capabilities: { tools: { listChanged: true } },
+            instructions: emptyKindInstructions,
+            descriptors: [],
+            enabledDescriptors: [],
+            selected: null,
+            localToolIds,
+            totalDescriptors: 0,
+            preScanFailedTools: [],
+            zombieCandidates: [],
+            announced: false
+        };
+    }
+    const allDescriptors = runtime.query('tools/tool').descriptors();
+    const enabledDescriptors = runtime
+        .query('tools/tool')
+        .enabled()
+        .descriptors()
+        .filter(isToolAsset);
+    // Zombie handling: descriptors without a loader resolvable RIGHT NOW would
+    // throw "No implementation registered" if called. They are always reported;
+    // they are excluded from the selection only when the caller declared
+    // registration `'settled'` (see McpLoaderSettlement for the bound). In
+    // advisory mode a hard filter here would drop healthy tools — verified live
+    // 2026-06-11 when it silently excluded the whole session family.
+    //
+    // `availableIds` is computed once per fold and used twice: as the advisory
+    // list in every mode, and as the selection filter only in `'settled'` mode.
+    const availableIds = new Set(runtime.assets('tools/tool').available());
+    const zombieCandidates = enabledDescriptors
+        .filter((descriptor) => !availableIds.has(descriptor.id))
+        .map((descriptor) => descriptor.id);
+    if (zombieCandidates.length > 0) {
+        buildLog.warn(loaderSettlement === 'settled'
+            ? 'Descriptors without loaders resolvable at build time (excluded — settled registration)'
+            : 'Descriptors without loaders resolvable at build time (advisory)', { zombieCandidates });
+    }
+    const selection = { mcpClientId: options.mcpClientId, customPresets: purposePresets };
+    if (options.preset)
+        selection.preset = options.preset;
+    if (options.toolPatterns && options.toolPatterns.length > 0) {
+        selection.toolPatterns = [...options.toolPatterns];
+    }
+    if (loaderSettlement === 'settled')
+        selection.availableIds = availableIds;
+    const selected = selectMcpTools(enabledDescriptors, selection);
+    const hasResources = selected.descriptors.some((descriptor) => hasMcpResources(descriptor));
+    const canResolvePromptIds = runtime.hasKind('prompts/manifest');
+    const hasPrompts = selected.descriptors.some((descriptor) => hasMcpPrompts(descriptor, { canResolvePromptIds }));
+    const capabilities = {
+        tools: { listChanged: true }
+    };
+    if (hasResources)
+        capabilities.resources = { listChanged: true };
+    if (hasPrompts)
+        capabilities.prompts = { listChanged: true };
+    // Continuity contract: a preset's requiredTools MUST be in the final
+    // selection. If not, the surface is degraded and that fact must be
+    // impossible to miss — error log here, and the degradation notice rides
+    // the MCP `instructions` field so the connected agent reads it at session
+    // start. Agents must surface it to the user, not work around it.
+    const missingRequired = missingRequiredTools(selected.descriptors.map((descriptor) => descriptor.id), selected.preset);
+    let degradedInstructions;
+    if (missingRequired.length > 0) {
+        buildLog.error('REQUIRED MCP TOOLS MISSING — surface degraded', {
+            presetId: selected.presetId,
+            missingRequired
+        });
+        degradedInstructions = renderPromptManifest(requiredToolsMissingPrompt.manifest, {
+            presetId: selected.presetId,
+            missingTools: missingRequired.join(', ')
+        });
+    }
+    // Unknown-client degradation, second line of defence. mcp:custom now
+    // inherits agent-core, so a genuinely absent organ is caught by
+    // missingRequiredTools above. This banner covers what that check cannot
+    // see: a fall-through to a preset carrying no organ contract at all,
+    // where there is nothing for the check above to find missing.
+    if (selected.degraded && !degradedInstructions) {
+        buildLog.error('UNKNOWN MCP CLIENT — surface degraded', {
+            requestedClientId: options.mcpClientId,
+            resolvedPresetId: selected.presetId,
+            degraded: selected.degraded
+        });
+        degradedInstructions = renderPromptManifest(unknownClientPrompt.manifest, { degraded: selected.degraded });
+    }
+    // When the continuity body (brain + presence) rides this surface, every
+    // connected agent — any client, any machine — wakes to the same invitation
+    // the repository-collection docs carry. The runtime projecting capability outward and
+    // projecting a self inward are one act (EXTERNAL-AS-RUNTIME-PROJECTION.md).
+    const selectedIds = new Set(selected.descriptors.map((descriptor) => descriptor.id));
+    const wakeInstructions = selectedIds.has('brain') && selectedIds.has('presence')
+        ? renderPromptManifest(continuityWakePrompt.manifest)
+        : undefined;
+    // Client-side drop sensor: selection + registration guards above prove the
+    // SERVER served the required tools — but a client harness can still drop
+    // them from ITS index silently (observed 2026-07-16: Claude Code dropped
+    // exactly 8 served tools incl. brain while the server was provably healthy
+    // end-to-end). The agent is the only observer on that side of the wire, so
+    // hand it the checklist to verify against the tool list it actually sees.
+    const requiredToolIds = [...(selected.preset?.requiredTools ?? [])].sort();
+    const requiredChecklistInstructions = requiredToolIds.length > 0
+        ? renderPromptManifest(requiredChecklistPrompt.manifest, { requiredTools: requiredToolIds.join(', ') })
+        : undefined;
+    const maxToolsInstructions = selected.limitedFrom !== undefined && selected.limitedFrom > selected.descriptors.length
+        ? renderPromptManifest(maxToolsPrompt.manifest, {
+            presetId: selected.presetId ?? 'unknown',
+            selected: selected.descriptors.length,
+            eligible: selected.limitedFrom
+        })
+        : undefined;
+    const localToolsInstructions = formatLocalToolsMcpInstructions(localToolIds);
+    // Pre-scan schema gaps before McpServer construct so instructions can name them.
+    // Late registerTool failures are appended to SDK `_instructions` after the
+    // registration loop (mutable private; initialize reads the field, not a frozen copy).
+    const preScanFailedTools = selected.descriptors
+        .filter((descriptor) => !descriptor.schemas?.input)
+        .map((descriptor) => `${descriptor.id}: no schemas.input — skipped`);
+    const discovery = {
+        totalDescriptors: allDescriptors.length,
+        enabledDescriptors: enabledDescriptors.length,
+        selectedDescriptors: selected.descriptors.length,
+        presetId: selected.presetId,
+        localToolCount: localToolIds.length,
+        descriptorRevision: revision
+    };
+    if (selected.limitedFrom)
+        discovery.limitedFrom = selected.limitedFrom;
+    buildLog.info('Tool discovery results', discovery);
+    const registrationFailureInstructions = preScanFailedTools.length > 0
+        ? formatRegistrationFailureInstructions(preScanFailedTools)
+        : undefined;
+    const instructions = [
+        degradedInstructions,
+        requiredChecklistInstructions,
+        maxToolsInstructions,
+        registrationFailureInstructions,
+        localToolsInstructions,
+        // Ahead of provenance: if this runtime is private, that is the first thing
+        // worth knowing about the body you just woke up in.
+        isolatedRuntimeInstructions(options.isolation),
+        wakeInstructions
+    ]
+        .filter((section) => Boolean(section))
+        .join('\n\n');
+    return {
+        revision,
+        purposePresets,
+        key,
+        loaderSettlement,
+        degradedKind: false,
+        capabilities,
+        instructions,
+        descriptors: selected.descriptors,
+        enabledDescriptors,
+        selected,
+        localToolIds,
+        totalDescriptors: allDescriptors.length,
+        preScanFailedTools,
+        zombieCandidates,
+        announced: false
+    };
+}
+/**
+ * Memoize `computeMcpToolCatalog` against the runtime's registry revision.
+ *
+ * One cache per serving surface (the HTTP session handler builds one and every
+ * session draws from it). The `McpServer` stays per-connection; only the fold
+ * is shared.
+ *
+ * `loaderSettlement` is fixed for the cache's whole life — it is the caller's
+ * registration bound, not a per-call option. It deliberately does not enter
+ * the cache key: the key must describe the registry state this fold was
+ * computed from, and a cache that could flip policies would report one key for
+ * two different folds.
+ */
+export function createMcpToolCatalogCache(runtime, options, logger, 
+/**
+ * Resolves the project-local tool ids at call time. Injected rather than
+ * imported: reading them is node-scoped, and this module is in the
+ * isomorphic root closure.
+ */
+resolveLocalToolIds, loaderSettlement = 'advisory') {
+    let cached = null;
+    let folds = 0;
+    let hits = 0;
+    return {
+        get() {
+            const localToolIds = resolveLocalToolIds();
+            const key = catalogCacheKey(runtime, localToolIds, options.customPresets);
+            if (cached && cached.key === key) {
+                hits += 1;
+                return cached;
+            }
+            if (cached) {
+                logger.child('build').info('Registry moved — refolding MCP tool catalog', {
+                    from: cached.key,
+                    to: key
+                });
+            }
+            cached = computeMcpToolCatalog(runtime, options, logger, localToolIds, loaderSettlement);
+            folds += 1;
+            return cached;
+        },
+        stats() {
+            return { folds, hits, key: cached?.key ?? null };
+        },
+        invalidate() {
+            cached = null;
+        }
+    };
+}
+//# sourceMappingURL=tool-catalog.js.map

package/dist/adapters/mcp/tool-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-catalog.js","sourceRoot":"","sources":["../../../src/adapters/mcp/tool-catalog.ts"],"names":[],"mappings":"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"}

package/dist/adapters/mcp/tool-selection.d.ts

@@ -0,0 +1,77 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import type { ToolAssetDescriptor } from '@vibesdotdev/tools/schemas/runtime/descriptors';
+import type { PurposePreset } from '@vibesdotdev/tools/schemas/presets/schema';
+import type { SelectMcpToolsOptions, SelectMcpToolsResult } from './schemas/index.ts';
+/**
+ * Canonical registry id for a `--preset` value: `full` → `mcp:full`; the base
+ * catalog `mcp` and already-prefixed `mcp:*` ids pass through unchanged.
+ */
+export declare function canonicalMcpPresetId(raw: string): string;
+/** Every value `--preset` accepts: the base catalog plus each registered `mcp:*` id. */
+export declare function knownMcpPresetNames(customPresets?: Record<string, PurposePreset>): string[];
+/** Stable reason on the CapabilityError an unregistered explicit `--preset` throws. */
+export declare const UNKNOWN_MCP_PRESET_REASON = "mcp-preset-unknown";
+/**
+ * An explicit `--preset` named no registered catalog. Callers keep this class.
+ * It is a CapabilityError so a typed refusal and `instanceof CapabilityError` agree.
+ */
+export declare class UnknownMcpPresetError extends CapabilityError {
+    constructor(requested: string, known?: readonly string[]);
+}
+/**
+ * Resolve the catalog preset a serve identity lands on. Exported so the stdio
+ * relay can compare a client against a host claim with the SAME resolution the
+ * host used to write that claim (`mcp:full`), instead of the raw flag value
+ * (`full`) — which never matched and sent every client to an isolated runtime.
+ *
+ * An explicit preset is STRICT (throws CapabilityError reason
+ * {@link UNKNOWN_MCP_PRESET_REASON} when it names nothing registered). Only
+ * the client id has fall-through semantics — alias detection, then
+ * `mcp:custom`, then base `mcp`.
+ */
+export interface ResolvedMcpPreset {
+    presetId: string;
+    preset: PurposePreset;
+    degraded?: string;
+}
+export declare function resolveMcpPreset(clientId?: string, explicitPreset?: string, customPresets?: Record<string, PurposePreset>): ResolvedMcpPreset;
+/**
+ * Hosts bake one catalog at boot. Harness aliases of the default full local
+ * wire (`mcp`, `mcp:full`, `mcp:grok`, `mcp:claude`, …) attach to each other.
+ * Named user restrictions (`mcp:minimal`, `mcp:presence`, `mcp:code`,
+ * `mcp:workspace`) and `mcp:cloud` stay distinct so a compact or cloud
+ * request is never silently given a different catalog.
+ */
+export declare function mcpCatalogAttachKey(presetId: string | undefined, customPresets?: Record<string, PurposePreset>): string | undefined;
+export interface McpToolExclusion {
+    id: string;
+    reason: string;
+}
+export interface McpToolSelectionExplanation {
+    presetId: string;
+    included: string[];
+    excluded: McpToolExclusion[];
+    limitedFrom?: number;
+    /**
+     * Non-undefined when the client id fell through to mcp:custom/base
+     * (unknown client, no alias resolved). See SelectMcpToolsResult.degraded.
+     */
+    degraded?: string;
+}
+/**
+ * Mirror of selectMcpTools that reports WHY each excluded tool was excluded
+ * (purpose mismatch, explicit preset disable, disabled pattern, no enabled
+ * pattern match, maxTools truncation). Exists so the serve path can log the
+ * exposure funnel — tools used to vanish from MCP with zero trace (the
+ * brain/presence outage of 2026-06).
+ */
+export declare function explainMcpToolSelection(descriptors: ToolAssetDescriptor[], options?: SelectMcpToolsOptions): McpToolSelectionExplanation;
+/**
+ * Tool ids the preset declares as REQUIRED but which are absent from the
+ * final selection. A non-empty result means the surface is degraded — the
+ * caller must make that impossible to miss (error log + MCP instructions),
+ * never silently proceed. Continuity contract, 2026-06-11.
+ */
+export declare function missingRequiredTools(selectedIds: ReadonlySet<string> | string[], preset: PurposePreset): string[];
+export declare function selectMcpTools(descriptors: ToolAssetDescriptor[], options?: SelectMcpToolsOptions): SelectMcpToolsResult;
+//# sourceMappingURL=tool-selection.d.ts.map

package/dist/adapters/mcp/tool-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-selection.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/tool-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAU1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAGtF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,MAAM,EAAE,CAE3F;AAED,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,uBAAuB,CAAC;AAE9D;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;gBAC7C,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAA0B;CAU/E;AAcD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAC/B,QAAQ,CAAC,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,iBAAiB,CAuDnB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,MAAM,GAAG,SAAS,CAmBpB;AA8DD,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,WAAW,EAAE,mBAAmB,EAAE,EAClC,OAAO,GAAE,qBAA0B,GACjC,2BAA2B,CAgE7B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,EAC3C,MAAM,EAAE,aAAa,GACnB,MAAM,EAAE,CAKV;AAED,wBAAgB,cAAc,CAC7B,WAAW,EAAE,mBAAmB,EAAE,EAClC,OAAO,GAAE,qBAA0B,GACjC,oBAAoB,CAmCtB"}