@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/dag/plan-parser.js

@@ -0,0 +1,236 @@
+/** Pattern for numbered list format: `1. [depends: 2,3] Task description` */
+const TASK_PATTERN = /^(\d+)\.\s*(?:\[depends:\s*([^\]]+)\])?\s*(.+)$/;
+/** Pattern for checkbox format: `- [ ] [depends: 1] Task description` */
+const CHECKBOX_PATTERN = /^-\s*\[[ x]\]\s*(?:\[depends:\s*([^\]]+)\])?\s*(.+)$/i;
+/**
+ * Extract title from markdown heading
+ */
+function extractTitle(lines) {
+    for (const line of lines) {
+        if (line.startsWith('# ')) {
+            return line.slice(2).trim();
+        }
+    }
+    return '';
+}
+/**
+ * Parse dependencies string into array
+ */
+function parseDependencies(deps) {
+    return deps ? deps.split(',').map((d) => d.trim()) : [];
+}
+/**
+ * Try to parse a numbered task from a line
+ */
+function parseNumberedTask(line) {
+    const match = line.match(TASK_PATTERN);
+    if (!match)
+        return null;
+    const [, num, deps, desc] = match;
+    if (!num || !desc)
+        return null;
+    return {
+        id: num,
+        title: desc,
+        description: desc,
+        type: inferTaskType(desc),
+        dependsOn: parseDependencies(deps),
+        ...extractTaskMetadata(desc),
+    };
+}
+/**
+ * Try to parse a checkbox task from a line
+ */
+function parseCheckboxTask(line, index) {
+    const match = line.match(CHECKBOX_PATTERN);
+    if (!match)
+        return null;
+    const [, deps, desc] = match;
+    if (!desc)
+        return null;
+    return {
+        id: String(index),
+        title: desc,
+        description: desc,
+        type: inferTaskType(desc),
+        dependsOn: parseDependencies(deps),
+        ...extractTaskMetadata(desc),
+    };
+}
+/**
+ * Parse all tasks from markdown lines
+ */
+function parseAllTasks(lines) {
+    const tasks = [];
+    let checkboxIndex = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const numberedTask = parseNumberedTask(trimmed);
+        if (numberedTask) {
+            tasks.push(numberedTask);
+            continue;
+        }
+        checkboxIndex++;
+        const checkboxTask = parseCheckboxTask(trimmed, checkboxIndex);
+        if (checkboxTask) {
+            tasks.push(checkboxTask);
+        }
+    }
+    return tasks;
+}
+/**
+ * Parse implementation plan markdown into structured tasks.
+ *
+ * Supports formats:
+ * - Numbered lists with dependencies: `1. [depends: 2,3] Task description`
+ * - Task blocks with metadata
+ * - Checkbox lists: `- [ ] Task description`
+ *
+ * @example
+ * ```markdown
+ * # Implementation Plan
+ *
+ * ## Tasks
+ * 1. Fix lint errors in cli2
+ * 2. [depends: 1] Fix typecheck errors in cli2
+ * 3. [depends: 1] Fix typecheck errors in schema-engine
+ * 4. [depends: 2,3] Run full test suite
+ * ```
+ */
+export function parsePlan(markdown) {
+    const lines = markdown.split('\n');
+    const title = extractTitle(lines);
+    const tasks = parseAllTasks(lines);
+    return {
+        title,
+        tasks,
+        metadata: {
+            totalTasks: tasks.length,
+            maxParallelism: calculateMaxParallelism(tasks),
+            criticalPathLength: calculateCriticalPath(tasks),
+        },
+    };
+}
+/**
+ * Task type detection rules - keywords map to task types
+ */
+const TASK_TYPE_RULES = [
+    { keywords: ['lint', 'biome'], type: 'lint-fix' },
+    { keywords: ['type', 'tsc', 'tsgo'], type: 'typecheck-fix' },
+    { keywords: ['test', 'vitest'], type: 'test-fix' },
+    { keywords: ['research', 'investigate'], type: 'research' },
+    { keywords: ['verify', 'check'], type: 'verify' },
+];
+/**
+ * Check if description contains any of the keywords
+ */
+function matchesKeywords(lower, keywords) {
+    return keywords.some((kw) => lower.includes(kw));
+}
+/**
+ * Infer task type from description
+ */
+function inferTaskType(desc) {
+    const lower = desc.toLowerCase();
+    for (const rule of TASK_TYPE_RULES) {
+        if (matchesKeywords(lower, rule.keywords)) {
+            return rule.type;
+        }
+    }
+    return 'implement';
+}
+/**
+ * Extract package and file from task description
+ */
+function extractTaskMetadata(desc) {
+    const result = {};
+    // Extract package name: "in cli2", "for schema-engine", "@myorg/cli2"
+    const pkgPatterns = [
+        /\bin\s+(?:@myorg\/)?(\w[\w-]*)/i,
+        /\bfor\s+(?:@myorg\/)?(\w[\w-]*)/i,
+        /@myorg\/([\w-]+)/,
+    ];
+    for (const pattern of pkgPatterns) {
+        const match = desc.match(pattern);
+        if (match) {
+            result.package = match[1];
+            break;
+        }
+    }
+    // Extract file path
+    const filePattern = /\b([\w/.-]+\.(?:ts|tsx|js|jsx|json|md))\b/;
+    const fileMatch = desc.match(filePattern);
+    if (fileMatch) {
+        result.file = fileMatch[1];
+    }
+    return result;
+}
+/**
+ * Calculate maximum parallelism (tasks with no dependencies)
+ */
+function calculateMaxParallelism(tasks) {
+    // Group by dependency depth
+    const depths = new Map();
+    function getDepth(taskId) {
+        const cached = depths.get(taskId);
+        if (cached !== undefined)
+            return cached;
+        const task = tasks.find((t) => t.id === taskId);
+        if (!task || !task.dependsOn.length) {
+            depths.set(taskId, 0);
+            return 0;
+        }
+        const maxDepDep = Math.max(...task.dependsOn.map(getDepth));
+        const depth = maxDepDep + 1;
+        depths.set(taskId, depth);
+        return depth;
+    }
+    // Calculate depths for all tasks
+    for (const task of tasks) {
+        getDepth(task.id);
+    }
+    // Count tasks at each depth level
+    const levelCounts = new Map();
+    for (const depth of depths.values()) {
+        levelCounts.set(depth, (levelCounts.get(depth) ?? 0) + 1);
+    }
+    return Math.max(...levelCounts.values(), 0);
+}
+/**
+ * Calculate critical path length (longest dependency chain)
+ */
+function calculateCriticalPath(tasks) {
+    const depths = new Map();
+    function getDepth(taskId) {
+        const cached = depths.get(taskId);
+        if (cached !== undefined)
+            return cached;
+        const task = tasks.find((t) => t.id === taskId);
+        if (!task || !task.dependsOn.length) {
+            depths.set(taskId, 1);
+            return 1;
+        }
+        const maxDepDep = Math.max(...task.dependsOn.map(getDepth));
+        const depth = maxDepDep + 1;
+        depths.set(taskId, depth);
+        return depth;
+    }
+    for (const task of tasks) {
+        getDepth(task.id);
+    }
+    return Math.max(...depths.values(), 0);
+}
+/**
+ * Convert parsed plan tasks to Task format for executor
+ */
+export function planTasksToGraphTasks(planTasks) {
+    return planTasks.map((pt) => ({
+        task: {
+            id: pt.id,
+            data: pt,
+            dependencies: pt.dependsOn,
+        },
+        dependsOn: pt.dependsOn.length > 0 ? pt.dependsOn : undefined,
+    }));
+}
+//# sourceMappingURL=plan-parser.js.map

package/dist/esm/blueprint/dag/task-graph-algorithms.d.ts

@@ -0,0 +1,13 @@
+import type { GraphStats, ValidationResult } from './interfaces.js';
+import type { Task, TaskNode } from './types.js';
+type NodesMap<T> = Map<string, TaskNode<T>>;
+type EdgesMap = Map<string, Set<string>>;
+export declare function topologicalSortTasksInput<T>(tasks: Task<T>[], taskMap: Map<string, Task<T>>): Task<T>[];
+export declare function getTopologicalOrderForGraph<T>(nodes: NodesMap<T>, edges: EdgesMap): Task<T>[];
+export declare function detectCyclesInGraph<T>(nodes: NodesMap<T>, edges: EdgesMap): string[][] | null;
+export declare function getCriticalPathForGraph<T>(nodes: NodesMap<T>, edges: EdgesMap): Task<T>[];
+export declare function getWavesForGraph<T>(nodes: NodesMap<T>, edges: EdgesMap): Task<T>[][];
+export declare function validateGraph<T>(nodes: NodesMap<T>, edges: EdgesMap, reverseEdges: EdgesMap): ValidationResult;
+export declare function getGraphStatsForGraph<T>(nodes: NodesMap<T>, edges: EdgesMap): GraphStats;
+export {};
+//# sourceMappingURL=task-graph-algorithms.d.ts.map

package/dist/esm/blueprint/dag/task-graph-algorithms.js

@@ -0,0 +1,236 @@
+import { CycleDetector } from './cycle-detector.js';
+export function topologicalSortTasksInput(tasks, taskMap) {
+    const visited = new Set();
+    const visiting = new Set();
+    const result = [];
+    for (const task of tasks) {
+        visitTask(task, taskMap, visited, visiting, result);
+    }
+    return result;
+}
+function visitTask(task, taskMap, visited, visiting, result) {
+    if (visited.has(task.id))
+        return;
+    if (visiting.has(task.id)) {
+        throw new Error(`Circular dependency detected involving task "${task.id}"`);
+    }
+    visiting.add(task.id);
+    for (const depId of task.dependencies) {
+        const dep = taskMap.get(depId);
+        if (dep)
+            visitTask(dep, taskMap, visited, visiting, result);
+    }
+    visiting.delete(task.id);
+    visited.add(task.id);
+    result.push(task);
+}
+function initializeInDegrees(nodes) {
+    const inDegree = new Map();
+    for (const [id, node] of nodes) {
+        inDegree.set(id, node.inDegree);
+    }
+    return inDegree;
+}
+function findZeroInDegreeNodes(inDegree) {
+    const queue = [];
+    for (const [id, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(id);
+        }
+    }
+    return queue;
+}
+function processTopologicalNode(taskId, nodes, edges, inDegree, queue) {
+    const node = nodes.get(taskId);
+    if (!node)
+        return null;
+    const dependents = edges.get(taskId);
+    if (dependents) {
+        for (const dependentId of dependents) {
+            const currentDegree = inDegree.get(dependentId) ?? 0;
+            inDegree.set(dependentId, currentDegree - 1);
+            if (inDegree.get(dependentId) === 0) {
+                queue.push(dependentId);
+            }
+        }
+    }
+    return node.task;
+}
+export function getTopologicalOrderForGraph(nodes, edges) {
+    const result = [];
+    const inDegree = initializeInDegrees(nodes);
+    const queue = findZeroInDegreeNodes(inDegree);
+    while (queue.length > 0) {
+        const taskId = queue.shift();
+        if (!taskId)
+            break;
+        const task = processTopologicalNode(taskId, nodes, edges, inDegree, queue);
+        if (task) {
+            result.push(task);
+        }
+    }
+    if (result.length !== nodes.size) {
+        throw new Error('Circular dependency detected');
+    }
+    return result;
+}
+export function detectCyclesInGraph(nodes, edges) {
+    const detector = new CycleDetector(edges);
+    return detector.detect(nodes.keys());
+}
+function initializeDepthMaps(nodes) {
+    const depth = new Map();
+    const parent = new Map();
+    for (const nodeId of nodes.keys()) {
+        depth.set(nodeId, 0);
+        parent.set(nodeId, null);
+    }
+    return { depth, parent };
+}
+function updateNeighborDepths(task, currentDepth, edges, depth, parent) {
+    const taskEdges = edges.get(task.id);
+    if (!taskEdges)
+        return;
+    for (const neighbor of taskEdges) {
+        const newDepth = currentDepth + 1;
+        if (newDepth > (depth.get(neighbor) ?? 0)) {
+            depth.set(neighbor, newDepth);
+            parent.set(neighbor, task.id);
+        }
+    }
+}
+function calculateDepths(nodes, edges, topOrder) {
+    const { depth, parent } = initializeDepthMaps(nodes);
+    for (const task of topOrder) {
+        const currentDepth = depth.get(task.id) ?? 0;
+        updateNeighborDepths(task, currentDepth, edges, depth, parent);
+    }
+    return { depth, parent };
+}
+function findDeepestNode(depth) {
+    let maxDepth = -1;
+    let endNode = null;
+    for (const [nodeId, nodeDepth] of depth) {
+        if (nodeDepth > maxDepth) {
+            maxDepth = nodeDepth;
+            endNode = nodeId;
+        }
+    }
+    return endNode;
+}
+function reconstructPath(nodes, endNode, parent) {
+    const path = [];
+    let current = endNode;
+    while (current !== null) {
+        const node = nodes.get(current);
+        if (node) {
+            path.unshift(node.task);
+        }
+        current = parent.get(current) ?? null;
+    }
+    return path;
+}
+export function getCriticalPathForGraph(nodes, edges) {
+    if (nodes.size === 0) {
+        return [];
+    }
+    if (nodes.size === 1) {
+        const task = nodes.values().next().value?.task;
+        return task ? [task] : [];
+    }
+    const topOrder = getTopologicalOrderForGraph(nodes, edges);
+    const { depth, parent } = calculateDepths(nodes, edges, topOrder);
+    const endNode = findDeepestNode(depth);
+    return reconstructPath(nodes, endNode, parent);
+}
+function processNodeDependents(node, edges, inDegree, nextQueue) {
+    const dependents = edges.get(node.task.id);
+    if (dependents) {
+        for (const dependentId of dependents) {
+            const currentDegree = inDegree.get(dependentId) ?? 0;
+            inDegree.set(dependentId, currentDegree - 1);
+            if (inDegree.get(dependentId) === 0) {
+                nextQueue.push(dependentId);
+            }
+        }
+    }
+}
+function processWave(nodes, edges, queue, inDegree) {
+    const wave = [];
+    const nextQueue = [];
+    for (const taskId of queue) {
+        const node = nodes.get(taskId);
+        if (!node)
+            continue;
+        wave.push(node.task);
+        processNodeDependents(node, edges, inDegree, nextQueue);
+    }
+    return { wave, nextQueue };
+}
+export function getWavesForGraph(nodes, edges) {
+    const waves = [];
+    const inDegree = initializeInDegrees(nodes);
+    let queue = findZeroInDegreeNodes(inDegree);
+    while (queue.length > 0) {
+        const { wave, nextQueue } = processWave(nodes, edges, queue, inDegree);
+        waves.push(wave);
+        queue = nextQueue;
+    }
+    return waves;
+}
+function getIsolatedNodes(nodes, edges) {
+    if (nodes.size <= 1)
+        return [];
+    const isolatedNodes = [];
+    for (const [id, node] of nodes) {
+        const hasIncoming = node.inDegree > 0;
+        const hasOutgoing = (edges.get(id)?.size ?? 0) > 0;
+        if (!hasIncoming && !hasOutgoing) {
+            isolatedNodes.push(id);
+        }
+    }
+    return isolatedNodes;
+}
+export function validateGraph(nodes, edges, reverseEdges) {
+    const cycles = detectCyclesInGraph(nodes, edges);
+    const errors = cycles?.length
+        ? cycles.map((cycle) => `Circular dependency: ${cycle.join(' -> ')}`)
+        : [];
+    const warnings = getIsolatedNodes(nodes, edges).map((id) => `Task "${id}" is isolated (no dependencies or dependents)`);
+    for (const [id, node] of nodes) {
+        const actualDeps = reverseEdges.get(id) ?? new Set();
+        for (const dep of node.task.dependencies) {
+            if (!actualDeps.has(dep)) {
+                warnings.push(`Task "${id}" declares dependency on "${dep}" but it's not wired in the graph`);
+            }
+        }
+    }
+    return {
+        valid: !errors.length,
+        errors,
+        warnings,
+    };
+}
+export function getGraphStatsForGraph(nodes, edges) {
+    const waves = getWavesForGraph(nodes, edges);
+    const isolatedNodes = getIsolatedNodes(nodes, edges);
+    let edgeCount = 0;
+    for (const edgeSet of edges.values()) {
+        edgeCount += edgeSet.size;
+    }
+    let maxWidth = 0;
+    for (const wave of waves) {
+        maxWidth = Math.max(maxWidth, wave.length);
+    }
+    const cycles = detectCyclesInGraph(nodes, edges);
+    return {
+        nodeCount: nodes.size,
+        edgeCount,
+        maxDepth: getCriticalPathForGraph(nodes, edges).length,
+        maxWidth,
+        waveCount: waves.length,
+        hasCycles: cycles !== null && cycles.length > 0,
+        isolatedNodes,
+    };
+}
+//# sourceMappingURL=task-graph-algorithms.js.map

package/dist/esm/blueprint/dag/task-graph.d.ts

@@ -0,0 +1,171 @@
+import type { GraphStats, ValidationResult } from './interfaces.js';
+import type { Task } from './types.js';
+import { CycleDetector } from './cycle-detector.js';
+/**
+ * DAG (Directed Acyclic Graph) analysis for parallel task execution.
+ *
+ * Provides:
+ * - Topological sorting (Kahn's Algorithm)
+ * - Cycle detection (DFS)
+ * - Critical path analysis (longest dependency chain)
+ * - Wave grouping (parallel execution batches)
+ * - Parallelization metrics
+ * - Validation and statistics
+ *
+ * Zero dependencies. Works with Bun, Node.js, Deno.
+ *
+ * @template T - The type of additional data attached to tasks
+ */
+export declare class TaskGraph<T = unknown> {
+    private nodes;
+    private edges;
+    private reverseEdges;
+    constructor();
+    /**
+     * Add a task to the graph.
+     * Must be called before adding dependencies.
+     */
+    addTask(task: Task<T>): void;
+    /**
+     * Add a task and automatically wire up its dependencies.
+     * This is the preferred method for LLM agents - single call instead of addTask + addDependency.
+     *
+     * @param task - Task with dependencies array populated
+     * @throws {Error} If task already exists or dependencies reference non-existent tasks
+     */
+    addTaskWithDependencies(task: Task<T>): void;
+    /**
+     * Bulk add tasks with automatic dependency wiring.
+     * Tasks are sorted by dependency depth before adding.
+     *
+     * @param tasks - Array of tasks to add
+     * @throws {Error} If circular dependencies detected or tasks reference non-existent dependencies
+     */
+    addTasksWithDependencies(tasks: Task<T>[]): void;
+    /**
+     * Add a dependency between two tasks.
+     * @param from - The task that must complete first
+     * @param to - The task that depends on `from`
+     * @throws {Error} If tasks don't exist, self-loop detected
+     */
+    addDependency(from: string, to: string): void;
+    private validateDependencyNodes;
+    private edgeExists;
+    private addForwardEdge;
+    private addReverseEdge;
+    private incrementInDegree;
+    /**
+     * Remove a dependency between two tasks.
+     * @param from - The source task
+     * @param to - The dependent task
+     * @returns true if dependency was removed, false if it didn't exist
+     */
+    removeDependency(from: string, to: string): boolean;
+    /**
+     * Get the in-degree (number of dependencies) for a task.
+     */
+    getInDegree(taskId: string): number;
+    /**
+     * Get the out-degree (number of dependents) for a task.
+     */
+    getOutDegree(taskId: string): number;
+    /**
+     * Get all task IDs in the graph.
+     */
+    getTaskIds(): string[];
+    /**
+     * Get a task by ID.
+     */
+    getTask(taskId: string): Task<T> | undefined;
+    /**
+     * Check if a task exists in the graph.
+     */
+    hasTask(taskId: string): boolean;
+    /**
+     * Get the number of tasks in the graph.
+     */
+    get size(): number;
+    /**
+     * Get the number of edges in the graph.
+     */
+    get edgeCount(): number;
+    /**
+     * Validate the graph structure.
+     * Checks for cycles, missing dependencies, and other issues.
+     */
+    validate(): ValidationResult;
+    /**
+     * Get comprehensive statistics about the graph.
+     */
+    getStats(): GraphStats;
+    /**
+     * Get tasks in topological order (Kahn's Algorithm).
+     * Tasks appear before their dependents.
+     * @throws {Error} If circular dependency detected
+     */
+    getTopologicalOrder(): Task<T>[];
+    /**
+     * Detect circular dependencies using DFS.
+     * @returns Array of cycles (each cycle is an array of task IDs), or null if acyclic
+     */
+    detectCycles(): string[][] | null;
+    /**
+     * Check if the graph contains any cycles.
+     * @returns true if cycles exist, false if acyclic
+     */
+    hasCycle(): boolean;
+    /**
+     * Get the critical path (longest dependency chain).
+     * This is the sequence of tasks that determines the minimum execution time.
+     *
+     * IMPORTANT: For optimal parallel scheduling, the invariant |waves| = |critical_path| must hold.
+     *
+     * Returns:
+     * - Empty array for empty graph
+     * - Single task for single-node graph (critical path length = 1)
+     * - Single task if all tasks are independent (critical path length = 1, same as wave count)
+     * - Longest dependency chain for graphs with dependencies
+     */
+    getCriticalPath(): Task<T>[];
+    /**
+     * Get the maximum number of tasks that can run in parallel.
+     */
+    getMaxParallelWidth(): number;
+    /**
+     * Group tasks into waves (batches) for parallel execution.
+     * Tasks in the same wave have no dependencies on each other.
+     * Each wave must complete before the next wave starts.
+     */
+    getWaves(): Task<T>[][];
+    /**
+     * Get direct dependencies of a task.
+     */
+    getDependencies(taskId: string): string[];
+    /**
+     * Get direct dependents of a task (tasks that depend on this one).
+     */
+    getDependents(taskId: string): string[];
+    /**
+     * Get all transitive dependencies of a task (including indirect).
+     */
+    getTransitiveDependencies(taskId: string): string[];
+    /**
+     * Get all transitive dependents of a task (including indirect).
+     */
+    getTransitiveDependents(taskId: string): string[];
+    /**
+     * Create a subgraph containing only the specified tasks and their edges.
+     */
+    subgraph(taskIds: string[]): TaskGraph<T>;
+    private copyTasksToSubgraph;
+    private copyEdgesToSubgraph;
+    private copyNodeEdgesToSubgraph;
+    /**
+     * Clone the graph.
+     */
+    clone(): TaskGraph<T>;
+    private copyAllTasks;
+    private copyAllEdges;
+}
+export { CycleDetector };
+//# sourceMappingURL=task-graph.d.ts.map