network-ai 3.2.10 → 3.3.0

package/dist/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/lib/compliance-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compliance-monitor.js","sourceRoot":"","sources":["../../lib/compliance-monitor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AA+DH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,iBAAiB;IACpB,OAAO,CAIb;IAEM,OAAO,GAAG,KAAK,CAAC;IAChB,KAAK,GAA0C,IAAI,CAAC;IAE5D,mCAAmC;IAC3B,YAAY,GAAwB,IAAI,GAAG,EAAE,CAAC;IACtD,sCAAsC;IAC9B,WAAW,GAAuC,IAAI,GAAG,EAAE,CAAC;IACpE,sBAAsB;IACd,SAAS,GAAa,EAAE,CAAC;IACjC,kCAAkC;IAC1B,UAAU,GAA0B,EAAE,CAAC;IAC/C,yDAAyD;IACjD,oBAAoB,GAAwB,IAAI,GAAG,EAAE,CAAC;IACtD,eAAe,GAAkB,IAAI,CAAC;IAE9C,YAAY,UAAoC,EAAE;QAChD,IAAI,CAAC,OAAO,GAAG;YACb,cAAc,EAAS,OAAO,CAAC,cAAc,IAAW,KAAK;YAC7D,YAAY,EAAW,OAAO,CAAC,YAAY,IAAa,EAAE;YAC1D,iBAAiB,EAAM,OAAO,CAAC,iBAAiB,IAAQ,IAAI;YAC5D,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,IAAI,GAAG;YAC3D,GAAG,EAAU,OAAO,CAAC,GAAG;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,YAAY;IACZ,6EAA6E;IAE7E,iCAAiC;IACjC,KAAK;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5E,CAAC;IAED,gCAAgC;IAChC,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,6EAA6E;IAC7E,mBAAmB;IACnB,6EAA6E;IAE7E;;;OAGG;IACH,YAAY,CAAC,MAAmB;QAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;QAEjC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAEpC,oBAAoB;QACpB,IAAI,IAAI,CAAC,eAAe,KAAK,IAAI,IAAI,IAAI,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;YACtE,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;QACjD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,0BAA0B;QAC1B,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAEhE,mBAAmB;QACnB,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAC7E,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;YAClD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACpD,UAAU,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;QAED,4BAA4B;QAC5B,IAAI,IAAI;YAAE,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,6EAA6E;IAC7E,UAAU;IACV,6EAA6E;IAE7E,kDAAkD;IAClD,aAAa,CAAC,MAA+F;QAC3G,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YAChC,IAAI,MAAM,CAAC,IAAI,IAAS,CAAC,CAAC,IAAI,KAAU,MAAM,CAAC,IAAI;gBAAO,OAAO,KAAK,CAAC;YACvE,IAAI,MAAM,CAAC,OAAO,IAAM,CAAC,CAAC,OAAO,KAAO,MAAM,CAAC,OAAO;gBAAI,OAAO,KAAK,CAAC;YACvE,IAAI,MAAM,CAAC,QAAQ,IAAK,CAAC,CAAC,QAAQ,KAAM,MAAM,CAAC,QAAQ;gBAAG,OAAO,KAAK,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED,kCAAkC;IAClC,eAAe;QACb,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;IACvB,CAAC;IAED,4DAA4D;IAC5D,UAAU;QAMR,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA+B,EAAE,CAAC;QAC9C,MAAM,OAAO,GAA8B,EAAE,CAAC;QAC9C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAChC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAI,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAK,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7D,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAY,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAa,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7D,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAS,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACxE,CAAC;IAED,qDAAqD;IACrD,cAAc,CAAC,MAA0B;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;QACnF,IAAI,GAAG,IAAI,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;;YACjD,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,6EAA6E;IAC7E,mBAAmB;IACnB,6EAA6E;IAErE,KAAK;QACX,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC9B,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC5B,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC;IAEO,sBAAsB;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC5C,IAAI,CAAC,GAAG,CAAC,iBAAiB;gBAAE,SAAS;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClD,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,MAAM,OAAO,GAAG,GAAG,GAAG,MAAM,CAAC;YAC7B,IAAI,OAAO,GAAG,GAAG,CAAC,iBAAiB,EAAE,CAAC;gBACpC,IAAI,CAAC,KAAK,CAAC;oBACT,IAAI,EAAE,kBAAkB;oBACxB,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,OAAO,EAAE,UAAU,GAAG,CAAC,OAAO,yBAAyB,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,iBAAiB,GAAG,IAAI,CAAC,IAAI;oBAC1I,QAAQ,EAAE,MAAM;oBAChB,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,iBAAiB,EAAE;iBACpD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAEO,oBAAoB;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAC7B,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,CAAC;gBACT,IAAI,EAAE,iBAAiB;gBACvB,OAAO,EAAE,QAAQ;gBACjB,OAAO,EAAE,cAAc,GAAG,CAAC,KAAK,+BAA+B,GAAG,CAAC,kBAAkB,aAAa;gBAClG,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,kBAAkB,EAAE;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,gBAAgB;QACtB,+DAA+D;QAC/D,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,oBAAoB,EAAE,CAAC;YACzD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,KAAK,CAAC;oBACT,IAAI,EAAE,aAAa;oBACnB,OAAO;oBACP,OAAO,EAAE,UAAU,OAAO,eAAe,KAAK,uCAAuC;oBACrF,QAAQ,EAAE,QAAQ;oBAClB,QAAQ,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE;iBACtC,CAAC,CAAC;gBACH,wCAAwC;gBACxC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAEO,cAAc,CAAC,OAAe,EAAE,IAAY,EAAE,GAAW;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;QACvE,IAAI,CAAC,GAAG,EAAE,qBAAqB;YAAE,OAAO;QAExC,MAAM,QAAQ,GAAO,GAAG,CAAC,gBAAgB,IAAI,MAAM,CAAC;QACpD,MAAM,QAAQ,GAAO,GAAG,CAAC,qBAAqB,CAAC;QAC/C,MAAM,UAAU,GAAK,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACpE,MAAM,WAAW,GAAI,GAAG,GAAG,QAAQ,CAAC;QACpC,MAAM,WAAW,GAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC;QAE9D,IAAI,WAAW,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC;gBACT,IAAI,EAAE,YAAY;gBAClB,OAAO;gBACP,OAAO,EAAE,UAAU,OAAO,kBAAkB,IAAI,KAAK,WAAW,CAAC,MAAM,QAAQ,QAAQ,GAAG,IAAI,WAAW,QAAQ,GAAG;gBACpH,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE;aAC3E,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,MAAqD;QACjE,MAAM,SAAS,GAAwB;YACrC,EAAE,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;YAChE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,GAAG,MAAM;SACV,CAAC;QAEF,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;YACnC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAChC,qBAAqB;YACrB,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC;gBAChE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,GAAG,CAAC,CAAC,CAAC,CAAC;YAChF,CAAC;QACH,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;CACF;AA9OD,8CA8OC"}

package/dist/lib/fsm-journey.d.ts

@@ -0,0 +1,238 @@
+/**
+ * FSM Journey Layer — Phase 4: Behavioral Control Plane
+ *
+ * Implements state machine–based workflow authorization. Agents can only act
+ * in their designated states, and tools can only be called when the current
+ * workflow state permits it.
+ *
+ * @module fsm-journey
+ */
+/** Named workflow states. Extend by passing custom string literals. */
+export type WorkflowStateName = string;
+/** Built-in canonical workflow states for common agent pipelines. */
+export declare const WORKFLOW_STATES: {
+    readonly INTAKE: "INTAKE";
+    readonly VALIDATE: "VALIDATE";
+    readonly RESEARCH: "RESEARCH";
+    readonly PLAN: "PLAN";
+    readonly EXECUTE: "EXECUTE";
+    readonly REVIEW: "REVIEW";
+    readonly DELIVER: "DELIVER";
+    readonly COMPLETE: "COMPLETE";
+    readonly ERROR: "ERROR";
+};
+/** A single state definition in the FSM. */
+export interface WorkflowStateDefinition {
+    /** Unique state name */
+    name: WorkflowStateName;
+    /** Human-readable description */
+    description?: string;
+    /** Agents authorised to perform actions in this state. '*' means any. */
+    authorizedAgents: string[];
+    /** Tools authorised in this state, keyed by agentId ('*' = any agent). */
+    authorizedTools?: Record<string, string[]>;
+    /** Maximum time (ms) the FSM may remain in this state before it's a violation. */
+    timeoutMs?: number;
+}
+/** A named transition between two states triggered by an event. */
+export interface StateTransition {
+    from: WorkflowStateName;
+    event: string;
+    to: WorkflowStateName;
+    /** If set, only this agent (or '*') may fire this transition. */
+    allowedBy?: string;
+}
+/** Describes what happened when a state transition was attempted. */
+export interface TransitionResult {
+    success: boolean;
+    previousState: WorkflowStateName;
+    currentState: WorkflowStateName;
+    reason?: string;
+}
+/** Result from an inline compliance check. */
+export interface ComplianceCheckResult {
+    allowed: boolean;
+    reason?: string;
+    currentState: WorkflowStateName;
+    agentId: string;
+    tool?: string;
+}
+/** Options passed to JourneyFSM constructor. */
+export interface JourneyFSMOptions {
+    states: WorkflowStateDefinition[];
+    transitions: StateTransition[];
+    initialState: WorkflowStateName;
+    /** Called whenever a transition fires (success or failure). */
+    onTransition?: (result: TransitionResult, agentId: string) => void;
+    /** Called whenever a compliance violation is blocked. */
+    onViolation?: (check: ComplianceCheckResult) => void;
+}
+/**
+ * Standalone tool authorization matrix.
+ *
+ * Maps `agentId -> state -> allowedTools[]`.
+ * The FSM embeds one automatically, but you can also use this independently.
+ *
+ * @example
+ * ```typescript
+ * const matrix = new ToolAuthorizationMatrix();
+ * matrix.allow('data_analyst', 'RESEARCH', ['search_web', 'query_db']);
+ * matrix.allow('*', 'REVIEW', ['read_blackboard']);
+ * matrix.isAllowed('data_analyst', 'RESEARCH', 'query_db'); // true
+ * ```
+ */
+export declare class ToolAuthorizationMatrix {
+    private rules;
+    /**
+     * Grant an agent permission to use a list of tools in a given state.
+     * Use `'*'` for agentId or toolNames to mean "all".
+     */
+    allow(agentId: string, state: WorkflowStateName, tools: string[]): void;
+    /** Revoke a specific tool permission. */
+    revoke(agentId: string, state: WorkflowStateName, tool: string): void;
+    /**
+     * Check if an agent is allowed to use a tool in a given state.
+     * Checks exact agentId first, then falls back to '*' wildcard.
+     */
+    isAllowed(agentId: string, state: WorkflowStateName, tool: string): boolean;
+    private _check;
+    /** Dump current rules for debugging/audit. */
+    dump(): Record<string, Record<string, string[]>>;
+}
+/**
+ * Finite-state machine for workflow authorization.
+ *
+ * Governs which agents can act (and with which tools) based on the current
+ * workflow state. Integrates an inline `ComplianceMiddleware` and a
+ * `ToolAuthorizationMatrix`.
+ *
+ * @example
+ * ```typescript
+ * import { JourneyFSM, WORKFLOW_STATES } from 'network-ai';
+ *
+ * const fsm = new JourneyFSM({
+ *   states: [
+ *     { name: 'INTAKE',   authorizedAgents: ['orchestrator'],  authorizedTools: { orchestrator: ['read_intake'] } },
+ *     { name: 'RESEARCH', authorizedAgents: ['data_analyst'],  authorizedTools: { data_analyst: ['query_db', 'search_web'] } },
+ *     { name: 'DELIVER',  authorizedAgents: ['orchestrator'],  authorizedTools: { '*': ['write_blackboard'] } },
+ *   ],
+ *   transitions: [
+ *     { from: 'INTAKE',   event: 'start_research', to: 'RESEARCH', allowedBy: 'orchestrator' },
+ *     { from: 'RESEARCH', event: 'research_done',  to: 'DELIVER',  allowedBy: '*' },
+ *   ],
+ *   initialState: 'INTAKE',
+ * });
+ *
+ * fsm.transition('start_research', 'orchestrator'); // moves to RESEARCH
+ * fsm.canAgentAct('data_analyst'); // true — we're now in RESEARCH
+ * ```
+ */
+export declare class JourneyFSM {
+    private currentState;
+    private stateMap;
+    private transitions;
+    private options;
+    private stateEnteredAt;
+    private history;
+    /** Embedded tool authorization matrix (populated from state definitions). */
+    readonly toolMatrix: ToolAuthorizationMatrix;
+    constructor(options: JourneyFSMOptions);
+    /** Current workflow state name. */
+    get state(): WorkflowStateName;
+    /** Full definition of the current state. */
+    get stateDefinition(): WorkflowStateDefinition;
+    /** How long (ms) the FSM has been in the current state. */
+    get timeInCurrentState(): number;
+    /** Whether the current state has timed out. */
+    get isTimedOut(): boolean;
+    /** Full transition history. */
+    get transitionHistory(): ReadonlyArray<{
+        state: WorkflowStateName;
+        enteredAt: number;
+        exitedAt?: number;
+        triggeredBy?: string;
+    }>;
+    /**
+     * Check if an agent is authorized to perform any action in the current state.
+     */
+    canAgentAct(agentId: string): boolean;
+    /**
+     * Check if an agent is authorized to use a specific tool in the current state.
+     * Checks both the tool matrix AND agent authorization.
+     */
+    canAgentUseTool(agentId: string, tool: string): boolean;
+    /**
+     * Inline compliance check — call this BEFORE executing any agent action.
+     * Returns `{ allowed: true }` or `{ allowed: false, reason }`.
+     */
+    checkCompliance(agentId: string, tool?: string): ComplianceCheckResult;
+    /**
+     * Fire a named event to transition the FSM to the next state.
+     * Returns a `TransitionResult` describing what happened.
+     */
+    transition(event: string, agentId: string): TransitionResult;
+    /**
+     * Returns all events available from the current state.
+     */
+    availableEvents(): string[];
+    /**
+     * Returns which agents are authorized in a given state (defaults to current).
+     */
+    getAuthorizedAgents(stateName?: WorkflowStateName): string[];
+    /**
+     * Reset the FSM to its initial state.
+     */
+    reset(): void;
+}
+/**
+ * Wraps an async action and blocks its execution if the FSM denies it.
+ *
+ * @example
+ * ```typescript
+ * const middleware = new ComplianceMiddleware(fsm);
+ *
+ * const result = await middleware.enforce('data_analyst', 'query_db', async () => {
+ *   return await db.query('SELECT * FROM invoices');
+ * });
+ * ```
+ */
+export declare class ComplianceMiddleware {
+    private fsm;
+    constructor(fsm: JourneyFSM);
+    /**
+     * Enforce compliance before running `action`.
+     * Throws if not authorized; returns the action's result if allowed.
+     */
+    enforce<T>(agentId: string, tool: string, action: () => Promise<T>): Promise<T>;
+    /**
+     * Synchronous version — use when the action is not async.
+     */
+    enforceSync<T>(agentId: string, tool: string, action: () => T): T;
+}
+/** Thrown when ComplianceMiddleware blocks an action. */
+export declare class ComplianceViolationError extends Error {
+    readonly check: ComplianceCheckResult;
+    constructor(message: string, check: ComplianceCheckResult);
+}
+/**
+ * Build a standard delivery pipeline FSM with sensible defaults.
+ * States: INTAKE → VALIDATE → RESEARCH → PLAN → EXECUTE → REVIEW → DELIVER → COMPLETE
+ *
+ * @example
+ * ```typescript
+ * const fsm = createDeliveryPipelineFSM({
+ *   orchestratorId: 'orchestrator',
+ *   researchAgentId: 'data_analyst',
+ *   executorId: 'code_writer',
+ * });
+ * ```
+ */
+export declare function createDeliveryPipelineFSM(options: {
+    orchestratorId?: string;
+    researchAgentId?: string;
+    executorId?: string;
+    reviewerId?: string;
+    onTransition?: JourneyFSMOptions['onTransition'];
+    onViolation?: JourneyFSMOptions['onViolation'];
+}): JourneyFSM;
+//# sourceMappingURL=fsm-journey.d.ts.map

package/dist/lib/fsm-journey.d.ts.map

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