agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/ag-ui/state-delta-cache.js

@@ -0,0 +1,422 @@
+/**
+ * State Delta Cache for AG-UI Protocol
+ *
+ * Pre-computes and caches JSON Patch deltas for common state transitions
+ * to reduce latency in AG-UI state synchronization.
+ *
+ * Features:
+ * - LRU cache with configurable size limit
+ * - Pre-computed deltas for common agent state transitions
+ * - Cache warming on initialization
+ * - Fallback to on-demand computation for cache misses
+ * - Cache hit/miss metrics for monitoring
+ *
+ * @module adapters/ag-ui/state-delta-cache
+ */
+import { createHash } from 'crypto';
+import { computeDiff, deepEqual } from './json-patch.js';
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    maxSize: 1000,
+    warmOnInit: true,
+    diffConfig: {},
+    ttl: 0, // 0 means unlimited
+    agentStatusPath: '/agent/status',
+    progressPath: '/progress/percent',
+    toolStatusPath: '/tool/status',
+};
+// ============================================================================
+// Pre-computed Transition Definitions
+// ============================================================================
+/**
+ * Agent status transitions
+ */
+const AGENT_STATUS_TRANSITIONS = [
+    ['idle', 'running'],
+    ['running', 'completed'],
+    ['running', 'error'],
+    ['running', 'cancelled'],
+    ['completed', 'idle'],
+    ['error', 'idle'],
+    ['cancelled', 'idle'],
+];
+/**
+ * Progress milestone transitions
+ */
+const PROGRESS_TRANSITIONS = [
+    [0, 25],
+    [25, 50],
+    [50, 75],
+    [75, 100],
+    [0, 50],
+    [50, 100],
+    [0, 100],
+];
+/**
+ * Tool execution status transitions
+ */
+const TOOL_STATUS_TRANSITIONS = [
+    ['pending', 'executing'],
+    ['executing', 'success'],
+    ['executing', 'failure'],
+    ['success', 'pending'],
+    ['failure', 'pending'],
+];
+// ============================================================================
+// State Delta Cache Implementation
+// ============================================================================
+/**
+ * LRU Cache for pre-computed state deltas
+ *
+ * Reduces latency by caching common state transitions and using
+ * pre-computed deltas instead of computing on-demand.
+ */
+export class StateDeltaCache {
+    config;
+    cache;
+    preComputedKeys;
+    // Metrics
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.cache = new Map();
+        this.preComputedKeys = new Set();
+        if (this.config.warmOnInit) {
+            this.warmCache();
+        }
+    }
+    // ============================================================================
+    // Cache Operations
+    // ============================================================================
+    /**
+     * Get delta from cache or compute on-demand
+     *
+     * @param fromState - Source state
+     * @param toState - Target state
+     * @returns JSON Patch operations to transform fromState to toState
+     */
+    getDelta(fromState, toState) {
+        const key = this.computeCacheKey(fromState, toState);
+        // Check cache
+        const cached = this.cache.get(key);
+        if (cached && !this.isExpired(cached)) {
+            this.hits++;
+            cached.lastAccessedAt = Date.now();
+            cached.accessCount++;
+            // Move to end for LRU (delete and re-add)
+            this.cache.delete(key);
+            this.cache.set(key, cached);
+            return cached.delta;
+        }
+        // Cache miss - compute delta
+        this.misses++;
+        const delta = computeDiff(fromState, toState, this.config.diffConfig);
+        // Store in cache
+        this.setDelta(key, delta);
+        return delta;
+    }
+    /**
+     * Check if a delta is cached for the given states
+     */
+    has(fromState, toState) {
+        const key = this.computeCacheKey(fromState, toState);
+        const cached = this.cache.get(key);
+        return cached !== undefined && !this.isExpired(cached);
+    }
+    /**
+     * Pre-compute and store a delta in the cache
+     */
+    precompute(fromState, toState) {
+        const key = this.computeCacheKey(fromState, toState);
+        const delta = computeDiff(fromState, toState, this.config.diffConfig);
+        this.setDelta(key, delta);
+        this.preComputedKeys.add(key);
+        return delta;
+    }
+    /**
+     * Invalidate a specific cache entry
+     */
+    invalidate(fromState, toState) {
+        const key = this.computeCacheKey(fromState, toState);
+        const deleted = this.cache.delete(key);
+        if (deleted) {
+            this.preComputedKeys.delete(key);
+        }
+        return deleted;
+    }
+    /**
+     * Invalidate all entries matching a path prefix
+     */
+    invalidateByPath(pathPrefix) {
+        let count = 0;
+        // We need to track entries by path, but our key is a hash
+        // This is a limitation - for now, we clear the entire cache
+        // In production, we'd maintain a secondary index by path
+        for (const [key, entry] of this.cache.entries()) {
+            // Check if any delta operation targets the given path
+            const matchesPath = entry.delta.some((op) => op.path === pathPrefix ||
+                op.path.startsWith(pathPrefix + '/'));
+            if (matchesPath) {
+                this.cache.delete(key);
+                this.preComputedKeys.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this.cache.clear();
+        this.preComputedKeys.clear();
+    }
+    /**
+     * Reset metrics
+     */
+    resetMetrics() {
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+    // ============================================================================
+    // Cache Warming
+    // ============================================================================
+    /**
+     * Warm the cache with pre-computed common transitions
+     */
+    warmCache() {
+        // Agent status transitions
+        for (const [from, to] of AGENT_STATUS_TRANSITIONS) {
+            this.precomputePathTransition(this.config.agentStatusPath, from, to, 'agent-status');
+        }
+        // Progress transitions
+        for (const [from, to] of PROGRESS_TRANSITIONS) {
+            this.precomputePathTransition(this.config.progressPath, from, to, 'progress');
+        }
+        // Tool status transitions
+        for (const [from, to] of TOOL_STATUS_TRANSITIONS) {
+            this.precomputePathTransition(this.config.toolStatusPath, from, to, 'tool-execution');
+        }
+    }
+    /**
+     * Pre-compute transition for a specific path
+     */
+    precomputePathTransition(path, fromValue, toValue, _category) {
+        const pathParts = this.parseJsonPointerPath(path);
+        const fromState = this.buildStateFromPath(pathParts, fromValue);
+        const toState = this.buildStateFromPath(pathParts, toValue);
+        this.precompute(fromState, toState);
+    }
+    /**
+     * Parse a JSON Pointer path into segments
+     */
+    parseJsonPointerPath(path) {
+        if (path === '' || path === '/')
+            return [];
+        if (!path.startsWith('/')) {
+            throw new Error(`Invalid JSON Pointer: ${path}`);
+        }
+        return path.slice(1).split('/');
+    }
+    /**
+     * Build a state object from path segments and value
+     */
+    buildStateFromPath(pathParts, value) {
+        if (pathParts.length === 0) {
+            return typeof value === 'object' && value !== null
+                ? value
+                : {};
+        }
+        const result = {};
+        let current = result;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            current[pathParts[i]] = {};
+            current = current[pathParts[i]];
+        }
+        current[pathParts[pathParts.length - 1]] = value;
+        return result;
+    }
+    // ============================================================================
+    // Custom Pre-computation
+    // ============================================================================
+    /**
+     * Pre-compute a status transition at a custom path
+     */
+    precomputeStatusTransition(path, fromStatus, toStatus) {
+        const pathParts = this.parseJsonPointerPath(path);
+        const fromState = this.buildStateFromPath(pathParts, fromStatus);
+        const toState = this.buildStateFromPath(pathParts, toStatus);
+        return this.precompute(fromState, toState);
+    }
+    /**
+     * Pre-compute a progress transition at a custom path
+     */
+    precomputeProgressTransition(path, fromPercent, toPercent) {
+        const pathParts = this.parseJsonPointerPath(path);
+        const fromState = this.buildStateFromPath(pathParts, fromPercent);
+        const toState = this.buildStateFromPath(pathParts, toPercent);
+        return this.precompute(fromState, toState);
+    }
+    /**
+     * Pre-compute all transitions between a set of values at a path
+     */
+    precomputeAllTransitions(path, values) {
+        let count = 0;
+        const pathParts = this.parseJsonPointerPath(path);
+        for (let i = 0; i < values.length; i++) {
+            for (let j = 0; j < values.length; j++) {
+                if (i !== j) {
+                    const fromState = this.buildStateFromPath(pathParts, values[i]);
+                    const toState = this.buildStateFromPath(pathParts, values[j]);
+                    // Only add if not already equal
+                    if (!deepEqual(fromState, toState)) {
+                        this.precompute(fromState, toState);
+                        count++;
+                    }
+                }
+            }
+        }
+        return count;
+    }
+    // ============================================================================
+    // Metrics
+    // ============================================================================
+    /**
+     * Get current cache metrics
+     */
+    getMetrics() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            size: this.cache.size,
+            maxSize: this.config.maxSize,
+            hitRate: total > 0 ? (this.hits / total) * 100 : 0,
+            evictions: this.evictions,
+            preComputedEntries: this.preComputedKeys.size,
+        };
+    }
+    /**
+     * Get cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get maximum cache size
+     */
+    get maxSize() {
+        return this.config.maxSize;
+    }
+    // ============================================================================
+    // Internal Methods
+    // ============================================================================
+    /**
+     * Compute cache key from two states
+     * Uses SHA-256 hash of JSON-stringified states
+     */
+    computeCacheKey(fromState, toState) {
+        const fromHash = this.hashState(fromState);
+        const toHash = this.hashState(toState);
+        return `${fromHash}:${toHash}`;
+    }
+    /**
+     * Hash a state object for cache key
+     */
+    hashState(state) {
+        // Ensure consistent key ordering by sorting
+        const serialized = JSON.stringify(state, Object.keys(state).sort());
+        return createHash('sha256').update(serialized).digest('hex').substring(0, 16);
+    }
+    /**
+     * Set a delta in the cache with LRU eviction
+     */
+    setDelta(key, delta) {
+        // Evict if at capacity (LRU)
+        while (this.cache.size >= this.config.maxSize) {
+            this.evictLRU();
+        }
+        const now = Date.now();
+        this.cache.set(key, {
+            delta,
+            createdAt: now,
+            lastAccessedAt: now,
+            accessCount: 0,
+        });
+    }
+    /**
+     * Evict the least recently used entry
+     */
+    evictLRU() {
+        // Map maintains insertion order, but we need LRU by access time
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            // Prefer evicting non-precomputed entries first
+            const isPrecomputed = this.preComputedKeys.has(key);
+            if (!isPrecomputed && entry.lastAccessedAt < oldestTime) {
+                oldestTime = entry.lastAccessedAt;
+                oldestKey = key;
+            }
+        }
+        // If all entries are pre-computed, evict oldest pre-computed
+        if (oldestKey === null) {
+            for (const [key, entry] of this.cache.entries()) {
+                if (entry.lastAccessedAt < oldestTime) {
+                    oldestTime = entry.lastAccessedAt;
+                    oldestKey = key;
+                }
+            }
+        }
+        if (oldestKey !== null) {
+            this.cache.delete(oldestKey);
+            this.preComputedKeys.delete(oldestKey);
+            this.evictions++;
+        }
+    }
+    /**
+     * Check if a cache entry is expired
+     */
+    isExpired(entry) {
+        if (this.config.ttl <= 0) {
+            return false; // No TTL
+        }
+        return Date.now() - entry.createdAt > this.config.ttl;
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new StateDeltaCache instance
+ */
+export function createStateDeltaCache(config = {}) {
+    return new StateDeltaCache(config);
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+/**
+ * Get all pre-defined agent status values
+ */
+export function getAgentStatusValues() {
+    return ['idle', 'running', 'completed', 'error', 'cancelled'];
+}
+/**
+ * Get all pre-defined progress milestones
+ */
+export function getProgressMilestones() {
+    return [0, 25, 50, 75, 100];
+}
+/**
+ * Get all pre-defined tool status values
+ */
+export function getToolStatusValues() {
+    return ['pending', 'executing', 'success', 'failure'];
+}
+//# sourceMappingURL=state-delta-cache.js.map

package/v3/dist/adapters/ag-ui/state-delta-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-delta-cache.js","sourceRoot":"","sources":["../../../src/adapters/ag-ui/state-delta-cache.ts"],"names":[],"mappings":"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"}

package/v3/dist/adapters/ag-ui/state-manager.d.ts

@@ -0,0 +1,249 @@
+/**
+ * AG-UI State Manager
+ *
+ * Manages agent state for AG-UI STATE_SNAPSHOT and STATE_DELTA synchronization.
+ * Provides atomic state updates with automatic delta computation.
+ *
+ * @module adapters/ag-ui/state-manager
+ */
+import { EventEmitter } from 'events';
+import type { JsonPatchOperation } from './event-types.js';
+import { type PatchResult, type DiffConfig } from './json-patch.js';
+import { StateDeltaCache, type StateDeltaCacheConfig } from './state-delta-cache.js';
+/**
+ * State manager configuration
+ */
+export interface StateManagerConfig {
+    /** Initial state */
+    initialState?: Record<string, unknown>;
+    /** Whether to auto-increment version on state changes */
+    autoVersion?: boolean;
+    /** Maximum state history to retain (for rollback) */
+    maxHistory?: number;
+    /** Whether to emit events on state changes */
+    emitEvents?: boolean;
+    /** Custom ID generator */
+    idGenerator?: () => string;
+    /** Custom timestamp generator */
+    timestampGenerator?: () => string;
+    /** Diff configuration */
+    diffConfig?: DiffConfig;
+    /** Enable delta caching for optimized diff computation */
+    enableCache?: boolean;
+    /** Delta cache configuration */
+    cacheConfig?: StateDeltaCacheConfig;
+}
+/**
+ * State change event payload
+ */
+export interface StateChangeEvent {
+    /** Change type */
+    type: 'snapshot' | 'delta';
+    /** Current version */
+    version: number;
+    /** Previous version (for delta) */
+    previousVersion?: number;
+    /** Delta operations (for delta type) */
+    delta?: JsonPatchOperation[];
+    /** Full state (for snapshot type) */
+    state?: Record<string, unknown>;
+    /** Timestamp of change */
+    timestamp: string;
+}
+/**
+ * State history entry
+ */
+export interface StateHistoryEntry {
+    /** State version */
+    version: number;
+    /** State snapshot */
+    state: Record<string, unknown>;
+    /** Timestamp */
+    timestamp: string;
+    /** Delta from previous state */
+    deltaFromPrevious?: JsonPatchOperation[];
+}
+/**
+ * AG-UI State Manager
+ *
+ * Manages bidirectional state synchronization between agent and UI
+ * using STATE_SNAPSHOT and STATE_DELTA events.
+ */
+export declare class StateManager extends EventEmitter {
+    private config;
+    private state;
+    private version;
+    private history;
+    private lastSnapshotVersion;
+    private connectionId;
+    private readonly deltaCache;
+    constructor(config?: StateManagerConfig);
+    /**
+     * Get the current state as a snapshot
+     */
+    getSnapshot(): Record<string, unknown>;
+    /**
+     * Get the current state version
+     */
+    getVersion(): number;
+    /**
+     * Generate a STATE_SNAPSHOT event payload
+     */
+    generateSnapshotEvent(): {
+        type: 'STATE_SNAPSHOT';
+        state: Record<string, unknown>;
+        version: number;
+    };
+    /**
+     * Check if a snapshot should be sent (e.g., on reconnection)
+     */
+    shouldSendSnapshot(clientVersion?: number): boolean;
+    /**
+     * Get the current state (readonly reference)
+     */
+    getState(): Readonly<Record<string, unknown>>;
+    /**
+     * Set the entire state, computing delta from current state
+     * Uses delta cache for optimized computation of common transitions
+     * Returns the delta operations
+     */
+    setState(newState: Record<string, unknown>): JsonPatchOperation[];
+    /**
+     * Update a specific path in the state
+     */
+    updatePath(path: string, value: unknown): JsonPatchOperation[];
+    /**
+     * Remove a value at a specific path
+     */
+    removePath(path: string): JsonPatchOperation[];
+    /**
+     * Merge an object into the state at a specific path
+     */
+    mergePath(path: string, value: Record<string, unknown>): JsonPatchOperation[];
+    /**
+     * Compute delta between current state and provided state
+     * Uses delta cache for optimized computation if enabled
+     */
+    computeDelta(oldState: Record<string, unknown>, newState: Record<string, unknown>): JsonPatchOperation[];
+    /**
+     * Apply a delta (JSON Patch) to the current state
+     * Atomic operation with rollback on error
+     */
+    applyDelta(delta: JsonPatchOperation[]): JsonPatchOperation[];
+    /**
+     * Generate a STATE_DELTA event payload for the given delta
+     */
+    generateDeltaEvent(delta: JsonPatchOperation[]): {
+        type: 'STATE_DELTA';
+        delta: JsonPatchOperation[];
+        version: number;
+    };
+    /**
+     * Apply patch from external source (e.g., client updates)
+     * Returns PatchResult for error handling
+     */
+    applyExternalPatch(patch: JsonPatchOperation[]): PatchResult;
+    /**
+     * Get state history
+     */
+    getHistory(): readonly StateHistoryEntry[];
+    /**
+     * Get state at a specific version
+     */
+    getStateAtVersion(version: number): Record<string, unknown> | undefined;
+    /**
+     * Rollback to a previous version
+     */
+    rollback(targetVersion: number): JsonPatchOperation[];
+    /**
+     * Add entry to history with size limit enforcement
+     */
+    private addToHistory;
+    /**
+     * Handle new connection (emit snapshot)
+     */
+    onConnection(connectionId: string): {
+        type: 'STATE_SNAPSHOT';
+        state: Record<string, unknown>;
+        version: number;
+    };
+    /**
+     * Handle reconnection (emit snapshot if needed)
+     */
+    onReconnection(connectionId: string, lastKnownVersion?: number): {
+        type: 'STATE_SNAPSHOT';
+        state: Record<string, unknown>;
+        version: number;
+    } | null;
+    /**
+     * Handle disconnection
+     */
+    onDisconnection(connectionId: string): void;
+    /**
+     * Get current connection ID
+     */
+    getConnectionId(): string | null;
+    /**
+     * Get value at a specific path
+     */
+    getValue<T = unknown>(path: string): T | undefined;
+    /**
+     * Check if path exists in state
+     */
+    hasPath(path: string): boolean;
+    /**
+     * Check if current state equals the provided state
+     */
+    equals(otherState: Record<string, unknown>): boolean;
+    /**
+     * Reset state to initial state
+     */
+    reset(): JsonPatchOperation[];
+    /**
+     * Clear all state
+     */
+    clear(): JsonPatchOperation[];
+    /**
+     * Clear history only (keep current state)
+     */
+    clearHistory(): void;
+    /**
+     * Get the delta cache instance (if enabled)
+     */
+    getDeltaCache(): StateDeltaCache | null;
+    /**
+     * Check if delta caching is enabled
+     */
+    isCacheEnabled(): boolean;
+    /**
+     * Get cache metrics (if cache is enabled)
+     */
+    getCacheMetrics(): {
+        hits: number;
+        misses: number;
+        size: number;
+        maxSize: number;
+        hitRate: number;
+        evictions: number;
+        preComputedEntries: number;
+    } | null;
+    /**
+     * Pre-compute delta for a specific state transition
+     * Useful for warming cache with known common transitions
+     */
+    precomputeTransition(fromState: Record<string, unknown>, toState: Record<string, unknown>): JsonPatchOperation[] | null;
+    /**
+     * Warm cache with common agent state transitions
+     */
+    warmCache(): void;
+    /**
+     * Clear the delta cache
+     */
+    clearCache(): void;
+}
+/**
+ * Create a new StateManager instance
+ */
+export declare function createStateManager(config?: StateManagerConfig): StateManager;
+export type { PatchResult, DiffConfig };
+//# sourceMappingURL=state-manager.d.ts.map