klaus-agent 0.3.1 → 0.4.1

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

@@ -0,0 +1,298 @@
+// Task graph — dependency-aware DAG with background execution and auto-unlock
+
+import { readFileSync, mkdirSync, existsSync } from "fs";
+import { writeFile, rename } from "fs/promises";
+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, blockedBy: [...task.blockedBy], blocks: [...task.blocks] } : undefined;
+  }
+
+  listAll(): TaskNode[] {
+    return [...this._tasks.values()].map((t) => ({
+      ...t,
+      blockedBy: [...t.blockedBy],
+      blocks: [...t.blocks],
+    }));
+  }
+
+  /** 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, blockedBy: [...node.blockedBy], blocks: [...node.blocks] };
+  }
+
+  /** 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, blockedBy: [...task.blockedBy], blocks: [...task.blocks] };
+  }
+
+
+  /**
+   * 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 _persistPromise: Promise<void> = Promise.resolve();
+
+  private _persist(): void {
+    if (!this._config.persistDir) return;
+    const dir = this._config.persistDir;
+    const tasks = [...this._tasks.values()];
+    this._persistPromise = this._persistPromise
+      .then(() => {
+        const data = JSON.stringify(tasks, null, 2);
+        const target = join(dir, "tasks.json");
+        const tmp = target + ".tmp";
+        return writeFile(tmp, data, "utf-8").then(() => rename(tmp, target));
+      })
+      .catch(() => { /* persist failure is non-fatal */ });
+  }
+
+  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 (!this._isValidTaskNode(entry)) continue;
+        this._tasks.set(entry.id, entry as TaskNode);
+      }
+    } catch {
+      // Corrupted file — start fresh
+    }
+  }
+
+  private static readonly _validStatuses = new Set(["pending", "in_progress", "completed", "failed"]);
+
+  private _isValidTaskNode(entry: unknown): entry is TaskNode {
+    if (!entry || typeof entry !== "object") return false;
+    const e = entry as Record<string, unknown>;
+    return (
+      typeof e.id === "string" &&
+      typeof e.subject === "string" &&
+      typeof e.status === "string" &&
+      TaskGraph._validStatuses.has(e.status as string) &&
+      Array.isArray(e.blockedBy) &&
+      Array.isArray(e.blocks) &&
+      typeof e.createdAt === "number" &&
+      typeof e.updatedAt === "number"
+    );
+  }
+}

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[];
+}

package/src/tools/executor.ts

@@ -5,7 +5,7 @@ import type { ToolCallBlock, TextContent } from "../llm/types.js";
 import type { Approval } from "../approval/types.js";
 import { Value } from "@sinclair/typebox/value";
 
-export interface ToolExecutorConfig {
+interface ToolExecutorConfig {
   tools: AgentTool[];
   mode: "sequential" | "parallel";
   approval: Approval;
@@ -16,7 +16,7 @@ export interface ToolExecutorConfig {
   onEvent: (event: ToolExecutorEvent) => void;
 }
 
-export type ToolExecutorEvent =
+type ToolExecutorEvent =
   | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown }
   | { type: "tool_execution_update"; toolCallId: string; toolName: string; partialResult: AgentToolResult }
   | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: AgentToolResult; isError: boolean };

package/src/tools/mcp-adapter.ts

@@ -156,17 +156,33 @@ export class MCPAdapter {
         // Approval is handled by the executor via approvalAction field
         // No need to request approval here
 
-        // Call with timeout
+        // Call with timeout and abort signal support
         const callPromise = client.callTool(def.name, params);
         let result: MCPToolResult;
 
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let abortHandler: (() => void) | undefined;
+        const racers: Promise<MCPToolResult>[] = [callPromise];
+
         if (timeout) {
-          const timeoutPromise = new Promise<never>((_, reject) =>
-            setTimeout(() => reject(new Error(`MCP tool ${def.name} timed out after ${timeout}ms`)), timeout),
-          );
-          result = await Promise.race([callPromise, timeoutPromise]);
-        } else {
-          result = await callPromise;
+          racers.push(new Promise<never>((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`MCP tool ${def.name} timed out after ${timeout}ms`)), timeout);
+          }));
+        }
+
+        if (context.signal.aborted) throw new Error("Aborted");
+        racers.push(new Promise<never>((_, reject) => {
+          abortHandler = () => reject(new Error("Aborted"));
+          context.signal.addEventListener("abort", abortHandler, { once: true });
+        }));
+
+        try {
+          result = await Promise.race(racers);
+        } finally {
+          if (timer !== undefined) clearTimeout(timer);
+          if (abortHandler) {
+            context.signal.removeEventListener("abort", abortHandler);
+          }
         }
 
         // Convert MCP result to AgentToolResult

package/src/utils/id.ts

@@ -1,8 +1,5 @@
+import { randomBytes } from "node:crypto";
+
 export function generateId(): string {
-  const chars = "0123456789abcdefghijklmnopqrstuvwxyz";
-  let id = "";
-  for (let i = 0; i < 12; i++) {
-    id += chars[Math.floor(Math.random() * chars.length)];
-  }
-  return id;
+  return randomBytes(9).toString("base64url").slice(0, 12);
 }

package/src/wire/wire.ts

@@ -3,7 +3,7 @@
 import { generateId } from "../utils/id.js";
 import type { WireMessage, WireSubscriber, WireSubscription } from "./types.js";
 
-export interface WireOptions {
+interface WireOptions {
   /** Max messages to buffer for replay to late subscribers. 0 = no buffering. */
   bufferSize?: number;
 }