klaus-agent 0.3.0 → 0.4.0

package/src/core/agent-loop.ts

@@ -25,7 +25,7 @@ import type { CompactionConfig } from "../compaction/types.js";
 import type { PlanningManager } from "../planning/planning-manager.js";
 import { PLANNING_TOOL_NAMES } from "../planning/types.js";
 import { executeToolCalls, type ToolCallResult } from "../tools/executor.js";
-import { estimateTokens, shouldCompact, findCutPoint } from "../compaction/compaction.js";
+import { estimateTokens, shouldCompact, findCutPoint, microCompact } from "../compaction/compaction.js";
 import { normalizeHistory } from "../injection/history-normalizer.js";
 import { calculateCost } from "../providers/shared.js";
 
@@ -109,6 +109,7 @@ export async function runAgentLoop(
 
   // Mutable copies of config values that before_agent_start can override
   let { modelId, systemPrompt, thinkingLevel } = config;
+  const keepRecentToolResults = compaction?.keepRecentToolResults ?? 3;
 
   // --- before_agent_start: let extensions modify agent config ---
   if (extensionRunner) {
@@ -251,6 +252,9 @@ export async function runAgentLoop(
           llmMessages = stripImages(llmMessages);
         }
 
+        // --- Micro compaction: shorten old tool results ---
+        llmMessages = microCompact(llmMessages, keepRecentToolResults);
+
         // --- Phase-aware tool filtering ---
         let visibleTools = allTools;
         if (config.planningManager?.phase === "planning" && config.planningManager.allowedInPlanning.size > 2) {

package/src/core/agent.ts

@@ -22,6 +22,7 @@ import type { SkillSource } from "../skills/types.js";
 import type { MCPServerConfig, MCPClient } from "../tools/mcp-adapter.js";
 import type { TaskFactory } from "../background/types.js";
 import type { PlanningConfig } from "../planning/types.js";
+import type { TaskGraphConfig } from "../task-graph/types.js";
 import { SessionManager } from "../session/session-manager.js";
 import { CheckpointManager } from "../checkpoint/checkpoint-manager.js";
 import { InjectionManager } from "../injection/injection-manager.js";
@@ -39,6 +40,9 @@ import { createBackgroundTaskTools } from "../background/tools.js";
 import { PlanningManager } from "../planning/planning-manager.js";
 import { createPlanningTools } from "../planning/tools.js";
 import { PlanningNagProvider } from "../planning/nag-injection.js";
+import { TaskGraph } from "../task-graph/task-graph.js";
+import { createTaskGraphTools } from "../task-graph/tools.js";
+import { TaskResultInjectionProvider } from "../task-graph/result-injection.js";
 import { runAgentLoop } from "./agent-loop.js";
 
 export interface AgentConfig {
@@ -64,6 +68,7 @@ export interface AgentConfig {
   mcp?: { servers: MCPServerConfig[]; clientFactory: (config: MCPServerConfig) => MCPClient };
   wire?: { bufferSize?: number };
   backgroundTasks?: { factories?: Record<string, TaskFactory> };
+  taskGraph?: TaskGraphConfig;
   planning?: PlanningConfig;
 }
 
@@ -89,6 +94,7 @@ export class Agent {
   private _wire: Wire;
   private _backgroundTaskManager: BackgroundTaskManager | undefined;
   private _planningManager: PlanningManager | undefined;
+  private _taskGraph: TaskGraph;
   private _initialized = false;
 
   constructor(config: AgentConfig) {
@@ -156,6 +162,9 @@ export class Agent {
     if (config.planning) {
       this._planningManager = new PlanningManager(config.planning);
     }
+
+    // Task graph
+    this._taskGraph = new TaskGraph(config.taskGraph ?? {});
   }
 
   // --- Public API ---
@@ -253,6 +262,10 @@ export class Agent {
     return this._planningManager;
   }
 
+  get taskGraph(): TaskGraph {
+    return this._taskGraph;
+  }
+
   setSystemPrompt(prompt: string): void {
     this._state.systemPrompt = prompt;
   }
@@ -282,6 +295,7 @@ export class Agent {
     this._followUpQueue = [];
     await this._mcpAdapter?.dispose();
     this._backgroundTaskManager?.dispose();
+    this._taskGraph.dispose();
     this._wire.dispose();
   }
 
@@ -373,12 +387,21 @@ export class Agent {
       this._state.tools = [...this._state.tools, ...createPlanningTools(this._planningManager)];
 
       // Register nag provider into injection manager (create one if needed)
-      const nagProvider = new PlanningNagProvider(this._planningManager);
-      if (this._injectionManager) {
-        this._injectionManager.addProvider(nagProvider);
-      } else {
-        this._injectionManager = new InjectionManager([nagProvider]);
-      }
+      this._addInjectionProvider(new PlanningNagProvider(this._planningManager));
+    }
+
+    // Task graph tools + result auto-injection
+    this._state.tools = [...this._state.tools, ...createTaskGraphTools(this._taskGraph)];
+    if (this._config.taskGraph?.autoInjectResults !== false) {
+      this._addInjectionProvider(new TaskResultInjectionProvider(this._taskGraph));
+    }
+  }
+
+  private _addInjectionProvider(provider: DynamicInjectionProvider): void {
+    if (this._injectionManager) {
+      this._injectionManager.addProvider(provider);
+    } else {
+      this._injectionManager = new InjectionManager([provider]);
     }
   }
 

package/src/index.ts

@@ -16,6 +16,7 @@ import type { SkillSource } from "./skills/types.js";
 import type { MCPServerConfig, MCPClient } from "./tools/mcp-adapter.js";
 import type { TaskFactory } from "./background/types.js";
 import type { PlanningConfig } from "./planning/types.js";
+import type { TaskGraphConfig } from "./task-graph/types.js";
 
 export interface CreateAgentConfig {
   // Required
@@ -43,6 +44,7 @@ export interface CreateAgentConfig {
   wire?: { bufferSize?: number };
   backgroundTasks?: { factories?: Record<string, TaskFactory> };
   planning?: PlanningConfig;
+  taskGraph?: TaskGraphConfig;
 
   // Advanced: provide your own LLM provider
   provider?: LLMProvider;
@@ -74,6 +76,7 @@ export function createAgent(config: CreateAgentConfig): Agent {
     wire: config.wire,
     backgroundTasks: config.backgroundTasks,
     planning: config.planning,
+    taskGraph: config.taskGraph,
   });
 }
 
@@ -98,7 +101,7 @@ export { ExtensionRunner } from "./extensions/runner.js";
 export { discoverSkills } from "./skills/discovery.js";
 export { loadSkill, renderSkillTemplate } from "./skills/loader.js";
 export { MCPAdapter } from "./tools/mcp-adapter.js";
-export { estimateTokens, shouldCompact, findCutPoint } from "./compaction/compaction.js";
+export { estimateTokens, shouldCompact, findCutPoint, microCompact } from "./compaction/compaction.js";
 export { calculateCost } from "./providers/shared.js";
 export { LLMSummarizer } from "./compaction/summarizer.js";
 export { Wire } from "./wire/wire.js";
@@ -107,6 +110,9 @@ export { createBackgroundTaskTools } from "./background/tools.js";
 export { PlanningManager } from "./planning/planning-manager.js";
 export { createPlanningTools } from "./planning/tools.js";
 export { PlanningNagProvider } from "./planning/nag-injection.js";
+export { TaskGraph } from "./task-graph/task-graph.js";
+export { createTaskGraphTools } from "./task-graph/tools.js";
+export { TaskResultInjectionProvider } from "./task-graph/result-injection.js";
 
 // Core types
 export type {
@@ -243,3 +249,12 @@ export type {
 } from "./planning/types.js";
 
 export { PLANNING_TOOL_NAMES } from "./planning/types.js";
+export { TASK_GRAPH_TOOL_NAMES } from "./task-graph/types.js";
+
+// Task graph types
+export type {
+  TaskGraphConfig,
+  TaskNode,
+  TaskStatus,
+  CompletedTaskResult,
+} from "./task-graph/types.js";

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

@@ -0,0 +1,29 @@
+// Auto-inject completed background task results before each LLM call
+
+import type { DynamicInjectionProvider, DynamicInjection } from "../injection/types.js";
+import type { AgentMessage } from "../types.js";
+import type { TaskGraph } from "./task-graph.js";
+
+export class TaskResultInjectionProvider implements DynamicInjectionProvider {
+  constructor(private _graph: TaskGraph) {}
+
+  async getInjections(_history: AgentMessage[]): Promise<DynamicInjection[]> {
+    const completed = this._graph.drainCompleted();
+    if (completed.length === 0) return [];
+
+    const lines = completed.map((c) => {
+      const status = c.status === "completed" ? "completed" : "FAILED";
+      const unblocked = c.unblockedTasks.length > 0
+        ? ` → unblocked: ${c.unblockedTasks.join(", ")}`
+        : "";
+      return `[task:${c.taskId}] ${c.subject} — ${status}: ${c.result}${unblocked}`;
+    });
+
+    return [
+      {
+        type: "task-results",
+        content: `<background-results>\n${lines.join("\n")}\n</background-results>`,
+      },
+    ];
+  }
+}

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