network-ai 4.15.2 → 5.0.0

package/dist/lib/goal-dsl.js

@@ -0,0 +1,392 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGoal = parseGoal;
+exports.goalFromObject = goalFromObject;
+exports.validateGoal = validateGoal;
+exports.compileGoal = compileGoal;
+// ============================================================================
+// PARSER
+// ============================================================================
+/**
+ * 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)
+ */
+function parseGoal(input) {
+    const trimmed = input.trim();
+    // Try JSON first
+    if (trimmed.startsWith('{')) {
+        const parsed = JSON.parse(trimmed);
+        return normalizeGoal(parsed);
+    }
+    // Simple YAML-like parser
+    return parseSimpleYaml(trimmed);
+}
+/** Parse from a plain object (e.g. loaded from file) */
+function goalFromObject(obj) {
+    return normalizeGoal(obj);
+}
+// ============================================================================
+// VALIDATOR
+// ============================================================================
+/**
+ * Validate a goal definition for correctness.
+ * Checks for cycles, missing dependencies, duplicate IDs, and required fields.
+ */
+function validateGoal(goal) {
+    const errors = [];
+    // Empty tasks
+    if (!goal.tasks || goal.tasks.length === 0) {
+        errors.push({ type: 'empty_tasks', message: 'Goal must have at least one task' });
+        return { valid: false, errors };
+    }
+    // Duplicate IDs
+    const idSet = new Set();
+    for (const task of goal.tasks) {
+        if (idSet.has(task.id)) {
+            errors.push({ type: 'duplicate_id', message: `Duplicate task ID: '${task.id}'`, taskId: task.id });
+        }
+        idSet.add(task.id);
+    }
+    // Required fields
+    for (const task of goal.tasks) {
+        if (!task.id || typeof task.id !== 'string') {
+            errors.push({ type: 'invalid_field', message: 'Task missing required field: id', taskId: task.id });
+        }
+        if (!task.agent || typeof task.agent !== 'string') {
+            errors.push({ type: 'missing_agent', message: `Task '${task.id}' missing required field: agent`, taskId: task.id });
+        }
+        if (!task.action || typeof task.action !== 'string') {
+            errors.push({ type: 'invalid_field', message: `Task '${task.id}' missing required field: action`, taskId: task.id });
+        }
+    }
+    // Missing dependencies
+    for (const task of goal.tasks) {
+        if (task.depends) {
+            for (const dep of task.depends) {
+                if (!idSet.has(dep)) {
+                    errors.push({
+                        type: 'missing_dependency',
+                        message: `Task '${task.id}' depends on unknown task '${dep}'`,
+                        taskId: task.id,
+                    });
+                }
+            }
+        }
+    }
+    // Cycle detection (Kahn's algorithm)
+    if (errors.length === 0) {
+        const hasCycle = detectCycle(goal.tasks);
+        if (hasCycle) {
+            errors.push({ type: 'cycle', message: 'Goal task graph contains a cycle' });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ============================================================================
+// COMPILER
+// ============================================================================
+/**
+ * Compile a validated goal into an executable plan with layered parallelism.
+ * Performs topological sort to determine execution layers.
+ *
+ * @throws If the goal is invalid.
+ */
+function compileGoal(goal) {
+    const validation = validateGoal(goal);
+    if (!validation.valid) {
+        throw new Error(`Invalid goal: ${validation.errors.map((e) => e.message).join('; ')}`);
+    }
+    const taskMap = new Map(goal.tasks.map((t) => [t.id, t]));
+    const adjacency = new Map();
+    // Build adjacency (task → dependents)
+    for (const task of goal.tasks) {
+        if (!adjacency.has(task.id))
+            adjacency.set(task.id, []);
+        if (task.depends) {
+            for (const dep of task.depends) {
+                const deps = adjacency.get(dep) ?? [];
+                deps.push(task.id);
+                adjacency.set(dep, deps);
+            }
+        }
+    }
+    // Topological sort into layers
+    const inDegree = new Map();
+    for (const task of goal.tasks) {
+        inDegree.set(task.id, task.depends?.length ?? 0);
+    }
+    const layers = [];
+    const taskOrder = [];
+    const remaining = new Set(goal.tasks.map((t) => t.id));
+    let layerIndex = 0;
+    while (remaining.size > 0) {
+        const ready = [];
+        for (const id of remaining) {
+            if ((inDegree.get(id) ?? 0) <= 0) {
+                ready.push(id);
+            }
+        }
+        if (ready.length === 0)
+            break; // Safety: shouldn't happen after validation
+        layers.push({ index: layerIndex++, taskIds: ready });
+        taskOrder.push(...ready);
+        for (const id of ready) {
+            remaining.delete(id);
+            const dependents = adjacency.get(id) ?? [];
+            for (const dep of dependents) {
+                inDegree.set(dep, (inDegree.get(dep) ?? 1) - 1);
+            }
+        }
+    }
+    const maxWidth = Math.max(...layers.map((l) => l.taskIds.length), 0);
+    return {
+        definition: goal,
+        layers,
+        depth: layers.length,
+        maxWidth,
+        taskOrder,
+        adjacency,
+    };
+}
+// ============================================================================
+// INTERNAL HELPERS
+// ============================================================================
+function detectCycle(tasks) {
+    const inDegree = new Map();
+    const adj = new Map();
+    for (const task of tasks) {
+        inDegree.set(task.id, 0);
+        adj.set(task.id, []);
+    }
+    for (const task of tasks) {
+        if (task.depends) {
+            for (const dep of task.depends) {
+                adj.get(dep)?.push(task.id);
+                inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1);
+            }
+        }
+    }
+    const queue = [];
+    for (const [id, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    let visited = 0;
+    while (queue.length > 0) {
+        const node = queue.shift();
+        visited++;
+        for (const next of adj.get(node) ?? []) {
+            const newDeg = (inDegree.get(next) ?? 1) - 1;
+            inDegree.set(next, newDeg);
+            if (newDeg === 0)
+                queue.push(next);
+        }
+    }
+    return visited !== tasks.length;
+}
+function normalizeGoal(raw) {
+    return {
+        name: raw.name ?? 'unnamed',
+        description: raw.description,
+        version: raw.version,
+        tasks: (raw.tasks ?? []).map((t) => ({
+            id: t.id,
+            agent: t.agent,
+            action: t.action,
+            depends: t.depends,
+            params: t.params,
+            timeoutMs: t.timeoutMs,
+            critical: t.critical ?? true,
+            retries: t.retries ?? 0,
+            outputKey: t.outputKey,
+        })),
+        constraints: raw.constraints,
+        outputs: raw.outputs,
+        metadata: raw.metadata,
+    };
+}
+function parseSimpleYaml(input) {
+    const lines = input.split('\n');
+    const result = {};
+    let currentTasks = [];
+    let currentTask = null;
+    let currentOutputs = [];
+    let currentOutput = null;
+    let section = 'root';
+    let constraints = {};
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\r$/, '');
+        const trimmedLine = line.trimStart();
+        if (trimmedLine === '' || trimmedLine.startsWith('#'))
+            continue;
+        const indent = line.length - trimmedLine.length;
+        // Top-level keys
+        if (indent === 0 && trimmedLine.includes(':')) {
+            // Save previous state
+            if (currentTask) {
+                currentTasks.push(currentTask);
+                currentTask = null;
+            }
+            if (currentOutput) {
+                currentOutputs.push(currentOutput);
+                currentOutput = null;
+            }
+            const [key, ...valParts] = trimmedLine.split(':');
+            const val = valParts.join(':').trim();
+            if (key.trim() === 'tasks') {
+                section = 'tasks';
+                continue;
+            }
+            if (key.trim() === 'constraints') {
+                section = 'constraints';
+                continue;
+            }
+            if (key.trim() === 'outputs') {
+                section = 'outputs';
+                continue;
+            }
+            result[key.trim()] = parseYamlValue(val);
+            section = 'root';
+            continue;
+        }
+        // Task list items
+        if (section === 'tasks' || section === 'task') {
+            if (trimmedLine.startsWith('- ')) {
+                if (currentTask)
+                    currentTasks.push(currentTask);
+                currentTask = {};
+                section = 'task';
+                // Parse inline key:value after -
+                const afterDash = trimmedLine.slice(2).trim();
+                if (afterDash.includes(':')) {
+                    const [k, ...vParts] = afterDash.split(':');
+                    currentTask[k.trim()] = parseYamlValue(vParts.join(':').trim());
+                }
+                continue;
+            }
+            if (currentTask && trimmedLine.includes(':')) {
+                const [k, ...vParts] = trimmedLine.split(':');
+                currentTask[k.trim()] = parseYamlValue(vParts.join(':').trim());
+                continue;
+            }
+        }
+        // Constraints
+        if (section === 'constraints' && trimmedLine.includes(':')) {
+            const [k, ...vParts] = trimmedLine.split(':');
+            constraints[k.trim()] = parseYamlValue(vParts.join(':').trim());
+            continue;
+        }
+        // Outputs
+        if (section === 'outputs' || section === 'output') {
+            if (trimmedLine.startsWith('- ')) {
+                if (currentOutput)
+                    currentOutputs.push(currentOutput);
+                currentOutput = {};
+                section = 'output';
+                const afterDash = trimmedLine.slice(2).trim();
+                if (afterDash.includes(':')) {
+                    const [k, ...vParts] = afterDash.split(':');
+                    currentOutput[k.trim()] = parseYamlValue(vParts.join(':').trim());
+                }
+                continue;
+            }
+            if (currentOutput && trimmedLine.includes(':')) {
+                const [k, ...vParts] = trimmedLine.split(':');
+                currentOutput[k.trim()] = parseYamlValue(vParts.join(':').trim());
+                continue;
+            }
+        }
+    }
+    // Flush remaining
+    if (currentTask)
+        currentTasks.push(currentTask);
+    if (currentOutput)
+        currentOutputs.push(currentOutput);
+    const goal = {
+        name: result['name'] ?? 'unnamed',
+        description: result['description'],
+        version: result['version'],
+        tasks: currentTasks.map((t) => ({
+            id: t['id'] ?? '',
+            agent: t['agent'] ?? '',
+            action: t['action'] ?? '',
+            depends: t['depends'],
+            params: t['params'],
+            timeoutMs: t['timeoutMs'],
+            critical: t['critical'],
+            retries: t['retries'],
+            outputKey: t['outputKey'],
+        })),
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+        outputs: currentOutputs.length > 0 ? currentOutputs.map((o) => ({
+            key: o['key'] ?? '',
+            type: o['type'],
+            required: o['required'],
+            description: o['description'],
+        })) : undefined,
+        metadata: result['metadata'],
+    };
+    return normalizeGoal(goal);
+}
+function parseYamlValue(val) {
+    if (val === '' || val === undefined)
+        return undefined;
+    if (val === 'true')
+        return true;
+    if (val === 'false')
+        return false;
+    if (val === 'null')
+        return null;
+    // Inline array [a, b, c]
+    if (val.startsWith('[') && val.endsWith(']')) {
+        const inner = val.slice(1, -1);
+        return inner.split(',').map((s) => parseYamlValue(s.trim()));
+    }
+    // Number
+    const num = Number(val);
+    if (!isNaN(num) && val !== '')
+        return num;
+    // Strip quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        return val.slice(1, -1);
+    }
+    return val;
+}
+//# sourceMappingURL=goal-dsl.js.map

package/dist/lib/goal-dsl.js.map

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

package/dist/lib/job-queue.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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
+ */
+import { EventEmitter } from 'events';
+/** Job status */
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** Priority level (lower = higher priority) */
+export type JobPriority = 0 | 1 | 2 | 3 | 4 | 5;
+/** A persistent job record */
+export interface JobRecord {
+    /** Unique job ID */
+    id: string;
+    /** Job type (e.g. 'delegateTask', 'batchProcess') */
+    type: string;
+    /** Job payload — any serializable data */
+    payload: Record<string, unknown>;
+    /** Current status */
+    status: JobStatus;
+    /** Priority (0 = highest, 5 = lowest; default: 2) */
+    priority: JobPriority;
+    /** Number of attempts so far */
+    attempts: number;
+    /** Maximum attempts (default: 3) */
+    maxAttempts: number;
+    /** When the job was created */
+    createdAt: number;
+    /** When the job was last updated */
+    updatedAt: number;
+    /** When the job started running */
+    startedAt?: number;
+    /** When the job completed or failed */
+    completedAt?: number;
+    /** Result data (on success) */
+    result?: unknown;
+    /** Error message (on failure) */
+    error?: string;
+    /** Job timeout in ms (default: 300000 = 5 min) */
+    timeoutMs: number;
+    /** Metadata for tracking */
+    metadata?: Record<string, unknown>;
+}
+/** Options for creating a new job */
+export interface JobCreateOptions {
+    /** Job type */
+    type: string;
+    /** Job payload */
+    payload: Record<string, unknown>;
+    /** Priority (default: 2) */
+    priority?: JobPriority;
+    /** Max attempts (default: 3) */
+    maxAttempts?: number;
+    /** Timeout in ms (default: 300000) */
+    timeoutMs?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Job handler function — processes a single job.
+ * Return a result on success, or throw to fail.
+ */
+export type JobHandler = (job: JobRecord) => Promise<unknown>;
+/** Job queue configuration */
+export interface JobQueueConfig {
+    /** Storage backend */
+    store: IJobStore;
+    /** Polling interval in ms (default: 1000) */
+    pollIntervalMs?: number;
+    /** Maximum concurrent jobs (default: 5) */
+    concurrency?: number;
+    /** Base retry delay in ms (default: 1000) */
+    retryBaseDelayMs?: number;
+    /** Maximum retry delay in ms (default: 60000) */
+    retryMaxDelayMs?: number;
+    /** Stale job threshold in ms — re-queue "running" jobs older than this (default: 600000 = 10 min) */
+    staleThresholdMs?: number;
+}
+/** Stats snapshot */
+export interface JobQueueStats {
+    pending: number;
+    running: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    total: number;
+}
+/**
+ * Pluggable storage backend for the job queue.
+ * Implement this for SQLite, Postgres, Redis, etc.
+ */
+export interface IJobStore {
+    /** Initialize the store (create tables/dirs) */
+    init(): Promise<void>;
+    /** Save or update a job */
+    save(job: JobRecord): Promise<void>;
+    /** Get a job by ID */
+    get(id: string): Promise<JobRecord | null>;
+    /** Delete a job by ID */
+    delete(id: string): Promise<void>;
+    /** List jobs by status, ordered by priority ASC then createdAt ASC */
+    listByStatus(status: JobStatus, limit?: number): Promise<JobRecord[]>;
+    /** Count jobs by status */
+    countByStatus(status: JobStatus): Promise<number>;
+    /** Find stale running jobs (startedAt < threshold) */
+    findStale(thresholdMs: number): Promise<JobRecord[]>;
+}
+/**
+ * File-system job store — persists jobs as individual JSON files.
+ * Simple and dependency-free. Suitable for single-node deployments.
+ */
+export declare class FileJobStore implements IJobStore {
+    private readonly dir;
+    constructor(dir: string);
+    init(): Promise<void>;
+    save(job: JobRecord): Promise<void>;
+    get(id: string): Promise<JobRecord | null>;
+    delete(id: string): Promise<void>;
+    listByStatus(status: JobStatus, limit?: number): Promise<JobRecord[]>;
+    countByStatus(status: JobStatus): Promise<number>;
+    findStale(thresholdMs: number): Promise<JobRecord[]>;
+}
+/**
+ * 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.
+ */
+export declare class JobQueue extends EventEmitter {
+    private handlers;
+    private activeJobs;
+    private pollTimer;
+    private running;
+    private readonly store;
+    private readonly pollIntervalMs;
+    private readonly concurrency;
+    private readonly retryBaseDelayMs;
+    private readonly retryMaxDelayMs;
+    private readonly staleThresholdMs;
+    constructor(config: JobQueueConfig);
+    /** Register a handler for a job type */
+    handle(type: string, handler: JobHandler): void;
+    /** Start the queue: init store, recover stale jobs, begin polling */
+    start(): Promise<void>;
+    /** Stop the queue (active jobs continue but no new ones are dequeued) */
+    stop(): Promise<void>;
+    /** Enqueue a new job */
+    enqueue(options: JobCreateOptions): Promise<JobRecord>;
+    /** Cancel a pending or running job */
+    cancel(jobId: string): Promise<JobRecord | null>;
+    /** Get a job by ID */
+    getJob(jobId: string): Promise<JobRecord | null>;
+    /** Get queue stats */
+    stats(): Promise<JobQueueStats>;
+    /** Whether the queue is running */
+    get isRunning(): boolean;
+    private poll;
+    private processJob;
+    private recoverStaleJobs;
+}
+//# sourceMappingURL=job-queue.d.ts.map

package/dist/lib/job-queue.d.ts.map

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