agentic-qe 3.8.14 → 3.9.1

package/dist/mcp/middleware/microcompact.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Agentic QE v3 - Microcompact Engine (IMP-01)
+ *
+ * Tracks MCP tool results over time and evicts stale entries to reduce
+ * context-window pressure. Registers as a postToolResult middleware on the
+ * IMP-00 middleware chain.
+ *
+ * Eviction rules (applied in order on each compact() call):
+ *   1. Results older than `maxAgeMs` are cleared — unless they are among
+ *      the most recent `keepLastN` results.
+ *   2. If total estimated tokens still exceed `contextBudget * contextPressureThreshold`,
+ *      the oldest non-protected results are cleared until the budget is satisfied.
+ *
+ * Cleared entries have their content replaced with a sentinel string so
+ * downstream consumers can detect compacted slots.
+ */
+import type { ToolMiddleware } from './middleware-chain';
+export interface MicrocompactOptions {
+    maxAgeMs?: number;
+    keepLastN?: number;
+    contextPressureThreshold?: number;
+    contextBudget?: number;
+    sentinel?: string;
+}
+export interface ToolResultEntry {
+    toolName: string;
+    result: unknown;
+    timestamp: number;
+    estimatedTokens: number;
+    cleared: boolean;
+}
+export interface MicrocompactResult {
+    clearedCount: number;
+    tokensSaved: number;
+    totalResults: number;
+    totalTokens: number;
+}
+/**
+ * Padded heuristic for token estimation: ceil(chars / 3).
+ * Intentionally conservative — overestimates slightly to give headroom.
+ */
+export declare function estimateTokensPadded(content: unknown): number;
+export declare class MicrocompactEngine {
+    private entries;
+    private readonly maxAgeMs;
+    private readonly keepLastN;
+    private readonly pressureThreshold;
+    private readonly contextBudget;
+    private readonly sentinel;
+    constructor(options?: MicrocompactOptions);
+    /** Register a new tool result for tracking. */
+    addResult(toolName: string, result: unknown): void;
+    /**
+     * Run the two-pass eviction algorithm and return a summary.
+     *
+     * Pass 1 — age-based: clear anything older than `maxAgeMs`, except the
+     *          most recent `keepLastN` entries (regardless of age).
+     * Pass 2 — pressure-based: if total tokens still exceed the threshold,
+     *          clear the oldest non-protected entries one-by-one until under budget.
+     */
+    compact(): MicrocompactResult;
+    /** Return current tracking statistics. */
+    getStats(): {
+        totalResults: number;
+        clearedCount: number;
+        totalTokens: number;
+    };
+    /** Expose estimateTokensPadded as a static method for external callers. */
+    static estimateTokensPadded(content: unknown): number;
+    /** Read-only access to the internal entries (useful for testing). */
+    getEntries(): ReadonlyArray<ToolResultEntry>;
+}
+/**
+ * Result of createMicrocompactMiddleware — returns both the middleware
+ * and the engine so callers can share the engine with other subsystems
+ * (e.g., the compaction pipeline's Tier 1).
+ */
+export interface MicrocompactMiddlewareResult {
+    middleware: ToolMiddleware;
+    engine: MicrocompactEngine;
+}
+/**
+ * Create a ToolMiddleware that plugs the MicrocompactEngine into the
+ * IMP-00 middleware chain.
+ *
+ * The middleware:
+ *   - Records every tool result via `addResult()`
+ *   - Runs `compact()` to evict stale historical entries
+ *   - Returns the current result unchanged (compaction targets history)
+ *
+ * Priority 100 — runs after most other post-hooks.
+ *
+ * Returns both the middleware and the underlying engine so the engine
+ * can be shared with the compaction pipeline (IMP-08 Tier 1).
+ */
+export declare function createMicrocompactMiddleware(options?: MicrocompactOptions): MicrocompactMiddlewareResult;
+//# sourceMappingURL=microcompact.d.ts.map

package/dist/mcp/middleware/microcompact.js

@@ -0,0 +1,179 @@
+/**
+ * Agentic QE v3 - Microcompact Engine (IMP-01)
+ *
+ * Tracks MCP tool results over time and evicts stale entries to reduce
+ * context-window pressure. Registers as a postToolResult middleware on the
+ * IMP-00 middleware chain.
+ *
+ * Eviction rules (applied in order on each compact() call):
+ *   1. Results older than `maxAgeMs` are cleared — unless they are among
+ *      the most recent `keepLastN` results.
+ *   2. If total estimated tokens still exceed `contextBudget * contextPressureThreshold`,
+ *      the oldest non-protected results are cleared until the budget is satisfied.
+ *
+ * Cleared entries have their content replaced with a sentinel string so
+ * downstream consumers can detect compacted slots.
+ */
+// ============================================================================
+// Defaults
+// ============================================================================
+const DEFAULT_MAX_AGE_MS = 3_600_000; // 60 minutes
+const DEFAULT_KEEP_LAST_N = 5;
+const DEFAULT_CONTEXT_PRESSURE_THRESHOLD = 0.8;
+const DEFAULT_CONTEXT_BUDGET = 100_000; // tokens
+const DEFAULT_SENTINEL = '[Old tool result content cleared]';
+// ============================================================================
+// Token Estimation
+// ============================================================================
+/**
+ * Padded heuristic for token estimation: ceil(chars / 3).
+ * Intentionally conservative — overestimates slightly to give headroom.
+ */
+export function estimateTokensPadded(content) {
+    const serialized = typeof content === 'string'
+        ? content
+        : JSON.stringify(content);
+    return Math.ceil(serialized.length / 3);
+}
+// ============================================================================
+// MicrocompactEngine
+// ============================================================================
+export class MicrocompactEngine {
+    entries = [];
+    maxAgeMs;
+    keepLastN;
+    pressureThreshold;
+    contextBudget;
+    sentinel;
+    constructor(options = {}) {
+        this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+        this.keepLastN = options.keepLastN ?? DEFAULT_KEEP_LAST_N;
+        this.pressureThreshold = options.contextPressureThreshold ?? DEFAULT_CONTEXT_PRESSURE_THRESHOLD;
+        this.contextBudget = options.contextBudget ?? DEFAULT_CONTEXT_BUDGET;
+        this.sentinel = options.sentinel ?? DEFAULT_SENTINEL;
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /** Register a new tool result for tracking. */
+    addResult(toolName, result) {
+        this.entries.push({
+            toolName,
+            result,
+            timestamp: Date.now(),
+            estimatedTokens: estimateTokensPadded(result),
+            cleared: false,
+        });
+    }
+    /**
+     * Run the two-pass eviction algorithm and return a summary.
+     *
+     * Pass 1 — age-based: clear anything older than `maxAgeMs`, except the
+     *          most recent `keepLastN` entries (regardless of age).
+     * Pass 2 — pressure-based: if total tokens still exceed the threshold,
+     *          clear the oldest non-protected entries one-by-one until under budget.
+     */
+    compact() {
+        const now = Date.now();
+        let clearedCount = 0;
+        let tokensSaved = 0;
+        const sentinelTokens = estimateTokensPadded(this.sentinel);
+        // Identify the protected tail (last N entries by insertion order).
+        const protectedStartIndex = Math.max(0, this.entries.length - this.keepLastN);
+        // --- Pass 1: age-based eviction ---
+        for (let i = 0; i < this.entries.length; i++) {
+            const entry = this.entries[i];
+            if (entry.cleared)
+                continue;
+            if (i >= protectedStartIndex)
+                continue; // protected
+            const age = now - entry.timestamp;
+            if (age > this.maxAgeMs) {
+                const saved = entry.estimatedTokens - sentinelTokens;
+                entry.result = this.sentinel;
+                entry.cleared = true;
+                entry.estimatedTokens = sentinelTokens;
+                clearedCount++;
+                tokensSaved += Math.max(0, saved);
+            }
+        }
+        // --- Pass 2: context-pressure eviction ---
+        const tokenCeiling = this.contextBudget * this.pressureThreshold;
+        let totalTokens = this.entries.reduce((sum, e) => sum + e.estimatedTokens, 0);
+        if (totalTokens > tokenCeiling) {
+            for (let i = 0; i < this.entries.length; i++) {
+                if (totalTokens <= tokenCeiling)
+                    break;
+                const entry = this.entries[i];
+                if (entry.cleared)
+                    continue;
+                if (i >= protectedStartIndex)
+                    continue; // still protected
+                const saved = entry.estimatedTokens - sentinelTokens;
+                totalTokens -= Math.max(0, saved);
+                entry.result = this.sentinel;
+                entry.cleared = true;
+                entry.estimatedTokens = sentinelTokens;
+                clearedCount++;
+                tokensSaved += Math.max(0, saved);
+            }
+        }
+        // Recompute total tokens for the summary.
+        totalTokens = this.entries.reduce((sum, e) => sum + e.estimatedTokens, 0);
+        return {
+            clearedCount,
+            tokensSaved,
+            totalResults: this.entries.length,
+            totalTokens,
+        };
+    }
+    /** Return current tracking statistics. */
+    getStats() {
+        const clearedCount = this.entries.filter(e => e.cleared).length;
+        const totalTokens = this.entries.reduce((sum, e) => sum + e.estimatedTokens, 0);
+        return {
+            totalResults: this.entries.length,
+            clearedCount,
+            totalTokens,
+        };
+    }
+    /** Expose estimateTokensPadded as a static method for external callers. */
+    static estimateTokensPadded(content) {
+        return estimateTokensPadded(content);
+    }
+    /** Read-only access to the internal entries (useful for testing). */
+    getEntries() {
+        return this.entries;
+    }
+}
+/**
+ * Create a ToolMiddleware that plugs the MicrocompactEngine into the
+ * IMP-00 middleware chain.
+ *
+ * The middleware:
+ *   - Records every tool result via `addResult()`
+ *   - Runs `compact()` to evict stale historical entries
+ *   - Returns the current result unchanged (compaction targets history)
+ *
+ * Priority 100 — runs after most other post-hooks.
+ *
+ * Returns both the middleware and the underlying engine so the engine
+ * can be shared with the compaction pipeline (IMP-08 Tier 1).
+ */
+export function createMicrocompactMiddleware(options) {
+    const engine = new MicrocompactEngine(options);
+    const disabled = process.env.AQE_MICROCOMPACT === 'false';
+    const middleware = {
+        name: 'microcompact',
+        priority: 100,
+        async postToolResult(_context, result) {
+            if (disabled)
+                return result;
+            engine.addResult(_context.toolName, result);
+            engine.compact();
+            return result;
+        },
+    };
+    return { middleware, engine };
+}
+//# sourceMappingURL=microcompact.js.map

package/dist/mcp/middleware/middleware-chain.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agentic QE v3 - Middleware Chain for MCP Tool Calls
+ *
+ * IMP-00: Extracts pre/post tool-call extension points from protocol-server.ts
+ * so future improvements (IMP-01, 02, 03, 04, 08) can register independently
+ * without editing handleToolsCall() or causing merge conflicts.
+ *
+ * Pattern: Sorted middleware chain with priority ordering.
+ * Lower priority number = runs first in pre-hooks, last in post-hooks (onion model).
+ */
+export interface ToolCallContext {
+    toolName: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+    sessionId?: string;
+    metadata: Record<string, unknown>;
+}
+export interface ToolMiddleware {
+    name: string;
+    priority: number;
+    preToolCall?(context: ToolCallContext): Promise<ToolCallContext>;
+    postToolResult?(context: ToolCallContext, result: unknown): Promise<unknown>;
+    onError?(context: ToolCallContext, error: Error): Promise<void>;
+}
+export declare class MiddlewareChain {
+    private middlewares;
+    register(mw: ToolMiddleware): void;
+    unregister(name: string): void;
+    getRegistered(): ReadonlyArray<{
+        name: string;
+        priority: number;
+    }>;
+    executePreHooks(ctx: ToolCallContext): Promise<ToolCallContext>;
+    executePostHooks(ctx: ToolCallContext, result: unknown): Promise<unknown>;
+    executeErrorHooks(ctx: ToolCallContext, error: Error): Promise<void>;
+}
+//# sourceMappingURL=middleware-chain.d.ts.map

package/dist/mcp/middleware/middleware-chain.js

@@ -0,0 +1,60 @@
+/**
+ * Agentic QE v3 - Middleware Chain for MCP Tool Calls
+ *
+ * IMP-00: Extracts pre/post tool-call extension points from protocol-server.ts
+ * so future improvements (IMP-01, 02, 03, 04, 08) can register independently
+ * without editing handleToolsCall() or causing merge conflicts.
+ *
+ * Pattern: Sorted middleware chain with priority ordering.
+ * Lower priority number = runs first in pre-hooks, last in post-hooks (onion model).
+ */
+// ============================================================================
+// Middleware Chain
+// ============================================================================
+export class MiddlewareChain {
+    middlewares = [];
+    register(mw) {
+        this.middlewares.push(mw);
+        this.middlewares.sort((a, b) => a.priority - b.priority);
+    }
+    unregister(name) {
+        this.middlewares = this.middlewares.filter(mw => mw.name !== name);
+    }
+    getRegistered() {
+        return this.middlewares.map(mw => ({ name: mw.name, priority: mw.priority }));
+    }
+    async executePreHooks(ctx) {
+        let current = ctx;
+        for (const mw of this.middlewares) {
+            if (mw.preToolCall) {
+                current = await mw.preToolCall(current);
+            }
+        }
+        return current;
+    }
+    async executePostHooks(ctx, result) {
+        let current = result;
+        // Post-hooks run in reverse priority order (onion model)
+        for (let i = this.middlewares.length - 1; i >= 0; i--) {
+            const mw = this.middlewares[i];
+            if (mw.postToolResult) {
+                current = await mw.postToolResult(ctx, current);
+            }
+        }
+        return current;
+    }
+    async executeErrorHooks(ctx, error) {
+        for (const mw of this.middlewares) {
+            if (mw.onError) {
+                try {
+                    await mw.onError(ctx, error);
+                }
+                catch (hookError) {
+                    // Error hooks must not crash the chain
+                    console.error(`[MiddlewareChain] Error in ${mw.name}.onError: ${hookError instanceof Error ? hookError.message : hookError}`);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=middleware-chain.js.map

package/dist/mcp/protocol-server.d.ts

@@ -6,6 +6,7 @@
  * ADR-039: Integrated with connection pooling, load balancing, and performance monitoring
  */
 import { ToolDefinition } from './types';
+import { type ToolMiddleware } from './middleware/middleware-chain';
 import { type EventAdapter } from '../adapters/ag-ui/index.js';
 export interface MCPServerConfig {
     name?: string;
@@ -42,6 +43,10 @@ export declare class MCPProtocolServer {
     private readonly balancer;
     private readonly monitor;
     private readonly eventAdapter;
+    private readonly middlewareChain;
+    private readonly sessionStore;
+    private readonly compactionPipeline;
+    private readonly loopTracker;
     private reconnecting;
     private pendingRequests;
     constructor(config?: MCPServerConfig);
@@ -62,6 +67,13 @@ export declare class MCPProtocolServer {
      * Stop the MCP server
      */
     stop(): Promise<void>;
+    /** IMP-00: Register a middleware into the tool-call chain. */
+    registerMiddleware(mw: ToolMiddleware): void;
+    /** IMP-00: Get registered middleware (for testing/introspection). */
+    getMiddleware(): ReadonlyArray<{
+        name: string;
+        priority: number;
+    }>;
     /**
      * Get server capabilities
      */