confused-ai-core 0.1.0

package/src/observability/tracer.ts

@@ -0,0 +1,105 @@
+/**
+ * In-Memory Tracer Implementation
+ *
+ * Simple in-memory tracing for development and debugging
+ */
+
+import { Tracer, TraceSpan, SpanStatus, SpanEvent } from './types.js';
+import type { EntityId } from '../core/types.js';
+
+/**
+ * In-memory tracer implementation
+ */
+export class InMemoryTracer implements Tracer {
+    private spans: Map<EntityId, TraceSpan> = new Map();
+    private currentSpanId?: EntityId;
+
+    startSpan(name: string, parentId?: EntityId): TraceSpan {
+        const id = this.generateId();
+        const traceId = parentId
+            ? this.spans.get(parentId)?.traceId ?? this.generateTraceId()
+            : this.generateTraceId();
+
+        const span: TraceSpan = {
+            id,
+            traceId,
+            parentId,
+            name,
+            startTime: new Date(),
+            status: SpanStatus.UNSET,
+            attributes: {},
+            events: [],
+        };
+
+        this.spans.set(id, span);
+        this.currentSpanId = id;
+
+        return span;
+    }
+
+    endSpan(spanId: EntityId, status: SpanStatus = SpanStatus.OK): void {
+        const span = this.spans.get(spanId);
+        if (span) {
+            Object.assign(span, {
+                endTime: new Date(),
+                status,
+            });
+        }
+
+        if (this.currentSpanId === spanId) {
+            this.currentSpanId = undefined;
+        }
+    }
+
+    addEvent(spanId: EntityId, event: Omit<SpanEvent, 'timestamp'>): void {
+        const span = this.spans.get(spanId);
+        if (span) {
+            span.events.push({
+                ...event,
+                timestamp: new Date(),
+            });
+        }
+    }
+
+    setAttributes(spanId: EntityId, attributes: Record<string, unknown>): void {
+        const span = this.spans.get(spanId);
+        if (span) {
+            Object.assign(span.attributes, attributes);
+        }
+    }
+
+    getSpan(spanId: EntityId): TraceSpan | undefined {
+        return this.spans.get(spanId);
+    }
+
+    getCurrentSpan(): TraceSpan | undefined {
+        return this.currentSpanId ? this.spans.get(this.currentSpanId) : undefined;
+    }
+
+    getTrace(traceId: string): TraceSpan[] {
+        return Array.from(this.spans.values()).filter(span => span.traceId === traceId);
+    }
+
+    /**
+     * Get all spans
+     */
+    getAllSpans(): TraceSpan[] {
+        return Array.from(this.spans.values());
+    }
+
+    /**
+     * Clear all spans
+     */
+    clear(): void {
+        this.spans.clear();
+        this.currentSpanId = undefined;
+    }
+
+    private generateId(): EntityId {
+        return `span-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+
+    private generateTraceId(): string {
+        return `trace-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+}

package/src/observability/types.ts

@@ -0,0 +1,341 @@
+/**
+ * Observability and telemetry types and interfaces
+ */
+
+import type { EntityId } from '../core/types.js';
+import type { AgentState } from '../core/types.js';
+import type { TaskStatus } from '../planner/types.js';
+
+/**
+ * Log levels
+ */
+export enum LogLevel {
+    DEBUG = 'debug',
+    INFO = 'info',
+    WARN = 'warn',
+    ERROR = 'error',
+    FATAL = 'fatal',
+}
+
+/**
+ * Log entry
+ */
+export interface LogEntry {
+    readonly id: EntityId;
+    readonly timestamp: Date;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly source: string;
+    readonly context: LogContext;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Log context
+ */
+export interface LogContext {
+    readonly agentId?: EntityId;
+    readonly taskId?: EntityId;
+    readonly planId?: EntityId;
+    readonly executionId?: EntityId;
+    readonly sessionId?: string;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly parentSpanId?: string;
+}
+
+/**
+ * Logger interface
+ */
+export interface Logger {
+    /**
+     * Log a debug message
+     */
+    debug(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void;
+
+    /**
+     * Log an info message
+     */
+    info(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void;
+
+    /**
+     * Log a warning message
+     */
+    warn(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void;
+
+    /**
+     * Log an error message
+     */
+    error(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void;
+
+    /**
+     * Log a fatal message
+     */
+    fatal(message: string, context?: Partial<LogContext>, metadata?: Record<string, unknown>): void;
+
+    /**
+     * Create a child logger with additional context
+     */
+    child(additionalContext: Partial<LogContext>): Logger;
+}
+
+/**
+ * Log transport for outputting logs
+ */
+export interface LogTransport {
+    /**
+     * Write a log entry
+     */
+    write(entry: LogEntry): Promise<void>;
+
+    /**
+     * Flush any buffered logs
+     */
+    flush(): Promise<void>;
+}
+
+/**
+ * Trace span representing an operation
+ */
+export interface TraceSpan {
+    readonly id: EntityId;
+    readonly traceId: string;
+    readonly parentId?: EntityId;
+    readonly name: string;
+    readonly startTime: Date;
+    readonly endTime?: Date;
+    readonly status: SpanStatus;
+    readonly attributes: Record<string, unknown>;
+    readonly events: SpanEvent[];
+}
+
+/**
+ * Span status
+ */
+export enum SpanStatus {
+    OK = 'ok',
+    ERROR = 'error',
+    UNSET = 'unset',
+}
+
+/**
+ * Span event
+ */
+export interface SpanEvent {
+    readonly timestamp: Date;
+    readonly name: string;
+    readonly attributes?: Record<string, unknown>;
+}
+
+/**
+ * Tracer interface for distributed tracing
+ */
+export interface Tracer {
+    /**
+     * Start a new span
+     */
+    startSpan(name: string, parentId?: EntityId): TraceSpan;
+
+    /**
+     * End a span
+     */
+    endSpan(spanId: EntityId, status?: SpanStatus): void;
+
+    /**
+     * Add an event to a span
+     */
+    addEvent(spanId: EntityId, event: Omit<SpanEvent, 'timestamp'>): void;
+
+    /**
+     * Set span attributes
+     */
+    setAttributes(spanId: EntityId, attributes: Record<string, unknown>): void;
+
+    /**
+     * Get a span by ID
+     */
+    getSpan(spanId: EntityId): TraceSpan | undefined;
+
+    /**
+     * Get the current active span
+     */
+    getCurrentSpan(): TraceSpan | undefined;
+
+    /**
+     * Get all spans for a trace
+     */
+    getTrace(traceId: string): TraceSpan[];
+}
+
+/**
+ * Metric types
+ */
+export enum MetricType {
+    COUNTER = 'counter',
+    GAUGE = 'gauge',
+    HISTOGRAM = 'histogram',
+    SUMMARY = 'summary',
+}
+
+/**
+ * Metric value
+ */
+export interface MetricValue {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly value: number;
+    readonly labels: Record<string, string>;
+    readonly timestamp: Date;
+}
+
+/**
+ * Metrics collector
+ */
+export interface MetricsCollector {
+    /**
+     * Record a counter metric
+     */
+    counter(name: string, value?: number, labels?: Record<string, string>): void;
+
+    /**
+     * Record a gauge metric
+     */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+
+    /**
+     * Record a histogram metric
+     */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+
+    /**
+     * Get all recorded metrics
+     */
+    getMetrics(): MetricValue[];
+
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+
+/**
+ * Agent event for telemetry
+ */
+export interface AgentEvent {
+    readonly timestamp: Date;
+    readonly agentId: EntityId;
+    readonly eventType: AgentEventType;
+    readonly previousState?: AgentState;
+    readonly currentState?: AgentState;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Agent event types
+ */
+export enum AgentEventType {
+    CREATED = 'created',
+    STARTED = 'started',
+    STATE_CHANGED = 'state_changed',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    DESTROYED = 'destroyed',
+}
+
+/**
+ * Task event for telemetry
+ */
+export interface TaskEvent {
+    readonly timestamp: Date;
+    readonly taskId: EntityId;
+    readonly agentId: EntityId;
+    readonly eventType: TaskEventType;
+    readonly previousStatus?: TaskStatus;
+    readonly currentStatus?: TaskStatus;
+    readonly executionTimeMs?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Task event types
+ */
+export enum TaskEventType {
+    CREATED = 'created',
+    STARTED = 'started',
+    STATUS_CHANGED = 'status_changed',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    RETRYING = 'retrying',
+    CANCELLED = 'cancelled',
+}
+
+/**
+ * Telemetry collector interface
+ */
+export interface TelemetryCollector {
+    /**
+     * Record an agent event
+     */
+    recordAgentEvent(event: Omit<AgentEvent, 'timestamp'>): void;
+
+    /**
+     * Record a task event
+     */
+    recordTaskEvent(event: Omit<TaskEvent, 'timestamp'>): void;
+
+    /**
+     * Get agent events
+     */
+    getAgentEvents(agentId?: EntityId): AgentEvent[];
+
+    /**
+     * Get task events
+     */
+    getTaskEvents(taskId?: EntityId): TaskEvent[];
+
+    /**
+     * Get agent statistics
+     */
+    getAgentStats(agentId: EntityId): AgentStats;
+
+    /**
+     * Export telemetry data
+     */
+    export(format: ExportFormat): string;
+}
+
+/**
+ * Agent statistics
+ */
+export interface AgentStats {
+    readonly agentId: EntityId;
+    readonly totalExecutions: number;
+    readonly successfulExecutions: number;
+    readonly failedExecutions: number;
+    readonly averageExecutionTimeMs: number;
+    readonly totalTokensUsed: number;
+    readonly totalCost: number;
+    readonly lastExecutionAt?: Date;
+}
+
+/**
+ * Export formats
+ */
+export enum ExportFormat {
+    JSON = 'json',
+    CSV = 'csv',
+    OTLP = 'otlp',
+}
+
+/**
+ * Observability configuration
+ */
+export interface ObservabilityConfig {
+    readonly logLevel: LogLevel;
+    readonly enableTracing: boolean;
+    readonly enableMetrics: boolean;
+    readonly enableTelemetry: boolean;
+    readonly samplingRate: number;
+    readonly transports: LogTransport[];
+    readonly exportIntervalMs?: number;
+}

package/src/orchestration/agent-adapter.ts

@@ -0,0 +1,33 @@
+/**
+ * Agent adapter for orchestration
+ *
+ * Wraps a run function as a core Agent so it can be registered with the Orchestrator.
+ */
+
+import { Agent, AgentInput, AgentOutput, AgentContext } from '../core/types.js';
+
+export interface RunnableAgentConfig {
+    readonly name: string;
+    readonly description?: string;
+    readonly run: (input: AgentInput, ctx: AgentContext) => Promise<AgentOutput>;
+}
+
+/**
+ * Creates a core Agent from a run function for use with the Orchestrator.
+ */
+export function createRunnableAgent(config: RunnableAgentConfig): Agent {
+    return new RunnableAgentAdapter(config);
+}
+
+class RunnableAgentAdapter extends Agent {
+    constructor(private readonly runConfig: RunnableAgentConfig) {
+        super({
+            name: runConfig.name,
+            description: runConfig.description,
+        });
+    }
+
+    async run(input: AgentInput, ctx: AgentContext): Promise<AgentOutput> {
+        return this.runConfig.run(input, ctx);
+    }
+}

package/src/orchestration/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Orchestration module exports
+ */
+
+export * from './types.js';
+export { OrchestratorImpl } from './orchestrator.js';
+export { MessageBusImpl } from './message-bus.js';
+export { RoundRobinLoadBalancer } from './load-balancer.js';
+export { createRunnableAgent } from './agent-adapter.js';
+export type { RunnableAgentConfig } from './agent-adapter.js';
+export { createSupervisor, createRole } from './supervisor.js';
+export type { SupervisorConfig } from './supervisor.js';
+export { createPipeline } from './pipeline.js';
+export type { PipelineConfig } from './pipeline.js';
+export { createToolkit, toolkitsToRegistry } from './toolkit.js';
+export type { Toolkit } from './toolkit.js';
+export type { MCPClient, MCPServerAdapter, MCPToolDescriptor, A2AMessage, A2AClient } from './mcp-types.js';
+
+// Agent Swarm exports (Kimi K2.5 inspired)
+export {
+    SwarmOrchestrator,
+    createSwarm,
+    createSwarmAgent,
+} from './swarm.js';
+export type {
+    SwarmConfig,
+    SwarmResult,
+    SubagentTemplate,
+    Subtask,
+    SubtaskResult,
+    ExecutionStage,
+    CriticalPathMetrics,
+    SubagentInstance,
+} from './swarm.js';

package/src/orchestration/load-balancer.ts

@@ -0,0 +1,151 @@
+/**
+ * Load Balancer Implementation
+ *
+ * Distributes tasks across agents based on various strategies
+ */
+
+import { LoadBalancer, AgentRegistration, DelegationTask } from './types.js';
+import type { EntityId } from '../core/types.js';
+
+/**
+ * Round-robin load balancer
+ */
+export class RoundRobinLoadBalancer implements LoadBalancer {
+    private lastIndex = 0;
+    private agentMetrics: Map<EntityId, { totalTasks: number; failedTasks: number; totalExecutionTime: number }> = new Map();
+
+    selectAgent(candidates: AgentRegistration[], _task: DelegationTask): AgentRegistration | undefined {
+        if (candidates.length === 0) {
+            return undefined;
+        }
+
+        // Filter to agents under their max load
+        const available = candidates.filter(reg =>
+            reg.metadata.currentLoad < reg.metadata.maxConcurrentTasks
+        );
+
+        if (available.length === 0) {
+            // All agents at capacity, pick the one with lowest load
+            return candidates.sort((a, b) => a.metadata.currentLoad - b.metadata.currentLoad)[0];
+        }
+
+        // Round-robin selection
+        const index = this.lastIndex % available.length;
+        this.lastIndex = (this.lastIndex + 1) % available.length;
+
+        return available[index];
+    }
+
+    updateMetrics(agentId: EntityId, executionTimeMs: number, success: boolean): void {
+        const metrics = this.agentMetrics.get(agentId) ?? {
+            totalTasks: 0,
+            failedTasks: 0,
+            totalExecutionTime: 0,
+        };
+
+        metrics.totalTasks++;
+        metrics.totalExecutionTime += executionTimeMs;
+        if (!success) {
+            metrics.failedTasks++;
+        }
+
+        this.agentMetrics.set(agentId, metrics);
+    }
+
+    /**
+     * Get metrics for an agent
+     */
+    getMetrics(agentId: EntityId): { totalTasks: number; failedTasks: number; averageExecutionTime: number } | undefined {
+        const metrics = this.agentMetrics.get(agentId);
+        if (!metrics) return undefined;
+
+        return {
+            totalTasks: metrics.totalTasks,
+            failedTasks: metrics.failedTasks,
+            averageExecutionTime: metrics.totalTasks > 0
+                ? metrics.totalExecutionTime / metrics.totalTasks
+                : 0,
+        };
+    }
+}
+
+/**
+ * Least connections load balancer
+ */
+export class LeastConnectionsLoadBalancer implements LoadBalancer {
+    private agentMetrics: Map<EntityId, { totalTasks: number; failedTasks: number; totalExecutionTime: number }> = new Map();
+
+    selectAgent(candidates: AgentRegistration[], _task: DelegationTask): AgentRegistration | undefined {
+        if (candidates.length === 0) {
+            return undefined;
+        }
+
+        // Sort by current load (ascending)
+        return candidates.sort((a, b) => a.metadata.currentLoad - b.metadata.currentLoad)[0];
+    }
+
+    updateMetrics(agentId: EntityId, executionTimeMs: number, success: boolean): void {
+        const metrics = this.agentMetrics.get(agentId) ?? {
+            totalTasks: 0,
+            failedTasks: 0,
+            totalExecutionTime: 0,
+        };
+
+        metrics.totalTasks++;
+        metrics.totalExecutionTime += executionTimeMs;
+        if (!success) {
+            metrics.failedTasks++;
+        }
+
+        this.agentMetrics.set(agentId, metrics);
+    }
+}
+
+/**
+ * Weighted response time load balancer
+ */
+export class WeightedResponseTimeLoadBalancer implements LoadBalancer {
+    private agentMetrics: Map<EntityId, { totalTasks: number; failedTasks: number; totalExecutionTime: number }> = new Map();
+
+    selectAgent(candidates: AgentRegistration[], _task: DelegationTask): AgentRegistration | undefined {
+        if (candidates.length === 0) {
+            return undefined;
+        }
+
+        // Calculate score based on average response time and current load
+        const scored = candidates.map(reg => {
+            const metrics = this.agentMetrics.get(reg.agent.id);
+            const avgResponseTime = metrics && metrics.totalTasks > 0
+                ? metrics.totalExecutionTime / metrics.totalTasks
+                : 1000; // Default to 1s if no data
+
+            const loadFactor = reg.metadata.currentLoad / reg.metadata.maxConcurrentTasks;
+
+            // Lower score is better
+            const score = avgResponseTime * (1 + loadFactor);
+
+            return { reg, score };
+        });
+
+        // Sort by score (ascending)
+        scored.sort((a, b) => a.score - b.score);
+
+        return scored[0].reg;
+    }
+
+    updateMetrics(agentId: EntityId, executionTimeMs: number, success: boolean): void {
+        const metrics = this.agentMetrics.get(agentId) ?? {
+            totalTasks: 0,
+            failedTasks: 0,
+            totalExecutionTime: 0,
+        };
+
+        metrics.totalTasks++;
+        metrics.totalExecutionTime += executionTimeMs;
+        if (!success) {
+            metrics.failedTasks++;
+        }
+
+        this.agentMetrics.set(agentId, metrics);
+    }
+}