network-ai 5.10.2 → 5.12.0

package/dist/esm/lib/job-queue.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Persistent Job Queue — Resumable task orchestration with durable storage
+ *
+ * Provides a job queue that persists jobs to disk (JSON files) with support
+ * for status tracking, retries, priority ordering, and crash recovery.
+ * Designed for long-running swarm orchestration tasks that must survive
+ * process restarts.
+ *
+ * Backends:
+ *   - FileJobStore (built-in) — JSON files in a directory
+ *   - IJobStore interface — implement for SQLite, Postgres, etc.
+ *
+ * Features:
+ *   - Priority-based FIFO queue
+ *   - Configurable retries with exponential backoff
+ *   - Job timeout enforcement
+ *   - Crash recovery: stale "running" jobs are re-queued on startup
+ *   - Pluggable storage backends
+ *
+ * Usage:
+ *   const queue = new JobQueue({ store: new FileJobStore('./data/jobs') });
+ *   await queue.start();
+ *   await queue.enqueue({ type: 'delegateTask', payload: { agentId: 'analyzer', ... } });
+ *
+ * @module JobQueue
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobQueue = exports.FileJobStore = void 0;
+const events_1 = require("events");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+// ============================================================================
+// FILE JOB STORE
+// ============================================================================
+/**
+ * File-system job store — persists jobs as individual JSON files.
+ * Simple and dependency-free. Suitable for single-node deployments.
+ */
+class FileJobStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async init() {
+        try {
+            await (0, promises_1.stat)(this.dir);
+        }
+        catch {
+            await (0, promises_1.mkdir)(this.dir, { recursive: true });
+        }
+    }
+    async save(job) {
+        const filePath = (0, path_1.join)(this.dir, `${job.id}.json`);
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(job, null, 2), 'utf-8');
+    }
+    async get(id) {
+        try {
+            const filePath = (0, path_1.join)(this.dir, `${id}.json`);
+            const raw = await (0, promises_1.readFile)(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(id) {
+        try {
+            await (0, promises_1.unlink)((0, path_1.join)(this.dir, `${id}.json`));
+        }
+        catch {
+            // Ignore if already deleted
+        }
+    }
+    async listByStatus(status, limit = 100) {
+        const files = await (0, promises_1.readdir)(this.dir);
+        const jobs = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await (0, promises_1.readFile)((0, path_1.join)(this.dir, file), 'utf-8');
+                const job = JSON.parse(raw);
+                if (job.status === status)
+                    jobs.push(job);
+            }
+            catch {
+                // Skip corrupt files
+            }
+        }
+        // Sort by priority ASC, then createdAt ASC
+        jobs.sort((a, b) => a.priority - b.priority || a.createdAt - b.createdAt);
+        return jobs.slice(0, limit);
+    }
+    async countByStatus(status) {
+        const jobs = await this.listByStatus(status, Infinity);
+        return jobs.length;
+    }
+    async findStale(thresholdMs) {
+        const cutoff = Date.now() - thresholdMs;
+        const running = await this.listByStatus('running', Infinity);
+        return running.filter((j) => j.startedAt !== undefined && j.startedAt < cutoff);
+    }
+}
+exports.FileJobStore = FileJobStore;
+// ============================================================================
+// JOB QUEUE
+// ============================================================================
+/**
+ * Persistent job queue with priority ordering, retries, and crash recovery.
+ *
+ * Register handlers for job types, then start the queue. Jobs are
+ * persisted to the configured store and survive process restarts.
+ */
+class JobQueue extends events_1.EventEmitter {
+    handlers = new Map();
+    activeJobs = new Map();
+    pollTimer = null;
+    running = false;
+    store;
+    pollIntervalMs;
+    concurrency;
+    retryBaseDelayMs;
+    retryMaxDelayMs;
+    staleThresholdMs;
+    constructor(config) {
+        super();
+        this.store = config.store;
+        this.pollIntervalMs = config.pollIntervalMs ?? 1000;
+        this.concurrency = config.concurrency ?? 5;
+        this.retryBaseDelayMs = config.retryBaseDelayMs ?? 1000;
+        this.retryMaxDelayMs = config.retryMaxDelayMs ?? 60_000;
+        this.staleThresholdMs = config.staleThresholdMs ?? 600_000;
+    }
+    /** Register a handler for a job type */
+    handle(type, handler) {
+        this.handlers.set(type, handler);
+    }
+    /** Start the queue: init store, recover stale jobs, begin polling */
+    async start() {
+        if (this.running)
+            return;
+        await this.store.init();
+        await this.recoverStaleJobs();
+        this.running = true;
+        this.pollTimer = setInterval(() => {
+            this.poll().catch((err) => this.emit('error', err));
+        }, this.pollIntervalMs);
+        this.emit('started');
+    }
+    /** Stop the queue (active jobs continue but no new ones are dequeued) */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        // Wait for active jobs to finish
+        await Promise.allSettled(this.activeJobs.values());
+        this.activeJobs.clear();
+        this.emit('stopped');
+    }
+    /** Enqueue a new job */
+    async enqueue(options) {
+        const job = {
+            id: (0, crypto_1.randomBytes)(8).toString('hex'),
+            type: options.type,
+            payload: options.payload,
+            status: 'pending',
+            priority: options.priority ?? 2,
+            attempts: 0,
+            maxAttempts: options.maxAttempts ?? 3,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            timeoutMs: options.timeoutMs ?? 300_000,
+            metadata: options.metadata,
+        };
+        await this.store.save(job);
+        this.emit('enqueued', job);
+        return job;
+    }
+    /** Cancel a pending or running job */
+    async cancel(jobId) {
+        const job = await this.store.get(jobId);
+        if (!job)
+            return null;
+        if (job.status === 'completed' || job.status === 'cancelled')
+            return job;
+        job.status = 'cancelled';
+        job.updatedAt = Date.now();
+        job.completedAt = Date.now();
+        await this.store.save(job);
+        this.emit('cancelled', job);
+        return job;
+    }
+    /** Get a job by ID */
+    async getJob(jobId) {
+        return this.store.get(jobId);
+    }
+    /** Get queue stats */
+    async stats() {
+        const [pending, running, completed, failed, cancelled] = await Promise.all([
+            this.store.countByStatus('pending'),
+            this.store.countByStatus('running'),
+            this.store.countByStatus('completed'),
+            this.store.countByStatus('failed'),
+            this.store.countByStatus('cancelled'),
+        ]);
+        return { pending, running, completed, failed, cancelled, total: pending + running + completed + failed + cancelled };
+    }
+    /** Whether the queue is running */
+    get isRunning() {
+        return this.running;
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    async poll() {
+        if (!this.running)
+            return;
+        const availableSlots = this.concurrency - this.activeJobs.size;
+        if (availableSlots <= 0)
+            return;
+        const jobs = await this.store.listByStatus('pending', availableSlots);
+        for (const job of jobs) {
+            if (this.activeJobs.has(job.id))
+                continue;
+            if (job.status !== 'pending')
+                continue;
+            const handler = this.handlers.get(job.type);
+            if (!handler) {
+                this.emit('unhandled', job);
+                continue;
+            }
+            const jobPromise = this.processJob(job, handler);
+            this.activeJobs.set(job.id, jobPromise);
+            jobPromise.finally(() => this.activeJobs.delete(job.id));
+        }
+    }
+    async processJob(job, handler) {
+        // Mark as running
+        job.status = 'running';
+        job.attempts++;
+        job.startedAt = Date.now();
+        job.updatedAt = Date.now();
+        await this.store.save(job);
+        this.emit('processing', job);
+        try {
+            const result = await Promise.race([
+                handler(job),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Job timed out after ${job.timeoutMs}ms`)), job.timeoutMs)),
+            ]);
+            // Success
+            job.status = 'completed';
+            job.result = result;
+            job.completedAt = Date.now();
+            job.updatedAt = Date.now();
+            await this.store.save(job);
+            this.emit('completed', job);
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            if (job.attempts < job.maxAttempts) {
+                // Retry with backoff
+                const delay = Math.min(this.retryBaseDelayMs * Math.pow(2, job.attempts - 1), this.retryMaxDelayMs);
+                job.status = 'pending';
+                job.error = errorMsg;
+                job.updatedAt = Date.now();
+                // Add delay before re-processing by updating createdAt (moves to back of queue)
+                job.createdAt = Date.now() + delay;
+                await this.store.save(job);
+                this.emit('retry', job, delay);
+            }
+            else {
+                // Final failure
+                job.status = 'failed';
+                job.error = errorMsg;
+                job.completedAt = Date.now();
+                job.updatedAt = Date.now();
+                await this.store.save(job);
+                this.emit('failed', job);
+            }
+        }
+    }
+    async recoverStaleJobs() {
+        const stale = await this.store.findStale(this.staleThresholdMs);
+        for (const job of stale) {
+            if (job.attempts < job.maxAttempts) {
+                job.status = 'pending';
+                job.updatedAt = Date.now();
+                await this.store.save(job);
+                this.emit('recovered', job);
+            }
+            else {
+                job.status = 'failed';
+                job.error = 'Stale job exceeded max attempts';
+                job.completedAt = Date.now();
+                job.updatedAt = Date.now();
+                await this.store.save(job);
+                this.emit('failed', job);
+            }
+        }
+    }
+}
+exports.JobQueue = JobQueue;
+//# sourceMappingURL=job-queue.js.map

package/dist/esm/lib/job-queue.js.map

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

package/dist/esm/lib/landscape-agent.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * LandscapeAgent — Environment topology tracker
+ *
+ * Polls {@link EnvironmentManager.list} on a fixed interval and writes a
+ * health record for each known environment to the blackboard under
+ * `landscape:health:<env>`.  TransportAgent reads these records before
+ * starting a DRAINING phase to detect degraded destinations early.
+ *
+ * Health logic:
+ *   - `missing`  — environment directory does not exist
+ *   - `degraded` — last transport targeting this env failed or rolled back
+ *   - `healthy`  — otherwise
+ *
+ * Blackboard keys written:
+ *   landscape:health:<env>  — {@link EnvironmentHealth} record (overwritten each poll)
+ *
+ * @module LandscapeAgent
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LandscapeAgent = void 0;
+// ============================================================================
+// LANDSCAPE AGENT
+// ============================================================================
+/**
+ * Slow-poll environment topology tracker.
+ *
+ * @example
+ * ```typescript
+ * const landscape = new LandscapeAgent({ blackboard, envManager });
+ * landscape.start();
+ *
+ * // Read health for a specific environment:
+ * const entry = blackboard.read('landscape:health:prod');
+ * const health = entry?.value as EnvironmentHealth;
+ * ```
+ */
+class LandscapeAgent {
+    _blackboard;
+    _envManager;
+    _agentId;
+    _pollIntervalMs;
+    _pollHandle = null;
+    _running = false;
+    constructor(options) {
+        this._blackboard = options.blackboard;
+        this._envManager = options.envManager;
+        this._agentId = options.agentId ?? 'basis:landscape';
+        this._pollIntervalMs = options.pollIntervalMs ?? 30_000;
+    }
+    // --------------------------------------------------------------------------
+    // Lifecycle
+    // --------------------------------------------------------------------------
+    /**
+     * Start the poll loop.  The first poll fires immediately.
+     */
+    start() {
+        if (this._running)
+            return;
+        this._running = true;
+        void this._poll(); // immediate first run
+        this._pollHandle = setInterval(() => void this._poll(), this._pollIntervalMs);
+    }
+    /** Stop the poll loop. */
+    stop() {
+        this._running = false;
+        if (this._pollHandle) {
+            clearInterval(this._pollHandle);
+            this._pollHandle = null;
+        }
+    }
+    /** Whether the agent is currently running. */
+    get isRunning() { return this._running; }
+    /**
+     * Perform a single health poll and write results to the blackboard.
+     * Can be called manually (e.g. from tests) without starting the loop.
+     */
+    async poll() {
+        return this._poll();
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    async _poll() {
+        const envs = this._envManager.list();
+        const results = [];
+        for (const env of envs) {
+            const health = this._computeHealth(env.name, env.exists, env.keyCount);
+            this._blackboard.write(`landscape:health:${env.name}`, health, this._agentId);
+            results.push(health);
+        }
+        return results;
+    }
+    _computeHealth(env, exists, keyCount) {
+        const lastChecked = new Date().toISOString();
+        if (!exists) {
+            return { env, status: 'missing', keyCount: 0, lastChecked };
+        }
+        // Inspect the most recent completed transport targeting this environment
+        const { status: lastTransportStatus, trId: lastTransportId } = this._findLastTransport(env);
+        if (lastTransportStatus === 'failed' || lastTransportStatus === 'rolled_back') {
+            return { env, status: 'degraded', keyCount, lastChecked, lastTransportStatus, lastTransportId };
+        }
+        return { env, status: 'healthy', keyCount, lastChecked, lastTransportStatus, lastTransportId };
+    }
+    /** Scan `transport:status:*` keys for the most recent TR that targeted `env`. */
+    _findLastTransport(env) {
+        const statusKeys = this._blackboard.listKeys().filter(k => k.startsWith('transport:status:'));
+        let latestTime = 0;
+        let latestStatus;
+        let latestTrId;
+        for (const key of statusKeys) {
+            const entry = this._blackboard.read(key);
+            if (!entry)
+                continue;
+            const rec = entry.value;
+            if (rec.toEnv !== env)
+                continue;
+            // Only consider terminal states
+            if (!rec.completedAt)
+                continue;
+            const t = new Date(rec.completedAt).getTime();
+            if (t > latestTime) {
+                latestTime = t;
+                latestStatus = rec.status;
+                latestTrId = rec.trId;
+            }
+        }
+        return { status: latestStatus, trId: latestTrId };
+    }
+}
+exports.LandscapeAgent = LandscapeAgent;
+//# sourceMappingURL=landscape-agent.js.map

package/dist/esm/lib/landscape-agent.js.map

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

package/dist/esm/lib/learning-loop.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * LearningLoop — Store successful DAG patterns and prefer proven ones.
+ *
+ * After a TeamResult completes, `recordOutcome()` extracts the DAG shape
+ * (agent→action edges, dependency structure) and scores it by success rate.
+ * Before planning, `suggestPatterns()` returns the top matching patterns
+ * so the GoalDecomposer or planner can bias toward proven approaches.
+ *
+ * @module LearningLoop
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LearningLoop = void 0;
+// ============================================================================
+// LEARNING LOOP
+// ============================================================================
+/**
+ * Records DAG execution outcomes and recalls proven patterns.
+ *
+ * @example
+ * ```ts
+ * const loop = new LearningLoop();
+ *
+ * // After execution:
+ * loop.recordOutcome({
+ *   goal: 'Review and fix code',
+ *   steps: [{ agent: 'reviewer', action: 'review' }, { agent: 'fixer', action: 'fix' }],
+ *   edges: [[], [0]],
+ *   success: true,
+ *   durationMs: 5000,
+ * });
+ *
+ * // Before planning:
+ * const proven = loop.suggestPatterns('code review', ['review']);
+ * ```
+ */
+class LearningLoop {
+    patterns = new Map();
+    maxPatterns;
+    minSuccessRate;
+    constructor(options = {}) {
+        this.maxPatterns = options.maxPatterns ?? 2000;
+        this.minSuccessRate = options.minSuccessRate ?? 0.3;
+    }
+    /**
+     * Record the outcome of a DAG execution.
+     * If a matching pattern exists (same signature), updates stats.
+     * Otherwise creates a new pattern entry.
+     */
+    recordOutcome(outcome) {
+        const sig = this.computeSignature(outcome.steps, outcome.edges);
+        const existing = this.findBySignature(sig);
+        if (existing) {
+            existing.usageCount++;
+            if (outcome.success)
+                existing.successCount++;
+            else
+                existing.failureCount++;
+            existing.successRate = existing.successCount / existing.usageCount;
+            existing.avgDurationMs = (existing.avgDurationMs * (existing.usageCount - 1) + outcome.durationMs) / existing.usageCount;
+            existing.lastUsedAt = Date.now();
+            if (outcome.tags) {
+                for (const t of outcome.tags) {
+                    if (!existing.tags.includes(t))
+                        existing.tags.push(t);
+                }
+            }
+            return existing.id;
+        }
+        const id = `pat_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const now = Date.now();
+        const pattern = {
+            id,
+            goalSignature: sig,
+            steps: [...outcome.steps],
+            edges: outcome.edges.map(e => [...e]),
+            usageCount: 1,
+            successCount: outcome.success ? 1 : 0,
+            failureCount: outcome.success ? 0 : 1,
+            successRate: outcome.success ? 1.0 : 0.0,
+            avgDurationMs: outcome.durationMs,
+            tags: outcome.tags ? [...outcome.tags] : [],
+            createdAt: now,
+            lastUsedAt: now,
+        };
+        this.patterns.set(id, pattern);
+        this.evict();
+        return id;
+    }
+    /**
+     * Suggest proven patterns matching a goal description and tags.
+     * Returns patterns sorted by (relevance × successRate).
+     */
+    suggestPatterns(goalHint, tags = [], maxResults = 5) {
+        const hintTokens = this.tokenize(goalHint);
+        const matches = [];
+        for (const pattern of this.patterns.values()) {
+            if (pattern.usageCount < 2)
+                continue; // not enough data
+            if (pattern.successRate < this.minSuccessRate)
+                continue;
+            let relevance = 0;
+            // Tag overlap scoring
+            if (tags.length > 0 && pattern.tags.length > 0) {
+                const overlap = tags.filter(t => pattern.tags.includes(t)).length;
+                relevance = overlap / Math.max(tags.length, 1);
+            }
+            // Goal signature token overlap (lightweight text similarity)
+            const patternTokens = this.tokenize(pattern.goalSignature);
+            if (hintTokens.length > 0 && patternTokens.length > 0) {
+                const tokenOverlap = hintTokens.filter(t => patternTokens.includes(t)).length;
+                const tokenScore = tokenOverlap / Math.max(hintTokens.length, 1);
+                relevance = Math.max(relevance, tokenScore);
+            }
+            if (relevance > 0) {
+                matches.push({
+                    pattern,
+                    relevance: relevance * pattern.successRate,
+                });
+            }
+        }
+        matches.sort((a, b) => b.relevance - a.relevance);
+        return matches.slice(0, maxResults);
+    }
+    /** Get a specific pattern by ID */
+    get(id) {
+        return this.patterns.get(id);
+    }
+    /** Get all patterns */
+    getAll() {
+        return [...this.patterns.values()];
+    }
+    /** Number of stored patterns */
+    size() {
+        return this.patterns.size;
+    }
+    /** Clear all patterns */
+    clear() {
+        this.patterns.clear();
+    }
+    /** Export patterns for persistence */
+    export() {
+        return [...this.patterns.values()];
+    }
+    /** Import patterns from a persisted array */
+    import(patterns) {
+        for (const p of patterns) {
+            this.patterns.set(p.id, p);
+        }
+        this.evict();
+    }
+    // --------------------------------------------------------------------------
+    // INTERNAL
+    // --------------------------------------------------------------------------
+    computeSignature(steps, edges) {
+        const stepParts = steps.map(s => `${s.agent}:${s.action}`).join('|');
+        const edgeParts = edges.map((deps, i) => deps.length > 0 ? `${i}<-${deps.join(',')}` : `${i}`).join(';');
+        return `${stepParts}#${edgeParts}`;
+    }
+    findBySignature(sig) {
+        for (const p of this.patterns.values()) {
+            if (p.goalSignature === sig)
+                return p;
+        }
+        return undefined;
+    }
+    tokenize(text) {
+        return text.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+    }
+    evict() {
+        if (this.patterns.size <= this.maxPatterns)
+            return;
+        // Remove lowest-scoring patterns
+        const sorted = [...this.patterns.entries()].sort((a, b) => (a[1].successRate * a[1].usageCount) - (b[1].successRate * b[1].usageCount));
+        const toRemove = sorted.slice(0, this.patterns.size - this.maxPatterns);
+        for (const [id] of toRemove)
+            this.patterns.delete(id);
+    }
+}
+exports.LearningLoop = LearningLoop;
+//# sourceMappingURL=learning-loop.js.map

package/dist/esm/lib/learning-loop.js.map

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