network-ai 4.15.3 → 5.0.0

package/dist/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/lib/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../lib/event-bus.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,mCAAsC;AAqFtC,kCAAkC;AAClC,MAAM,cAAc,GAAkC;IACpD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,oBAAqB,SAAQ,qBAAY;IAC5C,MAAM,GAAe,EAAE,CAAC;IACxB,SAAS,GAAoB,EAAE,CAAC;IAChC,GAAG,GAAG,CAAC,CAAC;IACR,SAAS,CAAS;IAClB,YAAY,CAAS;IACrB,gBAAgB,CAAS;IACzB,mBAAmB,GAAG,CAAC,CAAC;IAEhC,YAAY,OAOX;QACC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,MAAM,CAAC;QAC9C,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,GAAG,CAAC;QACjD,IAAI,CAAC,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,CAAC,CAAC;IACzD,CAAC;IAED;;;OAGG;IACH,OAAO,CACL,MAAmB,EACnB,IAAY,EACZ,QAAuB,EACvB,IAA6B,EAC7B,OAAgB,EAChB,aAAsB;QAEtB,MAAM,KAAK,GAAa;YACtB,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;YACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM;YACN,IAAI;YACJ,QAAQ;YACR,OAAO;YACP,aAAa;YACb,IAAI;SACL,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE3B,eAAe;QACf,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAE1B,OAAO,KAAK,CAAC,GAAG,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAiD;QACxD,MAAM,IAAI,GAAkB;YAC1B,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC;YACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACzB,CAAC;QAEF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;QAE7B,yBAAyB;QACzB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAC9C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QACtE,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,gBAAgB,GAAG,CAAC,IAAI,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,gBAAgB,CAAC;IACxF,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAuB;QAC5B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE9E,6CAA6C;QAC7C,IAAI,YAAY,GAAyB,IAAI,CAAC;QAC9C,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACpD,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,OAAO,EAAE,CAAC;gBACvC,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;gBACjC,MAAM;YACR,CAAC;QACH,CAAC;QAED,gBAAgB;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACxC,IAAI,CAAC,CAAC,GAAG,GAAG,OAAO,IAAI,CAAC,CAAC,GAAG,GAAG,KAAK;gBAAE,OAAO,KAAK,CAAC;YACnD,IAAI,OAAO,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC1E,IAAI,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO;gBAAE,OAAO,KAAK,CAAC;YACpE,IAAI,OAAO,EAAE,aAAa,IAAI,CAAC,CAAC,aAAa,KAAK,OAAO,CAAC,aAAa;gBAAE,OAAO,KAAK,CAAC;YACtF,IAAI,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,MAAM;gBAAE,OAAO,KAAK,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,YAAY;YACZ,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;SAChC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,GAAW;QACpB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACpD,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC;gBACnC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qEAAqE;IACrE,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,2BAA2B;IAC3B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,8BAA8B;IAC9B,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,sDAAsD;IACtD,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACxB,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;SAC/B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,IAAwD;QAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBACtB,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;QACD,mBAAmB;QACnB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACjD,iBAAiB;QACjB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAC9C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;CACF;AA5ND,oDA4NC"}

package/dist/lib/explainability.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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
+ */
+/** A single factor that influenced a decision. */
+export interface DecisionFactor {
+    name: string;
+    value: unknown;
+    weight?: number;
+    description?: string;
+}
+/** Structured record of one orchestrator decision. */
+export interface DecisionCard {
+    /** Unique trace id */
+    traceId: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Which component made the decision */
+    source: string;
+    /** Short label for the decision type */
+    decision: string;
+    /** The outcome chosen */
+    outcome: string;
+    /** Factors that contributed */
+    factors: DecisionFactor[];
+    /** Parent trace (e.g. the delegation that spawned this) */
+    parentTraceId?: string;
+    /** Agent involved, if any */
+    agentId?: string;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare class ExplainabilityTracer {
+    private cards;
+    private maxCards;
+    constructor(options?: {
+        maxCards?: number;
+    });
+    /**
+     * Record a decision card. Returns the generated traceId.
+     */
+    record(card: Omit<DecisionCard, 'traceId' | 'timestamp'> & {
+        traceId?: string;
+        timestamp?: string;
+    }): string;
+    /** Get a single card by traceId. */
+    getCard(traceId: string): DecisionCard | undefined;
+    /** Get all cards sharing a parentTraceId — i.e. the full trace tree for a delegation. */
+    getTrace(parentTraceId: string): DecisionCard[];
+    /** Get cards filtered by source, decision type, agent, or time range. */
+    query(filter: {
+        source?: string;
+        decision?: string;
+        agentId?: string;
+        since?: string;
+        until?: string;
+    }): DecisionCard[];
+    /** Total number of recorded cards. */
+    get size(): number;
+    /** Clear all recorded cards. */
+    clear(): void;
+    /** Export all cards as a JSON-serializable array. */
+    export(): DecisionCard[];
+    private generateId;
+}
+//# sourceMappingURL=explainability.d.ts.map

package/dist/lib/explainability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainability.d.ts","sourceRoot":"","sources":["../../lib/explainability.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAI3C;;OAEG;IACH,MAAM,CACJ,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3F,MAAM;IAqBT,oCAAoC;IACpC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIlD,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY,EAAE;IAM/C,yEAAyE;IACzE,KAAK,CAAC,MAAM,EAAE;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,YAAY,EAAE;IAWlB,sCAAsC;IACtC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gCAAgC;IAChC,KAAK,IAAI,IAAI;IAIb,qDAAqD;IACrD,MAAM,IAAI,YAAY,EAAE;IAIxB,OAAO,CAAC,UAAU;CAQnB"}

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

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

package/dist/lib/goal-dsl.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Goal DSL — Schema-driven goal definitions for swarm orchestration
+ *
+ * Provides a declarative way to define multi-agent goals with constraints,
+ * dependencies, and validation rules. Goals can be defined in TypeScript
+ * objects or parsed from YAML/JSON strings.
+ *
+ * Features:
+ *   - Typed GoalDefinition with tasks, constraints, and outputs
+ *   - Dependency graph validation (cycle detection, missing refs)
+ *   - Constraint checking (budget, timeout, required agents)
+ *   - YAML/JSON parsing (YAML via simple built-in parser, no deps)
+ *   - Goal compilation to executable task DAGs
+ *
+ * Usage:
+ *   const goal = parseGoal(`
+ *     name: research-and-summarize
+ *     tasks:
+ *       - id: research
+ *         agent: researcher
+ *         action: search
+ *       - id: summarize
+ *         agent: writer
+ *         action: summarize
+ *         depends: [research]
+ *   `);
+ *   const plan = compileGoal(goal);
+ *
+ * @module GoalDSL
+ * @version 1.0.0
+ */
+/** A single task within a goal */
+export interface GoalTask {
+    /** Unique task ID within this goal */
+    id: string;
+    /** Agent or adapter:agent to execute this task */
+    agent: string;
+    /** Action/instruction for the agent */
+    action: string;
+    /** Task IDs this depends on (must complete before this starts) */
+    depends?: string[];
+    /** Parameters to pass to the agent */
+    params?: Record<string, unknown>;
+    /** Per-task timeout in ms */
+    timeoutMs?: number;
+    /** Whether failure of this task fails the entire goal (default: true) */
+    critical?: boolean;
+    /** Retry count (default: 0) */
+    retries?: number;
+    /** Output key — result stored under this key for downstream tasks */
+    outputKey?: string;
+}
+/** Constraints on goal execution */
+export interface GoalConstraints {
+    /** Maximum total budget */
+    maxBudget?: number;
+    /** Maximum total time in ms */
+    maxTimeMs?: number;
+    /** Required agent capabilities */
+    requiredCapabilities?: string[];
+    /** Maximum parallel tasks */
+    maxParallelism?: number;
+    /** Minimum confidence threshold for results */
+    minConfidence?: number;
+}
+/** Expected output definition */
+export interface GoalOutput {
+    /** Output key name */
+    key: string;
+    /** Expected type ('string' | 'number' | 'object' | 'array' | 'boolean') */
+    type?: string;
+    /** Whether this output is required (default: true) */
+    required?: boolean;
+    /** Description of the output */
+    description?: string;
+}
+/** Complete goal definition */
+export interface GoalDefinition {
+    /** Goal name */
+    name: string;
+    /** Goal description */
+    description?: string;
+    /** Version */
+    version?: string;
+    /** Tasks to execute */
+    tasks: GoalTask[];
+    /** Execution constraints */
+    constraints?: GoalConstraints;
+    /** Expected outputs */
+    outputs?: GoalOutput[];
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Validation error */
+export interface GoalValidationError {
+    /** Error type */
+    type: 'missing_dependency' | 'cycle' | 'duplicate_id' | 'empty_tasks' | 'invalid_field' | 'missing_agent';
+    /** Human-readable message */
+    message: string;
+    /** Related task ID */
+    taskId?: string;
+}
+/** Validation result */
+export interface GoalValidationResult {
+    /** Whether the goal is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: GoalValidationError[];
+}
+/** Compiled execution layer (tasks that can run in parallel) */
+export interface ExecutionLayer {
+    /** Layer index (0 = first) */
+    index: number;
+    /** Task IDs in this layer */
+    taskIds: string[];
+}
+/** Compiled goal — ready for execution */
+export interface CompiledGoal {
+    /** Original goal definition */
+    definition: GoalDefinition;
+    /** Execution layers (topologically sorted) */
+    layers: ExecutionLayer[];
+    /** Total parallel depth */
+    depth: number;
+    /** Maximum width (max tasks in a single layer) */
+    maxWidth: number;
+    /** All task IDs in execution order */
+    taskOrder: string[];
+    /** Dependency adjacency map */
+    adjacency: Map<string, string[]>;
+}
+/**
+ * Parse a goal from a YAML-like or JSON string.
+ *
+ * Supports a simple YAML subset (no anchors, tags, or multi-doc):
+ *   - Key: value pairs
+ *   - Lists with `- item` syntax
+ *   - Inline arrays `[a, b, c]`
+ *   - Nested indentation
+ *   - JSON input (auto-detected)
+ */
+export declare function parseGoal(input: string): GoalDefinition;
+/** Parse from a plain object (e.g. loaded from file) */
+export declare function goalFromObject(obj: Record<string, unknown>): GoalDefinition;
+/**
+ * Validate a goal definition for correctness.
+ * Checks for cycles, missing dependencies, duplicate IDs, and required fields.
+ */
+export declare function validateGoal(goal: GoalDefinition): GoalValidationResult;
+/**
+ * Compile a validated goal into an executable plan with layered parallelism.
+ * Performs topological sort to determine execution layers.
+ *
+ * @throws If the goal is invalid.
+ */
+export declare function compileGoal(goal: GoalDefinition): CompiledGoal;
+//# sourceMappingURL=goal-dsl.d.ts.map

package/dist/lib/goal-dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-dsl.d.ts","sourceRoot":"","sources":["../../lib/goal-dsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,6BAA6B;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,uBAAuB;IACvB,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uBAAuB;AACvB,MAAM,WAAW,mBAAmB;IAClC,iBAAiB;IACjB,IAAI,EAAE,oBAAoB,GAAG,OAAO,GAAG,cAAc,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,CAAC;IAC1G,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAwB;AACxB,MAAM,WAAW,oBAAoB;IACnC,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,wBAAwB;IACxB,MAAM,EAAE,mBAAmB,EAAE,CAAC;CAC/B;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,UAAU,EAAE,cAAc,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+BAA+B;IAC/B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAClC;AAMD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAWvD;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAE3E;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAuDvE;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,YAAY,CAgE9D"}