@vurb/core 3.2.0

package/dist/introspection/TokenEconomics.js

@@ -0,0 +1,292 @@
+/**
+ * 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
+ */
+// ============================================================================
+// Default Thresholds
+// ============================================================================
+const DEFAULT_THRESHOLDS = {
+    low: 1000,
+    medium: 4000,
+    high: 8000,
+};
+const DEFAULT_MAX_OVERHEAD_RATIO = 0.3;
+// ============================================================================
+// Token Estimation
+// ============================================================================
+/**
+ * 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 function estimateTokens(text) {
+    // GPT-family heuristic: ~4 characters per token for English
+    // JSON/code tends to be ~3.5 chars/token due to syntax characters
+    return Math.ceil(text.length / 3.5);
+}
+/**
+ * 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 function profileBlock(block) {
+    const text = block.text ?? '';
+    const bytes = new TextEncoder().encode(text).byteLength;
+    const estimatedTokens = estimateTokens(text);
+    return {
+        type: block.type,
+        estimatedTokens,
+        bytes,
+    };
+}
+// ============================================================================
+// Runtime Profiling
+// ============================================================================
+/**
+ * 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 function profileResponse(toolName, actionKey, blocks, overheadBlocks = 0, config = {}) {
+    const thresholds = resolveThresholds(config);
+    const blockProfiles = blocks.map(profileBlock);
+    const totalTokens = blockProfiles.reduce((sum, b) => sum + b.estimatedTokens, 0);
+    // Split tokens into overhead vs data
+    const overheadTokens = overheadBlocks > 0
+        ? blockProfiles
+            .slice(-overheadBlocks)
+            .reduce((sum, b) => sum + b.estimatedTokens, 0)
+        : 0;
+    const dataTokens = totalTokens - overheadTokens;
+    // Bug #46 fix: when ALL blocks are overhead (dataTokens === 0),
+    // report Infinity instead of 0 to correctly trigger OVERHEAD WARNING
+    const overheadRatio = dataTokens > 0
+        ? overheadTokens / dataTokens
+        : (overheadTokens > 0 ? Infinity : 0);
+    const risk = classifyRisk(totalTokens, thresholds);
+    const advisory = generateAdvisory(toolName, totalTokens, risk, overheadRatio, config);
+    return {
+        toolName,
+        actionKey,
+        estimatedTokens: totalTokens,
+        blockCount: blocks.length,
+        blocks: blockProfiles,
+        overheadTokens,
+        dataTokens,
+        overheadRatio,
+        risk,
+        advisory,
+    };
+}
+// ============================================================================
+// Static Analysis
+// ============================================================================
+/**
+ * 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 function computeStaticProfile(toolName, schemaKeys, agentLimitMax, egressMaxBytes) {
+    // Estimate per-field token cost
+    const fieldBreakdown = schemaKeys.map(name => ({
+        name,
+        estimatedTokens: estimateFieldTokens(name),
+        isCollection: /(?:ids|keys|values|records|results|rows|elements|entries|tags|items|users|events|files|nodes|edges|logs|names|emails|roles)$/i.test(name) || name.toLowerCase().includes('list') || name.toLowerCase().includes('items'),
+    }));
+    // Base token cost: field names + structure + JSON overhead
+    const baseTokens = fieldBreakdown.reduce((sum, f) => sum + f.estimatedTokens, 0);
+    // Minimum: one item with all fields
+    const minTokens = baseTokens + 20; // JSON structure overhead
+    // Maximum: bounded by egressMaxBytes, agentLimit, or worst-case estimate
+    const { maxTokens, bounded } = computeBounds(baseTokens, agentLimitMax, egressMaxBytes);
+    const risk = classifyRisk(maxTokens, DEFAULT_THRESHOLDS);
+    const recommendations = buildRecommendations(toolName, bounded, risk, schemaKeys, agentLimitMax, fieldBreakdown);
+    return {
+        toolName,
+        minTokens,
+        maxTokens,
+        bounded,
+        fieldBreakdown,
+        risk,
+        recommendations,
+    };
+}
+/**
+ * Aggregate static profiles into a server-level summary.
+ *
+ * @param profiles - All static profiles for the server
+ * @returns Server-level token economics summary
+ */
+export function aggregateProfiles(profiles) {
+    const totalMinTokens = profiles.reduce((sum, p) => sum + p.minTokens, 0);
+    const totalMaxTokens = profiles.reduce((sum, p) => sum + p.maxTokens, 0);
+    const unboundedTools = profiles.filter(p => !p.bounded);
+    const criticalTools = profiles.filter(p => p.risk === 'critical');
+    const highRiskTools = profiles.filter(p => p.risk === 'high');
+    const overallRisk = criticalTools.length > 0
+        ? 'critical'
+        : highRiskTools.length > 0
+            ? 'high'
+            : unboundedTools.length > 0
+                ? 'medium'
+                : 'low';
+    return {
+        toolCount: profiles.length,
+        totalMinTokens,
+        totalMaxTokens,
+        unboundedToolCount: unboundedTools.length,
+        unboundedToolNames: unboundedTools.map(p => p.toolName),
+        overallRisk,
+        criticalToolNames: criticalTools.map(p => p.toolName),
+        recommendations: [
+            ...criticalTools.flatMap(p => p.recommendations.map(r => `[${p.toolName}] ${r}`)),
+            ...highRiskTools.flatMap(p => p.recommendations.map(r => `[${p.toolName}] ${r}`)),
+        ],
+    };
+}
+// ============================================================================
+// Internals
+// ============================================================================
+/**
+ * Classify token risk based on thresholds.
+ * @internal
+ */
+function classifyRisk(tokens, thresholds) {
+    if (tokens <= thresholds.low)
+        return 'low';
+    if (tokens <= thresholds.medium)
+        return 'medium';
+    if (tokens <= thresholds.high)
+        return 'high';
+    return 'critical';
+}
+/**
+ * Resolve thresholds with defaults.
+ * @internal
+ */
+function resolveThresholds(config) {
+    return {
+        low: config.thresholds?.low ?? DEFAULT_THRESHOLDS.low,
+        medium: config.thresholds?.medium ?? DEFAULT_THRESHOLDS.medium,
+        high: config.thresholds?.high ?? DEFAULT_THRESHOLDS.high,
+    };
+}
+/** Advisory templates keyed by risk level. @internal */
+const ADVISORY_TEMPLATES = {
+    critical: (toolName, tokens) => `COGNITIVE OVERLOAD: Tool "${toolName}" response estimated at ${tokens} tokens. ` +
+        `This will consume significant context window space. Consider adding agentLimit() or egressMaxBytes().`,
+    high: (toolName, tokens) => `HIGH TOKEN DENSITY: Tool "${toolName}" response estimated at ${tokens} tokens. ` +
+        `Consider reducing response verbosity or adding pagination.`,
+};
+/**
+ * Generate advisory for elevated risk levels.
+ * @internal
+ */
+function generateAdvisory(toolName, tokens, risk, overheadRatio, config) {
+    const template = ADVISORY_TEMPLATES[risk];
+    if (template)
+        return template(toolName, tokens);
+    const maxRatio = config.maxOverheadRatio ?? DEFAULT_MAX_OVERHEAD_RATIO;
+    if (overheadRatio > maxRatio) {
+        return `OVERHEAD WARNING: Tool "${toolName}" has ${Math.round(overheadRatio * 100)}% overhead ratio. ` +
+            `System rules and UI decorators are consuming significant context.`;
+    }
+    return null;
+}
+/**
+ * Compute upper bounds for token estimation.
+ * @internal
+ */
+function computeBounds(baseTokens, agentLimitMax, egressMaxBytes) {
+    // egressMaxBytes provides a hard ceiling
+    if (egressMaxBytes !== null)
+        return { maxTokens: Math.ceil(egressMaxBytes / 3.5), bounded: true };
+    // agentLimit bounds the collection size
+    if (agentLimitMax !== null)
+        return { maxTokens: baseTokens * agentLimitMax + 50, bounded: true };
+    // No bounds — worst-case estimate (100 items)
+    return { maxTokens: baseTokens * 100, bounded: false };
+}
+const RECOMMENDATION_RULES = [
+    { predicate: (bounded) => !bounded, message: 'Add .agentLimit() to bound collection size' },
+    { predicate: (_, risk) => risk === 'critical' || risk === 'high', message: 'Add .egressMaxBytes() to cap payload size' },
+    { predicate: (_, __, hasUnbounded) => hasUnbounded, message: 'Collection fields detected without agentLimit — risk of context flooding' },
+    { predicate: (_, __, ___, fieldCount) => fieldCount > 15, message: 'Consider reducing schema field count (>15 fields adds cognitive load)' },
+];
+/**
+ * Build recommendations based on profile characteristics.
+ * @internal
+ */
+function buildRecommendations(_toolName, bounded, risk, schemaKeys, agentLimitMax, fieldBreakdown) {
+    const hasUnboundedCollections = fieldBreakdown.some(f => f.isCollection) && agentLimitMax === null;
+    return RECOMMENDATION_RULES
+        .filter(rule => rule.predicate(bounded, risk, hasUnboundedCollections, schemaKeys.length))
+        .map(rule => rule.message);
+}
+/**
+ * Estimate tokens for a single field name.
+ * Heuristic: field name tokens + value tokens (estimated from name length).
+ * @internal
+ */
+function estimateFieldTokens(fieldName) {
+    // Field name in JSON: "fieldName": → ~name.length/4 + 1
+    const nameTokens = Math.ceil(fieldName.length / 4) + 1;
+    // Value estimate: assume average 5 tokens per field value
+    const valueTokens = 5;
+    return nameTokens + valueTokens;
+}
+//# sourceMappingURL=TokenEconomics.js.map

package/dist/introspection/TokenEconomics.js.map

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

package/dist/introspection/ToolContract.d.ts

@@ -0,0 +1,161 @@
+/**
+ * ToolContract — Behavioral Contract Materialization
+ *
+ * Unifies the declarative surface (tool names, schemas, tags) with
+ * the behavioral contract (Presenter egress schema, system rules,
+ * cognitive guardrails, middleware chain, state-sync policies) into
+ * a single, serializable, diffable, hashable artifact.
+ *
+ * **Key insight**: Vurb's Presenter is not just a response
+ * formatter — it's a declarative behavioral specification. The Zod
+ * schema, system rules, agent limits, and affordances are all
+ * explicit, serializable contracts. By materializing them into a
+ * `ToolContract`, we create a fingerprint that changes when behavior
+ * changes — even if the MCP tool declaration stays identical.
+ *
+ * **Zero developer effort**: The contract materializes from what the
+ * developer has already declared. No annotations, no config, no
+ * ceremony — just `materializeContract(builder)`.
+ *
+ * Pure-function module: no state, no side effects.
+ *
+ * @module
+ */
+import { type ToolBuilder } from '../core/types.js';
+/**
+ * Complete behavioral contract for a single tool.
+ *
+ * Captures both the MCP-visible surface (schema, description) and
+ * the behavioral internals (Presenter egress, rules, guardrails,
+ * middleware, state-sync, concurrency).
+ */
+export interface ToolContract {
+    /** Declarative surface visible via MCP `tools/list` */
+    readonly surface: ToolSurface;
+    /** Behavioral contract extracted from runtime primitives */
+    readonly behavior: ToolBehavior;
+    /** Token economics profile for cognitive overload detection */
+    readonly tokenEconomics: TokenEconomicsProfile;
+    /** Handler entitlements from static analysis */
+    readonly entitlements: HandlerEntitlements;
+}
+/** Declarative surface — what `tools/list` exposes */
+export interface ToolSurface {
+    /** Tool name */
+    readonly name: string;
+    /** Tool description */
+    readonly description: string | undefined;
+    /** Tags for selective exposure */
+    readonly tags: readonly string[];
+    /** Per-action contracts */
+    readonly actions: Record<string, ActionContract>;
+    /** SHA-256 of canonical JSON Schema */
+    readonly inputSchemaDigest: string;
+}
+/** Per-action behavioral contract */
+export interface ActionContract {
+    /** Human-readable description */
+    readonly description: string | undefined;
+    /** Whether this action is destructive */
+    readonly destructive: boolean;
+    /** Whether this action is idempotent */
+    readonly idempotent: boolean;
+    /** Whether this action is read-only */
+    readonly readOnly: boolean;
+    /** Required field names */
+    readonly requiredFields: readonly string[];
+    /** Presenter name (if MVA pattern is used) */
+    readonly presenterName: string | undefined;
+    /** SHA-256 of action-level input schema */
+    readonly inputSchemaDigest: string;
+    /** Whether the action has per-action middleware */
+    readonly hasMiddleware: boolean;
+}
+/** Behavioral contract — internal runtime guarantees */
+export interface ToolBehavior {
+    /** SHA-256 of Presenter's Zod schema shape (field names + types) */
+    readonly egressSchemaDigest: string | null;
+    /**
+     * Fingerprint of system rules configuration.
+     * Static rules: SHA-256 of sorted rule strings.
+     * Dynamic rules: `"dynamic:<function-hash>"`.
+     */
+    readonly systemRulesFingerprint: string;
+    /** Cognitive guardrail configuration */
+    readonly cognitiveGuardrails: CognitiveGuardrailsContract;
+    /** Middleware chain identity */
+    readonly middlewareChain: readonly string[];
+    /** State sync policy fingerprint */
+    readonly stateSyncFingerprint: string | null;
+    /** Concurrency configuration fingerprint */
+    readonly concurrencyFingerprint: string | null;
+    /** Affordance topology — tool names from suggestActions */
+    readonly affordanceTopology: readonly string[];
+    /** Embedded child Presenter names */
+    readonly embeddedPresenters: readonly string[];
+}
+/** Cognitive guardrails configuration snapshot */
+export interface CognitiveGuardrailsContract {
+    /** Maximum items before truncation (from Presenter) */
+    readonly agentLimitMax: number | null;
+    /** Maximum egress payload bytes (from builder) */
+    readonly egressMaxBytes: number | null;
+}
+/**
+ * Token economics profile for cognitive overload detection.
+ *
+ * Captures the expected token density of a tool's responses
+ * to detect context inflation that would evict system rules
+ * from the LLM's working memory.
+ */
+export interface TokenEconomicsProfile {
+    /** Estimated tokens per field in the egress schema */
+    readonly schemaFieldCount: number;
+    /** Whether collections may be unbounded (no agentLimit) */
+    readonly unboundedCollection: boolean;
+    /** Estimated base token overhead (rules + UI + affordances) */
+    readonly baseOverheadTokens: number;
+    /** Risk level based on configuration */
+    readonly inflationRisk: 'low' | 'medium' | 'high' | 'critical';
+}
+/**
+ * Handler entitlements derived from static analysis.
+ *
+ * Tracks I/O capabilities that the handler accesses, forming
+ * a security contract. If a read-only tool suddenly imports
+ * `fs.writeFileSync`, the entitlement contract breaks.
+ */
+export interface HandlerEntitlements {
+    /** Whether any handler references filesystem APIs */
+    readonly filesystem: boolean;
+    /** Whether any handler references network/fetch APIs */
+    readonly network: boolean;
+    /** Whether any handler references child_process/exec APIs */
+    readonly subprocess: boolean;
+    /** Whether any handler references crypto/signing APIs */
+    readonly crypto: boolean;
+    /** Whether any handler uses dynamic code evaluation (eval, Function, vm) */
+    readonly codeEvaluation: boolean;
+    /** Raw entitlement identifiers for granular diff */
+    readonly raw: readonly string[];
+}
+/**
+ * Materialize a `ToolContract` from a builder's public API.
+ *
+ * Extracts all behavioral metadata from the builder's introspection
+ * methods without accessing any private internals. This guarantees
+ * compatibility with any `ToolBuilder` implementation.
+ *
+ * @param builder - A registered tool builder
+ * @returns A fully materialized `ToolContract`
+ */
+export declare function materializeContract<TContext>(builder: ToolBuilder<TContext>): Promise<ToolContract>;
+/**
+ * Compile contracts for all tools in a registry.
+ *
+ * @param builders - Iterable of all registered tool builders
+ * @returns Record mapping tool names to their materialized contracts
+ */
+export declare function compileContracts<TContext>(builders: Iterable<ToolBuilder<TContext>>): Promise<Record<string, ToolContract>>;
+export { sha256, canonicalize } from './canonicalize.js';
+//# sourceMappingURL=ToolContract.d.ts.map

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

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