klaus-agent 0.4.0 → 0.4.1

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/task-graph.ts

@@ -1,6 +1,7 @@
 // Task graph — dependency-aware DAG with background execution and auto-unlock
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "fs";
+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";
@@ -22,11 +23,15 @@ export class TaskGraph {
 
   get(id: string): TaskNode | undefined {
     const task = this._tasks.get(id);
-    return task ? { ...task } : undefined;
+    return task ? { ...task, blockedBy: [...task.blockedBy], blocks: [...task.blocks] } : undefined;
   }
 
   listAll(): TaskNode[] {
-    return [...this._tasks.values()];
+    return [...this._tasks.values()].map((t) => ({
+      ...t,
+      blockedBy: [...t.blockedBy],
+      blocks: [...t.blocks],
+    }));
   }
 
   /** Tasks that are pending with no unfinished blockers. */
@@ -63,7 +68,7 @@ export class TaskGraph {
     };
     this._tasks.set(node.id, node);
     this._persist();
-    return { ...node };
+    return { ...node, blockedBy: [...node.blockedBy], blocks: [...node.blocks] };
   }
 
   /** Add a dependency: `taskId` is blocked by `blockedById`. */
@@ -115,7 +120,7 @@ export class TaskGraph {
     }
     task.updatedAt = Date.now();
     this._persist();
-    return { ...task };
+    return { ...task, blockedBy: [...task.blockedBy], blocks: [...task.blocks] };
   }
 
 
@@ -242,13 +247,20 @@ export class TaskGraph {
     return false;
   }
 
+  private _persistPromise: Promise<void> = Promise.resolve();
+
   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);
+    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 {
@@ -259,12 +271,28 @@ export class TaskGraph {
       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);
-        }
+        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/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;
 }