klaus-agent 0.3.1 → 0.4.1

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,10 @@ 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 { resolveProvider } from "../llm/provider.js";
 import { runAgentLoop } from "./agent-loop.js";
 
 export interface AgentConfig {
@@ -64,6 +69,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 +95,8 @@ export class Agent {
   private _wire: Wire;
   private _backgroundTaskManager: BackgroundTaskManager | undefined;
   private _planningManager: PlanningManager | undefined;
+  private _taskGraph: TaskGraph;
+  private _createdSubagents: Agent[] = [];
   private _initialized = false;
 
   constructor(config: AgentConfig) {
@@ -156,6 +164,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 +264,10 @@ export class Agent {
     return this._planningManager;
   }
 
+  get taskGraph(): TaskGraph {
+    return this._taskGraph;
+  }
+
   setSystemPrompt(prompt: string): void {
     this._state.systemPrompt = prompt;
   }
@@ -280,8 +295,12 @@ export class Agent {
     this._listeners.clear();
     this._steeringQueue = [];
     this._followUpQueue = [];
+    await Promise.allSettled(this._createdSubagents.map((sub) => sub.dispose()));
+    this._createdSubagents = [];
+    this._approval.dispose();
     await this._mcpAdapter?.dispose();
     this._backgroundTaskManager?.dispose();
+    this._taskGraph.dispose();
     this._wire.dispose();
   }
 
@@ -289,7 +308,6 @@ export class Agent {
 
   private async _ensureInitialized(): Promise<void> {
     if (this._initialized) return;
-    this._initialized = true;
 
     // Init session and restore messages
     if (this._sessionManager) {
@@ -348,14 +366,17 @@ export class Agent {
     // Init fixed subagents and create TaskTool
     if (this._config.subagents && this._laborMarket && this._taskExecutor) {
       for (const [name, subConfig] of Object.entries(this._config.subagents)) {
+        const subModel = subConfig.model ?? this._config.model;
+        const subProvider = subConfig.model ? resolveProvider(subConfig.model) : this._provider;
         const subAgent = new Agent({
-          model: this._config.model,
+          model: subModel,
           systemPrompt: subConfig.systemPrompt,
           tools: subConfig.tools ?? [],
-          provider: this._provider,
+          provider: subProvider,
           approval: this._approval.share(),
           name,
         });
+        this._createdSubagents.push(subAgent);
         this._laborMarket.addFixed(name, subAgent, subConfig.description);
       }
       // Add built-in TaskTool so LLM can delegate to subagents
@@ -373,12 +394,23 @@ 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));
+    }
+
+    this._initialized = true;
+  }
+
+  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,
   });
 }
 
@@ -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/injection/history-normalizer.ts

@@ -1,6 +1,6 @@
 // History normalizer — merge adjacent user messages
 
-import type { AgentMessage, Message } from "../types.js";
+import type { AgentMessage, Message, ContentBlock } from "../types.js";
 
 export function normalizeHistory(messages: AgentMessage[]): AgentMessage[] {
   if (messages.length <= 1) return messages;
@@ -23,17 +23,27 @@ export function normalizeHistory(messages: AgentMessage[]): AgentMessage[] {
       (prev as Message).role === "user"
     ) {
       const prevMsg = prev as Message & { role: "user" };
-      const prevText = typeof prevMsg.content === "string"
-        ? prevMsg.content
-        : prevMsg.content.filter((b) => b.type === "text").map((b) => (b as { text: string }).text).join("\n");
-      const currentText = typeof current.content === "string"
-        ? current.content
-        : current.content.filter((b) => b.type === "text").map((b) => (b as { text: string }).text).join("\n");
-
-      result[result.length - 1] = {
-        role: "user",
-        content: prevText + "\n" + currentText,
-      };
+      const prevBlocks = typeof prevMsg.content === "string"
+        ? [{ type: "text" as const, text: prevMsg.content }]
+        : prevMsg.content;
+      const currentBlocks = typeof current.content === "string"
+        ? [{ type: "text" as const, text: current.content }]
+        : current.content;
+
+      const merged: ContentBlock[] = [...prevBlocks, ...currentBlocks];
+
+      // Optimize: if all blocks are text, collapse to a single string
+      if (merged.every((b) => b.type === "text")) {
+        result[result.length - 1] = {
+          role: "user",
+          content: merged.map((b) => (b as { text: string }).text).join("\n"),
+        };
+      } else {
+        result[result.length - 1] = {
+          role: "user",
+          content: merged,
+        };
+      }
       continue;
     }
 

package/src/llm/types.ts

@@ -76,6 +76,8 @@ export interface TextBlock {
 export interface ThinkingBlock {
   type: "thinking";
   thinking: string;
+  /** Opaque signature returned by the provider; must be echoed back in subsequent requests. */
+  signature?: string;
 }
 
 export type AssistantContentBlock = TextBlock | ToolCallBlock | ThinkingBlock;

package/src/multi-agent/task-executor.ts

@@ -4,7 +4,7 @@ import type { Agent } from "../core/agent.js";
 import type { LaborMarket } from "./labor-market.js";
 import type { AgentMessage, AgentEvent, AssistantMessage } from "../types.js";
 
-export interface TaskResult {
+interface TaskResult {
   messages: AgentMessage[];
   lastAssistantMessage?: AssistantMessage;
 }

package/src/multi-agent/types.ts

@@ -1,10 +1,13 @@
 // Multi-agent types
 
 import type { AgentTool } from "../tools/types.js";
+import type { ModelConfig } from "../llm/types.js";
 
 export interface SubagentConfig {
   name: string;
   systemPrompt: string | (() => string | Promise<string>);
   tools?: AgentTool[];
   description: string;
+  /** Override the parent agent's model config. If omitted, inherits the parent's model. */
+  model?: ModelConfig;
 }

package/src/planning/planning-manager.ts

@@ -4,6 +4,9 @@ import type { TodoItem, TodoStatus, PlanPhase, PlanningState, PlanningConfig } f
 import { PLANNING_TOOL_NAMES } from "./types.js";
 import { generateId } from "../utils/id.js";
 
+/** Number of built-in tools always added to allowedInPlanning (todo + plan_mode). */
+const BUILT_IN_PLANNING_TOOL_COUNT = Object.keys(PLANNING_TOOL_NAMES).length;
+
 export class PlanningManager {
   private _state: PlanningState;
   private _config: PlanningConfig;
@@ -43,6 +46,11 @@ export class PlanningManager {
     return this._allowedInPlanning;
   }
 
+  /** Whether user configured read-only tools beyond the built-in planning tools. */
+  get hasConfiguredReadOnlyTools(): boolean {
+    return this._allowedInPlanning.size > BUILT_IN_PLANNING_TOOL_COUNT;
+  }
+
   // --- Phase control ---
 
   startExecution(): string {

package/src/providers/anthropic.ts

@@ -11,6 +11,12 @@ import type {
 } from "../llm/types.js";
 import { withRetry, RETRYABLE_PATTERNS, mapThinkingBudget } from "./shared.js";
 
+// Anthropic SDK type extension not yet in published typings
+interface ContentBlockDeltaSignature {
+  type: "signature_delta";
+  signature: string;
+}
+
 export class AnthropicProvider implements LLMProvider {
   private client: Anthropic;
 
@@ -72,70 +78,77 @@ export class AnthropicProvider implements LLMProvider {
     const stream = this.client.messages.stream(params, { signal });
 
     for await (const event of stream) {
-        if (event.type === "content_block_start") {
-          const block = event.content_block;
-          if (block.type === "text") {
-            contentBlocks.push({ type: "text", text: "" });
-          } else if (block.type === "tool_use") {
-            contentBlocks.push({ type: "tool_call", id: block.id, name: block.name, input: {} });
-            toolInputBuffers.set(event.index, "");
-            yield { type: "tool_call_start", id: block.id, name: block.name };
-          } else if (block.type === "thinking") {
-            contentBlocks.push({ type: "thinking", thinking: "" });
-          }
-        } else if (event.type === "content_block_delta") {
-          const delta = event.delta;
-          if (delta.type === "text_delta") {
-            const block = contentBlocks[event.index];
-            if (block && block.type === "text") {
-              block.text += delta.text;
-            }
-            yield { type: "text", text: delta.text };
-          } else if (delta.type === "input_json_delta") {
-            const buf = (toolInputBuffers.get(event.index) ?? "") + delta.partial_json;
-            toolInputBuffers.set(event.index, buf);
-            const block = contentBlocks[event.index];
-            if (block && block.type === "tool_call") {
-              yield { type: "tool_call_delta", id: block.id, input: delta.partial_json };
-            }
-          } else if (delta.type === "thinking_delta") {
-            const block = contentBlocks[event.index];
-            if (block && block.type === "thinking") {
-              block.thinking += delta.thinking;
-            }
-            yield { type: "thinking", thinking: delta.thinking };
+      if (event.type === "content_block_start") {
+        const block = event.content_block;
+        if (block.type === "text") {
+          contentBlocks.push({ type: "text", text: "" });
+        } else if (block.type === "tool_use") {
+          contentBlocks.push({ type: "tool_call", id: block.id, name: block.name, input: {} });
+          toolInputBuffers.set(event.index, "");
+          yield { type: "tool_call_start", id: block.id, name: block.name };
+        } else if (block.type === "thinking") {
+          contentBlocks.push({ type: "thinking", thinking: "" });
+        }
+      } else if (event.type === "content_block_delta") {
+        const delta = event.delta;
+        if (delta.type === "text_delta") {
+          const block = contentBlocks[event.index];
+          if (block && block.type === "text") {
+            block.text += delta.text;
           }
-        } else if (event.type === "content_block_stop") {
+          yield { type: "text", text: delta.text };
+        } else if (delta.type === "input_json_delta") {
+          const buf = (toolInputBuffers.get(event.index) ?? "") + delta.partial_json;
+          toolInputBuffers.set(event.index, buf);
           const block = contentBlocks[event.index];
           if (block && block.type === "tool_call") {
-            const buf = toolInputBuffers.get(event.index) ?? "{}";
-            try {
-              block.input = JSON.parse(buf || "{}");
-            } catch {
-              block.input = {};
-            }
-            toolInputBuffers.delete(event.index);
+            yield { type: "tool_call_delta", id: block.id, input: delta.partial_json };
+          }
+        } else if (delta.type === "thinking_delta") {
+          const block = contentBlocks[event.index];
+          if (block && block.type === "thinking") {
+            block.thinking += delta.thinking;
           }
-        } else if (event.type === "message_delta") {
-          if (event.usage) {
-            usage = {
-              inputTokens: usage.inputTokens,
-              outputTokens: event.usage.output_tokens,
-              totalTokens: usage.inputTokens + event.usage.output_tokens,
-            };
+          yield { type: "thinking", thinking: delta.thinking };
+        } else if ((delta as unknown as ContentBlockDeltaSignature).type === "signature_delta") {
+          const sigDelta = delta as unknown as ContentBlockDeltaSignature;
+          const block = contentBlocks[event.index];
+          if (block && block.type === "thinking") {
+            block.signature = (block.signature ?? "") + sigDelta.signature;
           }
-        } else if (event.type === "message_start") {
-          if (event.message.usage) {
-            usage = {
-              inputTokens: event.message.usage.input_tokens,
-              outputTokens: event.message.usage.output_tokens,
-              totalTokens: event.message.usage.input_tokens + event.message.usage.output_tokens,
-              cacheReadTokens: (event.message.usage as any).cache_read_input_tokens,
-              cacheWriteTokens: (event.message.usage as any).cache_creation_input_tokens,
-            };
+        }
+      } else if (event.type === "content_block_stop") {
+        const block = contentBlocks[event.index];
+        if (block && block.type === "tool_call") {
+          const buf = toolInputBuffers.get(event.index) ?? "{}";
+          try {
+            block.input = JSON.parse(buf || "{}");
+          } catch {
+            block.input = {};
           }
+          toolInputBuffers.delete(event.index);
+        }
+      } else if (event.type === "message_delta") {
+        if (event.usage) {
+          usage = {
+            inputTokens: usage.inputTokens,
+            outputTokens: event.usage.output_tokens,
+            totalTokens: usage.inputTokens + event.usage.output_tokens,
+          };
+        }
+      } else if (event.type === "message_start") {
+        if (event.message.usage) {
+          const u = event.message.usage;
+          usage = {
+            inputTokens: u.input_tokens,
+            outputTokens: u.output_tokens,
+            totalTokens: u.input_tokens + u.output_tokens,
+            cacheReadTokens: u.cache_read_input_tokens ?? undefined,
+            cacheWriteTokens: u.cache_creation_input_tokens ?? undefined,
+          };
         }
       }
+    }
 
     const message: AssistantMessage = { role: "assistant", content: contentBlocks };
     yield { type: "done", message, usage };
@@ -179,7 +192,7 @@ function mapAssistantBlock(block: AssistantContentBlock): Anthropic.ContentBlock
     return { type: "tool_use", id: block.id, name: block.name, input: block.input };
   }
   if (block.type === "thinking") {
-    return { type: "thinking", thinking: block.thinking, signature: "" };
+    return { type: "thinking", thinking: block.thinking, signature: block.signature ?? "" };
   }
   return { type: "text", text: JSON.stringify(block) };
 }

package/src/providers/google.ts

@@ -49,7 +49,7 @@ export class GeminiProvider implements LLMProvider {
           maxOutputTokens: maxTokens ?? 8192,
           ...(thinkingBudget ? {
             thinkingConfig: { thinkingBudget },
-          } as any : {}),
+          } as Record<string, unknown> : {}),
         },
       },
       this.baseUrl ? { baseUrl: this.baseUrl } : undefined,

package/src/providers/openai-codex.ts

@@ -291,6 +291,8 @@ function mapReasoningEffort(modelId: string, level?: ThinkingLevel): string | un
 
 // --- SSE parsing ---
 
+const MAX_SSE_BUFFER_BYTES = 1024 * 1024; // 1MB cap to prevent unbounded accumulation
+
 async function* parseSSE(response: Response): AsyncGenerator<Record<string, unknown>> {
   if (!response.body) return;
 
@@ -304,6 +306,10 @@ async function* parseSSE(response: Response): AsyncGenerator<Record<string, unkn
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
 
+      if (buffer.length > MAX_SSE_BUFFER_BYTES) {
+        throw new Error(`SSE buffer exceeded ${MAX_SSE_BUFFER_BYTES} bytes — aborting to prevent unbounded memory growth`);
+      }
+
       let idx = buffer.indexOf("\n\n");
       while (idx !== -1) {
         const chunk = buffer.slice(0, idx);
@@ -326,8 +332,7 @@ async function* parseSSE(response: Response): AsyncGenerator<Record<string, unkn
       }
     }
   } finally {
-    try { await reader.cancel(); } catch { /* ignore */ }
-    try { reader.releaseLock(); } catch { /* ignore */ }
+    reader.cancel().catch(() => {});
   }
 }
 

package/src/providers/openai.ts

@@ -8,11 +8,15 @@ import type {
   AssistantMessage,
   AssistantContentBlock,
   TokenUsage,
-  ThinkingLevel,
   Message,
 } from "../llm/types.js";
 import { withRetry, RETRYABLE_PATTERNS, mapReasoningEffort } from "./shared.js";
 
+// OpenAI o1/o3 reasoning content not yet in published typings
+interface DeltaWithReasoning {
+  reasoning_content?: string;
+}
+
 export class OpenAIProvider implements LLMProvider {
   private client: OpenAI;
 
@@ -75,8 +79,9 @@ export class OpenAIProvider implements LLMProvider {
         }
 
         // Reasoning/thinking content (o1/o3 series)
-        if ((delta as any).reasoning_content) {
-          const thinking = (delta as any).reasoning_content as string;
+        const reasoningContent = (delta as unknown as DeltaWithReasoning).reasoning_content;
+        if (reasoningContent) {
+          const thinking = reasoningContent;
           if (contentBlocks.length === 0 || contentBlocks[contentBlocks.length - 1].type !== "thinking") {
             contentBlocks.push({ type: "thinking", thinking: "" });
           }

package/src/providers/shared.ts

@@ -12,13 +12,14 @@ export const RETRYABLE_PATTERNS: Record<string, string[]> = {
   codex: [...COMMON_RETRYABLE, "rate_limit", "usage_limit", "overloaded"],
 };
 
-export function isRetryableError(error: Error, patterns: string[]): boolean {
+function isRetryableError(error: Error, patterns: string[]): boolean {
   return patterns.some((p) => error.message.includes(p));
 }
 
 /**
  * Wraps a streaming generator with exponential backoff retry logic.
- * Only retries on connection-level failures before streaming starts.
+ * Only retries on connection-level failures before any events have been yielded.
+ * Once streaming starts (first event yielded), errors are not retried to avoid duplicate output.
  */
 export async function* withRetry(
   streamOnce: () => AsyncIterable<AssistantMessageEvent>,
@@ -33,15 +34,19 @@ export async function* withRetry(
       await new Promise((r) => setTimeout(r, delay));
     }
 
+    let hasYielded = false;
     try {
-      yield* streamOnce();
+      for await (const event of streamOnce()) {
+        hasYielded = true;
+        yield event;
+      }
       return;
     } catch (err) {
       lastError = err instanceof Error ? err : new Error(String(err));
 
-      if (!isRetryableError(lastError, retryablePatterns) || attempt === maxRetries) {
-        yield { type: "error", error: lastError };
-        return;
+      // If we already yielded events, don't retry — caller has consumed partial output
+      if (hasYielded || !isRetryableError(lastError, retryablePatterns) || attempt === maxRetries) {
+        throw lastError;
       }
     }
   }

package/src/session/session-manager.ts

@@ -247,12 +247,23 @@ export class SessionManager {
       this._sessionId = (header as SessionHeader).id;
     }
 
-    // Rest are entries
+    // Rest are entries — validate required fields before accepting
     for (let i = 1; i < records.length; i++) {
-      const entry = records[i] as SessionEntry;
-      this._entries.push(entry);
-      this._entriesById.set(entry.id, entry);
+      const entry = records[i];
+      if (!this._isValidEntry(entry)) continue;
+      this._entries.push(entry as SessionEntry);
+      this._entriesById.set(entry.id, entry as SessionEntry);
       this._leafId = entry.id;
     }
   }
+
+  private _isValidEntry(record: unknown): record is SessionEntry {
+    if (!record || typeof record !== "object") return false;
+    const r = record as Record<string, unknown>;
+    return (
+      typeof r.type === "string" &&
+      typeof r.id === "string" &&
+      typeof r.timestamp === "string"
+    );
+  }
 }

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