network-ai 5.10.2 → 5.12.0

package/dist/esm/lib/errors.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Typed Error Classes for Network-AI
+ *
+ * Provides specific error types so consumers can catch and handle
+ * different failure modes independently (e.g., retry on rate limit,
+ * re-authenticate on token expiry, alert on namespace violation).
+ *
+ * All errors extend NetworkAIError, which extends Error.
+ *
+ * @module Errors
+ * @version 1.0.0
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = exports.ParallelLimitError = exports.AdapterNotInitializedError = exports.AdapterNotFoundError = exports.AdapterAlreadyRegisteredError = exports.ConflictError = exports.LockAcquisitionError = exports.ValidationError = exports.NamespaceViolationError = exports.IdentityVerificationError = exports.NetworkAIError = void 0;
+exports.mapErrorToSkillResult = mapErrorToSkillResult;
+// ============================================================================
+// BASE ERROR
+// ============================================================================
+/**
+ * Base error class for all Network-AI errors.
+ * Every error includes a machine-readable `code` and optional `details`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   blackboard.write('key', value, 'agent');
+ * } catch (err) {
+ *   if (err instanceof NetworkAIError) {
+ *     console.log(err.code);    // e.g., 'IDENTITY_VERIFICATION_FAILED'
+ *     console.log(err.details); // { agentId: 'agent' }
+ *   }
+ * }
+ * ```
+ */
+class NetworkAIError extends Error {
+    /** Machine-readable error code */
+    code;
+    /** Additional structured context */
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = 'NetworkAIError';
+        this.code = code;
+        this.details = details;
+        // Fix prototype chain for instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.NetworkAIError = NetworkAIError;
+// ============================================================================
+// BLACKBOARD ERRORS
+// ============================================================================
+/**
+ * Thrown when an agent fails identity verification on blackboard write.
+ */
+class IdentityVerificationError extends NetworkAIError {
+    constructor(agentId) {
+        super(`Identity verification failed for agent '${agentId}'`, 'IDENTITY_VERIFICATION_FAILED', { agentId });
+        this.name = 'IdentityVerificationError';
+    }
+}
+exports.IdentityVerificationError = IdentityVerificationError;
+/**
+ * Thrown when an agent tries to write to a namespace it doesn't have access to.
+ */
+class NamespaceViolationError extends NetworkAIError {
+    constructor(agentId, key) {
+        super(`Agent '${agentId}' not allowed to write to key '${key}'`, 'NAMESPACE_VIOLATION', { agentId, key });
+        this.name = 'NamespaceViolationError';
+    }
+}
+exports.NamespaceViolationError = NamespaceViolationError;
+/**
+ * Thrown when a value fails size or structure validation before write.
+ */
+class ValidationError extends NetworkAIError {
+    constructor(reason) {
+        super(`Value validation failed: ${reason}`, 'VALIDATION_FAILED', { reason });
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+// ============================================================================
+// LOCK ERRORS
+// ============================================================================
+/**
+ * Thrown when a file-system lock cannot be acquired within the timeout.
+ */
+class LockAcquisitionError extends NetworkAIError {
+    constructor(operation) {
+        super(`Failed to acquire lock for ${operation}`, 'LOCK_ACQUISITION_FAILED', { operation });
+        this.name = 'LockAcquisitionError';
+    }
+}
+exports.LockAcquisitionError = LockAcquisitionError;
+/**
+ * Thrown when a conflict is detected during the atomic commit workflow.
+ */
+class ConflictError extends NetworkAIError {
+    constructor(key, expectedHash, actualHash) {
+        super(`Conflict detected for key '${key}': data changed since proposal`, 'CONFLICT_DETECTED', { key, expectedHash, actualHash });
+        this.name = 'ConflictError';
+    }
+}
+exports.ConflictError = ConflictError;
+// ============================================================================
+// ADAPTER ERRORS
+// ============================================================================
+/**
+ * Thrown when an adapter is already registered under the same name.
+ */
+class AdapterAlreadyRegisteredError extends NetworkAIError {
+    constructor(adapterName) {
+        super(`Adapter "${adapterName}" is already registered`, 'ADAPTER_ALREADY_REGISTERED', { adapterName });
+        this.name = 'AdapterAlreadyRegisteredError';
+    }
+}
+exports.AdapterAlreadyRegisteredError = AdapterAlreadyRegisteredError;
+/**
+ * Thrown when referencing an adapter name that isn't in the registry.
+ */
+class AdapterNotFoundError extends NetworkAIError {
+    constructor(adapterName) {
+        super(`Adapter "${adapterName}" is not registered`, 'ADAPTER_NOT_FOUND', { adapterName });
+        this.name = 'AdapterNotFoundError';
+    }
+}
+exports.AdapterNotFoundError = AdapterNotFoundError;
+/**
+ * Thrown when calling executeAgent on an adapter before it has been initialized.
+ */
+class AdapterNotInitializedError extends NetworkAIError {
+    constructor(adapterName) {
+        super(`Adapter "${adapterName}" is not initialized. Call initialize() first.`, 'ADAPTER_NOT_INITIALIZED', { adapterName });
+        this.name = 'AdapterNotInitializedError';
+    }
+}
+exports.AdapterNotInitializedError = AdapterNotInitializedError;
+// ============================================================================
+// ORCHESTRATOR ERRORS
+// ============================================================================
+/**
+ * Thrown when too many parallel agents are requested.
+ */
+class ParallelLimitError extends NetworkAIError {
+    constructor(requested, maximum) {
+        super(`Cannot spawn ${requested} agents. Maximum is ${maximum}. Decompose further or use 'chain' strategy.`, 'PARALLEL_LIMIT_EXCEEDED', { requested, maximum });
+        this.name = 'ParallelLimitError';
+    }
+}
+exports.ParallelLimitError = ParallelLimitError;
+/**
+ * Thrown when an operation exceeds its timeout.
+ */
+class TimeoutError extends NetworkAIError {
+    constructor(timeoutMs) {
+        super(`Operation timed out after ${timeoutMs}ms`, 'TIMEOUT', { timeoutMs });
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+// ============================================================================
+// ERROR MAPPING UTILITY
+// ============================================================================
+/** Error codes that are considered recoverable (caller can retry). */
+const RECOVERABLE_CODES = new Set([
+    'LOCK_ACQUISITION_FAILED',
+    'TIMEOUT',
+    'CONFLICT_DETECTED',
+]);
+/**
+ * Convert any error to a standardised SkillResult with `success: false`.
+ *
+ * For {@link NetworkAIError} subclasses the machine-readable `code` and
+ * `details` are preserved.  Unknown errors are wrapped as `INTERNAL_ERROR`.
+ */
+function mapErrorToSkillResult(error) {
+    if (error instanceof NetworkAIError) {
+        return {
+            success: false,
+            error: {
+                code: error.code,
+                message: error.message,
+                recoverable: RECOVERABLE_CODES.has(error.code),
+                trace: error.details,
+            },
+        };
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+        success: false,
+        error: {
+            code: 'INTERNAL_ERROR',
+            message: msg,
+            recoverable: false,
+        },
+    };
+}
+//# sourceMappingURL=errors.js.map

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

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

package/dist/esm/lib/event-bus.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * OrchestratorEventBus — Central event stream for replay & time-travel debugging.
+ *
+ * Collects events from all orchestrator subsystems (blackboard, auth, adapters,
+ * topology, decisions) into a single monotonically-sequenced stream with periodic
+ * state snapshots for efficient point-in-time reconstruction.
+ *
+ * @module EventBus
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestratorEventBus = void 0;
+const events_1 = require("events");
+// Severity ordering for filtering
+const SEVERITY_ORDER = {
+    trace: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+// ============================================================================
+// EVENT BUS
+// ============================================================================
+/**
+ * Central event bus for the orchestrator.
+ *
+ * Provides:
+ * - Unified monotonic event stream from all subsystems
+ * - Periodic state snapshots for O(1) point-in-time reconstruction
+ * - Replay with filtering (source, agent, severity, correlation)
+ * - Configurable retention (max events, max snapshots)
+ *
+ * @example
+ * ```ts
+ * const bus = new OrchestratorEventBus();
+ * bus.publish('blackboard', 'write', 'info', { key: 'x', value: 42 }, 'agent-1');
+ * bus.snapshot({ blackboard: bb.getSnapshot(), agents: {} });
+ * const replay = bus.replay({ fromSeq: 0, toSeq: 100 });
+ * ```
+ */
+class OrchestratorEventBus extends events_1.EventEmitter {
+    events = [];
+    snapshots = [];
+    seq = 0;
+    maxEvents;
+    maxSnapshots;
+    snapshotInterval;
+    eventsSinceSnapshot = 0;
+    constructor(options) {
+        super();
+        this.maxEvents = options?.maxEvents ?? 50_000;
+        this.maxSnapshots = options?.maxSnapshots ?? 100;
+        this.snapshotInterval = options?.snapshotInterval ?? 0;
+    }
+    /**
+     * Publish an event to the bus.
+     * Returns the assigned sequence number.
+     */
+    publish(source, type, severity, data, agentId, correlationId) {
+        const event = {
+            seq: this.seq++,
+            timestamp: new Date().toISOString(),
+            source,
+            type,
+            severity,
+            agentId,
+            correlationId,
+            data,
+        };
+        this.events.push(event);
+        this.eventsSinceSnapshot++;
+        // Evict oldest
+        if (this.events.length > this.maxEvents) {
+            this.events.splice(0, this.events.length - this.maxEvents);
+        }
+        this.emit('event', event);
+        return event.seq;
+    }
+    /**
+     * Take a state snapshot at the current sequence position.
+     */
+    snapshot(state) {
+        const snap = {
+            atSeq: this.seq - 1,
+            timestamp: new Date().toISOString(),
+            blackboard: state.blackboard,
+            agents: state.agents,
+            budget: state.budget,
+            metadata: state.metadata,
+        };
+        this.snapshots.push(snap);
+        this.eventsSinceSnapshot = 0;
+        // Evict oldest snapshots
+        if (this.snapshots.length > this.maxSnapshots) {
+            this.snapshots.splice(0, this.snapshots.length - this.maxSnapshots);
+        }
+        this.emit('snapshot', snap);
+        return snap;
+    }
+    /**
+     * Check if an automatic snapshot should be taken (called internally after publish).
+     * Returns true if a snapshot is due. Callers must provide state via `snapshot()`.
+     */
+    isSnapshotDue() {
+        return this.snapshotInterval > 0 && this.eventsSinceSnapshot >= this.snapshotInterval;
+    }
+    /**
+     * Replay events with optional filtering.
+     * Returns the nearest base snapshot + matching events.
+     */
+    replay(options) {
+        const fromSeq = options?.fromSeq ?? 0;
+        const toSeq = options?.toSeq ?? this.seq;
+        const minSev = options?.minSeverity ? SEVERITY_ORDER[options.minSeverity] : 0;
+        // Find nearest snapshot at or before fromSeq
+        let baseSnapshot = null;
+        for (let i = this.snapshots.length - 1; i >= 0; i--) {
+            if (this.snapshots[i].atSeq <= fromSeq) {
+                baseSnapshot = this.snapshots[i];
+                break;
+            }
+        }
+        // Filter events
+        const filtered = this.events.filter((e) => {
+            if (e.seq < fromSeq || e.seq > toSeq)
+                return false;
+            if (options?.sources && !options.sources.includes(e.source))
+                return false;
+            if (options?.agentId && e.agentId !== options.agentId)
+                return false;
+            if (options?.correlationId && e.correlationId !== options.correlationId)
+                return false;
+            if (SEVERITY_ORDER[e.severity] < minSev)
+                return false;
+            return true;
+        });
+        return {
+            baseSnapshot,
+            events: filtered,
+            totalEvents: this.events.length,
+        };
+    }
+    /**
+     * Get the event at a specific sequence number.
+     */
+    getEvent(seq) {
+        return this.events.find((e) => e.seq === seq);
+    }
+    /**
+     * Get the most recent N events.
+     */
+    recent(count) {
+        return this.events.slice(-count);
+    }
+    /**
+     * Get all snapshots.
+     */
+    getSnapshots() {
+        return [...this.snapshots];
+    }
+    /**
+     * Find the nearest snapshot at or before a given sequence.
+     */
+    snapshotAt(seq) {
+        for (let i = this.snapshots.length - 1; i >= 0; i--) {
+            if (this.snapshots[i].atSeq <= seq) {
+                return this.snapshots[i];
+            }
+        }
+        return null;
+    }
+    /** Current sequence counter value (next event will get this seq). */
+    get currentSeq() {
+        return this.seq;
+    }
+    /** Total stored events. */
+    get size() {
+        return this.events.length;
+    }
+    /** Total stored snapshots. */
+    get snapshotCount() {
+        return this.snapshots.length;
+    }
+    /** Clear all events and snapshots, reset sequence. */
+    clear() {
+        this.events.length = 0;
+        this.snapshots.length = 0;
+        this.seq = 0;
+        this.eventsSinceSnapshot = 0;
+    }
+    /**
+     * Export the full stream (events + snapshots) as a serializable object.
+     */
+    export() {
+        return {
+            events: [...this.events],
+            snapshots: [...this.snapshots],
+        };
+    }
+    /**
+     * Import a previously exported stream, merging into current state.
+     */
+    import(data) {
+        if (!Array.isArray(data.events) || !Array.isArray(data.snapshots)) {
+            throw new Error('Invalid import data: expected { events: [], snapshots: [] }');
+        }
+        for (const e of data.events) {
+            this.events.push(e);
+            if (e.seq >= this.seq) {
+                this.seq = e.seq + 1;
+            }
+        }
+        for (const s of data.snapshots) {
+            this.snapshots.push(s);
+        }
+        // Sort by sequence
+        this.events.sort((a, b) => a.seq - b.seq);
+        this.snapshots.sort((a, b) => a.atSeq - b.atSeq);
+        // Enforce limits
+        if (this.events.length > this.maxEvents) {
+            this.events.splice(0, this.events.length - this.maxEvents);
+        }
+        if (this.snapshots.length > this.maxSnapshots) {
+            this.snapshots.splice(0, this.snapshots.length - this.maxSnapshots);
+        }
+    }
+}
+exports.OrchestratorEventBus = OrchestratorEventBus;
+//# sourceMappingURL=event-bus.js.map

package/dist/esm/lib/event-bus.js.map

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

package/dist/esm/lib/explainability.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * ExplainabilityTracer — structured decision cards for agent actions.
+ *
+ * Records every significant decision made during task orchestration so that
+ * operators can audit *why* a particular outcome was produced.
+ *
+ * @module explainability
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplainabilityTracer = void 0;
+/**
+ * Collects decision cards during a session.
+ *
+ * Usage:
+ * ```ts
+ * const tracer = new ExplainabilityTracer();
+ * tracer.record({
+ *   source: 'AuthGuardian',
+ *   decision: 'permission_check',
+ *   outcome: 'granted',
+ *   factors: [{ name: 'trust_level', value: 0.8 }],
+ * });
+ * const cards = tracer.getTrace(traceId);
+ * ```
+ */
+class ExplainabilityTracer {
+    cards = [];
+    maxCards;
+    constructor(options) {
+        this.maxCards = options?.maxCards ?? 10_000;
+    }
+    /**
+     * Record a decision card. Returns the generated traceId.
+     */
+    record(card) {
+        const traceId = card.traceId ?? this.generateId();
+        const full = {
+            traceId,
+            timestamp: card.timestamp ?? new Date().toISOString(),
+            source: card.source,
+            decision: card.decision,
+            outcome: card.outcome,
+            factors: card.factors,
+            parentTraceId: card.parentTraceId,
+            agentId: card.agentId,
+            metadata: card.metadata,
+        };
+        this.cards.push(full);
+        // Evict oldest when over limit
+        if (this.cards.length > this.maxCards) {
+            this.cards.splice(0, this.cards.length - this.maxCards);
+        }
+        return traceId;
+    }
+    /** Get a single card by traceId. */
+    getCard(traceId) {
+        return this.cards.find((c) => c.traceId === traceId);
+    }
+    /** Get all cards sharing a parentTraceId — i.e. the full trace tree for a delegation. */
+    getTrace(parentTraceId) {
+        return this.cards.filter((c) => c.traceId === parentTraceId || c.parentTraceId === parentTraceId);
+    }
+    /** Get cards filtered by source, decision type, agent, or time range. */
+    query(filter) {
+        return this.cards.filter((c) => {
+            if (filter.source && c.source !== filter.source)
+                return false;
+            if (filter.decision && c.decision !== filter.decision)
+                return false;
+            if (filter.agentId && c.agentId !== filter.agentId)
+                return false;
+            if (filter.since && c.timestamp < filter.since)
+                return false;
+            if (filter.until && c.timestamp > filter.until)
+                return false;
+            return true;
+        });
+    }
+    /** Total number of recorded cards. */
+    get size() {
+        return this.cards.length;
+    }
+    /** Clear all recorded cards. */
+    clear() {
+        this.cards.length = 0;
+    }
+    /** Export all cards as a JSON-serializable array. */
+    export() {
+        return [...this.cards];
+    }
+    generateId() {
+        // Simple random hex id (no crypto dependency needed for trace ids)
+        const bytes = new Uint8Array(12);
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = Math.floor(Math.random() * 256);
+        }
+        return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    }
+}
+exports.ExplainabilityTracer = ExplainabilityTracer;
+//# sourceMappingURL=explainability.js.map

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

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