@webpresso/agent-kit 0.21.4 → 0.23.0

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

@@ -1,370 +0,0 @@
-import { CycleDetector } from './cycle-detector.js';
-import { detectCyclesInGraph, getCriticalPathForGraph, getGraphStatsForGraph, getTopologicalOrderForGraph, getWavesForGraph, topologicalSortTasksInput, validateGraph, } from './task-graph-algorithms.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 class TaskGraph {
-    nodes;
-    edges; // from -> to[]
-    reverseEdges; // to -> from[] (for validation)
-    constructor() {
-        this.nodes = new Map();
-        this.edges = new Map();
-        this.reverseEdges = new Map();
-    }
-    /**
-     * Add a task to the graph.
-     * Must be called before adding dependencies.
-     */
-    addTask(task) {
-        if (this.nodes.has(task.id)) {
-            throw new Error(`Task "${task.id}" already exists in the graph`);
-        }
-        this.nodes.set(task.id, {
-            task,
-            inDegree: 0,
-        });
-    }
-    /**
-     * 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) {
-        this.addTask(task);
-        for (const depId of task.dependencies) {
-            if (!this.nodes.has(depId)) {
-                // Remove the task we just added to maintain consistency
-                this.nodes.delete(task.id);
-                throw new Error(`Cannot add task "${task.id}": dependency "${depId}" does not exist. ` +
-                    `Add dependencies first, or use addTask() + addDependency() for more control.`);
-            }
-            this.addDependency(depId, task.id);
-        }
-    }
-    /**
-     * 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) {
-        // Build a map for quick lookup
-        const taskMap = new Map(tasks.map((t) => [t.id, t]));
-        // Topological sort the input tasks
-        const sorted = topologicalSortTasksInput(tasks, taskMap);
-        // Add in sorted order
-        for (const task of sorted) {
-            this.addTaskWithDependencies(task);
-        }
-    }
-    /**
-     * 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, to) {
-        this.validateDependencyNodes(from, to);
-        if (this.edgeExists(from, to))
-            return;
-        this.addForwardEdge(from, to);
-        this.addReverseEdge(from, to);
-        this.incrementInDegree(to);
-    }
-    validateDependencyNodes(from, to) {
-        if (!this.nodes.has(from)) {
-            throw new Error(`Cannot add dependency: source task "${from}" does not exist`);
-        }
-        if (!this.nodes.has(to)) {
-            throw new Error(`Cannot add dependency: target task "${to}" does not exist`);
-        }
-        if (from === to) {
-            throw new Error(`Cannot add self-loop: task "${from}" cannot depend on itself`);
-        }
-    }
-    edgeExists(from, to) {
-        return this.edges.get(from)?.has(to) ?? false;
-    }
-    addForwardEdge(from, to) {
-        if (!this.edges.has(from)) {
-            this.edges.set(from, new Set());
-        }
-        this.edges.get(from)?.add(to);
-    }
-    addReverseEdge(from, to) {
-        if (!this.reverseEdges.has(to)) {
-            this.reverseEdges.set(to, new Set());
-        }
-        this.reverseEdges.get(to)?.add(from);
-    }
-    incrementInDegree(taskId) {
-        const node = this.nodes.get(taskId);
-        if (node)
-            node.inDegree++;
-    }
-    /**
-     * 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, to) {
-        const edges = this.edges.get(from);
-        if (!edges?.has(to)) {
-            return false;
-        }
-        edges.delete(to);
-        if (edges.size === 0) {
-            this.edges.delete(from);
-        }
-        // Remove reverse edge
-        const revEdges = this.reverseEdges.get(to);
-        if (revEdges) {
-            revEdges.delete(from);
-            if (revEdges.size === 0) {
-                this.reverseEdges.delete(to);
-            }
-        }
-        // Decrement in-degree
-        const toNode = this.nodes.get(to);
-        if (toNode && toNode.inDegree > 0) {
-            toNode.inDegree--;
-        }
-        return true;
-    }
-    /**
-     * Get the in-degree (number of dependencies) for a task.
-     */
-    getInDegree(taskId) {
-        const node = this.nodes.get(taskId);
-        return node?.inDegree ?? 0;
-    }
-    /**
-     * Get the out-degree (number of dependents) for a task.
-     */
-    getOutDegree(taskId) {
-        return this.edges.get(taskId)?.size ?? 0;
-    }
-    /**
-     * Get all task IDs in the graph.
-     */
-    getTaskIds() {
-        return Array.from(this.nodes.keys());
-    }
-    /**
-     * Get a task by ID.
-     */
-    getTask(taskId) {
-        return this.nodes.get(taskId)?.task;
-    }
-    /**
-     * Check if a task exists in the graph.
-     */
-    hasTask(taskId) {
-        return this.nodes.has(taskId);
-    }
-    /**
-     * Get the number of tasks in the graph.
-     */
-    get size() {
-        return this.nodes.size;
-    }
-    /**
-     * Get the number of edges in the graph.
-     */
-    get edgeCount() {
-        let count = 0;
-        for (const edges of this.edges.values()) {
-            count += edges.size;
-        }
-        return count;
-    }
-    /**
-     * Validate the graph structure.
-     * Checks for cycles, missing dependencies, and other issues.
-     */
-    validate() {
-        return validateGraph(this.nodes, this.edges, this.reverseEdges);
-    }
-    /**
-     * Get comprehensive statistics about the graph.
-     */
-    getStats() {
-        return getGraphStatsForGraph(this.nodes, this.edges);
-    }
-    /**
-     * Get tasks in topological order (Kahn's Algorithm).
-     * Tasks appear before their dependents.
-     * @throws {Error} If circular dependency detected
-     */
-    getTopologicalOrder() {
-        return getTopologicalOrderForGraph(this.nodes, this.edges);
-    }
-    /**
-     * Detect circular dependencies using DFS.
-     * @returns Array of cycles (each cycle is an array of task IDs), or null if acyclic
-     */
-    detectCycles() {
-        return detectCyclesInGraph(this.nodes, this.edges);
-    }
-    /**
-     * Check if the graph contains any cycles.
-     * @returns true if cycles exist, false if acyclic
-     */
-    hasCycle() {
-        const cycles = this.detectCycles();
-        return cycles !== null && cycles.length > 0;
-    }
-    /**
-     * 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() {
-        return getCriticalPathForGraph(this.nodes, this.edges);
-    }
-    /**
-     * Get the maximum number of tasks that can run in parallel.
-     */
-    getMaxParallelWidth() {
-        const waves = getWavesForGraph(this.nodes, this.edges);
-        let maxWidth = 0;
-        for (const wave of waves) {
-            maxWidth = Math.max(maxWidth, wave.length);
-        }
-        return maxWidth;
-    }
-    /**
-     * 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() {
-        return getWavesForGraph(this.nodes, this.edges);
-    }
-    /**
-     * Get direct dependencies of a task.
-     */
-    getDependencies(taskId) {
-        return Array.from(this.reverseEdges.get(taskId) ?? []);
-    }
-    /**
-     * Get direct dependents of a task (tasks that depend on this one).
-     */
-    getDependents(taskId) {
-        return Array.from(this.edges.get(taskId) ?? []);
-    }
-    /**
-     * Get all transitive dependencies of a task (including indirect).
-     */
-    getTransitiveDependencies(taskId) {
-        const visited = new Set();
-        const stack = [...(this.reverseEdges.get(taskId) ?? [])];
-        while (stack.length > 0) {
-            // Safe: loop condition ensures stack is non-empty
-            const dep = stack.pop();
-            if (!dep)
-                break;
-            if (visited.has(dep))
-                continue;
-            visited.add(dep);
-            stack.push(...(this.reverseEdges.get(dep) ?? []));
-        }
-        return Array.from(visited);
-    }
-    /**
-     * Get all transitive dependents of a task (including indirect).
-     */
-    getTransitiveDependents(taskId) {
-        const visited = new Set();
-        const stack = [...(this.edges.get(taskId) ?? [])];
-        while (stack.length > 0) {
-            // Safe: loop condition ensures stack is non-empty
-            const dep = stack.pop();
-            if (!dep)
-                break;
-            if (visited.has(dep))
-                continue;
-            visited.add(dep);
-            stack.push(...(this.edges.get(dep) ?? []));
-        }
-        return Array.from(visited);
-    }
-    /**
-     * Create a subgraph containing only the specified tasks and their edges.
-     */
-    subgraph(taskIds) {
-        const sub = new TaskGraph();
-        const idSet = new Set(taskIds);
-        this.copyTasksToSubgraph(taskIds, sub);
-        this.copyEdgesToSubgraph(taskIds, idSet, sub);
-        return sub;
-    }
-    copyTasksToSubgraph(taskIds, sub) {
-        for (const id of taskIds) {
-            const node = this.nodes.get(id);
-            if (node)
-                sub.addTask({ ...node.task, dependencies: [] });
-        }
-    }
-    copyEdgesToSubgraph(taskIds, idSet, sub) {
-        for (const id of taskIds) {
-            this.copyNodeEdgesToSubgraph(id, idSet, sub);
-        }
-    }
-    copyNodeEdgesToSubgraph(id, idSet, sub) {
-        const edges = this.edges.get(id);
-        if (!edges)
-            return;
-        for (const to of edges) {
-            if (idSet.has(to))
-                sub.addDependency(id, to);
-        }
-    }
-    /**
-     * Clone the graph.
-     */
-    clone() {
-        const cloned = new TaskGraph();
-        this.copyAllTasks(cloned);
-        this.copyAllEdges(cloned);
-        return cloned;
-    }
-    copyAllTasks(target) {
-        for (const [, node] of this.nodes) {
-            target.addTask({ ...node.task });
-        }
-    }
-    copyAllEdges(target) {
-        for (const [from, edges] of this.edges) {
-            for (const to of edges) {
-                target.addDependency(from, to);
-            }
-        }
-    }
-}
-export { CycleDetector };
-//# sourceMappingURL=task-graph.js.map

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

@@ -1,17 +0,0 @@
-/**
- * Generic task interface for DAG analysis.
- * Applications should extend this with their specific task data.
- */
-export interface Task<T = unknown> {
-    id: string;
-    data?: T;
-    dependencies: string[];
-}
-/**
- * Internal node representation in the graph.
- */
-export interface TaskNode<T = unknown> {
-    task: Task<T>;
-    inDegree: number;
-}
-//# sourceMappingURL=types.d.ts.map

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

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map

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

@@ -1,5 +0,0 @@
-export { graphEdgeSchema, graphEdgeTypeSchema, graphLayoutSchema, graphNodeSchema, graphNodeTypeSchema, normalizedGraphSchema, type GraphEdge, type GraphEdgeType, type GraphLayout, type GraphNode, type GraphNodeType, type NormalizedGraph, } from './schema.js';
-export { parseMermaidToGraph } from './mermaid-parser.js';
-export { serializeGraphToMermaid } from './mermaid-serializer.js';
-export { taskGraphToNormalizedGraph } from './task-graph-adapter.js';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,5 +0,0 @@
-export { graphEdgeSchema, graphEdgeTypeSchema, graphLayoutSchema, graphNodeSchema, graphNodeTypeSchema, normalizedGraphSchema, } from './schema.js';
-export { parseMermaidToGraph } from './mermaid-parser.js';
-export { serializeGraphToMermaid } from './mermaid-serializer.js';
-export { taskGraphToNormalizedGraph } from './task-graph-adapter.js';
-//# sourceMappingURL=index.js.map

package/dist/esm/blueprint/graph/mermaid-parser.d.ts

@@ -1,3 +0,0 @@
-import { type NormalizedGraph } from '#graph/schema';
-export declare function parseMermaidToGraph(mermaid: string): NormalizedGraph;
-//# sourceMappingURL=mermaid-parser.d.ts.map

package/dist/esm/blueprint/graph/mermaid-parser.js

@@ -1,93 +0,0 @@
-import { normalizedGraphSchema, } from '#graph/schema';
-const DIRECTION_LINE = /^graph\s+(TD|LR|BT|RL)$/;
-const EDGE_WITH_LABEL = /^([A-Za-z0-9_-]+)(?:\[([^\]]+)\])?\s*--\|([^|]+)\|\s*([A-Za-z0-9_-]+)(?:\[([^\]]+)\])?$/;
-const EDGE_SIMPLE = /^([A-Za-z0-9_-]+)(?:\[([^\]]+)\])?\s*-->\s*([A-Za-z0-9_-]+)(?:\[([^\]]+)\])?$/;
-const NODE_ONLY = /^([A-Za-z0-9_-]+)\[([^\]]+)\]$/;
-function upsertNode(nodes, id, label) {
-    const existing = nodes.get(id);
-    if (existing) {
-        if (label && existing.label === id) {
-            nodes.set(id, { ...existing, label });
-        }
-        return;
-    }
-    nodes.set(id, {
-        id,
-        type: 'task',
-        label: label ?? id,
-    });
-}
-function parseEdge(line, nodes, edges) {
-    const labeled = line.match(EDGE_WITH_LABEL);
-    if (labeled) {
-        const source = labeled[1] ?? '';
-        const sourceLabel = labeled[2];
-        const edgeLabel = (labeled[3] ?? '').trim();
-        const target = labeled[4] ?? '';
-        const targetLabel = labeled[5];
-        upsertNode(nodes, source, sourceLabel);
-        upsertNode(nodes, target, targetLabel);
-        edges.push({
-            source,
-            target,
-            type: 'depends_on',
-            label: edgeLabel,
-        });
-        return true;
-    }
-    const simple = line.match(EDGE_SIMPLE);
-    if (!simple) {
-        return false;
-    }
-    const source = simple[1] ?? '';
-    const sourceLabel = simple[2];
-    const target = simple[3] ?? '';
-    const targetLabel = simple[4];
-    upsertNode(nodes, source, sourceLabel);
-    upsertNode(nodes, target, targetLabel);
-    edges.push({
-        source,
-        target,
-        type: 'depends_on',
-    });
-    return true;
-}
-export function parseMermaidToGraph(mermaid) {
-    const lines = mermaid
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0 && !line.startsWith('%%'))
-        .map((line) => (line.endsWith(';') ? line.slice(0, -1).trim() : line));
-    if (!lines.length) {
-        throw new Error('Mermaid input is empty');
-    }
-    const directionMatch = lines[0]?.match(DIRECTION_LINE);
-    if (!directionMatch?.[1]) {
-        throw new Error('Mermaid must start with "graph <direction>"');
-    }
-    const direction = directionMatch[1];
-    const nodes = new Map();
-    const edges = [];
-    for (const line of lines.slice(1)) {
-        if (line === '' || line.startsWith('subgraph') || line === 'end') {
-            continue;
-        }
-        if (parseEdge(line, nodes, edges)) {
-            continue;
-        }
-        const nodeOnly = line.match(NODE_ONLY);
-        if (nodeOnly) {
-            const id = nodeOnly[1] ?? '';
-            const label = nodeOnly[2] ?? id;
-            upsertNode(nodes, id, label);
-            continue;
-        }
-        throw new Error(`Unsupported Mermaid line: ${line}`);
-    }
-    return normalizedGraphSchema.parse({
-        nodes: [...nodes.values()],
-        edges,
-        layout: { direction },
-    });
-}
-//# sourceMappingURL=mermaid-parser.js.map

package/dist/esm/blueprint/graph/mermaid-serializer.d.ts

@@ -1,3 +0,0 @@
-import type { NormalizedGraph } from '#graph/schema';
-export declare function serializeGraphToMermaid(graph: NormalizedGraph): string;
-//# sourceMappingURL=mermaid-serializer.d.ts.map

package/dist/esm/blueprint/graph/mermaid-serializer.js

@@ -1,20 +0,0 @@
-function escapeLabel(label) {
-    return label.replace(/\[/g, '(').replace(/\]/g, ')');
-}
-export function serializeGraphToMermaid(graph) {
-    const direction = graph.layout?.direction ?? 'TD';
-    const lines = [`graph ${direction}`];
-    for (const node of graph.nodes) {
-        lines.push(`  ${node.id}[${escapeLabel(node.label)}]`);
-    }
-    for (const edge of graph.edges) {
-        if (edge.label) {
-            lines.push(`  ${edge.source} --|${escapeLabel(edge.label)}| ${edge.target}`);
-        }
-        else {
-            lines.push(`  ${edge.source} --> ${edge.target}`);
-        }
-    }
-    return `${lines.join('\n')}\n`;
-}
-//# sourceMappingURL=mermaid-serializer.js.map

package/dist/esm/blueprint/graph/schema.d.ts

@@ -1,89 +0,0 @@
-import { z } from 'zod';
-export declare const graphNodeTypeSchema: z.ZodEnum<{
-    blueprint: "blueprint";
-    decision: "decision";
-    external: "external";
-    task: "task";
-    milestone: "milestone";
-    tech_debt: "tech_debt";
-}>;
-export declare const graphEdgeTypeSchema: z.ZodEnum<{
-    depends_on: "depends_on";
-    blocks: "blocks";
-    relates_to: "relates_to";
-}>;
-export declare const graphNodeSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodEnum<{
-        blueprint: "blueprint";
-        decision: "decision";
-        external: "external";
-        task: "task";
-        milestone: "milestone";
-        tech_debt: "tech_debt";
-    }>;
-    label: z.ZodString;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-export declare const graphEdgeSchema: z.ZodObject<{
-    source: z.ZodString;
-    target: z.ZodString;
-    type: z.ZodEnum<{
-        depends_on: "depends_on";
-        blocks: "blocks";
-        relates_to: "relates_to";
-    }>;
-    label: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-export declare const graphLayoutSchema: z.ZodObject<{
-    direction: z.ZodDefault<z.ZodEnum<{
-        TD: "TD";
-        LR: "LR";
-        BT: "BT";
-        RL: "RL";
-    }>>;
-    rankdir: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const normalizedGraphSchema: z.ZodObject<{
-    nodes: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodEnum<{
-            blueprint: "blueprint";
-            decision: "decision";
-            external: "external";
-            task: "task";
-            milestone: "milestone";
-            tech_debt: "tech_debt";
-        }>;
-        label: z.ZodString;
-        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>;
-    edges: z.ZodArray<z.ZodObject<{
-        source: z.ZodString;
-        target: z.ZodString;
-        type: z.ZodEnum<{
-            depends_on: "depends_on";
-            blocks: "blocks";
-            relates_to: "relates_to";
-        }>;
-        label: z.ZodOptional<z.ZodString>;
-        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>;
-    layout: z.ZodOptional<z.ZodObject<{
-        direction: z.ZodDefault<z.ZodEnum<{
-            TD: "TD";
-            LR: "LR";
-            BT: "BT";
-            RL: "RL";
-        }>>;
-        rankdir: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type GraphNodeType = z.infer<typeof graphNodeTypeSchema>;
-export type GraphEdgeType = z.infer<typeof graphEdgeTypeSchema>;
-export type GraphNode = z.infer<typeof graphNodeSchema>;
-export type GraphEdge = z.infer<typeof graphEdgeSchema>;
-export type GraphLayout = z.infer<typeof graphLayoutSchema>;
-export type NormalizedGraph = z.infer<typeof normalizedGraphSchema>;
-//# sourceMappingURL=schema.d.ts.map