@yuaone/core 0.1.0

package/dist/parallel-executor.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @module parallel-executor
+ * @description 병렬 실행 관리자 — 다수의 서브 에이전트를 동시성 제한 내에서 병렬 실행.
+ *
+ * DAGOrchestrator가 의존성 순서를 결정하고, ParallelExecutor는
+ * 독립적인 태스크 배치를 maxParallel 제한 내에서 동시에 실행한다.
+ *
+ * 각 태스크는 격리된 SubAgent로 실행되며,
+ * 하나가 실패해도 나머지는 계속 진행한다 (fault isolation).
+ */
+import { EventEmitter } from "node:events";
+import type { BYOKConfig, ToolExecutor } from "./types.js";
+import { type SubAgentResult, type DAGContextLike } from "./sub-agent.js";
+/** Configuration for the ParallelExecutor */
+export interface ParallelExecutorConfig {
+    /** Maximum number of sub-agents running concurrently */
+    maxParallel: number;
+    /** Default BYOK configuration for LLM calls (used when no per-task override) */
+    byokConfig: BYOKConfig;
+    /** Absolute path to the project root */
+    projectPath: string;
+    /** Factory to create a ToolExecutor scoped to a working directory */
+    createToolExecutor: (workDir: string, enabledTools?: string[]) => ToolExecutor;
+    /**
+     * Optional callback to resolve a per-task BYOK configuration.
+     * Called for each task before execution. If it returns a config, that config
+     * is used instead of the default `byokConfig`. If not provided or returns
+     * undefined, the task's `byokOverride` or the default config is used.
+     *
+     * Resolution order: task.byokOverride > modelResolver(task) > byokConfig
+     */
+    modelResolver?: (task: PlannedTaskLike) => BYOKConfig | undefined;
+}
+/** Task input compatible with PlannedTask from types.ts */
+export interface PlannedTaskLike {
+    /** Unique task identifier */
+    id: string;
+    /** Task goal description */
+    goal: string;
+    /** Files this task is allowed to write */
+    targetFiles: string[];
+    /** Files this task may read (read-only) */
+    readFiles: string[];
+    /** Tool names to enable */
+    tools: string[];
+    /** Estimated number of iterations */
+    estimatedIterations: number;
+    /** Priority (0–10, higher = more urgent) */
+    priority: number;
+    /** Optional per-task BYOK config override */
+    byokOverride?: BYOKConfig;
+}
+export interface ParallelExecutorEvents {
+    "parallel:start": (taskIds: string[], maxParallel: number) => void;
+    "parallel:task_start": (taskId: string) => void;
+    "parallel:task_complete": (result: SubAgentResult) => void;
+    "parallel:all_complete": (results: SubAgentResult[]) => void;
+}
+/**
+ * ParallelExecutor — coordinates multiple sub-agents with concurrency control.
+ *
+ * Uses a semaphore pattern: maintains a count of running tasks and spawns
+ * new ones as slots become available. Tasks within a batch are independent
+ * (dependency ordering is handled by the DAGOrchestrator layer above).
+ *
+ * @example
+ * ```typescript
+ * const executor = new ParallelExecutor({
+ *   maxParallel: 3,
+ *   byokConfig: { provider: "anthropic", apiKey: "..." },
+ *   projectPath: "/project",
+ *   createToolExecutor: (dir, tools) => createExecutor(dir, tools),
+ * });
+ *
+ * executor.on("parallel:task_complete", (result) => {
+ *   console.log(`${result.taskId}: ${result.success ? "OK" : "FAIL"}`);
+ * });
+ *
+ * const results = await executor.executeBatch(tasks, dagContext);
+ * ```
+ */
+export declare class ParallelExecutor extends EventEmitter {
+    private readonly config;
+    private readonly runningAgents;
+    private abortedAll;
+    constructor(config: ParallelExecutorConfig);
+    /**
+     * Execute multiple tasks in parallel, respecting the max concurrency limit.
+     *
+     * Tasks are independent — no dependency ordering is performed here
+     * (that is the DAGOrchestrator's responsibility). Tasks are sorted by
+     * priority (highest first) and launched as concurrency slots open.
+     *
+     * If one task fails, others continue to completion (fault isolation).
+     *
+     * @param tasks Array of planned tasks to execute
+     * @param dagContext DAG-level context passed to each sub-agent
+     * @returns Array of results, one per task, in completion order
+     */
+    executeBatch(tasks: PlannedTaskLike[], dagContext: DAGContextLike): Promise<SubAgentResult[]>;
+    /**
+     * Get the task IDs of currently running sub-agents.
+     * @returns Array of task ID strings
+     */
+    getRunningTasks(): string[];
+    /**
+     * Abort all running sub-agents.
+     * Each sub-agent will finish its current iteration and then stop.
+     */
+    abortAll(): void;
+    /**
+     * Run a single task as a SubAgent and return the result.
+     */
+    /**
+     * Resolve the BYOK configuration for a specific task.
+     *
+     * Resolution order (first non-undefined wins):
+     * 1. task.byokOverride — explicit per-task override
+     * 2. config.modelResolver(task) — dynamic callback resolution
+     * 3. config.byokConfig — batch-level default
+     */
+    private resolveByokConfig;
+    private runTask;
+}
+//# sourceMappingURL=parallel-executor.d.ts.map

package/dist/parallel-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-executor.d.ts","sourceRoot":"","sources":["../src/parallel-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EAEb,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAIxB,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,UAAU,EAAE,UAAU,CAAC;IACvB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,kBAAkB,EAAE,CAClB,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EAAE,KACpB,YAAY,CAAC;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,UAAU,GAAG,SAAS,CAAC;CACnE;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qCAAqC;IACrC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B;AAID,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,qBAAqB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,wBAAwB,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAC3D,uBAAuB,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,IAAI,CAAC;CAC9D;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,sBAAsB;IAK1C;;;;;;;;;;;;OAYG;IACG,YAAY,CAChB,KAAK,EAAE,eAAe,EAAE,EACxB,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,cAAc,EAAE,CAAC;IAsF5B;;;OAGG;IACH,eAAe,IAAI,MAAM,EAAE;IAI3B;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAShB;;OAEG;IACH;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;YAMX,OAAO;CAiDtB"}

package/dist/parallel-executor.js

@@ -0,0 +1,201 @@
+/**
+ * @module parallel-executor
+ * @description 병렬 실행 관리자 — 다수의 서브 에이전트를 동시성 제한 내에서 병렬 실행.
+ *
+ * DAGOrchestrator가 의존성 순서를 결정하고, ParallelExecutor는
+ * 독립적인 태스크 배치를 maxParallel 제한 내에서 동시에 실행한다.
+ *
+ * 각 태스크는 격리된 SubAgent로 실행되며,
+ * 하나가 실패해도 나머지는 계속 진행한다 (fault isolation).
+ */
+import { EventEmitter } from "node:events";
+import { SubAgent, } from "./sub-agent.js";
+// ─── ParallelExecutor Class ───
+/**
+ * ParallelExecutor — coordinates multiple sub-agents with concurrency control.
+ *
+ * Uses a semaphore pattern: maintains a count of running tasks and spawns
+ * new ones as slots become available. Tasks within a batch are independent
+ * (dependency ordering is handled by the DAGOrchestrator layer above).
+ *
+ * @example
+ * ```typescript
+ * const executor = new ParallelExecutor({
+ *   maxParallel: 3,
+ *   byokConfig: { provider: "anthropic", apiKey: "..." },
+ *   projectPath: "/project",
+ *   createToolExecutor: (dir, tools) => createExecutor(dir, tools),
+ * });
+ *
+ * executor.on("parallel:task_complete", (result) => {
+ *   console.log(`${result.taskId}: ${result.success ? "OK" : "FAIL"}`);
+ * });
+ *
+ * const results = await executor.executeBatch(tasks, dagContext);
+ * ```
+ */
+export class ParallelExecutor extends EventEmitter {
+    config;
+    runningAgents = new Map();
+    abortedAll = false;
+    constructor(config) {
+        super();
+        this.config = config;
+    }
+    /**
+     * Execute multiple tasks in parallel, respecting the max concurrency limit.
+     *
+     * Tasks are independent — no dependency ordering is performed here
+     * (that is the DAGOrchestrator's responsibility). Tasks are sorted by
+     * priority (highest first) and launched as concurrency slots open.
+     *
+     * If one task fails, others continue to completion (fault isolation).
+     *
+     * @param tasks Array of planned tasks to execute
+     * @param dagContext DAG-level context passed to each sub-agent
+     * @returns Array of results, one per task, in completion order
+     */
+    async executeBatch(tasks, dagContext) {
+        if (tasks.length === 0)
+            return [];
+        this.abortedAll = false;
+        const taskIds = tasks.map((t) => t.id);
+        this.emit("parallel:start", taskIds, this.config.maxParallel);
+        // Sort by priority descending (higher priority first)
+        const sortedTasks = [...tasks].sort((a, b) => b.priority - a.priority);
+        const results = [];
+        const pending = [...sortedTasks];
+        // Use a promise-based semaphore pattern
+        const inFlight = new Set();
+        while (pending.length > 0 || inFlight.size > 0) {
+            if (this.abortedAll) {
+                // Drain pending without executing
+                for (const task of pending) {
+                    results.push({
+                        taskId: task.id,
+                        success: false,
+                        summary: "Aborted: parallel executor was cancelled",
+                        changedFiles: [],
+                        tokensUsed: { input: 0, output: 0 },
+                        iterations: 0,
+                        phase: "cleanup",
+                        error: "Aborted by orchestrator",
+                    });
+                }
+                pending.length = 0;
+                // Wait for in-flight to finish (they were already aborted)
+                if (inFlight.size > 0) {
+                    const remaining = await Promise.allSettled([...inFlight]);
+                    for (const settled of remaining) {
+                        if (settled.status === "fulfilled") {
+                            results.push(settled.value);
+                        }
+                    }
+                    inFlight.clear();
+                }
+                break;
+            }
+            // Fill up to maxParallel slots
+            while (pending.length > 0 &&
+                inFlight.size < this.config.maxParallel &&
+                !this.abortedAll) {
+                const task = pending.shift();
+                const promise = this.runTask(task, dagContext);
+                inFlight.add(promise);
+                // When this task completes, remove from in-flight and collect result
+                promise.then((result) => {
+                    inFlight.delete(promise);
+                    results.push(result);
+                    this.runningAgents.delete(task.id);
+                    this.emit("parallel:task_complete", result);
+                }).catch((err) => {
+                    inFlight.delete(promise);
+                    this.runningAgents.delete(task.id);
+                    this.emit("parallel:task_error", { taskId: task.id, error: err });
+                });
+            }
+            // Wait for at least one task to complete before continuing
+            if (inFlight.size > 0) {
+                await Promise.race([...inFlight]);
+            }
+        }
+        this.emit("parallel:all_complete", results);
+        return results;
+    }
+    /**
+     * Get the task IDs of currently running sub-agents.
+     * @returns Array of task ID strings
+     */
+    getRunningTasks() {
+        return [...this.runningAgents.keys()];
+    }
+    /**
+     * Abort all running sub-agents.
+     * Each sub-agent will finish its current iteration and then stop.
+     */
+    abortAll() {
+        this.abortedAll = true;
+        for (const [, agent] of this.runningAgents) {
+            agent.abort();
+        }
+    }
+    // ─── Private ───
+    /**
+     * Run a single task as a SubAgent and return the result.
+     */
+    /**
+     * Resolve the BYOK configuration for a specific task.
+     *
+     * Resolution order (first non-undefined wins):
+     * 1. task.byokOverride — explicit per-task override
+     * 2. config.modelResolver(task) — dynamic callback resolution
+     * 3. config.byokConfig — batch-level default
+     */
+    resolveByokConfig(task) {
+        return task.byokOverride
+            ?? this.config.modelResolver?.(task)
+            ?? this.config.byokConfig;
+    }
+    async runTask(task, dagContext) {
+        const taskByokConfig = this.resolveByokConfig(task);
+        const subAgentConfig = {
+            taskId: task.id,
+            goal: task.goal,
+            targetFiles: task.targetFiles,
+            readFiles: task.readFiles,
+            maxIterations: task.estimatedIterations,
+            projectPath: this.config.projectPath,
+            byokConfig: taskByokConfig,
+            tools: task.tools,
+            createToolExecutor: this.config.createToolExecutor,
+            priority: task.priority,
+        };
+        const agent = new SubAgent(subAgentConfig);
+        this.runningAgents.set(task.id, agent);
+        // Forward sub-agent events
+        agent.on("subagent:phase", (taskId, phase) => {
+            this.emit("subagent:phase", taskId, phase);
+        });
+        agent.on("subagent:iteration", (taskId, index, tokens) => {
+            this.emit("subagent:iteration", taskId, index, tokens);
+        });
+        this.emit("parallel:task_start", task.id);
+        try {
+            return await agent.run(dagContext);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                taskId: task.id,
+                success: false,
+                summary: `Unexpected error: ${errorMessage}`,
+                changedFiles: [],
+                tokensUsed: { input: 0, output: 0 },
+                iterations: 0,
+                phase: "cleanup",
+                error: errorMessage,
+            };
+        }
+    }
+}
+//# sourceMappingURL=parallel-executor.js.map

package/dist/parallel-executor.js.map

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

package/dist/perf-optimizer.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @module perf-optimizer
+ * @description YUAN Performance Optimizer — monitors and optimizes agent execution performance.
+ *
+ * Provides:
+ * - Execution timing per phase and tool call
+ * - Token budget tracking and waste detection
+ * - Parallelization hint generation from task dependency graphs
+ * - Content-addressable caching for tool calls and LLM responses
+ * - Human-readable performance reports with efficiency scoring
+ *
+ * Only depends on Node builtins (crypto for cache keys).
+ */
+/** A single performance metric sample */
+export interface PerfMetric {
+    name: string;
+    category: "timing" | "tokens" | "cache" | "parallel";
+    value: number;
+    unit: string;
+    timestamp: number;
+}
+/** Aggregated metrics for a single execution phase */
+export interface PhaseMetrics {
+    phase: string;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    tokensUsed: {
+        input: number;
+        output: number;
+    };
+    toolCalls: number;
+    cacheHits: number;
+    cacheMisses: number;
+}
+/** Identified performance bottleneck with actionable suggestion */
+export interface BottleneckInfo {
+    phase: string;
+    issue: string;
+    impact: "high" | "medium" | "low";
+    suggestion: string;
+    estimatedSavingMs?: number;
+}
+/** A single entry in the tool/response cache */
+export interface CacheEntry {
+    key: string;
+    value: unknown;
+    hits: number;
+    createdAt: number;
+    lastAccessedAt: number;
+    sizeBytes: number;
+}
+/** Suggestion for tasks that could benefit from parallel execution */
+export interface ParallelHint {
+    taskIds: string[];
+    currentSequentialMs: number;
+    estimatedParallelMs: number;
+    speedupFactor: number;
+}
+/** Complete performance report for a session */
+export interface PerfReport {
+    sessionId: string;
+    totalDurationMs: number;
+    phases: PhaseMetrics[];
+    bottlenecks: BottleneckInfo[];
+    cacheStats: {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        savedMs: number;
+    };
+    parallelHints: ParallelHint[];
+    tokenSummary: {
+        total: number;
+        byPhase: Record<string, number>;
+        wasteEstimate: number;
+    };
+    efficiencyScore: number;
+    suggestions: string[];
+}
+/** Configuration for PerfOptimizer */
+export interface PerfOptimizerConfig {
+    /** Enable tool call caching (default: true) */
+    enableCaching?: boolean;
+    /** Maximum number of cache entries (default: 500) */
+    maxCacheSize?: number;
+    /** Maximum cache memory in bytes (default: 50MB) */
+    maxCacheMemory?: number;
+    /** Track parallelization opportunities (default: true) */
+    trackParallelHints?: boolean;
+    /** Phase is a bottleneck if it takes > X% of total time (default: 40) */
+    bottleneckThresholdPercent?: number;
+}
+/**
+ * Monitors and optimizes agent execution performance.
+ *
+ * Tracks phase timing, token usage, tool call durations, and caching.
+ * Generates actionable performance reports with bottleneck identification,
+ * parallelization hints, and an overall efficiency score.
+ */
+export declare class PerfOptimizer {
+    private readonly config;
+    private activePhases;
+    private completedPhases;
+    private toolCallRecords;
+    private metrics;
+    private cache;
+    private totalCacheMemory;
+    private globalCacheHits;
+    private globalCacheMisses;
+    private previousRunDurations;
+    constructor(config?: PerfOptimizerConfig);
+    /**
+     * Mark the start of an execution phase.
+     * @param phase - Phase name (e.g. "analyze", "plan", "implement", "verify", "fix")
+     */
+    startPhase(phase: string): void;
+    /**
+     * Mark the end of an execution phase.
+     * @param phase - Phase name that was previously started
+     * @param tokens - Optional token usage for this phase
+     */
+    endPhase(phase: string, tokens?: {
+        input: number;
+        output: number;
+    }): void;
+    /**
+     * Record a tool call with its duration.
+     * Automatically tracks cache hits/misses for the active phase.
+     * @param tool - Tool name
+     * @param input - Tool input (used for cache key generation)
+     * @param durationMs - How long the tool call took
+     */
+    recordToolCall(tool: string, input: unknown, durationMs: number): void;
+    /**
+     * Record token usage for a specific phase.
+     * @param phase - Phase name
+     * @param input - Input tokens consumed
+     * @param output - Output tokens generated
+     */
+    recordTokenUsage(phase: string, input: number, output: number): void;
+    /**
+     * Retrieve a cached tool call result.
+     * @param tool - Tool name
+     * @param input - Tool input
+     * @returns Cached result or undefined if not found
+     */
+    getCached(tool: string, input: unknown): unknown | undefined;
+    /**
+     * Store a tool call result in the cache.
+     * Automatically evicts LRU entries when limits are exceeded.
+     * @param tool - Tool name
+     * @param input - Tool input
+     * @param result - Result to cache
+     */
+    setCached(tool: string, input: unknown, result: unknown): void;
+    /**
+     * Clear all cached entries.
+     */
+    clearCache(): void;
+    /**
+     * Identify execution bottlenecks based on phase timing and token usage.
+     * @returns Array of bottleneck descriptions with suggestions
+     */
+    getBottlenecks(): BottleneckInfo[];
+    /**
+     * Analyze a task dependency graph and identify parallelization opportunities.
+     * @param taskDeps - Map of taskId → array of dependency taskIds
+     * @returns Array of parallelization hints with estimated speedup
+     */
+    getParallelHints(taskDeps: Map<string, string[]>): ParallelHint[];
+    /**
+     * Calculate an overall efficiency score (0-100) based on multiple factors.
+     * @returns Efficiency score where 100 is optimal
+     */
+    getEfficiencyScore(): number;
+    /**
+     * Generate a complete performance report for the session.
+     * @param sessionId - Session identifier
+     * @returns Structured performance report
+     */
+    generateReport(sessionId: string): PerfReport;
+    /**
+     * Format a performance report as a human-readable string.
+     * @param report - Report to format
+     * @returns Multi-line formatted string
+     */
+    formatReport(report: PerfReport): string;
+    /**
+     * Store current run duration for future historical comparison, then reset all state.
+     */
+    reset(): void;
+    /** Add a metric, bounded by MAX_METRICS */
+    private addMetric;
+    /** Compute total duration from completed phases */
+    private getTotalDuration;
+    /** Generate a content-addressable hash for tool+input */
+    private hashInput;
+    /** Evict LRU cache entries until there's room */
+    private evictIfNeeded;
+    /** Remove the least recently used cache entry */
+    private evictLRU;
+    /** Count tool calls with duplicate inputs */
+    private countDuplicateToolCalls;
+    /** Estimate wasted tokens from redundant tool calls */
+    private estimateTokenWaste;
+    /** Generate actionable suggestions from bottleneck analysis */
+    private generateSuggestions;
+    /** Format milliseconds as human-readable string */
+    private formatMs;
+}
+//# sourceMappingURL=perf-optimizer.d.ts.map

package/dist/perf-optimizer.d.ts.map

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