@webpresso/agent-kit 0.21.0

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

@@ -0,0 +1,370 @@
+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

@@ -0,0 +1,17 @@
+/**
+ * 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

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

package/dist/esm/blueprint/db/cold-start.d.ts

@@ -0,0 +1,8 @@
+export interface ColdStartResult {
+    rebuilt: boolean;
+    blueprintsCount: number;
+    techDebtCount: number;
+    durationMs: number;
+}
+export declare function coldStartIfNeeded(cwd: string): Promise<ColdStartResult>;
+//# sourceMappingURL=cold-start.d.ts.map

package/dist/esm/blueprint/db/cold-start.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { openDb } from './connection.js';
+import { ingestAll } from './ingester.js';
+import { migrateLegacyAgentDb } from './legacy-migration.js';
+import { resolveBlueprintProjectionDbPath, withProjectionDbWriteLock } from './paths.js';
+import { recordProjectionMetadata } from '#freshness.js';
+export async function coldStartIfNeeded(cwd) {
+    const start = Date.now();
+    // F12/R10/E12: detect+migrate legacy `.agent/.blueprints.db` once per repo.
+    migrateLegacyAgentDb(cwd);
+    const target = resolveBlueprintProjectionDbPath(cwd);
+    if (existsSync(target)) {
+        return { rebuilt: false, blueprintsCount: 0, techDebtCount: 0, durationMs: 0 };
+    }
+    // F9/R7: worktree-scoped write lock. Throws LockTimeoutError on failure —
+    // no silent 5s "proceeds anyway" escape on write paths.
+    return withProjectionDbWriteLock(cwd, async () => {
+        // Re-check after lock acquisition — another writer may have created it.
+        if (existsSync(target)) {
+            return { rebuilt: false, blueprintsCount: 0, techDebtCount: 0, durationMs: 0 };
+        }
+        mkdirSync(path.dirname(target), { recursive: true });
+        const conn = openDb(target);
+        let blueprintsCount = 0;
+        let techDebtCount = 0;
+        try {
+            const result = await ingestAll({ db: conn.db, cwd });
+            blueprintsCount = result.blueprintsIngested;
+            techDebtCount = result.techDebtIngested;
+            recordProjectionMetadata({
+                dbPath: target,
+                cwd,
+                ingestedAt: Date.now(),
+            });
+        }
+        finally {
+            conn.close();
+        }
+        const durationMs = Date.now() - start;
+        process.stderr.write(`[cold-start] Rebuilt in ${durationMs}ms (${blueprintsCount} blueprints, ${techDebtCount} tech-debt items)\n`);
+        return { rebuilt: true, blueprintsCount, techDebtCount, durationMs };
+    });
+}
+//# sourceMappingURL=cold-start.js.map

package/dist/esm/blueprint/db/connection.d.ts

@@ -0,0 +1,8 @@
+import { Database, type Statement } from '#db/sqlite.js';
+export type DbConnection = {
+    readonly db: Database;
+    readonly close: () => void;
+};
+export declare function openDb(dbPath: string): DbConnection;
+export declare function preparedQuery<T>(db: Database, sql: string): Statement<[], T>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/esm/blueprint/db/connection.js

@@ -0,0 +1,45 @@
+import { Database } from '#db/sqlite.js';
+import { runMigrations } from './migrations/run.js';
+const OPEN_DB_BUSY_RETRY_MS = 50;
+const OPEN_DB_BUSY_RETRIES = 5;
+function isSqliteBusy(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.message.includes('SQLITE_BUSY') || error.message.includes('database is locked');
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function initializeDb(db) {
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    runMigrations(db);
+}
+export function openDb(dbPath) {
+    const db = new Database(dbPath);
+    let lastError = null;
+    for (let attempt = 0; attempt <= OPEN_DB_BUSY_RETRIES; attempt += 1) {
+        try {
+            initializeDb(db);
+            return {
+                db,
+                close: () => db.close(),
+            };
+        }
+        catch (error) {
+            lastError = error;
+            if (!isSqliteBusy(error) || attempt === OPEN_DB_BUSY_RETRIES) {
+                db.close();
+                throw error;
+            }
+            sleepSync(OPEN_DB_BUSY_RETRY_MS);
+        }
+    }
+    db.close();
+    throw lastError;
+}
+export function preparedQuery(db, sql) {
+    return db.prepare(sql);
+}
+//# sourceMappingURL=connection.js.map

package/dist/esm/blueprint/db/enums.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+export declare const BLUEPRINT_STATUS: readonly ["draft", "planned", "in-progress", "completed", "parked", "archived"];
+export declare const BLUEPRINT_COMPLEXITY: readonly ["XS", "S", "M", "L", "XL"];
+export declare const TASK_STATUS: readonly ["todo", "in-progress", "blocked", "done", "dropped"];
+export declare const TECH_DEBT_STATUS: readonly ["accepted", "needs-remediation", "monitoring", "resolved"];
+export declare const SEVERITY: readonly ["CRITICAL", "HIGH", "MEDIUM", "LOW"];
+export declare const TECH_DEBT_SEVERITY: readonly ["critical", "high", "medium", "low"];
+export declare const TECH_DEBT_CATEGORY_VALUES: readonly ["documentation", "architecture", "testing", "performance", "security", "maintenance", "dependencies"];
+export declare const REVIEW_CADENCE: readonly ["weekly", "biweekly", "monthly", "quarterly"];
+export declare const VISIBILITY: readonly ["public", "private"];
+export declare const TASK_FILE_OP: readonly ["create", "modify", "delete"];
+export declare const blueprintStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    draft: "draft";
+    planned: "planned";
+    "in-progress": "in-progress";
+    parked: "parked";
+    archived: "archived";
+}>;
+export declare const blueprintComplexitySchema: z.ZodEnum<{
+    XS: "XS";
+    S: "S";
+    M: "M";
+    L: "L";
+    XL: "XL";
+}>;
+export declare const taskStatusSchema: z.ZodEnum<{
+    blocked: "blocked";
+    "in-progress": "in-progress";
+    todo: "todo";
+    done: "done";
+    dropped: "dropped";
+}>;
+export declare const techDebtStatusSchema: z.ZodEnum<{
+    accepted: "accepted";
+    "needs-remediation": "needs-remediation";
+    monitoring: "monitoring";
+    resolved: "resolved";
+}>;
+export declare const severitySchema: z.ZodEnum<{
+    CRITICAL: "CRITICAL";
+    HIGH: "HIGH";
+    MEDIUM: "MEDIUM";
+    LOW: "LOW";
+}>;
+export declare const techDebtSeveritySchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    critical: "critical";
+}>;
+export declare const techDebtCategorySchema: z.ZodEnum<{
+    dependencies: "dependencies";
+    performance: "performance";
+    testing: "testing";
+    security: "security";
+    documentation: "documentation";
+    architecture: "architecture";
+    maintenance: "maintenance";
+}>;
+export declare const reviewCadenceSchema: z.ZodEnum<{
+    weekly: "weekly";
+    biweekly: "biweekly";
+    monthly: "monthly";
+    quarterly: "quarterly";
+}>;
+export declare const visibilitySchema: z.ZodEnum<{
+    private: "private";
+    public: "public";
+}>;
+export declare const taskFileOpSchema: z.ZodEnum<{
+    create: "create";
+    modify: "modify";
+    delete: "delete";
+}>;
+//# sourceMappingURL=enums.d.ts.map

package/dist/esm/blueprint/db/enums.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export const BLUEPRINT_STATUS = [
+    'draft',
+    'planned',
+    'in-progress',
+    'completed',
+    'parked',
+    'archived',
+];
+export const BLUEPRINT_COMPLEXITY = ['XS', 'S', 'M', 'L', 'XL'];
+export const TASK_STATUS = ['todo', 'in-progress', 'blocked', 'done', 'dropped'];
+export const TECH_DEBT_STATUS = ['accepted', 'needs-remediation', 'monitoring', 'resolved'];
+export const SEVERITY = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
+export const TECH_DEBT_SEVERITY = ['critical', 'high', 'medium', 'low'];
+export const TECH_DEBT_CATEGORY_VALUES = [
+    'documentation',
+    'architecture',
+    'testing',
+    'performance',
+    'security',
+    'maintenance',
+    'dependencies',
+];
+export const REVIEW_CADENCE = ['weekly', 'biweekly', 'monthly', 'quarterly'];
+export const VISIBILITY = ['public', 'private'];
+export const TASK_FILE_OP = ['create', 'modify', 'delete'];
+export const blueprintStatusSchema = z.enum(BLUEPRINT_STATUS);
+export const blueprintComplexitySchema = z.enum(BLUEPRINT_COMPLEXITY);
+export const taskStatusSchema = z.enum(TASK_STATUS);
+export const techDebtStatusSchema = z.enum(TECH_DEBT_STATUS);
+export const severitySchema = z.enum(SEVERITY);
+export const techDebtSeveritySchema = z.enum(TECH_DEBT_SEVERITY);
+export const techDebtCategorySchema = z.enum(TECH_DEBT_CATEGORY_VALUES);
+export const reviewCadenceSchema = z.enum(REVIEW_CADENCE);
+export const visibilitySchema = z.enum(VISIBILITY);
+export const taskFileOpSchema = z.enum(TASK_FILE_OP);
+//# sourceMappingURL=enums.js.map

package/dist/esm/blueprint/db/ingester.d.ts

@@ -0,0 +1,25 @@
+import { Database } from '#db/sqlite.js';
+import type { RunnerEvent } from '#runners/types';
+export interface IngestOptions {
+    readonly db: Database;
+    readonly cwd: string;
+    readonly dryRun?: boolean;
+}
+export interface IngestResult {
+    readonly blueprintsIngested: number;
+    readonly techDebtIngested: number;
+    readonly durationMs: number;
+    readonly errors: string[];
+}
+export declare function ingestBlueprints(opts: IngestOptions): Promise<IngestResult>;
+export declare function ingestTechDebt(opts: IngestOptions): Promise<IngestResult>;
+export declare function ingestAll(opts: IngestOptions): Promise<IngestResult>;
+export interface IngestRunnerEventInput {
+    readonly db: Database;
+    readonly executionHandle: string;
+    readonly sequence: number;
+    readonly event: RunnerEvent;
+    readonly runnerVersion: string;
+}
+export declare function ingestRunnerEvent(input: IngestRunnerEventInput): void;
+//# sourceMappingURL=ingester.d.ts.map