network-ai 5.10.2 → 5.11.0

package/dist/esm/lib/compliance-monitor.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Real-Time Compliance Monitor — Phase 4: Behavioral Control Plane
+ *
+ * Async monitoring loop that continuously checks for:
+ * - Turn-taking violations (agent acting out of turn)
+ * - Response timeouts (agent silent for too long)
+ * - Journey adherence (current FSM state timed out)
+ * - Tool usage anomalies (tool called more than allowed rate)
+ *
+ * @module compliance-monitor
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComplianceMonitor = void 0;
+// ============================================================================
+// COMPLIANCE MONITOR
+// ============================================================================
+/**
+ * Real-time async compliance monitor.
+ *
+ * @example
+ * ```typescript
+ * import { ComplianceMonitor } from 'network-ai';
+ *
+ * const monitor = new ComplianceMonitor({
+ *   pollIntervalMs: 5_000,
+ *   fsm,
+ *   agentConfigs: [
+ *     { agentId: 'data_analyst', responseTimeoutMs: 30_000, maxToolCallsPerWindow: 10 },
+ *   ],
+ *   onViolation: v => console.warn('[COMPLIANCE]', v.type, v.message),
+ * });
+ *
+ * monitor.start();
+ *
+ * // Record actions as agents work
+ * monitor.recordAction({ agentId: 'data_analyst', action: 'query', tool: 'query_db' });
+ *
+ * // Later…
+ * monitor.stop();
+ * const violations = monitor.getViolations();
+ * ```
+ */
+class ComplianceMonitor {
+    options;
+    running = false;
+    timer = null;
+    // agentId -> last action timestamp
+    lastActionAt = new Map();
+    // agentId -> { tool -> timestamps[] }
+    toolCallLog = new Map();
+    // recorded turn order
+    turnOrder = [];
+    // violations collected internally
+    violations = [];
+    // agentId -> action count (for sequential turn checking)
+    consecutiveActionsBy = new Map();
+    lastActingAgent = null;
+    constructor(options = {}) {
+        this.options = {
+            pollIntervalMs: options.pollIntervalMs ?? 5_000,
+            agentConfigs: options.agentConfigs ?? [],
+            collectViolations: options.collectViolations ?? true,
+            maxViolationsInMemory: options.maxViolationsInMemory ?? 500,
+            fsm: options.fsm,
+            onViolation: options.onViolation,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Lifecycle
+    // --------------------------------------------------------------------------
+    /** Start the monitoring loop. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.timer = setInterval(() => this._poll(), this.options.pollIntervalMs);
+    }
+    /** Stop the monitoring loop. */
+    stop() {
+        this.running = false;
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Whether the monitor is currently running. */
+    get isRunning() {
+        return this.running;
+    }
+    // --------------------------------------------------------------------------
+    // Action recording
+    // --------------------------------------------------------------------------
+    /**
+     * Record an agent action. Call this every time an agent performs an action
+     * so the monitor can track turn-taking, timeouts, and tool rates.
+     */
+    recordAction(action) {
+        const now = action.timestamp ?? Date.now();
+        const { agentId, tool } = action;
+        this.lastActionAt.set(agentId, now);
+        // Track turn taking
+        if (this.lastActingAgent !== null && this.lastActingAgent !== agentId) {
+            this.consecutiveActionsBy.set(this.lastActingAgent, 0);
+        }
+        const prev = this.consecutiveActionsBy.get(agentId) ?? 0;
+        this.consecutiveActionsBy.set(agentId, prev + 1);
+        this.lastActingAgent = agentId;
+        this.turnOrder.push(agentId);
+        // Keep turn order bounded
+        if (this.turnOrder.length > 1000)
+            this.turnOrder.splice(0, 500);
+        // Track tool calls
+        if (tool) {
+            if (!this.toolCallLog.has(agentId))
+                this.toolCallLog.set(agentId, new Map());
+            const agentTools = this.toolCallLog.get(agentId);
+            if (!agentTools.has(tool))
+                agentTools.set(tool, []);
+            agentTools.get(tool).push(now);
+        }
+        // Immediate tool-rate check
+        if (tool)
+            this._checkToolRate(agentId, tool, now);
+    }
+    // --------------------------------------------------------------------------
+    // Queries
+    // --------------------------------------------------------------------------
+    /** Get all collected violations (newest last). */
+    getViolations(filter) {
+        if (!filter)
+            return [...this.violations];
+        return this.violations.filter(v => {
+            if (filter.type && v.type !== filter.type)
+                return false;
+            if (filter.agentId && v.agentId !== filter.agentId)
+                return false;
+            if (filter.severity && v.severity !== filter.severity)
+                return false;
+            return true;
+        });
+    }
+    /** Clear collected violations. */
+    clearViolations() {
+        this.violations = [];
+    }
+    /** Get a compliance summary (counts per type and agent). */
+    getSummary() {
+        const bySeverity = {};
+        const byType = {};
+        const byAgent = {};
+        for (const v of this.violations) {
+            bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
+            byType[v.type] = (byType[v.type] ?? 0) + 1;
+            byAgent[v.agentId] = (byAgent[v.agentId] ?? 0) + 1;
+        }
+        return { total: this.violations.length, bySeverity, byType, byAgent };
+    }
+    /** Update (or add) a per-agent config at runtime. */
+    setAgentConfig(config) {
+        const idx = this.options.agentConfigs.findIndex(c => c.agentId === config.agentId);
+        if (idx >= 0)
+            this.options.agentConfigs[idx] = config;
+        else
+            this.options.agentConfigs.push(config);
+    }
+    // --------------------------------------------------------------------------
+    // Internal polling
+    // --------------------------------------------------------------------------
+    _poll() {
+        this._checkResponseTimeouts();
+        this._checkJourneyTimeout();
+        this._checkTurnTaking();
+    }
+    _checkResponseTimeouts() {
+        const now = Date.now();
+        for (const cfg of this.options.agentConfigs) {
+            if (!cfg.responseTimeoutMs)
+                continue;
+            const lastAt = this.lastActionAt.get(cfg.agentId);
+            if (!lastAt)
+                continue;
+            const elapsed = now - lastAt;
+            if (elapsed > cfg.responseTimeoutMs) {
+                this._emit({
+                    type: 'RESPONSE_TIMEOUT',
+                    agentId: cfg.agentId,
+                    message: `Agent "${cfg.agentId}" has been silent for ${Math.round(elapsed / 1000)}s (limit: ${Math.round(cfg.responseTimeoutMs / 1000)}s)`,
+                    severity: 'high',
+                    metadata: { elapsed, limit: cfg.responseTimeoutMs },
+                });
+            }
+        }
+    }
+    _checkJourneyTimeout() {
+        const fsm = this.options.fsm;
+        if (!fsm)
+            return;
+        if (fsm.isTimedOut) {
+            this._emit({
+                type: 'JOURNEY_TIMEOUT',
+                agentId: 'system',
+                message: `FSM state "${fsm.state}" has exceeded its timeout (${fsm.timeInCurrentState}ms elapsed)`,
+                severity: 'high',
+                metadata: { state: fsm.state, elapsed: fsm.timeInCurrentState },
+            });
+        }
+    }
+    _checkTurnTaking() {
+        // Detect any single agent acting more than 5 consecutive times
+        for (const [agentId, count] of this.consecutiveActionsBy) {
+            if (count >= 5) {
+                this._emit({
+                    type: 'TURN_TAKING',
+                    agentId,
+                    message: `Agent "${agentId}" has taken ${count} consecutive actions without yielding`,
+                    severity: 'medium',
+                    metadata: { consecutiveCount: count },
+                });
+                // Reset after emitting so we don't spam
+                this.consecutiveActionsBy.set(agentId, 0);
+            }
+        }
+    }
+    _checkToolRate(agentId, tool, now) {
+        const cfg = this.options.agentConfigs.find(c => c.agentId === agentId);
+        if (!cfg?.maxToolCallsPerWindow)
+            return;
+        const windowMs = cfg.toolRateWindowMs ?? 60_000;
+        const maxCalls = cfg.maxToolCallsPerWindow;
+        const timestamps = this.toolCallLog.get(agentId)?.get(tool) ?? [];
+        const windowStart = now - windowMs;
+        const recentCalls = timestamps.filter(t => t >= windowStart);
+        if (recentCalls.length > maxCalls) {
+            this._emit({
+                type: 'TOOL_ABUSE',
+                agentId,
+                message: `Agent "${agentId}" called tool "${tool}" ${recentCalls.length}x in ${windowMs / 1000}s (max: ${maxCalls})`,
+                severity: 'high',
+                metadata: { tool, callCount: recentCalls.length, windowMs, max: maxCalls },
+            });
+        }
+    }
+    _emit(params) {
+        const violation = {
+            id: `cv_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            timestamp: new Date().toISOString(),
+            ...params,
+        };
+        if (this.options.collectViolations) {
+            this.violations.push(violation);
+            // Trim if over limit
+            if (this.violations.length > this.options.maxViolationsInMemory) {
+                this.violations.splice(0, Math.floor(this.options.maxViolationsInMemory / 4));
+            }
+        }
+        this.options.onViolation?.(violation);
+    }
+}
+exports.ComplianceMonitor = ComplianceMonitor;
+//# sourceMappingURL=compliance-monitor.js.map

package/dist/esm/lib/compliance-monitor.js.map

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

package/dist/esm/lib/confidence-filter.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Confidence Filter — Multi-agent result confidence scoring & filtering
+ *
+ * Scores agent findings by confidence, filters by threshold, and optionally
+ * validates low-confidence findings with a secondary agent. Inspired by
+ * Claude Code's confidence-based multi-agent filtering pattern.
+ *
+ * @module ConfidenceFilter
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfidenceFilter = void 0;
+// ============================================================================
+// CONFIDENCE FILTER
+// ============================================================================
+/**
+ * Filters and validates multi-agent findings based on confidence scores.
+ *
+ * @example
+ * ```typescript
+ * const filter = new ConfidenceFilter(registry, baseCtx, { defaultThreshold: 70 });
+ *
+ * const findings: Finding[] = [
+ *   { id: '1', description: 'SQL injection in login.ts', confidence: 95, sourceAgent: 'scanner-a' },
+ *   { id: '2', description: 'Possible XSS in comments', confidence: 45, sourceAgent: 'scanner-b' },
+ * ];
+ *
+ * const filtered = filter.filter(findings);
+ * // filtered.accepted → finding #1, filtered.rejected → finding #2
+ *
+ * // Validate a low-confidence finding with a secondary agent
+ * const validated = await filter.validate(findings[1], 'expert-reviewer');
+ * ```
+ */
+class ConfidenceFilter {
+    registry;
+    baseContext;
+    options;
+    /**
+     * @param registry Adapter registry for validation calls (optional — filter-only mode if null)
+     * @param baseContext Default execution context for validation agents
+     * @param options Filter configuration
+     */
+    constructor(registry, baseContext, options = {}) {
+        this.registry = registry;
+        this.baseContext = baseContext;
+        this.options = options;
+    }
+    /**
+     * Score a single finding. Returns a normalised 0–100 confidence score.
+     * Currently a pass-through; override or extend for custom scoring logic.
+     */
+    score(finding) {
+        return Math.max(0, Math.min(100, finding.confidence));
+    }
+    /**
+     * Filter findings by confidence threshold.
+     *
+     * @param findings Findings to filter
+     * @param threshold Override the default threshold for this call
+     */
+    filter(findings, threshold) {
+        const t = threshold ?? this.options.defaultThreshold ?? 70;
+        const accepted = [];
+        const rejected = [];
+        for (const f of findings) {
+            const s = this.score(f);
+            if (s >= t) {
+                accepted.push(f);
+            }
+            else {
+                rejected.push(f);
+            }
+        }
+        return { accepted, rejected, threshold: t };
+    }
+    /**
+     * Validate a finding using a secondary agent.
+     * The validator agent's result is used to update `validatedBy` and `validated`.
+     *
+     * @param finding The finding to validate
+     * @param validatorAgentId Agent to perform the validation (overrides options)
+     * @returns Updated finding with validation metadata
+     */
+    async validate(finding, validatorAgentId) {
+        const agentId = validatorAgentId ?? this.options.validatorAgent;
+        if (!agentId) {
+            throw new Error('No validator agent specified');
+        }
+        if (!this.registry || !this.baseContext) {
+            throw new Error('Registry and baseContext required for validation');
+        }
+        const payload = this.options.validationPayloadFactory
+            ? this.options.validationPayloadFactory(finding)
+            : {
+                action: 'validate',
+                params: { findingId: finding.id, description: finding.description, confidence: finding.confidence },
+            };
+        const ctx = {
+            ...this.baseContext,
+            metadata: { ...this.baseContext.metadata, validating: finding.id },
+        };
+        const result = await this.registry.executeAgent(agentId, payload, ctx);
+        return {
+            ...finding,
+            validatedBy: agentId,
+            validated: result.success,
+            confidence: result.success
+                ? Math.min(100, finding.confidence + 20) // boost confidence if validated
+                : Math.max(0, finding.confidence - 10), // reduce if validation failed
+        };
+    }
+    /**
+     * Validate all rejected findings from a filter result.
+     * Returns the updated filter result with re-scored findings.
+     */
+    async validateRejected(filterResult, validatorAgentId) {
+        const validated = [];
+        for (const f of filterResult.rejected) {
+            validated.push(await this.validate(f, validatorAgentId));
+        }
+        // Re-filter after validation
+        const newAccepted = [];
+        const newRejected = [];
+        for (const f of validated) {
+            if (f.confidence >= filterResult.threshold) {
+                newAccepted.push(f);
+            }
+            else {
+                newRejected.push(f);
+            }
+        }
+        return {
+            accepted: [...filterResult.accepted, ...newAccepted],
+            rejected: newRejected,
+            threshold: filterResult.threshold,
+        };
+    }
+    /**
+     * Aggregate findings from multiple sources using a strategy.
+     *
+     * - `highest`: Keep the finding with the highest confidence for each id
+     * - `average`: Average the confidence scores for each id
+     * - `unanimous`: Only keep findings that appear in ALL sources
+     * - `majority`: Only keep findings that appear in more than half of sources
+     *
+     * @param findingSets Arrays of findings from different agents
+     * @param strategy Aggregation strategy to use
+     */
+    aggregate(findingSets, strategy = 'highest') {
+        const totalInput = findingSets.reduce((sum, s) => sum + s.length, 0);
+        const sourceCount = findingSets.length;
+        if (sourceCount === 0) {
+            return { findings: [], strategy, totalInput: 0, sourceCount: 0 };
+        }
+        // Group by finding id
+        const grouped = new Map();
+        for (const set of findingSets) {
+            for (const f of set) {
+                if (!grouped.has(f.id))
+                    grouped.set(f.id, []);
+                grouped.get(f.id).push(f);
+            }
+        }
+        let findings;
+        switch (strategy) {
+            case 'highest': {
+                findings = [];
+                for (const [, group] of grouped) {
+                    const best = group.reduce((a, b) => (a.confidence > b.confidence ? a : b));
+                    findings.push(best);
+                }
+                break;
+            }
+            case 'average': {
+                findings = [];
+                for (const [, group] of grouped) {
+                    const avgConfidence = Math.round(group.reduce((s, f) => s + f.confidence, 0) / group.length);
+                    findings.push({ ...group[0], confidence: avgConfidence });
+                }
+                break;
+            }
+            case 'unanimous': {
+                findings = [];
+                for (const [, group] of grouped) {
+                    if (group.length === sourceCount) {
+                        const avgConfidence = Math.round(group.reduce((s, f) => s + f.confidence, 0) / group.length);
+                        findings.push({ ...group[0], confidence: avgConfidence });
+                    }
+                }
+                break;
+            }
+            case 'majority': {
+                findings = [];
+                const majorityThreshold = Math.floor(sourceCount / 2) + 1;
+                for (const [, group] of grouped) {
+                    if (group.length >= majorityThreshold) {
+                        const avgConfidence = Math.round(group.reduce((s, f) => s + f.confidence, 0) / group.length);
+                        findings.push({ ...group[0], confidence: avgConfidence });
+                    }
+                }
+                break;
+            }
+        }
+        return { findings, strategy, totalInput, sourceCount };
+    }
+}
+exports.ConfidenceFilter = ConfidenceFilter;
+//# sourceMappingURL=confidence-filter.js.map

package/dist/esm/lib/confidence-filter.js.map

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