klaus-agent 0.3.1 → 0.4.0

package/src/task-graph/task-graph.ts

@@ -0,0 +1,270 @@
+// Task graph — dependency-aware DAG with background execution and auto-unlock
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "fs";
+import { join } from "path";
+import { generateId } from "../utils/id.js";
+import type { TaskNode, TaskStatus, TaskGraphConfig, CompletedTaskResult } from "./types.js";
+
+export class TaskGraph {
+  private _tasks = new Map<string, TaskNode>();
+  private _config: TaskGraphConfig;
+  private _completedQueue: CompletedTaskResult[] = [];
+  private _backgroundAborts = new Map<string, AbortController>();
+
+  constructor(config: TaskGraphConfig = {}) {
+    this._config = config;
+    if (config.persistDir) {
+      mkdirSync(config.persistDir, { recursive: true });
+      this._loadFromDisk();
+    }
+  }
+
+
+  get(id: string): TaskNode | undefined {
+    const task = this._tasks.get(id);
+    return task ? { ...task } : undefined;
+  }
+
+  listAll(): TaskNode[] {
+    return [...this._tasks.values()];
+  }
+
+  /** Tasks that are pending with no unfinished blockers. */
+  listReady(): TaskNode[] {
+    return this.listAll().filter(
+      (t) => t.status === "pending" && t.blockedBy.length === 0,
+    );
+  }
+
+  /** Tasks waiting on unfinished blockers. */
+  listBlocked(): TaskNode[] {
+    return this.listAll().filter(
+      (t) => t.status === "pending" && t.blockedBy.length > 0,
+    );
+  }
+
+
+  create(subject: string, description = ""): TaskNode {
+    const max = this._config.maxTasks ?? 100;
+    if (this._tasks.size >= max) {
+      throw new Error(`Task limit reached: ${max}.`);
+    }
+
+    const node: TaskNode = {
+      id: generateId(),
+      subject,
+      description,
+      status: "pending",
+      blockedBy: [],
+      blocks: [],
+      owner: "",
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    this._tasks.set(node.id, node);
+    this._persist();
+    return { ...node };
+  }
+
+  /** Add a dependency: `taskId` is blocked by `blockedById`. */
+  addDependency(taskId: string, blockedById: string): void {
+    const task = this._require(taskId);
+    const blocker = this._require(blockedById);
+
+    if (task.blockedBy.includes(blockedById)) return;
+
+    // Cycle detection: if blocker is (transitively) blocked by task, adding this edge creates a cycle
+    if (this._isTransitivelyBlockedBy(blockedById, taskId)) {
+      throw new Error(`Adding dependency ${blockedById} → ${taskId} would create a cycle.`);
+    }
+
+    task.blockedBy.push(blockedById);
+    blocker.blocks.push(taskId);
+    task.updatedAt = Date.now();
+    blocker.updatedAt = Date.now();
+    this._persist();
+  }
+
+  update(taskId: string, fields: { status?: TaskStatus; owner?: string; result?: string }): TaskNode {
+    const task = this._require(taskId);
+
+    if (fields.status !== undefined && fields.status !== task.status) {
+      if (fields.status === "in_progress" && task.blockedBy.length > 0) {
+        throw new Error(`Task ${taskId} is blocked by: ${task.blockedBy.join(", ")}`);
+      }
+      task.status = fields.status;
+
+      if (fields.status === "completed" || fields.status === "failed") {
+        task.result = fields.result ?? task.result;
+        const unblocked = this._clearDependency(taskId);
+
+        this._completedQueue.push({
+          taskId,
+          subject: task.subject,
+          result: task.result ?? "",
+          status: fields.status,
+          unblockedTasks: unblocked,
+        });
+      }
+    }
+
+    if (fields.owner !== undefined) task.owner = fields.owner;
+    // result is already set inside the completion branch above; only apply here for non-completion updates
+    if (fields.result !== undefined && task.status !== "completed" && task.status !== "failed") {
+      task.result = fields.result;
+    }
+    task.updatedAt = Date.now();
+    this._persist();
+    return { ...task };
+  }
+
+
+  /**
+   * Run an async function in the background for a task.
+   * Auto-updates task status to in_progress/completed/failed.
+   */
+  runBackground(
+    taskId: string,
+    fn: (signal: AbortSignal) => Promise<string>,
+  ): void {
+    const task = this._require(taskId);
+    if (task.blockedBy.length > 0) {
+      throw new Error(`Task ${taskId} is blocked by: ${task.blockedBy.join(", ")}`);
+    }
+
+    const ac = new AbortController();
+    const bgId = generateId();
+    task.status = "in_progress";
+    task.backgroundId = bgId;
+    task.updatedAt = Date.now();
+    this._backgroundAborts.set(bgId, ac);
+    this._persist();
+
+    fn(ac.signal).then(
+      (result) => {
+        this._backgroundAborts.delete(bgId);
+        try { this.update(taskId, { status: "completed", result }); } catch { /* task may have been removed */ }
+      },
+      (err) => {
+        this._backgroundAborts.delete(bgId);
+        try {
+          this.update(taskId, {
+            status: "failed",
+            result: err instanceof Error ? err.message : String(err),
+          });
+        } catch { /* task may have been removed */ }
+      },
+    );
+  }
+
+  abortBackground(taskId: string): boolean {
+    const task = this._tasks.get(taskId);
+    if (!task?.backgroundId) return false;
+    const ac = this._backgroundAborts.get(task.backgroundId);
+    if (!ac) return false;
+    ac.abort();
+    return true;
+  }
+
+
+  drainCompleted(): CompletedTaskResult[] {
+    const results = [...this._completedQueue];
+    this._completedQueue = [];
+    return results;
+  }
+
+
+  render(): string {
+    const tasks = this.listAll();
+    if (tasks.length === 0) return "No tasks.";
+
+    const lines = tasks.map((t) => {
+      const icon = t.status === "completed" ? "[x]"
+        : t.status === "failed" ? "[!]"
+        : t.status === "in_progress" ? "[>]"
+        : t.blockedBy.length > 0 ? "[~]"
+        : "[ ]";
+      const deps = t.blockedBy.length > 0 ? ` (blocked by: ${t.blockedBy.join(", ")})` : "";
+      return `${icon} ${t.id}: ${t.subject}${deps}`;
+    });
+
+    const done = tasks.filter((t) => t.status === "completed").length;
+    const ready = tasks.filter((t) => t.status === "pending" && t.blockedBy.length === 0).length;
+    return `Tasks: ${done}/${tasks.length} done, ${ready} ready\n${lines.join("\n")}`;
+  }
+
+  dispose(): void {
+    for (const ac of this._backgroundAborts.values()) {
+      ac.abort();
+    }
+    this._backgroundAborts.clear();
+  }
+
+
+  private _require(id: string): TaskNode {
+    const task = this._tasks.get(id);
+    if (!task) throw new Error(`Task not found: ${id}`);
+    return task;
+  }
+
+  /** Remove completedId from all tasks' blockedBy. Returns IDs of newly unblocked tasks. */
+  private _clearDependency(completedId: string): string[] {
+    const completed = this._tasks.get(completedId);
+    if (!completed) return [];
+
+    const unblocked: string[] = [];
+    for (const dependentId of completed.blocks) {
+      const task = this._tasks.get(dependentId);
+      if (!task) continue;
+      const idx = task.blockedBy.indexOf(completedId);
+      if (idx !== -1) {
+        task.blockedBy.splice(idx, 1);
+        if (task.blockedBy.length === 0 && task.status === "pending") {
+          unblocked.push(task.id);
+        }
+      }
+    }
+    return unblocked;
+  }
+
+  /** Check if `taskId` is transitively blocked by `targetId`. */
+  private _isTransitivelyBlockedBy(taskId: string, targetId: string): boolean {
+    const visited = new Set<string>();
+    const stack = [taskId];
+    while (stack.length > 0) {
+      const current = stack.pop()!;
+      if (current === targetId) return true;
+      if (visited.has(current)) continue;
+      visited.add(current);
+      const node = this._tasks.get(current);
+      if (node) stack.push(...node.blockedBy);
+    }
+    return false;
+  }
+
+  private _persist(): void {
+    if (!this._config.persistDir) return;
+    const data = JSON.stringify([...this._tasks.values()], null, 2);
+    const target = join(this._config.persistDir, "tasks.json");
+    const tmp = target + ".tmp";
+    writeFileSync(tmp, data, "utf-8");
+    renameSync(tmp, target);
+  }
+
+  private _loadFromDisk(): void {
+    if (!this._config.persistDir) return;
+    const filePath = join(this._config.persistDir, "tasks.json");
+    if (!existsSync(filePath)) return;
+    try {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (!Array.isArray(raw)) return;
+      for (const entry of raw) {
+        if (entry && typeof entry === "object" && typeof entry.id === "string" && typeof entry.subject === "string") {
+          this._tasks.set(entry.id, entry as TaskNode);
+        }
+      }
+    } catch {
+      // Corrupted file — start fresh
+    }
+  }
+}

package/src/task-graph/tools.ts

@@ -0,0 +1,109 @@
+// Task graph tools — CRUD + dependency management + background execution
+
+import { Type } from "@sinclair/typebox";
+import type { AgentTool, AgentToolResult } from "../tools/types.js";
+import type { TaskGraph } from "./task-graph.js";
+import { TASK_GRAPH_TOOL_NAMES } from "./types.js";
+import type { TaskStatus, TaskNode } from "./types.js";
+
+export function createTaskGraphTools(graph: TaskGraph): AgentTool[] {
+  return [
+    {
+      name: TASK_GRAPH_TOOL_NAMES.create,
+      label: "Create Task",
+      description:
+        "Create a new task in the task graph. Tasks start as pending. " +
+        "Use task_depend to set up dependency ordering.",
+      parameters: Type.Object({
+        subject: Type.String({ description: "Short title for the task." }),
+        description: Type.Optional(Type.String({ description: "Detailed description." })),
+      }),
+      async execute(_id, params: { subject: string; description?: string }): Promise<AgentToolResult> {
+        const task = graph.create(params.subject, params.description);
+        return text(`Created task ${task.id}: ${task.subject}\n\n${graph.render()}`);
+      },
+    },
+    {
+      name: TASK_GRAPH_TOOL_NAMES.depend,
+      label: "Add Task Dependency",
+      description:
+        "Add a dependency: task_id cannot start until blocked_by_id completes. " +
+        "Rejects if this would create a cycle.",
+      parameters: Type.Object({
+        task_id: Type.String({ description: "Task that is blocked." }),
+        blocked_by_id: Type.String({ description: "Task that must complete first." }),
+      }),
+      async execute(_id, params: { task_id: string; blocked_by_id: string }): Promise<AgentToolResult> {
+        graph.addDependency(params.task_id, params.blocked_by_id);
+        return text(`Dependency added: ${params.task_id} blocked by ${params.blocked_by_id}\n\n${graph.render()}`);
+      },
+    },
+    {
+      name: TASK_GRAPH_TOOL_NAMES.update,
+      label: "Update Task",
+      description:
+        "Update a task's status, owner, or result. " +
+        "Setting status to 'completed' auto-unblocks dependent tasks. " +
+        "Cannot start a task that has unfinished blockers.",
+      parameters: Type.Object({
+        task_id: Type.String({ description: "Task ID." }),
+        status: Type.Optional(Type.Union(
+          [Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed"), Type.Literal("failed")],
+          { description: "New status." },
+        )),
+        owner: Type.Optional(Type.String({ description: "Assign to an agent or user." })),
+        result: Type.Optional(Type.String({ description: "Result summary." })),
+      }),
+      async execute(_id, params: { task_id: string; status?: string; owner?: string; result?: string }): Promise<AgentToolResult> {
+        const task = graph.update(params.task_id, {
+          status: params.status as TaskStatus | undefined,
+          owner: params.owner,
+          result: params.result,
+        });
+        return text(`Updated task ${task.id}\n\n${graph.render()}`);
+      },
+    },
+    {
+      name: TASK_GRAPH_TOOL_NAMES.list,
+      label: "List Tasks",
+      description: "List all tasks with their status, dependencies, and progress.",
+      parameters: Type.Object({
+        filter: Type.Optional(Type.Union(
+          [Type.Literal("all"), Type.Literal("ready"), Type.Literal("blocked"), Type.Literal("in_progress"), Type.Literal("completed")],
+          { description: "Filter tasks by category. Default: all." },
+        )),
+      }),
+      async execute(_id, params: { filter?: string }): Promise<AgentToolResult> {
+        let tasks: TaskNode[];
+        switch (params.filter) {
+          case "ready": tasks = graph.listReady(); break;
+          case "blocked": tasks = graph.listBlocked(); break;
+          case "in_progress": tasks = graph.listAll().filter((t) => t.status === "in_progress"); break;
+          case "completed": tasks = graph.listAll().filter((t) => t.status === "completed"); break;
+          default: tasks = graph.listAll();
+        }
+        if (tasks.length === 0) return text(`No tasks matching filter: ${params.filter ?? "all"}`);
+        if (!params.filter || params.filter === "all") return text(graph.render());
+        const lines = tasks.map((t) => `${t.id}: ${t.subject} [${t.status}]`);
+        return text(`${params.filter}: ${tasks.length} task(s)\n${lines.join("\n")}`);
+      },
+    },
+    {
+      name: TASK_GRAPH_TOOL_NAMES.get,
+      label: "Get Task",
+      description: "Get detailed information about a specific task.",
+      parameters: Type.Object({
+        task_id: Type.String({ description: "Task ID." }),
+      }),
+      async execute(_id, params: { task_id: string }): Promise<AgentToolResult> {
+        const task = graph.get(params.task_id);
+        if (!task) return text(`Task not found: ${params.task_id}`);
+        return text(JSON.stringify(task, null, 2));
+      },
+    },
+  ];
+}
+
+function text(t: string): AgentToolResult {
+  return { content: [{ type: "text", text: t }] };
+}

package/src/task-graph/types.ts

@@ -0,0 +1,52 @@
+// Task graph types — dependency-aware task DAG with background execution
+
+export const TASK_GRAPH_TOOL_NAMES = {
+  create: "task_create",
+  depend: "task_depend",
+  update: "task_update",
+  list: "task_list",
+  get: "task_get",
+} as const;
+
+export type TaskStatus = "pending" | "in_progress" | "completed" | "failed";
+
+export interface TaskNode {
+  id: string;
+  subject: string;
+  description: string;
+  status: TaskStatus;
+  /** IDs of tasks that must complete before this one can start. */
+  blockedBy: string[];
+  /** IDs of tasks that this task blocks (reverse edges, maintained automatically). */
+  blocks: string[];
+  /** Agent or user assigned to this task. */
+  owner: string;
+  /** Result summary after completion/failure. */
+  result?: string;
+  /** Background execution handle ID, if running in background. */
+  backgroundId?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface TaskGraphConfig {
+  /** Directory for persisting task graph to disk. If omitted, in-memory only. */
+  persistDir?: string;
+
+  /** Maximum number of tasks. Default: 100. */
+  maxTasks?: number;
+
+  /**
+   * Auto-inject completed background task results before each LLM call.
+   * Default: true.
+   */
+  autoInjectResults?: boolean;
+}
+
+export interface CompletedTaskResult {
+  taskId: string;
+  subject: string;
+  result: string;
+  status: "completed" | "failed";
+  unblockedTasks: string[];
+}