agentic-qe 3.8.14 → 3.9.1

package/dist/context/compaction/tier4-reactive.js

@@ -0,0 +1,129 @@
+/**
+ * Agentic QE v3 - Tier 4: Reactive Compaction (IMP-08)
+ *
+ * Last-resort compaction triggered by 413 errors or context overflow
+ * detection. Aggressively peels the oldest conversation rounds until
+ * the estimated token count drops below the recovery target.
+ *
+ * This tier is destructive — it drops messages entirely (no summary).
+ * It exists to recover from situations where the context window is
+ * critically full and the session would otherwise fail.
+ */
+import { estimateTokensPadded } from '../../mcp/middleware/microcompact';
+// ============================================================================
+// Defaults
+// ============================================================================
+const DEFAULT_RECOVERY_TARGET = 30_000;
+const DEFAULT_MIN_PRESERVED = 4;
+// ============================================================================
+// Tier4Reactive
+// ============================================================================
+export class Tier4Reactive {
+    recoveryTarget;
+    minPreserved;
+    constructor(options = {}) {
+        this.recoveryTarget = options.recoveryTarget ?? DEFAULT_RECOVERY_TARGET;
+        this.minPreserved = options.minPreservedMessages ?? DEFAULT_MIN_PRESERVED;
+    }
+    /**
+     * Aggressively peel oldest messages until under the recovery target.
+     *
+     * Algorithm:
+     *   1. Compute total tokens.
+     *   2. If already under target, return early.
+     *   3. Walk forward from the oldest message, dropping messages until
+     *      remaining tokens are at or below recoveryTarget.
+     *   4. Never drop below minPreservedMessages from the tail.
+     *   5. When dropping a tool_result, also drop its paired tool_use (and vice versa).
+     */
+    compact(messages, trigger = 'context_overflow') {
+        if (messages.length === 0) {
+            return {
+                tier: 4,
+                survivingMessages: [],
+                survivingTokens: 0,
+                droppedCount: 0,
+                tokensSaved: 0,
+                trigger,
+            };
+        }
+        // Annotate tokens
+        const annotated = messages.map(m => ({
+            ...m,
+            estimatedTokens: m.estimatedTokens ?? estimateTokensPadded(m.content),
+        }));
+        const totalTokens = annotated.reduce((s, m) => s + m.estimatedTokens, 0);
+        // Already under target?
+        if (totalTokens <= this.recoveryTarget) {
+            return {
+                tier: 4,
+                survivingMessages: messages,
+                survivingTokens: totalTokens,
+                droppedCount: 0,
+                tokensSaved: 0,
+                trigger,
+            };
+        }
+        // Build pair map: toolUseId -> indices of both tool_use and tool_result
+        const pairMap = new Map();
+        for (let i = 0; i < annotated.length; i++) {
+            const m = annotated[i];
+            if (m.toolUseId) {
+                const existing = pairMap.get(m.toolUseId) ?? [];
+                existing.push(i);
+                pairMap.set(m.toolUseId, existing);
+            }
+        }
+        // Mark messages for dropping
+        const dropped = new Set();
+        let remainingTokens = totalTokens;
+        // The tail we must preserve
+        const preserveFrom = Math.max(0, annotated.length - this.minPreserved);
+        for (let i = 0; i < annotated.length; i++) {
+            if (remainingTokens <= this.recoveryTarget)
+                break;
+            if (i >= preserveFrom)
+                break; // Don't touch the preserved tail
+            if (dropped.has(i))
+                continue;
+            // Drop this message
+            dropped.add(i);
+            remainingTokens -= annotated[i].estimatedTokens;
+            // If part of a pair, drop the partner too
+            if (annotated[i].toolUseId) {
+                const partners = pairMap.get(annotated[i].toolUseId) ?? [];
+                for (const partnerIdx of partners) {
+                    if (!dropped.has(partnerIdx) && partnerIdx < preserveFrom) {
+                        dropped.add(partnerIdx);
+                        remainingTokens -= annotated[partnerIdx].estimatedTokens;
+                    }
+                }
+            }
+        }
+        const surviving = annotated.filter((_, i) => !dropped.has(i));
+        const survivingTokens = surviving.reduce((s, m) => s + m.estimatedTokens, 0);
+        return {
+            tier: 4,
+            survivingMessages: surviving,
+            survivingTokens,
+            droppedCount: dropped.size,
+            tokensSaved: totalTokens - survivingTokens,
+            trigger,
+        };
+    }
+    /**
+     * Convenience: check if a given HTTP status or error message indicates
+     * a context overflow that should trigger reactive compaction.
+     */
+    static isContextOverflow(statusOrMessage) {
+        if (typeof statusOrMessage === 'number') {
+            return statusOrMessage === 413;
+        }
+        const lower = statusOrMessage.toLowerCase();
+        return lower.includes('context_length_exceeded')
+            || lower.includes('maximum context length')
+            || lower.includes('too many tokens')
+            || lower.includes('413');
+    }
+}
+//# sourceMappingURL=tier4-reactive.js.map

package/dist/coordination/agent-memory-branch.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Agent Memory Branching via RVF Copy-on-Write (ADR-067)
+ *
+ * Provides per-agent isolated memory branches using RVF's COW derive().
+ * Each spawned agent gets a lightweight .rvf branch file that shares
+ * the parent's data via copy-on-write. Writes are isolated to the branch.
+ *
+ * Lifecycle:
+ *   spawn → createBranch() → agent works on isolated branch
+ *   success → mergeBranch() → changed vectors flow back to parent
+ *   failure → discardBranch() → delete branch file (zero cost)
+ *
+ * Storage cost: ~0.5% of parent for typical agent workloads
+ * (only changed vectors are physically copied).
+ *
+ * @module coordination/agent-memory-branch
+ */
+import type { RvfNativeAdapter } from '../integrations/ruvector/rvf-native-adapter.js';
+import type { WitnessChain } from '../audit/witness-chain.js';
+export interface BranchHandle {
+    /** Agent ID that owns this branch */
+    agentId: string;
+    /** Path to the child .rvf file */
+    childPath: string;
+    /** Path to the parent .rvf file */
+    parentPath: string;
+    /** The child RVF adapter (for agent to use) */
+    childAdapter: RvfNativeAdapter;
+    /** When the branch was created */
+    createdAt: number;
+    /**
+     * Ingest log — records vectors the agent added to the child.
+     * On merge, these are replayed into the parent. This is necessary
+     * because the RVF NAPI doesn't expose "read vector by ID."
+     */
+    ingestLog: Array<{
+        id: string;
+        vector: Float32Array;
+    }>;
+}
+export interface BranchInfo {
+    /** Agent ID (derived from filename) */
+    agentId: string;
+    /** Path to the branch .rvf file */
+    path: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** When the file was last modified */
+    modifiedAt: Date;
+}
+export type MergeStrategy = 'child-wins' | 'parent-wins';
+export interface MergeResult {
+    /** Number of vectors merged from child to parent */
+    vectorsMerged: number;
+    /** Strategy used */
+    strategy: MergeStrategy;
+    /** Duration of merge in milliseconds */
+    durationMs: number;
+}
+export interface AgentMemoryBranchConfig {
+    /** Directory to store branch .rvf files (default: .agentic-qe/branches/) */
+    branchDir: string;
+    /** Default merge strategy (default: child-wins) */
+    defaultStrategy: MergeStrategy;
+    /** Max age in ms before orphan cleanup (default: 1 hour) */
+    orphanMaxAgeMs: number;
+}
+export declare class AgentMemoryBranch {
+    private readonly config;
+    private readonly parentAdapter;
+    private readonly activeBranches;
+    private witnessChain;
+    constructor(parentAdapter: RvfNativeAdapter, config?: Partial<AgentMemoryBranchConfig>);
+    /** Attach a witness chain for merge/discard audit trail */
+    setWitnessChain(wc: WitnessChain): void;
+    /**
+     * Create a COW branch for an agent.
+     * The child .rvf inherits all parent data via copy-on-write.
+     * Reads fall through to parent; writes are isolated to the child.
+     */
+    createBranch(agentId: string): BranchHandle;
+    /**
+     * Record a vector that an agent ingested into its branch.
+     * This log is replayed into the parent on merge (child-wins strategy).
+     *
+     * Agents MUST call this alongside childAdapter.ingest() so that
+     * merge can replay the actual vectors into the parent.
+     */
+    recordIngest(agentId: string, entries: Array<{
+        id: string;
+        vector: Float32Array;
+    }>): void;
+    /**
+     * Merge a successful agent's branch back to the parent.
+     * Replays the agent's ingest log into the parent (child-wins) or
+     * discards all child changes (parent-wins).
+     */
+    mergeBranch(handle: BranchHandle, strategy?: MergeStrategy): Promise<MergeResult>;
+    /**
+     * Discard a failed agent's branch.
+     * Simply deletes the child .rvf file — zero computational cost.
+     */
+    discardBranch(handle: BranchHandle): void;
+    /** Get active branch for an agent (if any) */
+    getBranch(agentId: string): BranchHandle | undefined;
+    /** List all active branches */
+    getActiveBranches(): BranchHandle[];
+    /** List all branch files on disk (including orphans) */
+    listBranchFiles(): BranchInfo[];
+    /**
+     * Clean up orphaned branch files older than maxAge.
+     * An orphan is a .rvf file in branchDir with no active branch.
+     */
+    cleanupOrphans(maxAgeMs?: number): number;
+    private cleanupBranchFile;
+}
+//# sourceMappingURL=agent-memory-branch.d.ts.map

package/dist/coordination/agent-memory-branch.js

@@ -0,0 +1,213 @@
+/**
+ * Agent Memory Branching via RVF Copy-on-Write (ADR-067)
+ *
+ * Provides per-agent isolated memory branches using RVF's COW derive().
+ * Each spawned agent gets a lightweight .rvf branch file that shares
+ * the parent's data via copy-on-write. Writes are isolated to the branch.
+ *
+ * Lifecycle:
+ *   spawn → createBranch() → agent works on isolated branch
+ *   success → mergeBranch() → changed vectors flow back to parent
+ *   failure → discardBranch() → delete branch file (zero cost)
+ *
+ * Storage cost: ~0.5% of parent for typical agent workloads
+ * (only changed vectors are physically copied).
+ *
+ * @module coordination/agent-memory-branch
+ */
+import { existsSync, mkdirSync, unlinkSync, readdirSync, statSync } from 'fs';
+import { join, basename } from 'path';
+const DEFAULT_CONFIG = {
+    branchDir: '.agentic-qe/branches',
+    defaultStrategy: 'child-wins',
+    orphanMaxAgeMs: 3600_000, // 1 hour
+};
+// ============================================================================
+// AgentMemoryBranch Service
+// ============================================================================
+export class AgentMemoryBranch {
+    config;
+    parentAdapter;
+    activeBranches = new Map();
+    witnessChain = null;
+    constructor(parentAdapter, config) {
+        this.parentAdapter = parentAdapter;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Attach a witness chain for merge/discard audit trail */
+    setWitnessChain(wc) {
+        this.witnessChain = wc;
+    }
+    // --------------------------------------------------------------------------
+    // Branch Lifecycle
+    // --------------------------------------------------------------------------
+    /**
+     * Create a COW branch for an agent.
+     * The child .rvf inherits all parent data via copy-on-write.
+     * Reads fall through to parent; writes are isolated to the child.
+     */
+    createBranch(agentId) {
+        if (this.activeBranches.has(agentId)) {
+            throw new Error(`Branch already exists for agent ${agentId}`);
+        }
+        // Ensure branch directory exists
+        if (!existsSync(this.config.branchDir)) {
+            mkdirSync(this.config.branchDir, { recursive: true });
+        }
+        const childPath = join(this.config.branchDir, `${agentId}.rvf`);
+        const parentPath = this.parentAdapter.path();
+        // COW derive — creates lightweight child sharing parent's data
+        const childAdapter = this.parentAdapter.derive(childPath);
+        const handle = {
+            agentId,
+            childPath,
+            parentPath,
+            childAdapter,
+            createdAt: Date.now(),
+            ingestLog: [],
+        };
+        this.activeBranches.set(agentId, handle);
+        return handle;
+    }
+    /**
+     * Record a vector that an agent ingested into its branch.
+     * This log is replayed into the parent on merge (child-wins strategy).
+     *
+     * Agents MUST call this alongside childAdapter.ingest() so that
+     * merge can replay the actual vectors into the parent.
+     */
+    recordIngest(agentId, entries) {
+        const handle = this.activeBranches.get(agentId);
+        if (!handle)
+            return;
+        for (const entry of entries) {
+            handle.ingestLog.push({ id: entry.id, vector: entry.vector });
+        }
+    }
+    /**
+     * Merge a successful agent's branch back to the parent.
+     * Replays the agent's ingest log into the parent (child-wins) or
+     * discards all child changes (parent-wins).
+     */
+    async mergeBranch(handle, strategy) {
+        const mergeStrategy = strategy ?? this.config.defaultStrategy;
+        const startTime = performance.now();
+        let vectorsMerged = 0;
+        if (mergeStrategy === 'child-wins' && handle.ingestLog.length > 0) {
+            // Replay the agent's ingest log into the parent
+            // These are the actual vectors the agent wrote — no zero-vector placeholders
+            try {
+                const result = this.parentAdapter.ingest(handle.ingestLog);
+                vectorsMerged = result.accepted;
+            }
+            catch (error) {
+                console.warn(`[AgentMemoryBranch] Merge replay failed for ${handle.agentId}:`, error);
+            }
+        }
+        // parent-wins: nothing to do — child changes are discarded
+        // Record in witness chain
+        this.witnessChain?.append('BRANCH_MERGE', {
+            agentId: handle.agentId,
+            strategy: mergeStrategy,
+            vectorsMerged,
+            branchPath: handle.childPath,
+        }, `agent-${handle.agentId}`);
+        // Cleanup child
+        this.cleanupBranchFile(handle);
+        this.activeBranches.delete(handle.agentId);
+        return {
+            vectorsMerged,
+            strategy: mergeStrategy,
+            durationMs: performance.now() - startTime,
+        };
+    }
+    /**
+     * Discard a failed agent's branch.
+     * Simply deletes the child .rvf file — zero computational cost.
+     */
+    discardBranch(handle) {
+        // Record in witness chain
+        this.witnessChain?.append('BRANCH_DISCARD', {
+            agentId: handle.agentId,
+            action: 'discard',
+            branchPath: handle.childPath,
+        }, `agent-${handle.agentId}`);
+        this.cleanupBranchFile(handle);
+        this.activeBranches.delete(handle.agentId);
+    }
+    // --------------------------------------------------------------------------
+    // Branch Management
+    // --------------------------------------------------------------------------
+    /** Get active branch for an agent (if any) */
+    getBranch(agentId) {
+        return this.activeBranches.get(agentId);
+    }
+    /** List all active branches */
+    getActiveBranches() {
+        return Array.from(this.activeBranches.values());
+    }
+    /** List all branch files on disk (including orphans) */
+    listBranchFiles() {
+        if (!existsSync(this.config.branchDir))
+            return [];
+        const files = readdirSync(this.config.branchDir)
+            .filter(f => f.endsWith('.rvf'));
+        return files.map(f => {
+            const fullPath = join(this.config.branchDir, f);
+            const stat = statSync(fullPath);
+            return {
+                agentId: basename(f, '.rvf'),
+                path: fullPath,
+                sizeBytes: stat.size,
+                modifiedAt: stat.mtime,
+            };
+        });
+    }
+    /**
+     * Clean up orphaned branch files older than maxAge.
+     * An orphan is a .rvf file in branchDir with no active branch.
+     */
+    cleanupOrphans(maxAgeMs) {
+        const maxAge = maxAgeMs ?? this.config.orphanMaxAgeMs;
+        const now = Date.now();
+        let cleaned = 0;
+        for (const info of this.listBranchFiles()) {
+            const age = now - info.modifiedAt.getTime();
+            if (age > maxAge && !this.activeBranches.has(info.agentId)) {
+                try {
+                    unlinkSync(info.path);
+                    // Also remove idmap sidecar if present
+                    const idmapPath = `${info.path}.idmap.json`;
+                    if (existsSync(idmapPath))
+                        unlinkSync(idmapPath);
+                    cleaned++;
+                }
+                catch {
+                    // Best effort cleanup
+                }
+            }
+        }
+        return cleaned;
+    }
+    // --------------------------------------------------------------------------
+    // Private Helpers
+    // --------------------------------------------------------------------------
+    cleanupBranchFile(handle) {
+        try {
+            handle.childAdapter.close();
+        }
+        catch { /* best effort */ }
+        try {
+            if (existsSync(handle.childPath)) {
+                unlinkSync(handle.childPath);
+            }
+            // Remove idmap sidecar
+            const idmapPath = `${handle.childPath}.idmap.json`;
+            if (existsSync(idmapPath)) {
+                unlinkSync(idmapPath);
+            }
+        }
+        catch { /* best effort */ }
+    }
+}
+//# sourceMappingURL=agent-memory-branch.js.map

package/dist/coordination/agent-teams/mailbox.d.ts

@@ -24,6 +24,15 @@ export declare class MailboxService {
     private readonly broadcastHandlers;
     /** Index of agents by domain for efficient broadcast */
     private readonly domainAgents;
+    /** R13: Optional cognitive router for bandwidth-efficient messaging (lazy-initialized) */
+    private cognitiveRouter;
+    private cognitiveRouterInitialized;
+    /**
+     * R13: Tracks which messages were stored with compressed payloads.
+     * Maps message ID to the RoutedMessage needed for decompression on receive().
+     * This avoids modifying the AgentMessage type while enabling real compression.
+     */
+    private readonly compressedMessages;
     /**
      * Create a mailbox for an agent. If a mailbox already exists for this
      * agent ID, the existing mailbox is returned unchanged.
@@ -132,6 +141,40 @@ export declare class MailboxService {
      * Create an immutable snapshot of a mutable mailbox.
      */
     private toSnapshot;
+    /**
+     * Lazily initialize the cognitive router when the feature flag is enabled.
+     * Returns the router instance or null if disabled / unavailable.
+     */
+    private ensureCognitiveRouter;
+    /**
+     * Attempt to compress a message via the cognitive router.
+     * When compression succeeds (compressed payload is smaller), returns a new
+     * AgentMessage with the compressed payload and tracks the RoutedMessage
+     * for later decompression. When compression is unavailable or unhelpful,
+     * returns the original message unchanged.
+     *
+     * Non-blocking: any error returns the original message unmodified.
+     */
+    private compressViaCognitive;
+    /**
+     * Decompress messages that were stored with compressed payloads.
+     * Uses the cognitive router's receive() to reconstruct original payloads.
+     * Messages that were not compressed are returned unchanged.
+     *
+     * Non-blocking: decompression failures return the stored payload as-is.
+     */
+    private decompressMessages;
+    /**
+     * Get cognitive routing statistics (bandwidth savings, compression rates).
+     * Returns null if cognitive routing is not enabled or not initialized.
+     */
+    getCognitiveRoutingStats(): {
+        totalMessages: number;
+        compressedMessages: number;
+        bandwidthSavedBytes: number;
+        bandwidthReductionPercent: number;
+        activeStreams: number;
+    } | null;
 }
 /**
  * Create a new MailboxService instance.