network-ai 5.10.2 → 5.11.0

package/dist/esm/lib/config-watcher.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * ConfigWatcher — Hot-reload configuration from disk.
+ *
+ * Uses `fs.watch()` to monitor config files and applies changes to
+ * live CONFIG, trust levels, resource profiles, and budget ceilings.
+ * Emits events on reload so components can react.
+ *
+ * @module ConfigWatcher
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigWatcher = void 0;
+const events_1 = require("events");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ============================================================================
+// CONFIG WATCHER
+// ============================================================================
+/**
+ * Watches config files on disk and applies changes to live objects.
+ *
+ * Supports three config file types:
+ * - **config.json** — patches `CONFIG` object fields
+ * - **trust_levels.json** — array of `{ agentId, level }` applied to AuthGuardian
+ * - **budget.json** — `{ ceiling, perAgentCeiling }` applied to FederatedBudget
+ *
+ * @example
+ * ```ts
+ * const watcher = new ConfigWatcher({
+ *   configPath: './data/config.json',
+ *   trustPath: './data/trust_levels.json',
+ *   targets: { config: CONFIG, authGuardian: guardian, budget: fed },
+ * });
+ * watcher.on('reload', (evt) => console.log('Reloaded:', evt.file));
+ * watcher.start();
+ * // ... later
+ * watcher.stop();
+ * ```
+ */
+class ConfigWatcher extends events_1.EventEmitter {
+    watchers = [];
+    targets;
+    configPath;
+    trustPath;
+    budgetPath;
+    debounceMs;
+    debounceTimers = new Map();
+    running = false;
+    constructor(options = {}) {
+        super();
+        this.configPath = options.configPath;
+        this.trustPath = options.trustPath;
+        this.budgetPath = options.budgetPath;
+        this.targets = options.targets ?? {};
+        this.debounceMs = options.debounceMs ?? 300;
+    }
+    /** Update targets after construction */
+    setTargets(targets) {
+        Object.assign(this.targets, targets);
+    }
+    /** Start watching all configured paths */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const paths = [this.configPath, this.trustPath, this.budgetPath].filter(Boolean);
+        for (const filePath of paths) {
+            try {
+                if (!fs.existsSync(filePath))
+                    continue;
+                const watcher = fs.watch(filePath, { persistent: false }, (_event) => {
+                    this.debouncedReload(filePath);
+                });
+                this.watchers.push(watcher);
+            }
+            catch {
+                // File doesn't exist or not watchable — skip silently
+            }
+        }
+    }
+    /** Stop all watchers */
+    stop() {
+        this.running = false;
+        for (const w of this.watchers) {
+            try {
+                w.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.watchers = [];
+        for (const timer of this.debounceTimers.values())
+            clearTimeout(timer);
+        this.debounceTimers.clear();
+    }
+    /** Manually trigger a reload for a specific file */
+    reload(filePath) {
+        this.applyReload(filePath);
+    }
+    /** Whether the watcher is currently active */
+    isRunning() {
+        return this.running;
+    }
+    // --------------------------------------------------------------------------
+    // INTERNAL
+    // --------------------------------------------------------------------------
+    debouncedReload(filePath) {
+        const existing = this.debounceTimers.get(filePath);
+        if (existing)
+            clearTimeout(existing);
+        this.debounceTimers.set(filePath, setTimeout(() => {
+            this.debounceTimers.delete(filePath);
+            this.applyReload(filePath);
+        }, this.debounceMs));
+    }
+    applyReload(filePath) {
+        try {
+            const resolved = path.resolve(filePath);
+            const raw = fs.readFileSync(resolved, 'utf-8');
+            const data = JSON.parse(raw);
+            const changes = [];
+            if (resolved === path.resolve(this.configPath ?? '')) {
+                this.applyConfig(data, changes);
+            }
+            else if (resolved === path.resolve(this.trustPath ?? '')) {
+                this.applyTrust(data, changes);
+            }
+            else if (resolved === path.resolve(this.budgetPath ?? '')) {
+                this.applyBudget(data, changes);
+            }
+            const evt = { file: filePath, timestamp: Date.now(), changes };
+            this.emit('reload', evt);
+        }
+        catch (err) {
+            const errEvt = {
+                file: filePath,
+                timestamp: Date.now(),
+                error: err instanceof Error ? err.message : String(err),
+            };
+            this.emit('error', errEvt);
+        }
+    }
+    applyConfig(data, changes) {
+        if (!this.targets.config || typeof data !== 'object' || data === null)
+            return;
+        const obj = data;
+        const allowed = new Set([
+            'maxParallelAgents', 'defaultTimeout', 'enableTracing',
+            'grantTokenTTL', 'maxBlackboardValueSize',
+        ]);
+        for (const [key, value] of Object.entries(obj)) {
+            if (allowed.has(key)) {
+                this.targets.config[key] = value;
+                changes.push(`config.${key}=${JSON.stringify(value)}`);
+            }
+        }
+    }
+    applyTrust(data, changes) {
+        if (!this.targets.authGuardian?.setTrustLevel || !Array.isArray(data))
+            return;
+        for (const entry of data) {
+            if (typeof entry === 'object' && entry !== null &&
+                'agentId' in entry && 'level' in entry &&
+                typeof entry.agentId === 'string' &&
+                typeof entry.level === 'number') {
+                const { agentId, level } = entry;
+                this.targets.authGuardian.setTrustLevel(agentId, level);
+                changes.push(`trust.${agentId}=${level}`);
+            }
+        }
+    }
+    applyBudget(data, changes) {
+        if (!this.targets.budget?.setCeiling || typeof data !== 'object' || data === null)
+            return;
+        const obj = data;
+        if (typeof obj.ceiling === 'number') {
+            this.targets.budget.setCeiling(obj.ceiling);
+            changes.push(`budget.ceiling=${obj.ceiling}`);
+        }
+    }
+}
+exports.ConfigWatcher = ConfigWatcher;
+//# sourceMappingURL=config-watcher.js.map

package/dist/esm/lib/config-watcher.js.map

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

package/dist/esm/lib/consistency.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * Configurable Consistency Levels for Blackboard Backends
+ *
+ * Wraps any `BlackboardBackend` with one of three consistency guarantees:
+ *
+ *  - `'eventual'`  (default) — writes return immediately; async replication
+ *                              happens in the background. Highest throughput.
+ *  - `'session'`             — read-your-writes guarantee. Every write made
+ *                              by this instance is immediately visible to
+ *                              subsequent reads, even before it propagates to
+ *                              other nodes. Tracked in a local session cache.
+ *  - `'strong'`              — writes are flushed to the backend before the
+ *                              async `writeAsync()` resolves. For backends
+ *                              that implement `FlushableBackend` (e.g.
+ *                              `RedisBackend`, `CrdtBackend`) this guarantees
+ *                              durability before the caller continues.
+ *
+ * Usage:
+ * ```typescript
+ * import { MemoryBackend } from './blackboard-backend';
+ * import { ConsistentBackend } from './consistency';
+ *
+ * const backend = new ConsistentBackend(new MemoryBackend(), 'session');
+ * backend.write('k', 'v', 'agent-1');
+ * backend.read('k'); // always returns 'v' in this session
+ * ```
+ *
+ * Integration with `getBlackboard()`:
+ * ```typescript
+ * const board = orchestrator.getBlackboard('live', {
+ *   backend: new RedisBackend(client),
+ *   consistency: 'strong',
+ * });
+ * ```
+ *
+ * @module Consistency
+ * @version 1.0.0
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsistentBackend = void 0;
+exports.isFlushable = isFlushable;
+/**
+ * Type guard — returns `true` if `backend` implements `FlushableBackend`.
+ *
+ * @example
+ * ```typescript
+ * if (isFlushable(backend)) {
+ *   await backend.flush();
+ * }
+ * ```
+ */
+function isFlushable(backend) {
+    return typeof backend.flush === 'function';
+}
+// ============================================================================
+// CONSISTENT BACKEND
+// ============================================================================
+/**
+ * A `BlackboardBackend` wrapper that adds configurable consistency semantics.
+ *
+ * Fully satisfies the synchronous `BlackboardBackend` interface so it can be
+ * used anywhere a plain backend is accepted. For `'strong'` consistency, use
+ * `writeAsync()` to await durability confirmation.
+ *
+ * @example
+ * ```typescript
+ * // Session consistency — read-your-writes
+ * const backend = new ConsistentBackend(new MemoryBackend(), 'session');
+ * backend.write('task', 'pending', 'agent-1');
+ * backend.read('task'); // → 'pending' (guaranteed, even before replication)
+ *
+ * // Strong consistency with Redis
+ * const backend = new ConsistentBackend(new RedisBackend(client), 'strong');
+ * await backend.writeAsync('result', data, 'agent-1');
+ * // Redis has confirmed the write
+ * ```
+ */
+class ConsistentBackend {
+    _backend;
+    _level;
+    /**
+     * Session write cache.
+     *
+     * - `BlackboardEntry`  → written in this session (overrides backend reads)
+     * - `null`             → deleted in this session (hides backend reads)
+     *
+     * Only populated for `'session'` consistency.
+     */
+    _session = new Map();
+    /**
+     * Create a new `ConsistentBackend`.
+     *
+     * @param backend  The underlying storage backend to wrap.
+     * @param level    Consistency level. Defaults to `'eventual'`.
+     */
+    constructor(backend, level = 'eventual') {
+        this._backend = backend;
+        this._level = level;
+    }
+    // --------------------------------------------------------------------------
+    // BlackboardBackend interface
+    // --------------------------------------------------------------------------
+    /**
+     * Read an entry.
+     *
+     * - `eventual` / `strong`: delegates directly to the underlying backend.
+     * - `session`: returns the session-cached entry if present; falls back to
+     *   the backend. Returns `null` for session-deleted keys even if the backend
+     *   still has them.
+     */
+    read(key) {
+        if (this._level === 'session') {
+            const cached = this._session.get(key);
+            if (cached === undefined) {
+                // Not in session cache — fall through to backend
+            }
+            else if (cached === null) {
+                // Session-deleted tombstone
+                return null;
+            }
+            else {
+                // Live session entry — check expiry
+                if (this._isExpired(cached)) {
+                    this._session.delete(key);
+                    return null;
+                }
+                return cached;
+            }
+        }
+        return this._backend.read(key);
+    }
+    /**
+     * Write a value synchronously.
+     *
+     * For all consistency levels this writes immediately to the underlying
+     * backend. For `'session'` the result is also cached locally so subsequent
+     * `read()` calls see it without waiting for replication.
+     *
+     * For `'strong'` consistency, prefer `writeAsync()` to await durability.
+     */
+    write(key, value, sourceAgent, ttl) {
+        const entry = this._backend.write(key, value, sourceAgent, ttl);
+        if (this._level === 'session') {
+            this._session.set(key, entry);
+        }
+        return entry;
+    }
+    /**
+     * Delete an entry.
+     *
+     * For `'session'` consistency, also records a session-tombstone so the key
+     * appears deleted to subsequent `read()` calls in this session.
+     */
+    delete(key) {
+        const result = this._backend.delete(key);
+        if (this._level === 'session') {
+            this._session.set(key, null); // tombstone
+        }
+        return result;
+    }
+    /**
+     * Return all non-expired, non-deleted keys.
+     *
+     * For `'session'` consistency, session-written keys are included even if
+     * not yet visible in the backend; session-deleted keys are excluded.
+     */
+    listKeys() {
+        if (this._level !== 'session') {
+            return this._backend.listKeys();
+        }
+        // Start with backend keys, then overlay session mutations
+        const backendKeys = new Set(this._backend.listKeys());
+        // Add session-written keys (not yet in backend, or overriding backend)
+        for (const [key, entry] of this._session.entries()) {
+            if (entry === null) {
+                // Session delete — remove from result
+                backendKeys.delete(key);
+            }
+            else if (!this._isExpired(entry)) {
+                backendKeys.add(key);
+            }
+        }
+        return Array.from(backendKeys);
+    }
+    /**
+     * Return a snapshot of all non-expired, non-deleted entries.
+     *
+     * For `'session'` consistency, session writes overlay the backend snapshot.
+     */
+    getSnapshot() {
+        if (this._level !== 'session') {
+            return this._backend.getSnapshot();
+        }
+        // Start from backend snapshot, apply session overlay
+        const result = { ...this._backend.getSnapshot() };
+        for (const [key, entry] of this._session.entries()) {
+            if (entry === null) {
+                // Session delete
+                delete result[key];
+            }
+            else if (!this._isExpired(entry)) {
+                result[key] = entry;
+            }
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // Extended consistency API
+    // --------------------------------------------------------------------------
+    /**
+     * Write a value and, for `'strong'` consistency, await durability
+     * confirmation from the backend.
+     *
+     * - `eventual` / `session`: behaves identically to `write()` but returns
+     *   a `Promise` for API uniformity.
+     * - `strong` + `FlushableBackend`: calls `backend.flush()` after the write
+     *   and resolves only after the flush completes.
+     * - `strong` + non-flushable backend: writes synchronously and resolves
+     *   immediately (backend writes are already synchronous/durable).
+     *
+     * @example
+     * ```typescript
+     * const entry = await backend.writeAsync('checkpoint', data, 'agent-1');
+     * // Under 'strong' + RedisBackend: Redis has persisted the entry by here
+     * ```
+     */
+    async writeAsync(key, value, sourceAgent, ttl) {
+        const entry = this.write(key, value, sourceAgent, ttl);
+        if (this._level === 'strong' && isFlushable(this._backend)) {
+            await this._backend.flush();
+        }
+        return entry;
+    }
+    /**
+     * The configured consistency level.
+     */
+    get consistencyLevel() {
+        return this._level;
+    }
+    /**
+     * The underlying backend being wrapped.
+     */
+    get backend() {
+        return this._backend;
+    }
+    /**
+     * Number of entries currently in the session cache (live + tombstones).
+     * Always `0` for `'eventual'` and `'strong'` levels.
+     */
+    get sessionSize() {
+        return this._session.size;
+    }
+    /**
+     * Clear the session write cache without modifying the underlying backend.
+     *
+     * After calling this, `read()` will reflect the backend state directly.
+     * Only meaningful for `'session'` consistency.
+     */
+    clearSession() {
+        this._session.clear();
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    _isExpired(entry) {
+        if (!entry.ttl)
+            return false;
+        return Date.now() > new Date(entry.timestamp).getTime() + entry.ttl * 1000;
+    }
+}
+exports.ConsistentBackend = ConsistentBackend;
+//# sourceMappingURL=consistency.js.map

package/dist/esm/lib/consistency.js.map

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