network-ai 4.15.3 → 5.0.0

package/dist/lib/quadtree.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Barnes-Hut QuadTree — Spatial indexing for O(n log n) force simulation
+ *
+ * Used by the topology dashboard to replace the naive O(n²) all-pairs
+ * repulsion with Barnes-Hut approximation. Also provides viewport queries
+ * for culling off-screen nodes.
+ *
+ * @module QuadTree
+ * @version 1.0.0
+ */
+/** A 2D point with an identifier */
+export interface QTPoint {
+    id: string;
+    x: number;
+    y: number;
+}
+/** Axis-aligned bounding box */
+export interface QTBounds {
+    x: number;
+    y: number;
+    halfW: number;
+    halfH: number;
+}
+/** Statistics about a QuadTree region (for Barnes-Hut) */
+export interface QTMass {
+    /** Total number of points in this region */
+    count: number;
+    /** Center of mass x */
+    cx: number;
+    /** Center of mass y */
+    cy: number;
+}
+/**
+ * A QuadTree for 2D spatial indexing with Barnes-Hut mass summaries.
+ *
+ * Usage:
+ * ```typescript
+ * const qt = new QuadTree({ x: 500, y: 400, halfW: 500, halfH: 400 });
+ * qt.insert({ id: 'a', x: 100, y: 200 });
+ * qt.insert({ id: 'b', x: 300, y: 150 });
+ *
+ * // Barnes-Hut force query (theta = 0.5)
+ * qt.forceOnPoint(100, 200, 0.5, (cx, cy, mass, dx, dy, distSq) => {
+ *   // Apply repulsion force from (cx, cy) with given mass
+ * });
+ *
+ * // Viewport query
+ * const visible = qt.queryRange({ x: 250, y: 250, halfW: 250, halfH: 250 });
+ * ```
+ */
+export declare class QuadTree {
+    private bounds;
+    private points;
+    private divided;
+    private nw;
+    private ne;
+    private sw;
+    private se;
+    private mass;
+    constructor(bounds: QTBounds);
+    /**
+     * Insert a point into the tree.
+     * @returns true if inserted, false if out of bounds
+     */
+    insert(point: QTPoint): boolean;
+    /**
+     * Build the tree from an array of points (faster than individual inserts).
+     */
+    static build(points: QTPoint[], bounds: QTBounds): QuadTree;
+    /**
+     * Find all points within a rectangular viewport.
+     */
+    queryRange(range: QTBounds): QTPoint[];
+    private queryRangeInto;
+    /**
+     * Traverse the tree with Barnes-Hut approximation for a single point.
+     *
+     * For each region, if the region is "far enough" (width/distance < theta),
+     * treat it as a point mass at the center of mass. Otherwise recurse.
+     *
+     * @param px - Query point x
+     * @param py - Query point y
+     * @param theta - Opening angle threshold (0.5 is common, higher = faster but less accurate)
+     * @param callback - Called for each mass interaction: (cx, cy, mass, dx, dy, distSq)
+     */
+    forceOnPoint(px: number, py: number, theta: number, callback: (cx: number, cy: number, mass: number, dx: number, dy: number, distSq: number) => void): void;
+    /** Total point count in this subtree */
+    get count(): number;
+    /** The mass summary of this subtree */
+    getMass(): QTMass;
+    /** The bounds of this node */
+    getBounds(): QTBounds;
+    /** Whether this node has been subdivided */
+    get isSubdivided(): boolean;
+    /**
+     * Get cluster summaries at a given depth or size threshold.
+     * Returns groups of points that share a QuadTree cell below the given size.
+     *
+     * @param maxCellSize - Maximum cell width to stop recursing (in world units)
+     * @returns Array of clusters, each with center, count, and contained point ids
+     */
+    getClusters(maxCellSize: number): Array<{
+        cx: number;
+        cy: number;
+        count: number;
+        ids: string[];
+    }>;
+    private collectClusters;
+    private collectAllIds;
+    private subdivide;
+    private containsPoint;
+    private intersects;
+}
+//# sourceMappingURL=quadtree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quadtree.d.ts","sourceRoot":"","sources":["../../lib/quadtree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,oCAAoC;AACpC,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,gCAAgC;AAChC,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,MAAM;IACrB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,IAAI,CAAsC;gBAEtC,MAAM,EAAE,QAAQ;IAQ5B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IA2B/B;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ;IAY3D;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,EAAE;IAMtC,OAAO,CAAC,cAAc;IA0BtB;;;;;;;;;;OAUG;IACH,YAAY,CACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAC/F,IAAI;IAiCP,wCAAwC;IACxC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,uCAAuC;IACvC,OAAO,IAAI,MAAM;IAIjB,8BAA8B;IAC9B,SAAS,IAAI,QAAQ;IAIrB,4CAA4C;IAC5C,IAAI,YAAY,IAAI,OAAO,CAE1B;IAMD;;;;;;OAMG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAMjG,OAAO,CAAC,eAAe;IA4BvB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,UAAU;CAQnB"}

package/dist/lib/quadtree.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Barnes-Hut QuadTree — Spatial indexing for O(n log n) force simulation
+ *
+ * Used by the topology dashboard to replace the naive O(n²) all-pairs
+ * repulsion with Barnes-Hut approximation. Also provides viewport queries
+ * for culling off-screen nodes.
+ *
+ * @module QuadTree
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuadTree = void 0;
+// ============================================================================
+// QUADTREE NODE
+// ============================================================================
+const QT_CAPACITY = 8; // Points per leaf before subdividing
+/**
+ * A QuadTree for 2D spatial indexing with Barnes-Hut mass summaries.
+ *
+ * Usage:
+ * ```typescript
+ * const qt = new QuadTree({ x: 500, y: 400, halfW: 500, halfH: 400 });
+ * qt.insert({ id: 'a', x: 100, y: 200 });
+ * qt.insert({ id: 'b', x: 300, y: 150 });
+ *
+ * // Barnes-Hut force query (theta = 0.5)
+ * qt.forceOnPoint(100, 200, 0.5, (cx, cy, mass, dx, dy, distSq) => {
+ *   // Apply repulsion force from (cx, cy) with given mass
+ * });
+ *
+ * // Viewport query
+ * const visible = qt.queryRange({ x: 250, y: 250, halfW: 250, halfH: 250 });
+ * ```
+ */
+class QuadTree {
+    bounds;
+    points = [];
+    divided = false;
+    nw = null;
+    ne = null;
+    sw = null;
+    se = null;
+    mass = { count: 0, cx: 0, cy: 0 };
+    constructor(bounds) {
+        this.bounds = bounds;
+    }
+    // --------------------------------------------------------------------------
+    // INSERTION
+    // --------------------------------------------------------------------------
+    /**
+     * Insert a point into the tree.
+     * @returns true if inserted, false if out of bounds
+     */
+    insert(point) {
+        if (!this.containsPoint(point.x, point.y))
+            return false;
+        // Update mass center incrementally
+        const prev = this.mass.count;
+        this.mass.cx = (this.mass.cx * prev + point.x) / (prev + 1);
+        this.mass.cy = (this.mass.cy * prev + point.y) / (prev + 1);
+        this.mass.count = prev + 1;
+        if (!this.divided && this.points.length < QT_CAPACITY) {
+            this.points.push(point);
+            return true;
+        }
+        if (!this.divided) {
+            this.subdivide();
+        }
+        if (this.nw.insert(point))
+            return true;
+        if (this.ne.insert(point))
+            return true;
+        if (this.sw.insert(point))
+            return true;
+        if (this.se.insert(point))
+            return true;
+        // Shouldn't happen if containsPoint passed, but safety fallback
+        return false;
+    }
+    /**
+     * Build the tree from an array of points (faster than individual inserts).
+     */
+    static build(points, bounds) {
+        const tree = new QuadTree(bounds);
+        for (const p of points) {
+            tree.insert(p);
+        }
+        return tree;
+    }
+    // --------------------------------------------------------------------------
+    // QUERIES
+    // --------------------------------------------------------------------------
+    /**
+     * Find all points within a rectangular viewport.
+     */
+    queryRange(range) {
+        const found = [];
+        this.queryRangeInto(range, found);
+        return found;
+    }
+    queryRangeInto(range, found) {
+        if (!this.intersects(range))
+            return;
+        for (const p of this.points) {
+            if (p.x >= range.x - range.halfW &&
+                p.x <= range.x + range.halfW &&
+                p.y >= range.y - range.halfH &&
+                p.y <= range.y + range.halfH) {
+                found.push(p);
+            }
+        }
+        if (this.divided) {
+            this.nw.queryRangeInto(range, found);
+            this.ne.queryRangeInto(range, found);
+            this.sw.queryRangeInto(range, found);
+            this.se.queryRangeInto(range, found);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // BARNES-HUT FORCE TRAVERSAL
+    // --------------------------------------------------------------------------
+    /**
+     * Traverse the tree with Barnes-Hut approximation for a single point.
+     *
+     * For each region, if the region is "far enough" (width/distance < theta),
+     * treat it as a point mass at the center of mass. Otherwise recurse.
+     *
+     * @param px - Query point x
+     * @param py - Query point y
+     * @param theta - Opening angle threshold (0.5 is common, higher = faster but less accurate)
+     * @param callback - Called for each mass interaction: (cx, cy, mass, dx, dy, distSq)
+     */
+    forceOnPoint(px, py, theta, callback) {
+        if (this.mass.count === 0)
+            return;
+        const dx = this.mass.cx - px;
+        const dy = this.mass.cy - py;
+        const distSq = dx * dx + dy * dy;
+        // If this is a leaf with points, interact directly
+        if (!this.divided) {
+            if (distSq > 0.01) {
+                callback(this.mass.cx, this.mass.cy, this.mass.count, dx, dy, distSq);
+            }
+            return;
+        }
+        // Barnes-Hut criterion: region width / distance < theta → approximate
+        const regionWidth = this.bounds.halfW * 2;
+        if (regionWidth * regionWidth < theta * theta * distSq) {
+            callback(this.mass.cx, this.mass.cy, this.mass.count, dx, dy, distSq);
+            return;
+        }
+        // Recurse into children
+        this.nw.forceOnPoint(px, py, theta, callback);
+        this.ne.forceOnPoint(px, py, theta, callback);
+        this.sw.forceOnPoint(px, py, theta, callback);
+        this.se.forceOnPoint(px, py, theta, callback);
+    }
+    // --------------------------------------------------------------------------
+    // ACCESSORS
+    // --------------------------------------------------------------------------
+    /** Total point count in this subtree */
+    get count() {
+        return this.mass.count;
+    }
+    /** The mass summary of this subtree */
+    getMass() {
+        return { ...this.mass };
+    }
+    /** The bounds of this node */
+    getBounds() {
+        return { ...this.bounds };
+    }
+    /** Whether this node has been subdivided */
+    get isSubdivided() {
+        return this.divided;
+    }
+    // --------------------------------------------------------------------------
+    // CLUSTERING SUPPORT
+    // --------------------------------------------------------------------------
+    /**
+     * Get cluster summaries at a given depth or size threshold.
+     * Returns groups of points that share a QuadTree cell below the given size.
+     *
+     * @param maxCellSize - Maximum cell width to stop recursing (in world units)
+     * @returns Array of clusters, each with center, count, and contained point ids
+     */
+    getClusters(maxCellSize) {
+        const clusters = [];
+        this.collectClusters(maxCellSize, clusters);
+        return clusters;
+    }
+    collectClusters(maxCellSize, out) {
+        if (this.mass.count === 0)
+            return;
+        const cellSize = this.bounds.halfW * 2;
+        // If this cell is small enough OR is a leaf, emit as cluster
+        if (cellSize <= maxCellSize || !this.divided) {
+            const ids = this.collectAllIds();
+            if (ids.length > 0) {
+                out.push({
+                    cx: this.mass.cx,
+                    cy: this.mass.cy,
+                    count: this.mass.count,
+                    ids,
+                });
+            }
+            return;
+        }
+        this.nw.collectClusters(maxCellSize, out);
+        this.ne.collectClusters(maxCellSize, out);
+        this.sw.collectClusters(maxCellSize, out);
+        this.se.collectClusters(maxCellSize, out);
+    }
+    collectAllIds() {
+        const ids = [];
+        for (const p of this.points)
+            ids.push(p.id);
+        if (this.divided) {
+            ids.push(...this.nw.collectAllIds());
+            ids.push(...this.ne.collectAllIds());
+            ids.push(...this.sw.collectAllIds());
+            ids.push(...this.se.collectAllIds());
+        }
+        return ids;
+    }
+    // --------------------------------------------------------------------------
+    // INTERNALS
+    // --------------------------------------------------------------------------
+    subdivide() {
+        const { x, y, halfW, halfH } = this.bounds;
+        const qW = halfW / 2;
+        const qH = halfH / 2;
+        this.nw = new QuadTree({ x: x - qW, y: y - qH, halfW: qW, halfH: qH });
+        this.ne = new QuadTree({ x: x + qW, y: y - qH, halfW: qW, halfH: qH });
+        this.sw = new QuadTree({ x: x - qW, y: y + qH, halfW: qW, halfH: qH });
+        this.se = new QuadTree({ x: x + qW, y: y + qH, halfW: qW, halfH: qH });
+        // Re-insert existing points into children
+        for (const p of this.points) {
+            this.nw.insert(p) || this.ne.insert(p) || this.sw.insert(p) || this.se.insert(p);
+        }
+        this.points = [];
+        this.divided = true;
+    }
+    containsPoint(x, y) {
+        return (x >= this.bounds.x - this.bounds.halfW &&
+            x <= this.bounds.x + this.bounds.halfW &&
+            y >= this.bounds.y - this.bounds.halfH &&
+            y <= this.bounds.y + this.bounds.halfH);
+    }
+    intersects(range) {
+        return !(range.x - range.halfW > this.bounds.x + this.bounds.halfW ||
+            range.x + range.halfW < this.bounds.x - this.bounds.halfW ||
+            range.y - range.halfH > this.bounds.y + this.bounds.halfH ||
+            range.y + range.halfH < this.bounds.y - this.bounds.halfH);
+    }
+}
+exports.QuadTree = QuadTree;
+//# sourceMappingURL=quadtree.js.map

package/dist/lib/quadtree.js.map

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

package/dist/lib/shared-blackboard.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Namespace-scoped, identity-verified shared state for multi-agent coordination.
+ *
+ * Every write is identity-verified (agent token), namespace-checked,
+ * size-validated, input-sanitized, and atomically persisted through
+ * the pluggable {@link BlackboardBackend}.
+ *
+ * @module SharedBlackboard
+ */
+import type { BlackboardBackend } from './blackboard-backend';
+import type { BlackboardEntry } from './orchestrator-types';
+/**
+ * Namespace-scoped, identity-verified shared state for multi-agent coordination.
+ *
+ * Every write is identity-verified (agent token), namespace-checked,
+ * size-validated, input-sanitized, and atomically persisted through
+ * {@link LockedBlackboard}.
+ *
+ * @example
+ * ```typescript
+ * const bb = new SharedBlackboard('./workspace');
+ * bb.registerAgent('analyst', 'secret-token', ['task:', 'analytics:']);
+ * bb.write('task:revenue', { q4: 42_000 }, 'analyst', 3600, 'secret-token');
+ * const entry = bb.read('task:revenue');
+ * ```
+ */
+export declare class SharedBlackboard {
+    private backend;
+    private agentTokens;
+    private agentNamespaces;
+    private piiRedactor;
+    constructor(backendOrPath: string | BlackboardBackend, options?: {
+        enablePIIRedaction?: boolean;
+    });
+    /**
+     * Enable or disable PII redaction on writes.
+     */
+    setPIIRedaction(enabled: boolean): void;
+    /**
+     * Register a verified agent identity. Only agents with registered tokens
+     * can write to the blackboard. The orchestrator registers agents after
+     * verifying their identity through the AuthGuardian.
+     */
+    registerAgent(agentId: string, verificationToken: string, allowedNamespaces?: string[]): void;
+    /**
+     * Check if an agent is allowed to access a key based on namespace rules.
+     */
+    private canAccessKey;
+    /**
+     * Verify that the calling agent is who they claim to be.
+     */
+    private verifyAgent;
+    /**
+     * Validate value size and structure before writing.
+     * Prevents DoS via oversized writes and circular data.
+     */
+    private validateValue;
+    /**
+     * Sanitize a key to prevent markdown injection.
+     */
+    private sanitizeKey;
+    /**
+     * Read an entry from the blackboard by key.
+     *
+     * @param key - The entry key to look up
+     * @returns The entry, or `null` if not found or expired
+     * @throws {@link ValidationError} if `key` is not a non-empty string
+     */
+    read(key: string): BlackboardEntry | null;
+    /**
+     * Write to the blackboard with identity verification, namespace checks,
+     * value validation, and input sanitization. Uses LockedBlackboard for
+     * atomic file-system writes.
+     *
+     * @param key - The key to write
+     * @param value - The value (will be sanitized and size-checked)
+     * @param sourceAgent - Agent claiming to write (verified against registered token)
+     * @param ttl - Optional TTL in seconds
+     * @param agentToken - Optional verification token for identity check
+     */
+    write(key: string, value: unknown, sourceAgent: string, ttl?: number, agentToken?: string): BlackboardEntry;
+    /**
+     * Check whether a key exists on the blackboard (not expired).
+     * @param key - The entry key to check
+     */
+    exists(key: string): boolean;
+    /**
+     * Get a full snapshot of all blackboard entries.
+     */
+    getSnapshot(): Record<string, BlackboardEntry>;
+    /**
+     * Get a namespace-scoped snapshot -- only returns keys an agent is allowed to see.
+     * Prevents data leakage between agents.
+     */
+    getScopedSnapshot(agentId: string): Record<string, BlackboardEntry>;
+    /**
+     * Clear all entries (for testing).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=shared-blackboard.d.ts.map

package/dist/lib/shared-blackboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-blackboard.d.ts","sourceRoot":"","sources":["../../lib/shared-blackboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAQ9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,WAAW,CAA4B;gBAEnC,aAAa,EAAE,MAAM,GAAG,iBAAiB,EAAE,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE;IAiBjG;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIvC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAM,EAAU,GAAG,IAAI;IAcpG;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAgBzC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,eAAe;IA+C3G;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAe9C;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAcnE;;OAEG;IACH,KAAK,IAAI,IAAI;CAOd"}