network-ai 4.15.2 → 5.0.0

package/dist/lib/agent-memory.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * AgentMemory — Multi-layer memory system for agents.
+ *
+ * Three memory layers:
+ * - **Episodic**: per-run short-term memory with time-based decay
+ * - **Procedural**: persistent skill/chain patterns (e.g. SkillComposer recipes)
+ * - **Shared long-term**: cross-agent knowledge base with relevance scoring
+ *
+ * @module AgentMemory
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentMemory = exports.SharedLongTermMemory = exports.ProceduralMemory = exports.EpisodicMemory = void 0;
+// ============================================================================
+// EPISODIC MEMORY
+// ============================================================================
+/**
+ * Short-term, per-run memory with exponential time decay.
+ * Entries lose relevance over time; stale entries are pruned.
+ */
+class EpisodicMemory {
+    entries = new Map();
+    maxEntries;
+    defaultHalfLifeMs;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 500;
+        this.defaultHalfLifeMs = options.defaultHalfLifeMs ?? 600_000; // 10 minutes
+    }
+    /** Store a new episodic memory */
+    store(content, tags = [], metadata = {}, halfLifeMs) {
+        const id = `ep_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const now = Date.now();
+        this.entries.set(id, {
+            id,
+            content,
+            tags,
+            createdAt: now,
+            lastAccessed: now,
+            accessCount: 0,
+            score: 1.0,
+            metadata,
+            halfLifeMs: halfLifeMs ?? this.defaultHalfLifeMs,
+        });
+        this.evict();
+        return id;
+    }
+    /** Recall entries matching criteria, scored by recency and decay */
+    recall(options = {}) {
+        const now = Date.now();
+        const results = [];
+        for (const entry of this.entries.values()) {
+            // Apply decay
+            const elapsed = now - entry.createdAt;
+            const decayFactor = Math.pow(0.5, elapsed / entry.halfLifeMs);
+            entry.score = decayFactor;
+            if (options.minScore !== undefined && entry.score < options.minScore)
+                continue;
+            if (options.since !== undefined && entry.createdAt < options.since)
+                continue;
+            if (options.tags && options.tags.length > 0) {
+                const matches = options.tags.some(t => entry.tags.includes(t));
+                if (!matches)
+                    continue;
+            }
+            entry.lastAccessed = now;
+            entry.accessCount++;
+            results.push(entry);
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, options.maxResults ?? 20);
+    }
+    /** Remove a specific entry */
+    remove(id) {
+        return this.entries.delete(id);
+    }
+    /** Clear all entries */
+    clear() {
+        this.entries.clear();
+    }
+    /** Number of stored entries */
+    size() {
+        return this.entries.size;
+    }
+    /** Prune entries below a score threshold */
+    prune(minScore = 0.01) {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [id, entry] of this.entries) {
+            const elapsed = now - entry.createdAt;
+            const decayFactor = Math.pow(0.5, elapsed / entry.halfLifeMs);
+            if (decayFactor < minScore) {
+                this.entries.delete(id);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+    evict() {
+        if (this.entries.size <= this.maxEntries)
+            return;
+        // Remove oldest entries
+        const sorted = [...this.entries.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+        const toRemove = sorted.slice(0, this.entries.size - this.maxEntries);
+        for (const [id] of toRemove)
+            this.entries.delete(id);
+    }
+}
+exports.EpisodicMemory = EpisodicMemory;
+// ============================================================================
+// PROCEDURAL MEMORY
+// ============================================================================
+/**
+ * Persistent memory for successful skill/chain patterns.
+ * Agents learn which patterns work and prefer them in future.
+ */
+class ProceduralMemory {
+    entries = new Map();
+    maxEntries;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 1000;
+    }
+    /** Register a pattern (chain/batch/loop/verify) */
+    register(id, content, patternType, tags = [], metadata = {}) {
+        const now = Date.now();
+        const existing = this.entries.get(id);
+        if (existing) {
+            existing.lastAccessed = now;
+            existing.accessCount++;
+            return existing;
+        }
+        const entry = {
+            id,
+            content,
+            tags,
+            patternType,
+            createdAt: now,
+            lastAccessed: now,
+            accessCount: 0,
+            score: 0.5,
+            metadata,
+            successCount: 0,
+            failureCount: 0,
+        };
+        this.entries.set(id, entry);
+        this.evict();
+        return entry;
+    }
+    /** Record success for a pattern — increases its score */
+    recordSuccess(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        entry.successCount++;
+        entry.score = entry.successCount / (entry.successCount + entry.failureCount);
+        entry.lastAccessed = Date.now();
+    }
+    /** Record failure for a pattern — decreases its score */
+    recordFailure(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        entry.failureCount++;
+        entry.score = entry.successCount / (entry.successCount + entry.failureCount);
+        entry.lastAccessed = Date.now();
+    }
+    /** Recall top-scoring patterns matching criteria */
+    recall(options = {}) {
+        const results = [];
+        for (const entry of this.entries.values()) {
+            if (options.patternType && entry.patternType !== options.patternType)
+                continue;
+            if (options.minScore !== undefined && entry.score < options.minScore)
+                continue;
+            if (options.tags && options.tags.length > 0) {
+                const matches = options.tags.some(t => entry.tags.includes(t));
+                if (!matches)
+                    continue;
+            }
+            entry.lastAccessed = Date.now();
+            entry.accessCount++;
+            results.push(entry);
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, options.maxResults ?? 20);
+    }
+    /** Get a specific pattern by ID */
+    get(id) {
+        return this.entries.get(id);
+    }
+    /** Number of stored patterns */
+    size() {
+        return this.entries.size;
+    }
+    /** Clear all patterns */
+    clear() {
+        this.entries.clear();
+    }
+    evict() {
+        if (this.entries.size <= this.maxEntries)
+            return;
+        const sorted = [...this.entries.entries()].sort((a, b) => a[1].score - b[1].score);
+        const toRemove = sorted.slice(0, this.entries.size - this.maxEntries);
+        for (const [id] of toRemove)
+            this.entries.delete(id);
+    }
+}
+exports.ProceduralMemory = ProceduralMemory;
+// ============================================================================
+// SHARED LONG-TERM MEMORY
+// ============================================================================
+/**
+ * Cross-agent shared knowledge base.
+ * Any agent can contribute; all agents can query.
+ * Relevance scored by tag overlap and access frequency.
+ */
+class SharedLongTermMemory {
+    entries = new Map();
+    maxEntries;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 5000;
+    }
+    /** Contribute knowledge to the shared store */
+    contribute(sourceAgent, content, tags = [], metadata = {}) {
+        const id = `shared_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const now = Date.now();
+        this.entries.set(id, {
+            id,
+            content,
+            tags,
+            createdAt: now,
+            lastAccessed: now,
+            accessCount: 0,
+            score: 0.5,
+            metadata,
+            sourceAgent,
+            accessedBy: new Set(),
+        });
+        this.evict();
+        return id;
+    }
+    /** Query shared memory, scored by tag overlap and recency */
+    query(agentId, options = {}) {
+        const results = [];
+        const queryTags = options.tags ?? [];
+        for (const entry of this.entries.values()) {
+            if (options.since !== undefined && entry.createdAt < options.since)
+                continue;
+            // Score by tag overlap
+            let tagScore = 0;
+            if (queryTags.length > 0) {
+                const overlap = queryTags.filter(t => entry.tags.includes(t)).length;
+                tagScore = overlap / queryTags.length;
+                if (overlap === 0)
+                    continue; // no tag overlap = skip
+            }
+            else {
+                tagScore = 0.5; // no filter = moderate relevance
+            }
+            // Boost by access frequency
+            const freqBoost = Math.min(entry.accessCount / 10, 1.0) * 0.3;
+            entry.score = tagScore * 0.7 + freqBoost;
+            if (options.minScore !== undefined && entry.score < options.minScore)
+                continue;
+            entry.lastAccessed = Date.now();
+            entry.accessCount++;
+            entry.accessedBy.add(agentId);
+            results.push(entry);
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, options.maxResults ?? 20);
+    }
+    /** Get all entries contributed by a specific agent */
+    getByAgent(sourceAgent) {
+        return [...this.entries.values()].filter(e => e.sourceAgent === sourceAgent);
+    }
+    /** Number of stored entries */
+    size() {
+        return this.entries.size;
+    }
+    /** Clear all entries */
+    clear() {
+        this.entries.clear();
+    }
+    evict() {
+        if (this.entries.size <= this.maxEntries)
+            return;
+        const sorted = [...this.entries.entries()].sort((a, b) => a[1].score - b[1].score);
+        const toRemove = sorted.slice(0, this.entries.size - this.maxEntries);
+        for (const [id] of toRemove)
+            this.entries.delete(id);
+    }
+}
+exports.SharedLongTermMemory = SharedLongTermMemory;
+// ============================================================================
+// UNIFIED AGENT MEMORY
+// ============================================================================
+/**
+ * Unified memory system combining all three layers.
+ * Instantiate per-agent for episodic, share ProceduralMemory and
+ * SharedLongTermMemory across agents.
+ *
+ * @example
+ * ```ts
+ * const procedural = new ProceduralMemory();
+ * const shared = new SharedLongTermMemory();
+ *
+ * const agentMemory = new AgentMemory('agent-1', { procedural, shared });
+ * agentMemory.episodic.store('Completed code review', ['review', 'code']);
+ * agentMemory.procedural.recordSuccess('chain-review-fix');
+ * agentMemory.shared.contribute('agent-1', 'Auth service uses JWT', ['auth']);
+ * ```
+ */
+class AgentMemory {
+    agentId;
+    episodic;
+    procedural;
+    shared;
+    constructor(agentId, options = {}) {
+        this.agentId = agentId;
+        this.episodic = options.episodic ?? new EpisodicMemory();
+        this.procedural = options.procedural ?? new ProceduralMemory();
+        this.shared = options.shared ?? new SharedLongTermMemory();
+    }
+    /** Recall across all layers, merged and ranked by score */
+    recallAll(options = {}) {
+        const results = [
+            ...this.episodic.recall(options),
+            ...this.procedural.recall(options),
+            ...this.shared.query(this.agentId, options),
+        ];
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, options.maxResults ?? 30);
+    }
+}
+exports.AgentMemory = AgentMemory;
+//# sourceMappingURL=agent-memory.js.map

package/dist/lib/agent-memory.js.map

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

package/dist/lib/agent-vcr.d.ts

@@ -0,0 +1,133 @@
+/**
+ * VCR — Record and replay LLM/agent interactions for testing
+ *
+ * Provides a VCR (Video Cassette Recorder) pattern for capturing
+ * agent execution calls and replaying them deterministically in tests.
+ *
+ * Modes:
+ *   - `record` — Intercepts calls, forwards to real handler, saves cassette
+ *   - `replay` — Matches calls to recorded cassettes, returns saved results
+ *   - `passthrough` — Disabled, all calls go to real handler
+ *
+ * Features:
+ *   - Cassettes stored as JSON files
+ *   - Request matching by agent ID + action + params hash
+ *   - Configurable matching strictness
+ *   - Call ordering enforcement (optional)
+ *   - Missing cassette detection with helpful errors
+ *
+ * Usage:
+ *   const vcr = new AgentVCR({ mode: 'record', cassettePath: './fixtures' });
+ *   const result = await vcr.execute('agent-1', payload, realHandler);
+ *   await vcr.save('my-test'); // Saves cassette to ./fixtures/my-test.json
+ *
+ *   // Later in tests:
+ *   const vcr2 = new AgentVCR({ mode: 'replay', cassettePath: './fixtures' });
+ *   await vcr2.load('my-test');
+ *   const result2 = await vcr2.execute('agent-1', payload); // Returns recorded result
+ *
+ * @module AgentVCR
+ * @version 1.0.0
+ */
+/** VCR operating mode */
+export type VCRMode = 'record' | 'replay' | 'passthrough';
+/** A single recorded interaction */
+export interface VCRInteraction {
+    /** Request fingerprint for matching */
+    fingerprint: string;
+    /** Agent ID */
+    agentId: string;
+    /** Action/instruction */
+    action: string;
+    /** Params hash (for matching) */
+    paramsHash: string;
+    /** Full request payload (for debugging) */
+    request: Record<string, unknown>;
+    /** Recorded response */
+    response: Record<string, unknown>;
+    /** When this was recorded */
+    recordedAt: number;
+    /** Execution duration in ms */
+    durationMs: number;
+}
+/** A cassette file — collection of recorded interactions */
+export interface VCRCassette {
+    /** Cassette name */
+    name: string;
+    /** When the cassette was created */
+    createdAt: number;
+    /** Recorded interactions */
+    interactions: VCRInteraction[];
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/** VCR configuration */
+export interface VCRConfig {
+    /** Operating mode */
+    mode: VCRMode;
+    /** Directory for cassette files */
+    cassettePath: string;
+    /** Match strictness: 'exact' matches full params, 'fuzzy' matches agent+action only */
+    matchMode?: 'exact' | 'fuzzy';
+    /** Whether to enforce call ordering in replay (default: false) */
+    ordered?: boolean;
+    /** Whether to throw on missing cassette in replay (default: true) */
+    throwOnMissing?: boolean;
+}
+/** Real execution handler — wraps the actual agent call */
+export type VCRHandler = (agentId: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** Match result for debugging */
+export interface VCRMatchResult {
+    matched: boolean;
+    fingerprint: string;
+    candidates: number;
+    bestMatch?: VCRInteraction;
+}
+/**
+ * Agent VCR — Record and replay agent execution calls.
+ *
+ * In `record` mode, calls are forwarded to the real handler and saved.
+ * In `replay` mode, calls are matched to saved cassettes.
+ */
+export declare class AgentVCR {
+    private cassette;
+    private replayIndex;
+    private readonly config;
+    constructor(config: VCRConfig);
+    /** Get current mode */
+    get mode(): VCRMode;
+    /** Set mode at runtime */
+    setMode(mode: VCRMode): void;
+    /**
+     * Execute an agent call through the VCR.
+     *
+     * @param agentId - The agent to call
+     * @param payload - The request payload
+     * @param handler - Real handler (required in record/passthrough mode)
+     */
+    execute(agentId: string, payload: Record<string, unknown>, handler?: VCRHandler): Promise<Record<string, unknown>>;
+    /**
+     * Load a cassette from disk.
+     */
+    load(name: string): Promise<VCRCassette>;
+    /**
+     * Save the current recording as a named cassette.
+     */
+    save(name: string): Promise<void>;
+    /** Get the current cassette */
+    getCassette(): VCRCassette | null;
+    /** Reset the VCR (clear cassette and replay index) */
+    reset(): void;
+    /** Get number of recorded interactions */
+    get interactionCount(): number;
+    /**
+     * Try to match a request to a recorded interaction.
+     * Useful for debugging match failures.
+     */
+    findMatch(agentId: string, payload: Record<string, unknown>): VCRMatchResult;
+    private recordExecution;
+    private replayExecution;
+    private computeFingerprint;
+    private hashParams;
+}
+//# sourceMappingURL=agent-vcr.d.ts.map

package/dist/lib/agent-vcr.d.ts.map

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