@vurb/core 3.2.0

package/dist/server/ServerAttachment.js

@@ -0,0 +1,709 @@
+/**
+ * ServerAttachment — MCP Server Integration Strategy
+ *
+ * Handles attaching a ToolRegistry to an MCP Server by registering
+ * request handlers for tools/list and tools/call.
+ *
+ * Supports both Server (low-level) and McpServer (high-level) via duck-typing.
+ *
+ * Pure-function module: receives dependencies, returns detach function.
+ */
+import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import {} from '@modelcontextprotocol/sdk/types.js';
+import { error, toolError } from '../core/response.js';
+import {} from '../core/types.js';
+import {} from '../core/execution/ProgressHelper.js';
+import { resolveServer } from './ServerResolver.js';
+import {} from '../observability/DebugObserver.js';
+import {} from '../observability/Tracing.js';
+import { StateSyncLayer } from '../state-sync/StateSyncLayer.js';
+import {} from '../state-sync/types.js';
+import {} from '../introspection/types.js';
+import { registerIntrospectionResource } from '../introspection/IntrospectionResource.js';
+import { AttestationError } from '../introspection/CryptoAttestation.js';
+import { enrichValidationError } from '../introspection/ContractAwareSelfHealing.js';
+import { compileContracts } from '../introspection/ToolContract.js';
+import { computeServerDigest } from '../introspection/BehaviorDigest.js';
+import {} from '../exposition/types.js';
+import { compileExposition } from '../exposition/ExpositionCompiler.js';
+import {} from '../prompt/PromptRegistry.js';
+import {} from '../prompt/types.js';
+import { StateMachineGate } from '../fsm/StateMachineGate.js';
+// ── Observability Propagation ────────────────────────────
+/**
+ * Propagate debug and tracing observers to all registered builders.
+ * Zero overhead when neither is configured.
+ */
+function propagateObservability(registry, debug, tracing, telemetry) {
+    if (debug && registry.enableDebug) {
+        registry.enableDebug(debug);
+    }
+    if (tracing && registry.enableTracing) {
+        registry.enableTracing(tracing);
+    }
+    if (telemetry && registry.enableTelemetry) {
+        registry.enableTelemetry(telemetry);
+    }
+}
+// ── Missing Context Guard ────────────────────────────────
+/**
+ * Proxy sentinel used when `contextFactory` is not provided.
+ *
+ * Instead of `undefined` (which causes cryptic `TypeError: Cannot read
+ * properties of undefined`), this proxy throws a clear, actionable error
+ * the moment a handler accesses any property on `ctx`.
+ *
+ * For `void` contexts where handlers never touch `ctx`, the proxy is
+ * never triggered — zero false positives.
+ *
+ * @internal — exported for reuse by `startServer.ts` edge handler.
+ */
+export const _missingContextProxy = new Proxy(Object.freeze({}), {
+    get(_target, prop) {
+        // Allow symbol access (e.g. Symbol.toPrimitive, Symbol.toStringTag) and
+        // JSON.stringify probing ('toJSON') to avoid breaking framework internals.
+        if (typeof prop === 'symbol')
+            return undefined;
+        throw new Error(`[vurb] Attempted to access "ctx.${String(prop)}" but no contextFactory was provided. ` +
+            `Add contextFactory to your attachToServer() options:\n\n` +
+            `  registry.attachToServer(server, {\n` +
+            `      contextFactory: (extra) => createAppContext(extra),\n` +
+            `  });\n`);
+    },
+});
+// ── Handler Factories ────────────────────────────────────
+/**
+ * Create the `tools/list` request handler.
+ *
+ * In flat mode, re-compiles exposition from the current registry state.
+ * In grouped mode, delegates to the registry's tag-filtered listing.
+ */
+function createToolListHandler(hCtx) {
+    return async (_request, extra) => {
+        // Per-request FSM clone for serverless isolation (Bug #3 + Bug #77 fix).
+        // Always clone the FSM so concurrent requests never share mutable state.
+        let fsm = hCtx.fsm;
+        if (fsm) {
+            fsm = fsm.clone();
+            if (hCtx.fsmStore) {
+                const sessionId = extractSessionId(extra) ?? '__default__';
+                const snap = await hCtx.fsmStore.load(sessionId);
+                if (snap)
+                    fsm.restore(snap);
+            }
+            else {
+                // In-memory fallback: restore from session-scoped snapshot
+                const sessionId = extractSessionId(extra) ?? '__default__';
+                const snap = hCtx.fsmMemorySnapshots?.get(sessionId);
+                if (snap)
+                    fsm.restore(snap);
+            }
+        }
+        let tools;
+        if (hCtx.isFlat) {
+            const exposition = hCtx.recompile();
+            tools = hCtx.filter
+                ? filterFlatTools(exposition.tools, exposition.routingMap, hCtx.filter)
+                : exposition.tools;
+        }
+        else {
+            tools = hCtx.filter
+                ? hCtx.registry.getTools(hCtx.filter)
+                : hCtx.registry.getAllTools();
+        }
+        // FSM State Gate: remove tools not allowed in the current state
+        if (fsm && fsm.hasBindings) {
+            tools = tools.filter(tool => fsm.isToolAllowed(tool.name));
+        }
+        return { tools: hCtx.syncLayer ? hCtx.syncLayer.decorateTools(tools) : tools };
+    };
+}
+/**
+ * Create the `tools/call` request handler.
+ *
+ * Handles both flat (O(1) dispatch) and grouped (registry routing) modes.
+ * Wires progress notifications when the client opts in via `_meta.progressToken`.
+ */
+function createToolCallHandler(hCtx) {
+    return async (request, extra) => {
+        const { name, arguments: args = {} } = request.params;
+        const ctx = hCtx.contextFactory
+            ? await hCtx.contextFactory(extra)
+            : _missingContextProxy;
+        const progressSink = createProgressSink(extra);
+        const signal = extractSignal(extra);
+        const emit = hCtx.telemetry;
+        // ── Telemetry: route event ──────────────────────────
+        // Resolve group/action from the routing map instead of naive
+        // split('_') — avoids misattributing tools with underscores
+        // in their names (e.g. 'user_accounts_list' → group='user_accounts', action='list').
+        const exposition = hCtx.isFlat ? hCtx.recompile() : undefined;
+        const flatRoute = exposition?.routingMap.get(name);
+        const toolGroup = flatRoute ? flatRoute.builder.getName() : name;
+        const action = flatRoute ? flatRoute.actionKey : name;
+        emit?.({ type: 'route', tool: toolGroup, action, args, timestamp: Date.now() });
+        // Per-request FSM clone for serverless isolation (Bug #3 + Bug #77 fix).
+        let fsm = hCtx.fsm;
+        if (fsm) {
+            fsm = fsm.clone();
+            if (hCtx.fsmStore) {
+                const sessionId = extractSessionId(extra) ?? '__default__';
+                const snap = await hCtx.fsmStore.load(sessionId);
+                if (snap)
+                    fsm.restore(snap);
+            }
+            else {
+                const sessionId = extractSessionId(extra) ?? '__default__';
+                const snap = hCtx.fsmMemorySnapshots?.get(sessionId);
+                if (snap)
+                    fsm.restore(snap);
+            }
+        }
+        // Bug #107 fix: enforce FSM gate on tools/call — not just tools/list.
+        // Without this, a client that knows a tool's name can bypass the gate.
+        if (fsm && fsm.hasBindings && !fsm.isToolAllowed(name)) {
+            return toolError('FORBIDDEN', {
+                message: `Tool "${name}" is not available in the current FSM state ("${fsm.currentState}").`,
+                suggestion: 'This tool is gated by the FSM State Gate. Call an allowed tool to advance the state first.',
+                availableActions: fsm.getVisibleToolNames([...new Set((exposition?.tools ?? hCtx.registry.getAllTools()).map(t => t.name))]),
+                severity: 'error',
+                details: { currentState: fsm.currentState, blockedTool: name },
+            });
+        }
+        let result;
+        const t0 = Date.now();
+        try {
+            if (hCtx.isFlat) {
+                // Reuse exposition compiled above for telemetry (avoid double recompile)
+                if (flatRoute) {
+                    const enrichedArgs = { ...args, [flatRoute.discriminator]: flatRoute.actionKey };
+                    result = await flatRoute.builder.execute(ctx, enrichedArgs, progressSink, signal);
+                    result = decorateIfSync(hCtx.syncLayer, flatRoute, result);
+                }
+                else {
+                    result = await hCtx.registry.routeCall(ctx, name, args, progressSink, signal);
+                    result = hCtx.syncLayer ? hCtx.syncLayer.decorateResult(name, result) : result;
+                }
+            }
+            else {
+                result = await hCtx.registry.routeCall(ctx, name, args, progressSink, signal);
+                result = hCtx.syncLayer ? hCtx.syncLayer.decorateResult(name, result) : result;
+            }
+        }
+        catch (err) {
+            emit?.({ type: 'error', tool: toolGroup, action, error: String(err), timestamp: Date.now() });
+            throw err;
+        }
+        // ── Self-Healing: enrich validation errors with contract deltas (Bug #43 fix) ──
+        if (result.isError && hCtx.selfHealing) {
+            const text = result.content?.[0]?.type === 'text' ? result.content[0].text : '';
+            if (text) {
+                const healing = enrichValidationError(text, toolGroup, action, hCtx.selfHealing);
+                if (healing.injected) {
+                    result = { ...result, content: [{ type: 'text', text: healing.enrichedError }] };
+                }
+            }
+        }
+        // ── Telemetry: execute event ─────────────────────────
+        emit?.({
+            type: 'execute', tool: toolGroup, action,
+            durationMs: Date.now() - t0,
+            isError: !!result.isError,
+            timestamp: Date.now(),
+        });
+        // FSM State Gate: auto-transition on successful execution
+        if (fsm && !result.isError) {
+            const transitionEvent = fsm.getTransitionEvent(name);
+            if (transitionEvent) {
+                const fromState = fsm.currentState;
+                const transition = await fsm.transition(transitionEvent);
+                if (transition.changed) {
+                    // Emit fsm.transition telemetry event
+                    if (hCtx.telemetry) {
+                        hCtx.telemetry({
+                            type: 'fsm.transition',
+                            tool: name,
+                            action: transitionEvent,
+                            from: fromState,
+                            to: fsm.currentState,
+                            timestamp: Date.now(),
+                        });
+                    }
+                    // Persist new state to external store (serverless/edge)
+                    // Use fallback session ID for transports without sessions (e.g., stdio) (Bug #44 fix)
+                    if (hCtx.fsmStore) {
+                        const sessionId = extractSessionId(extra) ?? '__default__';
+                        await hCtx.fsmStore.save(sessionId, fsm.snapshot());
+                    }
+                    else if (hCtx.fsmMemorySnapshots) {
+                        // Bug #77 fix: persist to in-memory session map
+                        const sessionId = extractSessionId(extra) ?? '__default__';
+                        hCtx.fsmMemorySnapshots.set(sessionId, fsm.snapshot());
+                    }
+                    // Notify client to re-fetch tools/list
+                    hCtx.notifyToolListChanged?.();
+                }
+            }
+        }
+        return result;
+    };
+}
+/**
+ * Decorate a flat-route result with state-sync metadata when applicable.
+ * Uses the canonical dot-notation key for policy matching.
+ */
+function decorateIfSync(syncLayer, flatRoute, result) {
+    if (!syncLayer)
+        return result;
+    const canonicalKey = `${flatRoute.builder.getName()}.${flatRoute.actionKey}`;
+    return syncLayer.decorateResult(canonicalKey, result);
+}
+/**
+ * Register `prompts/list` and `prompts/get` handlers on the server.
+ *
+ * Wires the prompt lifecycle notification sink and the internal
+ * loopback dispatcher that allows prompts to invoke tools in-memory.
+ */
+function registerPromptHandlers(resolved, server, prompts, registry, filter, contextFactory) {
+    // Wire lifecycle sync
+    const serverAny = server;
+    const sendFn = serverAny['sendPromptListChanged'];
+    if (typeof sendFn === 'function') {
+        prompts.setNotificationSink(() => { sendFn.call(server); });
+    }
+    // prompts/list
+    resolved.setRequestHandler(ListPromptsRequestSchema, async (request) => {
+        const params = {};
+        if (filter)
+            params.filter = filter;
+        if (request?.params?.cursor)
+            params.cursor = request.params.cursor;
+        return await prompts.listPrompts(params);
+    });
+    // prompts/get — with loopback dispatcher and signal propagation
+    resolved.setRequestHandler(GetPromptRequestSchema, async (request, extra) => {
+        const { name, arguments: args = {} } = request.params;
+        const ctx = contextFactory
+            ? await contextFactory(extra)
+            : _missingContextProxy;
+        const signal = extractSignal(extra);
+        const enrichedCtx = injectLoopbackDispatcher(ctx, registry, signal);
+        return prompts.routeGet(enrichedCtx, name, args);
+    });
+}
+/**
+ * Inject `invokeTool()` into the context so prompt handlers can call
+ * tools in-memory. Runs the Tool's full pipeline with RBAC enforced.
+ * Propagates the cancellation signal from the parent request.
+ */
+function injectLoopbackDispatcher(ctx, registry, signal) {
+    // Protect the original context from mutation — use prototype-based proxy
+    // for object contexts (safe — no property copy). For non-object contexts
+    // (primitives or null), start with an empty wrapper.
+    let wrapped;
+    if (ctx != null && typeof ctx === 'object') {
+        wrapped = Object.create(ctx);
+    }
+    else {
+        // ctx is null, undefined, or a primitive — start fresh.
+        // No prototype pollution risk here: no properties to copy.
+        wrapped = {};
+    }
+    wrapped['invokeTool'] = async (toolName, toolArgs = {}) => {
+        const response = await registry.routeCall(wrapped, toolName, toolArgs, undefined, signal);
+        const text = response.content
+            .filter((c) => c.type === 'text')
+            .map((c) => c.text)
+            .join('\n');
+        return {
+            text,
+            isError: response.isError ?? false,
+            raw: response,
+        };
+    };
+    return wrapped;
+}
+/**
+ * Create the detach function that replaces all handlers with no-ops.
+ */
+function createDetachFn(resolved, hasPrompts) {
+    return () => {
+        resolved.setRequestHandler(ListToolsRequestSchema, () => ({ tools: [] }));
+        resolved.setRequestHandler(CallToolRequestSchema, () => error('Tool handlers have been detached'));
+        if (hasPrompts) {
+            resolved.setRequestHandler(ListPromptsRequestSchema, () => ({ prompts: [] }));
+            resolved.setRequestHandler(GetPromptRequestSchema, () => ({
+                messages: [{ role: 'user', content: { type: 'text', text: 'Prompt handlers have been detached' } }],
+            }));
+        }
+    };
+}
+// ── Public API ───────────────────────────────────────────
+/**
+ * Attach a registry to an MCP Server.
+ *
+ * Resolves the server type, registers tools/list and tools/call handlers,
+ * and returns a detach function to remove the handlers.
+ *
+ * @param server - Server or McpServer instance (duck-typed)
+ * @param registry - Delegate providing tool listing and routing
+ * @param options - Filter and context factory options
+ * @returns A detach function to remove the handlers
+ */
+export async function attachToServer(server, registry, options = {}) {
+    const resolved = resolveServer(server);
+    const { filter, contextFactory, debug, tracing, stateSync, introspection, serverName, toolExposition = 'flat', actionSeparator = '_', prompts, zeroTrust, selfHealing, } = options;
+    // 1. Propagate observability to all registered builders
+    propagateObservability(registry, debug, tracing, options.telemetry);
+    // 2. Create State Sync layer (zero overhead when not configured)
+    //    Merge manual policies with fluent hints from builders (.invalidates(), .cached())
+    const mergedSyncConfig = mergeStateSyncConfig(stateSync, registry.getBuilders());
+    const syncLayer = mergedSyncConfig ? new StateSyncLayer(mergedSyncConfig) : undefined;
+    // 3. Register introspection resource (zero overhead when disabled)
+    if (introspection?.enabled) {
+        registerIntrospectionResource(resolved, introspection, serverName ?? 'vurb-server', { values: () => registry.getBuilders() }, contextFactory);
+    }
+    // 3b. Zero-Trust: compile contracts, compute digest, verify attestation
+    //     Zero overhead when not configured — no crypto operations run.
+    if (zeroTrust) {
+        const contracts = await compileContracts(registry.getBuilders());
+        const serverDigest = await computeServerDigest(contracts);
+        // Synchronous digest comparison (no signer needed for pinning)
+        if (zeroTrust.expectedDigest && serverDigest.digest !== zeroTrust.expectedDigest) {
+            if (zeroTrust.failOnMismatch ?? true) {
+                throw new AttestationError(`[Vurb] Zero-Trust attestation failed: computed digest ${serverDigest.digest} does not match expected ${zeroTrust.expectedDigest}`, {
+                    valid: false,
+                    computedDigest: serverDigest.digest,
+                    expectedDigest: zeroTrust.expectedDigest,
+                    signature: null,
+                    signerName: typeof zeroTrust.signer === 'string' ? zeroTrust.signer : zeroTrust.signer.name,
+                    attestedAt: new Date().toISOString(),
+                    error: `Digest mismatch: ${serverDigest.digest} !== ${zeroTrust.expectedDigest}`,
+                });
+            }
+        }
+    }
+    // 4. Build handler context (shared state for all handler factories)
+    // FSM State Gate: auto-bind tool bindings from builders
+    const { fsm, fsmStore } = options;
+    if (fsm) {
+        autoBindFsmFromBuilders(fsm, registry.getBuilders(), toolExposition, actionSeparator);
+    }
+    // Wire the notification sink for list_changed (FSM transitions)
+    let notifyToolListChanged;
+    if (fsm) {
+        const serverAny = server;
+        const sendFn = serverAny['sendToolListChanged'] ?? serverAny['notification'];
+        if (typeof sendFn === 'function') {
+            notifyToolListChanged = () => {
+                try {
+                    void sendFn.call(server, { method: 'notifications/tools/list_changed' });
+                }
+                catch {
+                    // Connection might not be established — ignore
+                }
+            };
+        }
+    }
+    const hCtx = {
+        registry,
+        ...(filter ? { filter } : {}),
+        ...(contextFactory ? { contextFactory } : {}),
+        ...(syncLayer ? { syncLayer } : {}),
+        toolExposition, actionSeparator,
+        isFlat: toolExposition === 'flat',
+        recompile: (() => {
+            let cachedBuilders;
+            let cachedResult;
+            return () => {
+                const builders = [...registry.getBuilders()];
+                if (cachedResult && cachedBuilders && builders.length === cachedBuilders.length && builders.every((b, i) => b === cachedBuilders[i])) {
+                    return cachedResult;
+                }
+                cachedBuilders = builders;
+                // Bug #131: route diagnostic warnings through debug observer
+                const warnFn = debug
+                    ? (msg) => debug({ type: 'error', tool: '', action: '', error: msg, step: 'route', timestamp: Date.now() })
+                    : undefined;
+                cachedResult = compileExposition(builders, toolExposition, actionSeparator, warnFn);
+                return cachedResult;
+            };
+        })(),
+        ...(fsm ? { fsm } : {}),
+        ...(fsmStore ? { fsmStore } : {}),
+        // Bug #77 fix: in-memory FSM snapshot store when no external fsmStore
+        // Bug #108 fix: bounded LRU eviction (max 10,000 entries) to prevent
+        // unbounded memory growth proportional to unique session count.
+        ...(fsm && !fsmStore ? { fsmMemorySnapshots: createBoundedSnapshotMap(10_000) } : {}),
+        ...(notifyToolListChanged ? { notifyToolListChanged } : {}),
+        ...(options.telemetry ? { telemetry: options.telemetry } : {}),
+        ...(selfHealing ? { selfHealing } : {}),
+    };
+    // 5. Register tool handlers
+    resolved.setRequestHandler(ListToolsRequestSchema, createToolListHandler(hCtx));
+    resolved.setRequestHandler(CallToolRequestSchema, createToolCallHandler(hCtx));
+    // 6. Register prompt handlers (zero overhead when omitted)
+    if (prompts) {
+        registerPromptHandlers(resolved, server, prompts, registry, filter, contextFactory);
+    }
+    // 7. Return detach function
+    return createDetachFn(resolved, prompts !== undefined);
+}
+// ── Flat Tool Filtering ──────────────────────────────────
+/**
+ * Filter flat tools by tag criteria.
+ *
+ * Maps each flat tool back to its originating builder to check tags,
+ * then applies the standard tag filter logic.
+ */
+function filterFlatTools(tools, routeMap, filter) {
+    const requiredTags = filter.tags && filter.tags.length > 0 ? new Set(filter.tags) : undefined;
+    const anyTags = filter.anyTag && filter.anyTag.length > 0 ? new Set(filter.anyTag) : undefined;
+    const excludeTags = filter.exclude && filter.exclude.length > 0 ? new Set(filter.exclude) : undefined;
+    if (!requiredTags && !anyTags && !excludeTags)
+        return tools;
+    return tools.filter(tool => {
+        const route = routeMap.get(tool.name);
+        if (!route)
+            return true; // Non-flat tool, include by default
+        const builderTags = route.builder.getTags();
+        // AND logic: builder must have ALL required tags
+        if (requiredTags && !Array.from(requiredTags).every(t => builderTags.includes(t))) {
+            return false;
+        }
+        // OR logic: builder must have at least ONE of these tags
+        if (anyTags && !builderTags.some(t => anyTags.has(t))) {
+            return false;
+        }
+        // Exclude: builder must NOT have ANY of these tags
+        if (excludeTags && builderTags.some(t => excludeTags.has(t))) {
+            return false;
+        }
+        return true;
+    });
+}
+// ── Progress Sink Factory ────────────────────────────────
+/**
+ * Duck-type check: the extra object from MCP SDK has _meta and sendNotification.
+ */
+function isMcpExtra(extra) {
+    return (typeof extra === 'object' &&
+        extra !== null &&
+        'sendNotification' in extra &&
+        typeof extra.sendNotification === 'function');
+}
+/**
+ * Create a ProgressSink from the MCP request `extra` object.
+ *
+ * When the client includes `_meta.progressToken` in its `tools/call` request,
+ * this factory returns a ProgressSink that maps each internal ProgressEvent
+ * to the MCP `notifications/progress` protocol wire format.
+ *
+ * When no progressToken is present (client didn't opt in),
+ * returns `undefined` — zero overhead.
+ *
+ * @param extra - The MCP request handler's extra argument (duck-typed)
+ * @returns A ProgressSink or undefined
+ */
+function createProgressSink(extra) {
+    if (!isMcpExtra(extra))
+        return undefined;
+    const token = extra._meta?.progressToken;
+    if (token === undefined)
+        return undefined;
+    const sendNotification = extra.sendNotification;
+    return (event) => {
+        // Fire-and-forget: progress notifications are best-effort.
+        // We intentionally do not await to avoid blocking the handler pipeline.
+        void sendNotification({
+            method: 'notifications/progress',
+            params: {
+                progressToken: token,
+                progress: event.percent,
+                total: 100,
+                message: event.message,
+            },
+        });
+    };
+}
+// ── Signal Extraction ────────────────────────────────────
+/**
+ * Extract the AbortSignal from the MCP SDK `extra` object.
+ *
+ * The SDK fires this signal when the client sends `notifications/cancelled`
+ * or when the transport connection drops. By extracting and propagating it,
+ * the framework enables cooperative cancellation at every pipeline layer.
+ *
+ * Returns `undefined` when not available — zero overhead.
+ *
+ * @param extra - The MCP request handler's extra argument (duck-typed)
+ * @returns The AbortSignal or undefined
+ */
+function extractSignal(extra) {
+    if (!isMcpExtra(extra))
+        return undefined;
+    return extra.signal;
+}
+// ── State Sync Hint Collection ──────────────────────────────
+/**
+ * Collect per-builder state sync hints and merge with manual config.
+ *
+ * Three scenarios:
+ * 1. Manual `stateSync` only — returns it unchanged
+ * 2. Fluent hints only — generates policies automatically
+ * 3. Both — fluent-generated policies are appended AFTER manual ones
+ *    (first-match-wins, so manual policies take precedence)
+ *
+ * Zero overhead when neither is configured.
+ */
+function mergeStateSyncConfig(manual, builders) {
+    const hintPolicies = collectHintPolicies(builders);
+    if (hintPolicies.length === 0)
+        return manual;
+    if (!manual)
+        return { policies: hintPolicies };
+    // Merge: manual first (higher precedence), then auto-generated
+    return {
+        ...manual,
+        policies: [...manual.policies, ...hintPolicies],
+    };
+}
+/**
+ * Walk all builders and convert their StateSyncHints into SyncPolicy[].
+ *
+ * For each builder with hints:
+ * - `'*'` key → tool-level policy matching `{toolName}.*`
+ * - Named action keys → action-level policy matching `{toolName}.{actionKey}`
+ */
+function collectHintPolicies(builders) {
+    const policies = [];
+    for (const builder of builders) {
+        if (!builder.getStateSyncHints)
+            continue;
+        const hints = builder.getStateSyncHints();
+        if (hints.size === 0)
+            continue;
+        const toolName = builder.getName();
+        for (const [key, hint] of hints) {
+            const match = key === '*' ? `${toolName}.*` : `${toolName}.${key}`;
+            policies.push({
+                match,
+                ...(hint.cacheControl ? { cacheControl: hint.cacheControl } : {}),
+                ...(hint.invalidates?.length ? { invalidates: [...hint.invalidates] } : {}),
+            });
+        }
+    }
+    return policies;
+}
+// ── Session ID Extraction ──────────────────────────────
+/**
+ * Create a bounded Map for in-memory FSM snapshots with LRU eviction.
+ *
+ * When the map exceeds `maxSize`, the oldest entry (first inserted) is evicted.
+ * Uses native `Map` iteration order guarantee (insertion order) as the LRU proxy.
+ * On `get()`, the accessed entry is re-inserted to refresh its position.
+ *
+ * Bug #108 fix: prevents unbounded memory growth proportional to unique sessions.
+ */
+function createBoundedSnapshotMap(maxSize) {
+    const map = new Map();
+    const originalSet = map.set.bind(map);
+    const originalGet = map.get.bind(map);
+    const originalHas = map.has.bind(map);
+    const originalDelete = map.delete.bind(map);
+    map.get = (key) => {
+        const value = originalGet(key);
+        if (value !== undefined) {
+            // Refresh position: delete and re-insert to make it "most recently used"
+            originalDelete(key);
+            originalSet(key, value);
+        }
+        return value;
+    };
+    map.set = (key, value) => {
+        // If key already exists, delete first to refresh position
+        if (originalHas(key)) {
+            originalDelete(key);
+        }
+        originalSet(key, value);
+        // Evict oldest entry if over capacity
+        if (map.size > maxSize) {
+            const oldest = map.keys().next().value;
+            if (oldest !== undefined)
+                originalDelete(oldest);
+        }
+        return map;
+    };
+    return map;
+}
+/**
+ * Extract the MCP session identifier from the request `extra` object.
+ *
+ * For Streamable HTTP transport, the session ID comes from the
+ * `Mcp-Session-Id` header. For stdio/SSE transports with persistent
+ * connections, a stable session ID may be available from the SDK.
+ *
+ * Returns `undefined` when not available (stdio transport without session tracking).
+ *
+ * @param extra - The MCP request handler's extra argument (duck-typed)
+ * @returns Session ID string or undefined
+ */
+function extractSessionId(extra) {
+    if (typeof extra !== 'object' || extra === null)
+        return undefined;
+    const ex = extra;
+    // Standard MCP SDK session ID
+    if (typeof ex['sessionId'] === 'string')
+        return ex['sessionId'];
+    // Streamable HTTP: from request headers  
+    const headers = ex['headers'];
+    if (headers && typeof headers['mcp-session-id'] === 'string') {
+        return headers['mcp-session-id'];
+    }
+    return undefined;
+}
+// ── FSM Auto-Binding ─────────────────────────────────
+/**
+ * Auto-bind FSM tool bindings from all registered builders.
+ *
+ * Walks all builders, checks for `.bindState()` metadata, and registers
+ * the bindings on the `StateMachineGate`. This allows the dev to use
+ * `.bindState()` on FluentToolBuilder without manually calling
+ * `gate.bindTool()` for each tool.
+ *
+ * In flat exposition mode, tool names are `{toolName}{separator}{actionKey}`.
+ * In grouped mode, tool names are just the builder's name.
+ */
+function autoBindFsmFromBuilders(gate, builders, exposition, separator) {
+    for (const builder of builders) {
+        // Duck-type: check if builder has getFsmBinding
+        const getFsm = builder['getFsmBinding'];
+        if (typeof getFsm !== 'function')
+            continue;
+        const binding = getFsm.call(builder);
+        if (!binding)
+            continue;
+        const toolName = builder.getName();
+        if (exposition === 'flat') {
+            // In flat mode, each action becomes a separate tool: toolName_actionKey
+            // We need to bind each flat tool name to the FSM
+            const actions = builder['getActions'];
+            if (typeof actions === 'function') {
+                const actionList = actions.call(builder);
+                for (const action of actionList) {
+                    const flatName = `${toolName}${separator}${action.key}`;
+                    gate.bindTool(flatName, binding.states, binding.transition);
+                }
+            }
+            else {
+                // Fallback: bind the base tool name
+                gate.bindTool(toolName, binding.states, binding.transition);
+            }
+        }
+        else {
+            // Grouped mode: tool name is just the builder name
+            gate.bindTool(toolName, binding.states, binding.transition);
+        }
+    }
+}
+//# sourceMappingURL=ServerAttachment.js.map