@vurb/core 3.2.0

package/dist/introspection/SemanticProbe.js

@@ -0,0 +1,274 @@
+/**
+ * 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
+ * `VurbTester.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 settled = await Promise.allSettled(batch.map(probe => evaluateProbe(probe, config)));
+        for (let j = 0; j < settled.length; j++) {
+            const outcome = settled[j];
+            if (outcome.status === 'fulfilled') {
+                results.push(outcome.value);
+            }
+            else {
+                // Graceful degradation — treat failed probes as fallback results
+                const probe = batch[j];
+                results.push({
+                    probe,
+                    similarityScore: 0.5,
+                    driftLevel: 'medium',
+                    contractViolated: false,
+                    violations: [`Probe evaluation failed: ${String(outcome.reason)}`],
+                    reasoning: 'Fallback: probe threw an exception during evaluation',
+                    rawResponse: null,
+                    evaluatedAt: new Date().toISOString(),
+                });
+            }
+        }
+    }
+    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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"}

package/dist/introspection/TokenEconomics.d.ts

@@ -0,0 +1,210 @@
+/**
+ * TokenEconomics — Cognitive Overload Detection
+ *
+ * **Evolution 3: Token Economics**
+ *
+ * Profiles the token density and context spread of MCP tool
+ * responses to detect cognitive overload scenarios where the
+ * LLM's working memory is flooded by verbose tool output,
+ * evicting system rules and degrading reasoning quality.
+ *
+ * **Key insight**: An MCP tool that returns 50KB of JSON per
+ * call will rapidly exhaust the context window. If that output
+ * isn't constrained by `agentLimit` or `egressMaxBytes`, the
+ * system rules injected by the Presenter's `addRules()` will
+ * be pushed out of the LLM's attention window — silently
+ * degrading behavioral correctness.
+ *
+ * This module provides:
+ *
+ * 1. **Static analysis**: Estimate token density from Presenter
+ *    schema and guardrail configuration (zero-cost at runtime).
+ *
+ * 2. **Runtime profiling**: Measure actual token counts of
+ *    response blocks after Presenter rendering (opt-in).
+ *
+ * 3. **Overload classification**: Classify responses into
+ *    risk levels based on configurable thresholds.
+ *
+ * 4. **Integration with BehaviorDigest**: Token economics risk
+ *    level is part of the behavioral contract — changes to
+ *    the token profile are tracked as contract deltas.
+ *
+ * Pure-function module for analysis; runtime profiling hooks
+ * are designed for zero-overhead when not configured.
+ *
+ * @module
+ */
+/**
+ * Token economics analysis for a single tool response.
+ */
+export interface TokenAnalysis {
+    /** Tool name */
+    readonly toolName: string;
+    /** Action key, if applicable */
+    readonly actionKey: string | null;
+    /** Estimated total tokens in the response */
+    readonly estimatedTokens: number;
+    /** Number of content blocks in the response */
+    readonly blockCount: number;
+    /** Per-block token breakdown */
+    readonly blocks: readonly BlockTokenProfile[];
+    /** Overhead tokens (rules, affordances, UI decorators) */
+    readonly overheadTokens: number;
+    /** Data payload tokens (actual tool output) */
+    readonly dataTokens: number;
+    /** Overhead-to-data ratio (higher = more overhead) */
+    readonly overheadRatio: number;
+    /** Risk classification */
+    readonly risk: TokenRisk;
+    /** Human-readable advisory */
+    readonly advisory: string | null;
+}
+/**
+ * Token profile for a single content block.
+ */
+export interface BlockTokenProfile {
+    /** Block type (e.g., 'text', 'resource', 'image') */
+    readonly type: string;
+    /** Estimated tokens in this block */
+    readonly estimatedTokens: number;
+    /** Raw byte size */
+    readonly bytes: number;
+}
+/**
+ * Token risk classification.
+ */
+export type TokenRisk = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Thresholds for token risk classification.
+ */
+export interface TokenThresholds {
+    /** Maximum tokens for 'low' risk (default: 1000) */
+    readonly low: number;
+    /** Maximum tokens for 'medium' risk (default: 4000) */
+    readonly medium: number;
+    /** Maximum tokens for 'high' risk (default: 8000) */
+    readonly high: number;
+}
+/**
+ * Configuration for the token economics profiler.
+ */
+export interface TokenEconomicsConfig {
+    /** Custom thresholds (defaults provided) */
+    readonly thresholds?: Partial<TokenThresholds>;
+    /** Whether to emit warnings to debug observer */
+    readonly emitWarnings?: boolean;
+    /** Maximum acceptable overhead ratio (default: 0.3) */
+    readonly maxOverheadRatio?: number;
+}
+/**
+ * Static token profile derived from Presenter configuration.
+ * Computed once at build time — zero runtime cost.
+ */
+export interface StaticTokenProfile {
+    /** Tool name */
+    readonly toolName: string;
+    /** Estimated minimum tokens per response */
+    readonly minTokens: number;
+    /** Estimated maximum tokens per response (with agentLimit) */
+    readonly maxTokens: number;
+    /** Whether the maximum is bounded (agentLimit/egressMaxBytes set) */
+    readonly bounded: boolean;
+    /** Per-field estimated token cost */
+    readonly fieldBreakdown: readonly FieldTokenEstimate[];
+    /** Risk classification based on max estimate */
+    readonly risk: TokenRisk;
+    /** Recommendations for reducing token cost */
+    readonly recommendations: readonly string[];
+}
+/**
+ * Per-field token estimate.
+ */
+export interface FieldTokenEstimate {
+    /** Field name */
+    readonly name: string;
+    /** Estimated tokens per occurrence */
+    readonly estimatedTokens: number;
+    /** Whether this field is a collection/array type */
+    readonly isCollection: boolean;
+}
+/**
+ * Estimate token count from a string using the ~4 chars/token heuristic.
+ *
+ * This is a fast approximation suitable for profiling. For precise
+ * token counting, use a tokenizer library (tiktoken, etc.).
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimate tokens for a content block structure (MCP response block).
+ *
+ * @param block - The content block with `type` and `text` fields
+ * @returns Block-level token profile
+ */
+export declare function profileBlock(block: {
+    type: string;
+    text?: string;
+}): BlockTokenProfile;
+/**
+ * Profile a complete tool response for token economics.
+ *
+ * Analyzes all content blocks in a tool response to compute
+ * total token usage, overhead ratio, and risk classification.
+ *
+ * @param toolName - Name of the tool that produced the response
+ * @param actionKey - Action key (if applicable)
+ * @param blocks - Content blocks from the tool response
+ * @param overheadBlocks - Number of blocks that are overhead (rules, UI)
+ * @param config - Token economics configuration
+ * @returns Complete token analysis
+ */
+export declare function profileResponse(toolName: string, actionKey: string | null, blocks: readonly {
+    type: string;
+    text?: string;
+}[], overheadBlocks?: number, config?: TokenEconomicsConfig): TokenAnalysis;
+/**
+ * Compute a static token profile from Presenter metadata.
+ *
+ * This runs once at manifest compilation time and produces
+ * a zero-cost profile that estimates the worst-case token
+ * usage for a tool based on its schema and guardrail config.
+ *
+ * @param toolName - Tool name
+ * @param schemaKeys - Presenter schema field names
+ * @param agentLimitMax - Maximum items from agentLimit() config
+ * @param egressMaxBytes - Maximum bytes from egressMaxBytes() config
+ * @returns Static token profile with recommendations
+ */
+export declare function computeStaticProfile(toolName: string, schemaKeys: readonly string[], agentLimitMax: number | null, egressMaxBytes: number | null): StaticTokenProfile;
+/**
+ * Aggregate static profiles into a server-level summary.
+ *
+ * @param profiles - All static profiles for the server
+ * @returns Server-level token economics summary
+ */
+export declare function aggregateProfiles(profiles: readonly StaticTokenProfile[]): ServerTokenSummary;
+/**
+ * Server-level token economics summary.
+ */
+export interface ServerTokenSummary {
+    /** Total number of tools */
+    readonly toolCount: number;
+    /** Sum of all tools' minimum token estimates */
+    readonly totalMinTokens: number;
+    /** Sum of all tools' maximum token estimates */
+    readonly totalMaxTokens: number;
+    /** Number of tools without bounded output */
+    readonly unboundedToolCount: number;
+    /** Names of unbounded tools */
+    readonly unboundedToolNames: readonly string[];
+    /** Overall risk classification */
+    readonly overallRisk: TokenRisk;
+    /** Names of critical-risk tools */
+    readonly criticalToolNames: readonly string[];
+    /** Aggregated recommendations */
+    readonly recommendations: readonly string[];
+}
+//# sourceMappingURL=TokenEconomics.d.ts.map

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

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