network-ai 5.10.2 → 5.11.0

package/dist/esm/lib/task-decomposer.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * Task decomposition engine for parallel multi-agent execution.
+ *
+ * Breaks complex tasks into parallel sub-agent calls, routes them through
+ * the adapter registry, caches results on the blackboard, and synthesizes
+ * outputs using configurable strategies (merge, vote, chain, first-success).
+ *
+ * @module TaskDecomposer
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskDecomposer = void 0;
+const crypto_1 = require("crypto");
+const adapter_registry_1 = require("../adapters/adapter-registry");
+const security_1 = require("../security");
+const errors_1 = require("./errors");
+const shared_blackboard_1 = require("./shared-blackboard");
+const auth_guardian_1 = require("./auth-guardian");
+const orchestrator_types_1 = require("./orchestrator-types");
+class TaskDecomposer {
+    blackboard;
+    authGuardian;
+    adapterRegistry;
+    /** Maximum number of tasks to run concurrently (0 = unlimited). */
+    maxConcurrency;
+    constructor(blackboard, authGuardian, adapterRegistry, options) {
+        if (!blackboard || !(blackboard instanceof shared_blackboard_1.SharedBlackboard)) {
+            throw new errors_1.ValidationError('blackboard must be an instance of SharedBlackboard');
+        }
+        if (!authGuardian || !(authGuardian instanceof auth_guardian_1.AuthGuardian)) {
+            throw new errors_1.ValidationError('authGuardian must be an instance of AuthGuardian');
+        }
+        if (!adapterRegistry || !(adapterRegistry instanceof adapter_registry_1.AdapterRegistry)) {
+            throw new errors_1.ValidationError('adapterRegistry must be an instance of AdapterRegistry');
+        }
+        this.blackboard = blackboard;
+        this.authGuardian = authGuardian;
+        this.adapterRegistry = adapterRegistry;
+        this.maxConcurrency = options?.maxConcurrency ?? 5;
+    }
+    /**
+     * Decomposes a complex task into parallel sub-agent calls
+     * This is the "Wall Breaker" - transforms impossible monolithic tasks
+     * into manageable parallel executions
+     */
+    async executeParallel(tasks, synthesisStrategy = 'merge', context) {
+        if (!tasks || !Array.isArray(tasks)) {
+            throw new errors_1.ValidationError('tasks must be an array');
+        }
+        if (tasks.length === 0) {
+            throw new errors_1.ValidationError('tasks array must not be empty');
+        }
+        if (!context || typeof context !== 'object' || !context.agentId) {
+            throw new errors_1.ValidationError('context is required and must include agentId');
+        }
+        // No hard parallel limit — caller controls concurrency via task count
+        const startTime = Date.now();
+        const individualResults = [];
+        // Check blackboard for cached results first
+        const cachedTasks = [];
+        const uncachedTasks = [];
+        for (const task of tasks) {
+            const cacheKey = `task:${task.agentType}:${this.hashPayload(task.taskPayload)}`;
+            const cached = this.blackboard.read(cacheKey);
+            if (cached) {
+                individualResults.push({
+                    agentType: task.agentType,
+                    success: true,
+                    result: cached.value,
+                    executionTime: 0, // From cache
+                });
+                cachedTasks.push(task);
+            }
+            else {
+                uncachedTasks.push(task);
+            }
+        }
+        // Execute uncached tasks with concurrency cap
+        if (uncachedTasks.length > 0) {
+            const results = await this.runWithConcurrencyLimit(uncachedTasks, task => this.executeSingleTask(task, context), this.maxConcurrency);
+            for (let i = 0; i < results.length; i++) {
+                const task = uncachedTasks[i];
+                const result = results[i];
+                individualResults.push(result);
+                // Cache successful results
+                if (result.success) {
+                    const cacheKey = `task:${task.agentType}:${this.hashPayload(task.taskPayload)}`;
+                    this.blackboard.write(cacheKey, result.result, context.agentId, 3600, 'system-orchestrator-token'); // 1 hour TTL
+                }
+            }
+        }
+        // Synthesize results based on strategy
+        const synthesizedResult = this.synthesize(individualResults, synthesisStrategy);
+        const totalTime = Date.now() - startTime;
+        const successCount = individualResults.filter(r => r.success).length;
+        return {
+            synthesizedResult,
+            individualResults,
+            executionMetrics: {
+                totalTime,
+                successRate: successCount / individualResults.length,
+                synthesisStrategy,
+            },
+        };
+    }
+    async executeSingleTask(task, context) {
+        const taskStart = Date.now();
+        try {
+            // Build the handoff message
+            const handoff = {
+                handoffId: (0, crypto_1.randomUUID)(),
+                sourceAgent: context.agentId,
+                targetAgent: task.agentType,
+                taskType: 'delegate',
+                payload: task.taskPayload,
+                metadata: {
+                    priority: 1,
+                    deadline: Date.now() + orchestrator_types_1.CONFIG.defaultTimeout,
+                    parentTaskId: context.taskId ?? null,
+                },
+            };
+            // Sanitize the instruction before sending to adapter
+            let sanitizedInstruction = task.taskPayload.instruction;
+            try {
+                sanitizedInstruction = security_1.InputSanitizer.sanitizeString(task.taskPayload.instruction, 10000);
+            }
+            catch { /* use original if sanitization fails */ }
+            // Use namespace-scoped snapshot -- target agent only sees keys it's allowed to see
+            const scopedSnapshot = this.blackboard.getScopedSnapshot(task.agentType);
+            // Route through the adapter registry (framework-agnostic)
+            const agentPayload = {
+                action: 'execute',
+                params: {},
+                handoff: {
+                    handoffId: handoff.handoffId,
+                    sourceAgent: handoff.sourceAgent,
+                    targetAgent: handoff.targetAgent,
+                    taskType: handoff.taskType,
+                    instruction: sanitizedInstruction,
+                    context: handoff.payload.context,
+                    constraints: handoff.payload.constraints,
+                    expectedOutput: handoff.payload.expectedOutput,
+                    metadata: handoff.metadata,
+                },
+                blackboardSnapshot: scopedSnapshot,
+            };
+            const agentContext = {
+                agentId: context.agentId,
+                taskId: context.taskId,
+                sessionId: context.sessionId,
+            };
+            const result = await this.adapterRegistry.executeAgent(task.agentType, agentPayload, agentContext);
+            // Sanitize adapter output before returning/caching
+            let sanitizedData = result.data;
+            try {
+                sanitizedData = security_1.InputSanitizer.sanitizeObject(result.data);
+            }
+            catch { /* use raw if sanitization fails */ }
+            return {
+                agentType: task.agentType,
+                success: true,
+                result: sanitizedData,
+                executionTime: Date.now() - taskStart,
+            };
+        }
+        catch (error) {
+            return {
+                agentType: task.agentType,
+                success: false,
+                result: {
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                    recoverable: true,
+                },
+                executionTime: Date.now() - taskStart,
+            };
+        }
+    }
+    synthesize(results, strategy) {
+        const successfulResults = results.filter(r => r.success);
+        if (successfulResults.length === 0) {
+            return {
+                error: 'All parallel tasks failed',
+                individualErrors: results.map(r => ({
+                    agent: r.agentType,
+                    error: r.result,
+                })),
+            };
+        }
+        switch (strategy) {
+            case 'merge':
+                // Combine all results into a unified object
+                return {
+                    merged: true,
+                    contributions: successfulResults.map(r => ({
+                        source: r.agentType,
+                        data: r.result,
+                    })),
+                    summary: this.generateMergeSummary(successfulResults),
+                };
+            case 'vote':
+                // Return the result with highest "confidence" (simplified: most data)
+                const scored = successfulResults.map(r => ({
+                    result: r,
+                    score: JSON.stringify(r.result).length,
+                }));
+                scored.sort((a, b) => b.score - a.score);
+                return {
+                    voted: true,
+                    winner: scored[0].result.agentType,
+                    result: scored[0].result.result,
+                };
+            case 'chain':
+                // Results should already be ordered; return the final one
+                return {
+                    chained: true,
+                    finalResult: successfulResults[successfulResults.length - 1].result,
+                    chainLength: successfulResults.length,
+                };
+            case 'first-success':
+                // Return the first successful result
+                return {
+                    firstSuccess: true,
+                    source: successfulResults[0].agentType,
+                    result: successfulResults[0].result,
+                };
+            default:
+                return successfulResults.map(r => r.result);
+        }
+    }
+    generateMergeSummary(results) {
+        const agents = results.map(r => r.agentType).join(', ');
+        return `Synthesized from ${results.length} agents: ${agents}`;
+    }
+    hashPayload(payload) {
+        // Simple hash for cache key generation
+        const str = JSON.stringify(payload);
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return Math.abs(hash).toString(16);
+    }
+    /**
+     * Execute async functions with a bounded concurrency pool.
+     * @param items Items to process
+     * @param fn Async function to apply to each item
+     * @param limit Max concurrent executions (0 = unlimited)
+     */
+    async runWithConcurrencyLimit(items, fn, limit) {
+        if (limit <= 0 || items.length <= limit) {
+            return Promise.all(items.map(fn));
+        }
+        const results = new Array(items.length);
+        let nextIndex = 0;
+        async function worker() {
+            while (nextIndex < items.length) {
+                const idx = nextIndex++;
+                results[idx] = await fn(items[idx]);
+            }
+        }
+        const workers = [];
+        for (let i = 0; i < Math.min(limit, items.length); i++) {
+            workers.push(worker());
+        }
+        await Promise.all(workers);
+        return results;
+    }
+}
+exports.TaskDecomposer = TaskDecomposer;
+//# sourceMappingURL=task-decomposer.js.map

package/dist/esm/lib/task-decomposer.js.map

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

package/dist/esm/lib/telemetry-provider.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Telemetry Provider — BYOT (Bring Your Own Telemetry) abstraction.
+ *
+ * Defines a minimal interface over distributed tracing providers such as
+ * OpenTelemetry, Datadog APM, Honeycomb, etc.  Network-AI core never imports
+ * a concrete telemetry SDK — only this interface — preserving the zero-
+ * dependency BYOC design.
+ *
+ * ## Wiring into adapter lifecycle hooks
+ *
+ * ```typescript
+ * import { createOtelHooks, CapturingTelemetryProvider } from 'network-ai';
+ * import { AdapterHookManager } from 'network-ai';
+ *
+ * const provider = new CapturingTelemetryProvider(); // or your own impl
+ * const hookManager = new AdapterHookManager();
+ * createOtelHooks(provider).forEach(h => hookManager.register(h));
+ * ```
+ *
+ * ## Implementing for OpenTelemetry
+ *
+ * ```typescript
+ * import { trace, SpanStatusCode } from '@opentelemetry/api';
+ * import type { ITelemetryProvider, SpanAttributes } from 'network-ai';
+ *
+ * class OtelProvider implements ITelemetryProvider {
+ *   private tracer = trace.getTracer('network-ai');
+ *   private spans = new Map<string, Span>();
+ *
+ *   startSpan(name: string, attrs: SpanAttributes = {}): string {
+ *     const span = this.tracer.startSpan(name, { attributes: attrs as Attributes });
+ *     const id = `span_${Date.now()}`;
+ *     this.spans.set(id, span);
+ *     return id;
+ *   }
+ *   endSpan(id: string, status: 'ok' | 'error'): void {
+ *     const span = this.spans.get(id);
+ *     if (!span) return;
+ *     span.setStatus({ code: status === 'ok' ? SpanStatusCode.OK : SpanStatusCode.ERROR });
+ *     span.end();
+ *     this.spans.delete(id);
+ *   }
+ *   recordEvent(id: string, name: string, attrs: SpanAttributes = {}): void {
+ *     this.spans.get(id)?.addEvent(name, attrs as Attributes);
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapturingTelemetryProvider = exports.NullTelemetryProvider = void 0;
+exports.createOtelHooks = createOtelHooks;
+// ============================================================================
+// NULL PROVIDER (default — zero overhead when no telemetry is configured)
+// ============================================================================
+/**
+ * No-op implementation.  Used as the default when no telemetry provider is
+ * supplied so the instrumentation path compiles to a handful of dead calls
+ * that the JIT eliminates.
+ */
+class NullTelemetryProvider {
+    /** @inheritdoc */
+    startSpan(_name, _attributes) { return ''; }
+    /** @inheritdoc */
+    endSpan(_spanId, _status, _attributes) { }
+    /** @inheritdoc */
+    recordEvent(_spanId, _name, _attributes) { }
+}
+exports.NullTelemetryProvider = NullTelemetryProvider;
+// ============================================================================
+// CAPTURING PROVIDER (for testing)
+// ============================================================================
+/**
+ * In-memory provider that stores every span and event for test assertions.
+ *
+ * @example
+ * ```typescript
+ * const provider = new CapturingTelemetryProvider();
+ * createOtelHooks(provider).forEach(h => hookManager.register(h));
+ *
+ * await registry.executeAgent('agent:foo', payload, ctx);
+ *
+ * const span = provider.spans.find(s => s.name === 'adapter.execute');
+ * expect(span?.status).toBe('ok');
+ * ```
+ */
+class CapturingTelemetryProvider {
+    /** All spans created since construction or last `clear()`. */
+    spans = [];
+    counter = 0;
+    /** @inheritdoc */
+    startSpan(name, attributes = {}) {
+        const spanId = `span_${++this.counter}`;
+        this.spans.push({ spanId, name, attributes: { ...attributes }, startedAt: Date.now(), events: [] });
+        return spanId;
+    }
+    /** @inheritdoc */
+    endSpan(spanId, status, attributes = {}) {
+        const span = this.spans.find(s => s.spanId === spanId);
+        if (!span)
+            return;
+        span.endedAt = Date.now();
+        span.status = status;
+        Object.assign(span.attributes, attributes);
+    }
+    /** @inheritdoc */
+    recordEvent(spanId, name, attributes = {}) {
+        const span = this.spans.find(s => s.spanId === spanId);
+        if (!span)
+            return;
+        span.events.push({ name, attributes: { ...attributes }, ts: Date.now() });
+    }
+    /** Clear all captured data and reset span counter. */
+    clear() {
+        this.spans.length = 0;
+        this.counter = 0;
+    }
+}
+exports.CapturingTelemetryProvider = CapturingTelemetryProvider;
+// ============================================================================
+// HOOK FACTORY
+// ============================================================================
+/** Metadata key used to propagate spanId through `HookContext`. @internal */
+const SPAN_ID_META_KEY = '_otelSpanId';
+/**
+ * Create a set of `ExecutionHook` objects that emit traces to `provider`.
+ *
+ * Register the returned hooks with an `AdapterHookManager`:
+ * ```typescript
+ * createOtelHooks(provider).forEach(h => hookManager.register(h));
+ * ```
+ *
+ * Three hooks are created — one per `HookPhase`:
+ * - `otel:beforeExecute` — calls `provider.startSpan('adapter.execute', {...})`
+ * - `otel:afterExecute`  — calls `provider.endSpan(spanId, 'ok')`
+ * - `otel:onError`       — calls `provider.endSpan(spanId, 'error')`
+ *
+ * Each hook has `priority: 100` so it runs before most user-defined hooks.
+ * The spanId is stored in `ctx.metadata._otelSpanId` for downstream hooks
+ * that wish to add their own `recordEvent` calls.
+ *
+ * **Permission check semantics:** `beforeExecute` fires once when execution
+ * begins — not per streaming chunk — matching the documented "once at start"
+ * semantics of `StreamingBaseAdapter`.
+ */
+function createOtelHooks(provider) {
+    return [
+        {
+            name: 'otel:beforeExecute',
+            phase: 'beforeExecute',
+            priority: 100,
+            handler(ctx) {
+                try {
+                    const spanId = provider.startSpan('adapter.execute', {
+                        agentId: ctx.agentId,
+                        action: ctx.payload.action ?? '',
+                        depth: ctx.depth,
+                    });
+                    ctx.metadata[SPAN_ID_META_KEY] = spanId;
+                }
+                catch {
+                    // Telemetry must never break execution
+                }
+                return ctx;
+            },
+        },
+        {
+            name: 'otel:afterExecute',
+            phase: 'afterExecute',
+            priority: 100,
+            handler(ctx) {
+                try {
+                    const spanId = ctx.metadata[SPAN_ID_META_KEY];
+                    if (spanId) {
+                        provider.endSpan(spanId, 'ok', {
+                            success: ctx.result?.success === true,
+                        });
+                    }
+                }
+                catch {
+                    // no-op
+                }
+                return ctx;
+            },
+        },
+        {
+            name: 'otel:onError',
+            phase: 'onError',
+            priority: 100,
+            handler(ctx) {
+                try {
+                    const spanId = ctx.metadata[SPAN_ID_META_KEY];
+                    if (spanId) {
+                        provider.endSpan(spanId, 'error', {
+                            errorMessage: ctx.error?.message ?? 'unknown',
+                        });
+                    }
+                }
+                catch {
+                    // no-op
+                }
+                return ctx;
+            },
+        },
+    ];
+}
+//# sourceMappingURL=telemetry-provider.js.map

package/dist/esm/lib/telemetry-provider.js.map

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

package/dist/esm/lib/timeline-scrubber.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * TimelineScrubber — Step through orchestrator history at any sequence point.
+ *
+ * Wraps an OrchestratorEventBus and reconstructs state at any point by
+ * loading the nearest snapshot and replaying events forward.  Dashboard
+ * clients can "drag a slider" to any sequence and get the state at that
+ * moment.
+ *
+ * @module TimelineScrubber
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimelineScrubber = void 0;
+// ============================================================================
+// STATE REDUCER
+// ============================================================================
+/** Apply a single bus event to mutable state. */
+function applyEvent(state, event) {
+    switch (event.source) {
+        case 'blackboard': {
+            if (event.type === 'write' || event.type === 'commit') {
+                const key = event.data.key;
+                if (key)
+                    state.blackboard[key] = event.data.value;
+            }
+            else if (event.type === 'delete') {
+                const key = event.data.key;
+                if (key)
+                    delete state.blackboard[key];
+            }
+            break;
+        }
+        case 'orchestrator': {
+            if (event.type === 'delegation_start' && event.agentId) {
+                const target = event.data.targetAgent;
+                if (target && !state.agents[target]) {
+                    state.agents[target] = { status: 'running', tokensUsed: 0 };
+                }
+                else if (target && state.agents[target]) {
+                    state.agents[target].status = 'running';
+                }
+            }
+            if (event.type === 'delegation_failed' && event.data.targetAgent) {
+                const target = event.data.targetAgent;
+                if (state.agents[target])
+                    state.agents[target].status = 'failed';
+            }
+            break;
+        }
+        case 'adapter': {
+            if (event.type === 'agent:execution:complete' && event.agentId) {
+                if (state.agents[event.agentId]) {
+                    state.agents[event.agentId].status = 'completed';
+                }
+            }
+            break;
+        }
+        case 'quality': {
+            if (event.type === 'reject' && event.agentId) {
+                if (state.agents[event.agentId]) {
+                    state.agents[event.agentId].status = 'failed';
+                }
+            }
+            break;
+        }
+        // Other sources: no state mutation needed for reconstruction
+        default:
+            break;
+    }
+}
+// ============================================================================
+// SCRUBBER
+// ============================================================================
+/**
+ * Reconstructs state at any point in the event stream.
+ *
+ * @example
+ * ```ts
+ * const scrubber = new TimelineScrubber(orchestrator.eventBus);
+ * const frame = scrubber.frameAt(42);
+ * // frame.blackboard — state of blackboard at seq 42
+ * // frame.agents — agent statuses at seq 42
+ *
+ * const range = scrubber.getRange();
+ * // range.minSeq, range.maxSeq — slider bounds
+ * ```
+ */
+class TimelineScrubber {
+    bus;
+    constructor(bus) {
+        this.bus = bus;
+    }
+    /**
+     * Reconstruct state at a specific sequence number.
+     */
+    frameAt(seq) {
+        // Find nearest snapshot at or before seq
+        const snapshot = this.bus.snapshotAt(seq);
+        // Determine replay start
+        const fromSeq = snapshot ? snapshot.atSeq + 1 : 0;
+        // Get events from snapshot to target seq
+        const replay = this.bus.replay({ fromSeq, toSeq: seq });
+        const appliedEvents = replay.events;
+        // Initialize state from snapshot or empty
+        const blackboard = snapshot
+            ? { ...snapshot.blackboard }
+            : {};
+        const agents = snapshot
+            ? Object.fromEntries(Object.entries(snapshot.agents).map(([k, v]) => [k, { ...v }]))
+            : {};
+        // Apply events forward
+        for (const event of appliedEvents) {
+            applyEvent({ blackboard, agents }, event);
+        }
+        // Find the event timestamp at this seq
+        const targetEvent = this.bus.getEvent(seq);
+        const timestamp = targetEvent?.timestamp ?? snapshot?.timestamp ?? new Date().toISOString();
+        return {
+            seq,
+            timestamp,
+            baseSnapshotSeq: snapshot?.atSeq ?? null,
+            appliedEvents,
+            blackboard,
+            agents,
+            budget: snapshot?.budget,
+        };
+    }
+    /**
+     * Get a range of frames (e.g. for scrubbing a window).
+     * Returns frames at evenly-spaced sequence numbers.
+     */
+    frameRange(fromSeq, toSeq, maxFrames = 50) {
+        const range = toSeq - fromSeq;
+        const step = Math.max(1, Math.floor(range / maxFrames));
+        const frames = [];
+        for (let s = fromSeq; s <= toSeq; s += step) {
+            frames.push(this.frameAt(s));
+        }
+        // Always include the last frame
+        if (frames.length === 0 || frames[frames.length - 1].seq !== toSeq) {
+            frames.push(this.frameAt(toSeq));
+        }
+        return frames;
+    }
+    /**
+     * Get the timeline range info (slider bounds).
+     */
+    getRange() {
+        const snapshots = this.bus.getSnapshots();
+        const replay = this.bus.replay();
+        return {
+            minSeq: replay.events.length > 0 ? replay.events[0].seq : 0,
+            maxSeq: this.bus.currentSeq - 1,
+            totalEvents: replay.totalEvents,
+            snapshotCount: snapshots.length,
+            snapshotSeqs: snapshots.map(s => s.atSeq),
+        };
+    }
+    /**
+     * Step forward from a given frame by N events.
+     */
+    stepForward(currentSeq, steps = 1) {
+        return this.frameAt(Math.min(currentSeq + steps, this.bus.currentSeq - 1));
+    }
+    /**
+     * Step backward from a given frame by N events.
+     */
+    stepBackward(currentSeq, steps = 1) {
+        return this.frameAt(Math.max(currentSeq - steps, 0));
+    }
+}
+exports.TimelineScrubber = TimelineScrubber;
+//# sourceMappingURL=timeline-scrubber.js.map