@vinkius-core/mcp-fusion 2.7.0 → 2.8.1

package/dist/introspection/GovernanceObserver.js

@@ -0,0 +1,132 @@
+import { SpanStatusCode } from '../observability/Tracing.js';
+/**
+ * Create a governance observer that emits debug events and/or tracing
+ * spans for governance operations.
+ *
+ * @param config - Observer configuration (debug handler and/or tracer)
+ * @returns A `GovernanceObserver` instance
+ *
+ * @example
+ * ```typescript
+ * import { createGovernanceObserver } from '@vinkius-core/mcp-fusion/introspection';
+ * import { createDebugObserver } from '@vinkius-core/mcp-fusion';
+ *
+ * const observer = createGovernanceObserver({
+ *     debug: createDebugObserver(),
+ * });
+ *
+ * const contracts = observer.observe(
+ *     'contract.compile',
+ *     'Compiling 5 tool contracts',
+ *     () => compileContracts(builders),
+ * );
+ * ```
+ */
+export function createGovernanceObserver(config) {
+    const { debug, tracer } = config;
+    function observe(operation, label, fn) {
+        const start = Date.now();
+        const span = tracer?.startSpan(`mcp.governance.${operation}`, {
+            attributes: {
+                'mcp.governance.operation': operation,
+                'mcp.governance.label': label,
+            },
+        });
+        try {
+            const result = fn();
+            const durationMs = Date.now() - start;
+            span?.setAttribute('mcp.governance.outcome', 'success');
+            span?.setAttribute('mcp.durationMs', durationMs);
+            span?.setStatus({ code: SpanStatusCode.OK });
+            debug?.({
+                type: 'governance',
+                operation,
+                label,
+                outcome: 'success',
+                durationMs,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        catch (err) {
+            const durationMs = Date.now() - start;
+            const message = err instanceof Error ? err.message : String(err);
+            span?.setAttribute('mcp.governance.outcome', 'failure');
+            span?.setAttribute('mcp.durationMs', durationMs);
+            span?.setStatus({ code: SpanStatusCode.ERROR, message });
+            span?.recordException(err instanceof Error ? err : new Error(message));
+            debug?.({
+                type: 'governance',
+                operation,
+                label,
+                outcome: 'failure',
+                detail: message,
+                durationMs,
+                timestamp: Date.now(),
+            });
+            throw err;
+        }
+        finally {
+            span?.end();
+        }
+    }
+    async function observeAsync(operation, label, fn) {
+        const start = Date.now();
+        const span = tracer?.startSpan(`mcp.governance.${operation}`, {
+            attributes: {
+                'mcp.governance.operation': operation,
+                'mcp.governance.label': label,
+            },
+        });
+        try {
+            const result = await fn();
+            const durationMs = Date.now() - start;
+            span?.setAttribute('mcp.governance.outcome', 'success');
+            span?.setAttribute('mcp.durationMs', durationMs);
+            span?.setStatus({ code: SpanStatusCode.OK });
+            debug?.({
+                type: 'governance',
+                operation,
+                label,
+                outcome: 'success',
+                durationMs,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        catch (err) {
+            const durationMs = Date.now() - start;
+            const message = err instanceof Error ? err.message : String(err);
+            span?.setAttribute('mcp.governance.outcome', 'failure');
+            span?.setAttribute('mcp.durationMs', durationMs);
+            span?.setStatus({ code: SpanStatusCode.ERROR, message });
+            span?.recordException(err instanceof Error ? err : new Error(message));
+            debug?.({
+                type: 'governance',
+                operation,
+                label,
+                outcome: 'failure',
+                detail: message,
+                durationMs,
+                timestamp: Date.now(),
+            });
+            throw err;
+        }
+        finally {
+            span?.end();
+        }
+    }
+    return { observe, observeAsync };
+}
+/**
+ * Create a no-op governance observer.
+ *
+ * Used when observability is not configured. Zero overhead.
+ */
+export function createNoopObserver() {
+    return {
+        observe: (_op, _label, fn) => fn(),
+        observeAsync: (_op, _label, fn) => fn(),
+    };
+}
+//# sourceMappingURL=GovernanceObserver.js.map

package/dist/introspection/GovernanceObserver.js.map

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

package/dist/introspection/SemanticProbe.d.ts

@@ -0,0 +1,207 @@
+/**
+ * SemanticProbe — LLM-as-a-Judge for Opaque Behavior Detection
+ *
+ * **Evolution 2: Semantic Probing**
+ *
+ * Provides a framework for using an LLM to evaluate whether
+ * a tool handler's actual runtime behavior matches its declared
+ * behavioral contract. This detects "semantic drift" — situations
+ * where the handler's output changes meaning even when the
+ * egress schema and system rules remain structurally identical.
+ *
+ * **Architecture**: This module defines the probe protocol,
+ * types, and evaluation pipeline. The actual LLM invocation
+ * is delegated to user-provided adapters — the module never
+ * makes LLM calls directly, maintaining the "no hidden
+ * network dependencies" principle.
+ *
+ * **Testing integration**: Designed to be integrated with
+ * `FusionTester.callAction()` for automated regression
+ * testing: "given these inputs, does the output semantically
+ * match the previous known-good output?"
+ *
+ * Pure-function module for probe construction and evaluation;
+ * LLM interaction is async via pluggable adapters.
+ *
+ * @module
+ */
+/**
+ * Configuration for semantic probing.
+ */
+export interface SemanticProbeConfig {
+    /** The LLM adapter to use for evaluation */
+    readonly adapter: SemanticProbeAdapter;
+    /** Risk thresholds for classification */
+    readonly thresholds?: Partial<SemanticThresholds>;
+    /** Maximum number of probes to run in parallel */
+    readonly concurrency?: number;
+    /** Whether to include raw LLM responses in results */
+    readonly includeRawResponses?: boolean;
+}
+/**
+ * Pluggable LLM adapter for semantic evaluation.
+ *
+ * Implementations should call an LLM with the provided prompt
+ * and return the structured evaluation result.
+ */
+export interface SemanticProbeAdapter {
+    /** Human-readable name (e.g., 'claude-3.5', 'gpt-4o') */
+    readonly name: string;
+    /**
+     * Send a semantic evaluation prompt to the LLM.
+     *
+     * @param prompt - Complete evaluation prompt
+     * @returns Raw LLM response text
+     */
+    evaluate(prompt: string): Promise<string>;
+}
+/**
+ * Thresholds for semantic drift classification.
+ */
+export interface SemanticThresholds {
+    /** Score below which drift is considered 'high' (default: 0.5) */
+    readonly highDriftThreshold: number;
+    /** Score below which drift is considered 'medium' (default: 0.75) */
+    readonly mediumDriftThreshold: number;
+}
+/**
+ * A semantic probe definition — a structured test case
+ * for LLM-based behavioral evaluation.
+ */
+export interface SemanticProbe {
+    /** Unique identifier for this probe */
+    readonly id: string;
+    /** Tool name being probed */
+    readonly toolName: string;
+    /** Action key being probed */
+    readonly actionKey: string;
+    /** Description of what this probe tests */
+    readonly description: string;
+    /** Input arguments to the tool */
+    readonly input: Record<string, unknown>;
+    /** Expected output (known-good baseline) */
+    readonly expectedOutput: unknown;
+    /** Actual output from the current handler */
+    readonly actualOutput: unknown;
+    /** Behavioral contract context for the judge */
+    readonly contractContext: ProbeContractContext;
+}
+/**
+ * Contract context injected into the LLM judge prompt.
+ *
+ * Provides the judge with enough information to evaluate
+ * whether the behavioral contract was violated.
+ */
+export interface ProbeContractContext {
+    /** Tool description */
+    readonly description: string | undefined;
+    /** Whether the action is declared readOnly */
+    readonly readOnly: boolean;
+    /** Whether the action is declared destructive */
+    readonly destructive: boolean;
+    /** System rules that should be respected */
+    readonly systemRules: readonly string[];
+    /** Schema field names (expected output shape) */
+    readonly schemaKeys: readonly string[];
+}
+/**
+ * Result of a single semantic probe evaluation.
+ */
+export interface SemanticProbeResult {
+    /** The probe that was evaluated */
+    readonly probe: SemanticProbe;
+    /** Semantic similarity score (0.0 = completely different, 1.0 = identical) */
+    readonly similarityScore: number;
+    /** Drift classification */
+    readonly driftLevel: DriftLevel;
+    /** Whether the behavioral contract was violated */
+    readonly contractViolated: boolean;
+    /** Specific violations detected by the judge */
+    readonly violations: readonly string[];
+    /** LLM judge's reasoning */
+    readonly reasoning: string;
+    /** Raw LLM response (if configured) */
+    readonly rawResponse: string | null;
+    /** ISO-8601 timestamp of evaluation */
+    readonly evaluatedAt: string;
+}
+/** Drift level classification */
+export type DriftLevel = 'none' | 'low' | 'medium' | 'high';
+/**
+ * Aggregated result of multiple semantic probes.
+ */
+export interface SemanticProbeReport {
+    /** Tool name */
+    readonly toolName: string;
+    /** All individual probe results */
+    readonly results: readonly SemanticProbeResult[];
+    /** Overall drift assessment */
+    readonly overallDrift: DriftLevel;
+    /** Number of contract violations */
+    readonly violationCount: number;
+    /** Whether the tool is considered semantically stable */
+    readonly stable: boolean;
+    /** Human-readable summary */
+    readonly summary: string;
+    /** ISO-8601 timestamp */
+    readonly completedAt: string;
+}
+/**
+ * Create a semantic probe from input/output pairs.
+ *
+ * @param toolName - Tool name
+ * @param actionKey - Action key
+ * @param input - Input arguments
+ * @param expectedOutput - Known-good baseline output
+ * @param actualOutput - Current handler output
+ * @param contractContext - Behavioral contract context
+ * @returns A structured semantic probe
+ */
+export declare function createProbe(toolName: string, actionKey: string, input: Record<string, unknown>, expectedOutput: unknown, actualOutput: unknown, contractContext: ProbeContractContext): SemanticProbe;
+/**
+ * Build the evaluation prompt for the LLM judge.
+ *
+ * The prompt is structured to elicit a JSON-formatted response
+ * with specific fields for programmatic parsing.
+ *
+ * @param probe - The semantic probe to evaluate
+ * @returns Complete evaluation prompt
+ */
+export declare function buildJudgePrompt(probe: SemanticProbe): string;
+/**
+ * Parse the LLM judge's response into a structured result.
+ *
+ * Handles malformed responses gracefully by falling back
+ * to conservative defaults.
+ *
+ * @param probe - The probe that was evaluated
+ * @param rawResponse - Raw LLM response text
+ * @param config - Probe configuration
+ * @returns Structured probe result
+ */
+export declare function parseJudgeResponse(probe: SemanticProbe, rawResponse: string, config: SemanticProbeConfig): SemanticProbeResult;
+/**
+ * Run a complete semantic probe evaluation.
+ *
+ * @param probe - The probe to evaluate
+ * @param config - Probe configuration (includes LLM adapter)
+ * @returns Evaluation result
+ */
+export declare function evaluateProbe(probe: SemanticProbe, config: SemanticProbeConfig): Promise<SemanticProbeResult>;
+/**
+ * Run multiple probes and aggregate results.
+ *
+ * @param probes - Array of probes to evaluate
+ * @param config - Probe configuration
+ * @returns Aggregated report
+ */
+export declare function evaluateProbes(probes: readonly SemanticProbe[], config: SemanticProbeConfig): Promise<SemanticProbeReport>;
+/**
+ * Aggregate individual probe results into a report.
+ *
+ * @param toolName - Tool name
+ * @param results - Individual probe results
+ * @returns Aggregated report
+ */
+export declare function aggregateResults(toolName: string, results: readonly SemanticProbeResult[]): SemanticProbeReport;
+//# sourceMappingURL=SemanticProbe.d.ts.map

package/dist/introspection/SemanticProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticProbe.d.ts","sourceRoot":"","sources":["../../src/introspection/SemanticProbe.ts"],"names":[],"mappings":"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"}

package/dist/introspection/SemanticProbe.js

@@ -0,0 +1,255 @@
+/**
+ * SemanticProbe — LLM-as-a-Judge for Opaque Behavior Detection
+ *
+ * **Evolution 2: Semantic Probing**
+ *
+ * Provides a framework for using an LLM to evaluate whether
+ * a tool handler's actual runtime behavior matches its declared
+ * behavioral contract. This detects "semantic drift" — situations
+ * where the handler's output changes meaning even when the
+ * egress schema and system rules remain structurally identical.
+ *
+ * **Architecture**: This module defines the probe protocol,
+ * types, and evaluation pipeline. The actual LLM invocation
+ * is delegated to user-provided adapters — the module never
+ * makes LLM calls directly, maintaining the "no hidden
+ * network dependencies" principle.
+ *
+ * **Testing integration**: Designed to be integrated with
+ * `FusionTester.callAction()` for automated regression
+ * testing: "given these inputs, does the output semantically
+ * match the previous known-good output?"
+ *
+ * Pure-function module for probe construction and evaluation;
+ * LLM interaction is async via pluggable adapters.
+ *
+ * @module
+ */
+// ============================================================================
+// Probe Construction
+// ============================================================================
+/**
+ * Create a semantic probe from input/output pairs.
+ *
+ * @param toolName - Tool name
+ * @param actionKey - Action key
+ * @param input - Input arguments
+ * @param expectedOutput - Known-good baseline output
+ * @param actualOutput - Current handler output
+ * @param contractContext - Behavioral contract context
+ * @returns A structured semantic probe
+ */
+export function createProbe(toolName, actionKey, input, expectedOutput, actualOutput, contractContext) {
+    const id = `${toolName}::${actionKey}::${Date.now()}`;
+    return {
+        id,
+        toolName,
+        actionKey,
+        description: `Semantic probe for ${toolName}.${actionKey}`,
+        input,
+        expectedOutput,
+        actualOutput,
+        contractContext,
+    };
+}
+/**
+ * Build the evaluation prompt for the LLM judge.
+ *
+ * The prompt is structured to elicit a JSON-formatted response
+ * with specific fields for programmatic parsing.
+ *
+ * @param probe - The semantic probe to evaluate
+ * @returns Complete evaluation prompt
+ */
+export function buildJudgePrompt(probe) {
+    return `You are a semantic evaluation judge for an MCP (Model Context Protocol) tool.
+
+Your task is to compare two outputs from the same tool handler and determine:
+1. Whether they are semantically equivalent
+2. Whether the current output violates the tool's behavioral contract
+
+## Tool Information
+- **Tool**: ${probe.toolName}
+- **Action**: ${probe.actionKey}
+- **Description**: ${probe.contractContext.description ?? 'No description'}
+- **Read-Only**: ${probe.contractContext.readOnly}
+- **Destructive**: ${probe.contractContext.destructive}
+
+## Behavioral Contract
+${probe.contractContext.systemRules.length > 0
+        ? `### System Rules\n${probe.contractContext.systemRules.map((r, i) => `${i + 1}. ${r}`).join('\n')}`
+        : 'No system rules declared.'}
+
+### Expected Output Schema Fields
+${probe.contractContext.schemaKeys.join(', ') || 'No schema declared'}
+
+## Input Arguments
+\`\`\`json
+${JSON.stringify(probe.input, null, 2)}
+\`\`\`
+
+## Expected Output (Baseline)
+\`\`\`json
+${JSON.stringify(probe.expectedOutput, null, 2)}
+\`\`\`
+
+## Actual Output (Current)
+\`\`\`json
+${JSON.stringify(probe.actualOutput, null, 2)}
+\`\`\`
+
+## Evaluation Instructions
+Compare the Expected Output with the Actual Output. Consider:
+- Are the outputs semantically equivalent (same meaning, even if format differs)?
+- Does the Actual Output violate any system rules?
+- Does the Actual Output return fields not in the expected schema?
+- Has the behavior meaningfully changed from the baseline?
+
+Respond with ONLY a JSON object in this exact format:
+\`\`\`json
+{
+  "similarityScore": <number 0.0-1.0>,
+  "contractViolated": <boolean>,
+  "violations": [<string descriptions of violations>],
+  "reasoning": "<brief explanation of your assessment>"
+}
+\`\`\``;
+}
+/**
+ * Parse the LLM judge's response into a structured result.
+ *
+ * Handles malformed responses gracefully by falling back
+ * to conservative defaults.
+ *
+ * @param probe - The probe that was evaluated
+ * @param rawResponse - Raw LLM response text
+ * @param config - Probe configuration
+ * @returns Structured probe result
+ */
+export function parseJudgeResponse(probe, rawResponse, config) {
+    const thresholds = resolveThresholds(config);
+    try {
+        // Extract JSON from response (handle markdown code blocks)
+        const jsonMatch = rawResponse.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            return fallbackResult(probe, rawResponse, config);
+        }
+        const parsed = JSON.parse(jsonMatch[0]);
+        const similarityScore = typeof parsed.similarityScore === 'number'
+            ? Math.max(0, Math.min(1, parsed.similarityScore))
+            : 0.5;
+        const driftLevel = classifyDrift(similarityScore, thresholds);
+        return {
+            probe,
+            similarityScore,
+            driftLevel,
+            contractViolated: parsed.contractViolated ?? false,
+            violations: parsed.violations ?? [],
+            reasoning: parsed.reasoning ?? 'No reasoning provided',
+            rawResponse: config.includeRawResponses ? rawResponse : null,
+            evaluatedAt: new Date().toISOString(),
+        };
+    }
+    catch {
+        return fallbackResult(probe, rawResponse, config);
+    }
+}
+/**
+ * Run a complete semantic probe evaluation.
+ *
+ * @param probe - The probe to evaluate
+ * @param config - Probe configuration (includes LLM adapter)
+ * @returns Evaluation result
+ */
+export async function evaluateProbe(probe, config) {
+    const prompt = buildJudgePrompt(probe);
+    const rawResponse = await config.adapter.evaluate(prompt);
+    return parseJudgeResponse(probe, rawResponse, config);
+}
+/**
+ * Run multiple probes and aggregate results.
+ *
+ * @param probes - Array of probes to evaluate
+ * @param config - Probe configuration
+ * @returns Aggregated report
+ */
+export async function evaluateProbes(probes, config) {
+    const concurrency = config.concurrency ?? 3;
+    // Run probes with concurrency control
+    const results = [];
+    for (let i = 0; i < probes.length; i += concurrency) {
+        const batch = probes.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map(probe => evaluateProbe(probe, config)));
+        results.push(...batchResults);
+    }
+    return aggregateResults(probes[0]?.toolName ?? 'unknown', results);
+}
+/**
+ * Aggregate individual probe results into a report.
+ *
+ * @param toolName - Tool name
+ * @param results - Individual probe results
+ * @returns Aggregated report
+ */
+export function aggregateResults(toolName, results) {
+    const violationCount = results.filter(r => r.contractViolated).length;
+    const avgSimilarity = results.length > 0
+        ? results.reduce((sum, r) => sum + r.similarityScore, 0) / results.length
+        : 1.0;
+    const overallDrift = results.length > 0
+        ? classifyDrift(avgSimilarity, {
+            highDriftThreshold: 0.5,
+            mediumDriftThreshold: 0.75,
+        })
+        : 'none';
+    const stable = overallDrift === 'none' || overallDrift === 'low';
+    const summary = results.length === 0
+        ? 'No probes evaluated.'
+        : `${results.length} probes evaluated. Avg similarity: ${(avgSimilarity * 100).toFixed(1)}%. ` +
+            `Drift: ${overallDrift}. Violations: ${violationCount}. ` +
+            `Status: ${stable ? 'STABLE' : 'UNSTABLE'}`;
+    return {
+        toolName,
+        results,
+        overallDrift,
+        violationCount,
+        stable,
+        summary,
+        completedAt: new Date().toISOString(),
+    };
+}
+// ============================================================================
+// Internals
+// ============================================================================
+const DEFAULT_THRESHOLDS = {
+    highDriftThreshold: 0.5,
+    mediumDriftThreshold: 0.75,
+};
+function resolveThresholds(config) {
+    return {
+        highDriftThreshold: config.thresholds?.highDriftThreshold ?? DEFAULT_THRESHOLDS.highDriftThreshold,
+        mediumDriftThreshold: config.thresholds?.mediumDriftThreshold ?? DEFAULT_THRESHOLDS.mediumDriftThreshold,
+    };
+}
+function classifyDrift(similarity, thresholds) {
+    if (similarity >= 0.95)
+        return 'none';
+    if (similarity >= thresholds.mediumDriftThreshold)
+        return 'low';
+    if (similarity >= thresholds.highDriftThreshold)
+        return 'medium';
+    return 'high';
+}
+function fallbackResult(probe, rawResponse, config) {
+    return {
+        probe,
+        similarityScore: 0.5,
+        driftLevel: 'medium',
+        contractViolated: false,
+        violations: ['Unable to parse LLM judge response'],
+        reasoning: 'Fallback: LLM response could not be parsed as JSON',
+        rawResponse: config.includeRawResponses ? rawResponse : null,
+        evaluatedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=SemanticProbe.js.map

package/dist/introspection/SemanticProbe.js.map

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