@webpresso/agent-kit 0.21.4 → 0.23.0

package/dist/esm/blueprint/dag/executor.d.ts

@@ -1,140 +0,0 @@
-import type { IClock } from './interfaces.js';
-import type { Task } from './types.js';
-import { TaskGraph } from './task-graph.js';
-/**
- * Task execution result
- */
-export interface TaskResult<T = unknown> {
-    taskId: string;
-    status: 'completed' | 'failed' | 'skipped';
-    output?: T;
-    error?: Error;
-    durationMs: number;
-    startedAt: number;
-    completedAt: number;
-}
-/**
- * Concurrency configuration by task type
- */
-export interface ConcurrencyConfig {
-    /** Global max concurrent tasks across all types */
-    global?: number;
-    /** Default max concurrent tasks per type (when no type-specific limit) */
-    default: number;
-    /** Per-type limits (overrides default) */
-    byType?: Record<string, number>;
-}
-/**
- * Task executor function signature
- * Receives task and returns result (or throws)
- */
-export type TaskExecutorFn<T, R> = (task: Task<T>) => Promise<R>;
-/**
- * Execution progress callback
- */
-export interface ExecutionProgress<T = unknown> {
-    totalTasks: number;
-    completedTasks: number;
-    failedTasks: number;
-    runningTasks: string[];
-    pendingTasks: number;
-    currentWave: number;
-    totalWaves: number;
-    latestResult?: TaskResult<T>;
-}
-export type ProgressCallback<T = unknown> = (progress: ExecutionProgress<T>) => void;
-/**
- * Executor options
- */
-export interface ExecutorOptions<R> {
-    concurrency?: ConcurrencyConfig;
-    onProgress?: ProgressCallback<R>;
-    /** Clock for time operations (injectable for testing) */
-    clock?: IClock;
-    /** Skip tasks whose dependencies failed */
-    skipOnFailedDependency?: boolean;
-    /** Timeout for individual tasks in milliseconds (0 = no timeout) */
-    taskTimeoutMs?: number;
-    /** AbortSignal for cancellation */
-    signal?: AbortSignal;
-}
-/**
- * Parallel DAG executor with concurrency controls.
- *
- * Uses Kahn's algorithm for topological execution order.
- * Supports per-task-type concurrency limits.
- *
- * Runtime-agnostic - works in Node.js, Bun, Deno, Cloudflare Workers.
- */
-export declare class ParallelExecutor<T = unknown, R = unknown> {
-    private graph;
-    private concurrency;
-    private executorFn;
-    private onProgress?;
-    private clock;
-    private skipOnFailedDependency;
-    private taskTimeoutMs;
-    private completed;
-    private failed;
-    private skipped;
-    private running;
-    private results;
-    private signal?;
-    private abortController?;
-    constructor(graph: TaskGraph<T>, executorFn: TaskExecutorFn<T, R>, options?: ExecutorOptions<R>);
-    /**
-     * Execute all tasks in parallel, respecting dependencies and concurrency limits.
-     * Returns results in completion order.
-     * @throws {Error} If graph is invalid or execution is aborted
-     */
-    execute(): Promise<TaskResult<R>[]>;
-    /**
-     * Check if execution has been aborted and throw if so.
-     * Checks both internal controller and external signal.
-     */
-    private throwIfAborted;
-    /**
-     * Get current execution state.
-     */
-    getState(): {
-        completed: string[];
-        failed: string[];
-        skipped: string[];
-        running: string[];
-    };
-    private executeWave;
-    private startPendingTasks;
-    private shouldSkipTask;
-    private skipTask;
-    private canStartTask;
-    private getTaskType;
-    /**
-     * Count running tasks of a specific type.
-     * FIX: Now properly tracks task types.
-     */
-    private countRunningByType;
-    private startTask;
-    /**
-     * Execute task with optional timeout support.
-     * State-of-the-art: proper timeout handling with AbortController pattern.
-     */
-    private executeWithTimeout;
-    private createTimeoutPromise;
-    private emitTaskStart;
-    private waitForAny;
-    private emitProgress;
-}
-/**
- * Create executor from task array with dependencies.
- * Convenience function for common use case.
- */
-export declare function createExecutor<T, R>(tasks: Array<{
-    task: Task<T>;
-    dependsOn?: string[];
-}>, executorFn: TaskExecutorFn<T, R>, options?: ExecutorOptions<R>): ParallelExecutor<T, R>;
-/**
- * Create executor directly from tasks using their dependencies arrays.
- * Most convenient for LLM agents.
- */
-export declare function createExecutorFromTasks<T, R>(tasks: Task<T>[], executorFn: TaskExecutorFn<T, R>, options?: ExecutorOptions<R>): ParallelExecutor<T, R>;
-//# sourceMappingURL=executor.d.ts.map

package/dist/esm/blueprint/dag/executor.js

@@ -1,292 +0,0 @@
-import { realClock } from './interfaces.js';
-import { TaskGraph } from './task-graph.js';
-/**
- * Parallel DAG executor with concurrency controls.
- *
- * Uses Kahn's algorithm for topological execution order.
- * Supports per-task-type concurrency limits.
- *
- * Runtime-agnostic - works in Node.js, Bun, Deno, Cloudflare Workers.
- */
-export class ParallelExecutor {
-    graph;
-    concurrency;
-    executorFn;
-    onProgress;
-    clock;
-    skipOnFailedDependency;
-    taskTimeoutMs;
-    // Execution state
-    completed = new Set();
-    failed = new Set();
-    skipped = new Set();
-    running = new Map();
-    results = [];
-    signal;
-    abortController;
-    constructor(graph, executorFn, options = {}) {
-        this.graph = graph;
-        this.executorFn = executorFn;
-        this.concurrency = options.concurrency ?? { default: 6 };
-        this.onProgress = options.onProgress;
-        this.clock = options.clock ?? realClock;
-        this.skipOnFailedDependency = options.skipOnFailedDependency ?? true;
-        this.taskTimeoutMs = options.taskTimeoutMs ?? 0;
-        this.signal = options.signal;
-        // Create internal abort controller for cleanup
-        this.abortController = new AbortController();
-        // Link external signal if provided
-        if (options.signal) {
-            options.signal.addEventListener('abort', () => {
-                this.abortController?.abort(options.signal?.reason);
-            });
-        }
-    }
-    /**
-     * Execute all tasks in parallel, respecting dependencies and concurrency limits.
-     * Returns results in completion order.
-     * @throws {Error} If graph is invalid or execution is aborted
-     */
-    async execute() {
-        // Check for abort before starting
-        this.throwIfAborted();
-        // Validate graph first
-        const validation = this.graph.validate();
-        if (!validation.valid) {
-            throw new Error(`Cannot execute invalid graph: ${validation.errors.join('; ')}`);
-        }
-        const waves = this.graph.getWaves();
-        const totalTasks = waves.flat().length;
-        for (let waveIdx = 0; waveIdx < waves.length; waveIdx++) {
-            this.throwIfAborted();
-            const wave = waves[waveIdx];
-            if (!wave)
-                continue;
-            await this.executeWave(wave, waveIdx + 1, waves.length, totalTasks);
-        }
-        return this.results;
-    }
-    /**
-     * Check if execution has been aborted and throw if so.
-     * Checks both internal controller and external signal.
-     */
-    throwIfAborted() {
-        // Check external signal first (passed in via options)
-        if (this.signal?.aborted) {
-            throw new Error(`Execution aborted: ${this.signal.reason || 'user request'}`);
-        }
-        // Check internal controller
-        if (this.abortController?.signal.aborted) {
-            throw new Error(`Execution aborted: ${this.abortController.signal.reason || 'user request'}`);
-        }
-    }
-    /**
-     * Get current execution state.
-     */
-    getState() {
-        return {
-            completed: Array.from(this.completed),
-            failed: Array.from(this.failed),
-            skipped: Array.from(this.skipped),
-            running: Array.from(this.running.keys()),
-        };
-    }
-    async executeWave(tasks, waveNum, totalWaves, totalTasks) {
-        const pending = [...tasks];
-        while (pending.length > 0 || this.running.size > 0) {
-            this.startPendingTasks(pending, waveNum, totalWaves, totalTasks);
-            if (this.running.size === 0)
-                break;
-            const result = await this.waitForAny();
-            this.results.push(result);
-            this.emitProgress(waveNum, totalWaves, totalTasks, result);
-        }
-    }
-    startPendingTasks(pending, waveNum, totalWaves, totalTasks) {
-        while (pending[0] && this.canStartTask(pending[0])) {
-            const task = pending.shift();
-            if (!task)
-                break;
-            if (this.shouldSkipTask(task)) {
-                this.skipTask(task, waveNum, totalWaves, totalTasks);
-            }
-            else {
-                this.startTask(task);
-            }
-        }
-    }
-    shouldSkipTask(task) {
-        if (!this.skipOnFailedDependency)
-            return false;
-        // Check if any dependency failed
-        const deps = this.graph.getDependencies(task.id);
-        for (const dep of deps) {
-            if (this.failed.has(dep) || this.skipped.has(dep)) {
-                return true;
-            }
-        }
-        return false;
-    }
-    skipTask(task, waveNum, totalWaves, totalTasks) {
-        const now = this.clock.now();
-        this.skipped.add(task.id);
-        const result = {
-            taskId: task.id,
-            status: 'skipped',
-            durationMs: 0,
-            startedAt: now,
-            completedAt: now,
-            error: new Error('Skipped due to failed dependency'),
-        };
-        this.results.push(result);
-        this.emitProgress(waveNum, totalWaves, totalTasks, result);
-    }
-    canStartTask(task) {
-        const taskType = this.getTaskType(task);
-        const typeLimit = this.concurrency.byType?.[taskType] ?? this.concurrency.default;
-        const currentOfType = this.countRunningByType(taskType);
-        // Check type-specific limit
-        if (currentOfType >= typeLimit)
-            return false;
-        // Check global limit (defaults to default if not specified)
-        const globalLimit = this.concurrency.global ?? this.concurrency.default;
-        if (this.running.size >= globalLimit)
-            return false;
-        return true;
-    }
-    getTaskType(task) {
-        // Extract type from task metadata if available
-        const meta = task.data;
-        const typeValue = meta?.type;
-        // Validate type is a string
-        if (typeof typeValue === 'string' && typeValue.length > 0) {
-            return typeValue;
-        }
-        return 'default';
-    }
-    /**
-     * Count running tasks of a specific type.
-     * FIX: Now properly tracks task types.
-     */
-    countRunningByType(type) {
-        let count = 0;
-        for (const info of this.running.values()) {
-            if (info.taskType === type) {
-                count++;
-            }
-        }
-        return count;
-    }
-    startTask(task) {
-        const startTime = this.clock.now();
-        const taskType = this.getTaskType(task);
-        // Emit task start via progress callback (state-of-the-art observability)
-        this.emitTaskStart(task.id, taskType);
-        const promise = this.executeWithTimeout(task, startTime)
-            .then((output) => ({
-            taskId: task.id,
-            status: 'completed',
-            output,
-            durationMs: this.clock.now() - startTime,
-            startedAt: startTime,
-            completedAt: this.clock.now(),
-        }))
-            .catch((error) => ({
-            taskId: task.id,
-            status: 'failed',
-            error: error instanceof Error ? error : new Error(String(error)),
-            durationMs: this.clock.now() - startTime,
-            startedAt: startTime,
-            completedAt: this.clock.now(),
-        }))
-            .finally(() => {
-            this.running.delete(task.id);
-        });
-        // Track completion status (fire-and-forget)
-        void promise.then((r) => {
-            if (r.status === 'completed') {
-                this.completed.add(task.id);
-            }
-            else {
-                this.failed.add(task.id);
-            }
-            return;
-        });
-        this.running.set(task.id, {
-            taskId: task.id,
-            taskType,
-            promise,
-        });
-    }
-    /**
-     * Execute task with optional timeout support.
-     * State-of-the-art: proper timeout handling with AbortController pattern.
-     */
-    executeWithTimeout(task, _startTime) {
-        if (this.taskTimeoutMs <= 0) {
-            return this.executorFn(task);
-        }
-        return Promise.race([this.executorFn(task), this.createTimeoutPromise(task.id)]);
-    }
-    createTimeoutPromise(taskId) {
-        return new Promise((resolve) => {
-            setTimeout(() => resolve(), this.taskTimeoutMs);
-        }).then(() => {
-            throw new Error(`Task "${taskId}" timed out after ${this.taskTimeoutMs}ms`);
-        });
-    }
-    emitTaskStart(_taskId, _taskType) {
-        if (!this.onProgress)
-            return;
-        // Progress callback gets task start info via runningTasks update
-        // This is called before the task is added to running, so it appears in next progress update
-    }
-    waitForAny() {
-        const promises = Array.from(this.running.values()).map((info) => info.promise);
-        return Promise.race(promises);
-    }
-    emitProgress(currentWave, totalWaves, totalTasks, latestResult) {
-        if (!this.onProgress)
-            return;
-        this.onProgress({
-            totalTasks,
-            completedTasks: this.completed.size,
-            failedTasks: this.failed.size,
-            runningTasks: Array.from(this.running.keys()),
-            pendingTasks: totalTasks - this.completed.size - this.failed.size - this.skipped.size - this.running.size,
-            currentWave,
-            totalWaves,
-            latestResult,
-        });
-    }
-}
-/**
- * Create executor from task array with dependencies.
- * Convenience function for common use case.
- */
-export function createExecutor(tasks, executorFn, options) {
-    const graph = new TaskGraph();
-    // Add all tasks first
-    for (const { task } of tasks) {
-        graph.addTask(task);
-    }
-    // Add dependencies
-    for (const { task, dependsOn } of tasks) {
-        if (dependsOn) {
-            for (const dep of dependsOn) {
-                graph.addDependency(dep, task.id);
-            }
-        }
-    }
-    return new ParallelExecutor(graph, executorFn, options);
-}
-/**
- * Create executor directly from tasks using their dependencies arrays.
- * Most convenient for LLM agents.
- */
-export function createExecutorFromTasks(tasks, executorFn, options) {
-    const graph = new TaskGraph();
-    graph.addTasksWithDependencies(tasks);
-    return new ParallelExecutor(graph, executorFn, options);
-}
-//# sourceMappingURL=executor.js.map

package/dist/esm/blueprint/dag/index.d.ts

@@ -1,20 +0,0 @@
-/**
- * webpresso blueprint/dag
- *
- * Workers-safe DAG (Directed Acyclic Graph) analysis utilities.
- * Zero Node.js dependencies — safe for Cloudflare Workers, Deno, Bun, and Node.js.
- *
- * For Node-only utilities (PackageGraph, IndependenceDetector),
- * use the `dag/local` subpath instead.
- *
- * @packageDocumentation
- */
-export type { ConcurrencyConfig, ExecutionProgress, ExecutorOptions, ProgressCallback, TaskExecutorFn, TaskResult, } from './executor.js';
-export { createExecutor, createExecutorFromTasks, ParallelExecutor } from './executor.js';
-export type { GraphStats, IClock, IFileSystem, IPackageGraph, ValidationResult, } from './interfaces.js';
-export { realClock } from './interfaces.js';
-export type { ParsedPlan, PlanTask } from './plan-parser.js';
-export { parsePlan, planTasksToGraphTasks } from './plan-parser.js';
-export { CycleDetector, TaskGraph } from './task-graph.js';
-export type { Task, TaskNode } from './types.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/esm/blueprint/dag/index.js

@@ -1,17 +0,0 @@
-/**
- * webpresso blueprint/dag
- *
- * Workers-safe DAG (Directed Acyclic Graph) analysis utilities.
- * Zero Node.js dependencies — safe for Cloudflare Workers, Deno, Bun, and Node.js.
- *
- * For Node-only utilities (PackageGraph, IndependenceDetector),
- * use the `dag/local` subpath instead.
- *
- * @packageDocumentation
- */
-export { createExecutor, createExecutorFromTasks, ParallelExecutor } from './executor.js';
-export { realClock } from './interfaces.js';
-export { parsePlan, planTasksToGraphTasks } from './plan-parser.js';
-// Task Graph
-export { CycleDetector, TaskGraph } from './task-graph.js';
-//# sourceMappingURL=index.js.map

package/dist/esm/blueprint/dag/interfaces.d.ts

@@ -1,56 +0,0 @@
-/**
- * Interfaces for dependency injection and testability.
- *
- * These interfaces allow mocking of external dependencies (filesystem, time)
- * for deterministic testing.
- */
-/**
- * Filesystem abstraction for package discovery.
- * Allows mocking filesystem access in tests.
- */
-export interface IFileSystem {
-    existsSync(path: string): boolean;
-    readFileSync(path: string, encoding: 'utf-8'): string;
-}
-/**
- * Clock abstraction for time-dependent operations.
- * Allows deterministic testing of duration calculations.
- */
-export interface IClock {
-    now(): number;
-}
-/**
- * Default clock using Date.now()
- */
-export declare const realClock: IClock;
-/**
- * Package graph interface for dependency analysis.
- * Allows mocking package structure in tests.
- */
-export interface IPackageGraph {
-    findPackageRoot(filePath: string): string | null;
-    getPackageName(packageRoot: string): string | null;
-    hasCrossPackageDependency(pkgA: string, pkgB: string): boolean;
-    areInSamePackage(filePathA: string, filePathB: string): boolean;
-}
-/**
- * Validation result for graph analysis.
- */
-export interface ValidationResult {
-    valid: boolean;
-    errors: string[];
-    warnings: string[];
-}
-/**
- * Graph statistics for analysis.
- */
-export interface GraphStats {
-    nodeCount: number;
-    edgeCount: number;
-    maxDepth: number;
-    maxWidth: number;
-    waveCount: number;
-    hasCycles: boolean;
-    isolatedNodes: string[];
-}
-//# sourceMappingURL=interfaces.d.ts.map

package/dist/esm/blueprint/dag/interfaces.js

@@ -1,13 +0,0 @@
-/**
- * Interfaces for dependency injection and testability.
- *
- * These interfaces allow mocking of external dependencies (filesystem, time)
- * for deterministic testing.
- */
-/**
- * Default clock using Date.now()
- */
-export const realClock = {
-    now: () => Date.now(),
-};
-//# sourceMappingURL=interfaces.js.map

package/dist/esm/blueprint/dag/local/independence.d.ts

@@ -1,107 +0,0 @@
-import type { IPackageGraph } from '#dag/interfaces';
-/**
- * Represents a task with its file access information.
- */
-export interface TaskFiles {
-    id: string;
-    files: string[];
-    readOnly: boolean;
-}
-/**
- * Result of parallelization analysis.
- */
-export interface ParallelizeResult {
-    canParallelize: boolean;
-    reason: string;
-    /** Files that would conflict if parallelized */
-    conflictingFiles?: string[];
-}
-/**
- * A false dependency that can be removed.
- */
-export interface FalseDependency {
-    from: string;
-    to: string;
-    reason: string;
-}
-/**
- * Analysis result for a pair of tasks.
- */
-export interface TaskPairAnalysis {
-    taskA: string;
-    taskB: string;
-    canParallelize: boolean;
-    reason: string;
-    packagesA: string[];
-    packagesB: string[];
-    overlappingFiles: string[];
-    hasCrossPackageDependency: boolean;
-}
-/**
- * IndependenceDetector analyzes tasks to find false dependencies.
- *
- * Uses file and package analysis to determine if tasks can run in parallel,
- * even when the plan declares a dependency between them.
- *
- * Accepts IPackageGraph interface for testability - package structure can be mocked.
- */
-export declare class IndependenceDetector {
-    private readonly packageGraph;
-    /**
-     * Create a new IndependenceDetector.
-     * @param rootOrPackageGraph - Either a root path (creates real PackageGraph) or an IPackageGraph for testing
-     */
-    constructor(rootOrPackageGraph: string | IPackageGraph);
-    /**
-     * Determine if two tasks can run in parallel based on their file access.
-     *
-     * Algorithm:
-     * 1. Get package for each file (walk up to package.json)
-     * 2. IF different packages AND no cross-package deps → PARALLEL
-     * 3. IF same package but no file overlap → PARALLEL
-     * 4. IF file overlap but both read-only → PARALLEL
-     * 5. ELSE → SERIAL
-     */
-    canParallelize(taskA: TaskFiles, taskB: TaskFiles): ParallelizeResult;
-    private analyzePackageLocation;
-    private analyzeFilesOutsidePackages;
-    private analyzeDifferentPackages;
-    private analyzeSamePackage;
-    /**
-     * Analyze a pair of tasks in detail.
-     * Useful for debugging why tasks can or cannot be parallelized.
-     */
-    analyzeTaskPair(taskA: TaskFiles, taskB: TaskFiles): TaskPairAnalysis;
-    /**
-     * Find all false dependencies in a task graph.
-     *
-     * @param tasks - List of tasks with their file information
-     * @param edges - List of declared dependencies (from → to)
-     * @returns List of edges that can be safely removed
-     */
-    findFalseDependencies(tasks: TaskFiles[], edges: Array<{
-        from: string;
-        to: string;
-    }>): FalseDependency[];
-    /**
-     * Analyze all task pairs and return detailed analysis.
-     * Useful for understanding the parallelization potential of a task set.
-     */
-    analyzeAllPairs(tasks: TaskFiles[]): {
-        totalPairs: number;
-        parallelizablePairs: number;
-        analyses: TaskPairAnalysis[];
-    };
-    private getPackagesForFiles;
-    private hasOverlap;
-    private hasCrossPackageDep;
-    private anyDependsOn;
-    private getOverlappingFiles;
-}
-/**
- * Create a mock package graph for testing.
- * @param packages - Map of file paths to package roots
- * @param dependencies - Map of package roots to their dependencies
- */
-export declare function createMockPackageGraph(packages: Map<string, string | null>, dependencies?: Map<string, string[]>): IPackageGraph;
-//# sourceMappingURL=independence.d.ts.map