klaus-agent 0.2.2 → 0.3.1

package/src/core/agent.ts

@@ -21,6 +21,7 @@ import type { SubagentConfig } from "../multi-agent/types.js";
 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 { SessionManager } from "../session/session-manager.js";
 import { CheckpointManager } from "../checkpoint/checkpoint-manager.js";
 import { InjectionManager } from "../injection/injection-manager.js";
@@ -35,6 +36,9 @@ import { LLMSummarizer, agentMessagesToCompactionInput } from "../compaction/sum
 import { Wire } from "../wire/wire.js";
 import { BackgroundTaskManager } from "../background/task-manager.js";
 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 { runAgentLoop } from "./agent-loop.js";
 
 export interface AgentConfig {
@@ -60,6 +64,7 @@ export interface AgentConfig {
   mcp?: { servers: MCPServerConfig[]; clientFactory: (config: MCPServerConfig) => MCPClient };
   wire?: { bufferSize?: number };
   backgroundTasks?: { factories?: Record<string, TaskFactory> };
+  planning?: PlanningConfig;
 }
 
 export class Agent {
@@ -83,6 +88,7 @@ export class Agent {
   private _mcpAdapter: MCPAdapter | undefined;
   private _wire: Wire;
   private _backgroundTaskManager: BackgroundTaskManager | undefined;
+  private _planningManager: PlanningManager | undefined;
   private _initialized = false;
 
   constructor(config: AgentConfig) {
@@ -145,6 +151,11 @@ export class Agent {
         }
       });
     }
+
+    // Planning
+    if (config.planning) {
+      this._planningManager = new PlanningManager(config.planning);
+    }
   }
 
   // --- Public API ---
@@ -238,6 +249,10 @@ export class Agent {
     return this._backgroundTaskManager;
   }
 
+  get planning(): PlanningManager | undefined {
+    return this._planningManager;
+  }
+
   setSystemPrompt(prompt: string): void {
     this._state.systemPrompt = prompt;
   }
@@ -352,6 +367,19 @@ export class Agent {
       const bgTools = createBackgroundTaskTools(this._backgroundTaskManager, this._config.backgroundTasks?.factories);
       this._state.tools = [...this._state.tools, ...bgTools];
     }
+
+    // Planning tools + nag injection
+    if (this._planningManager) {
+      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]);
+      }
+    }
   }
 
   private _normalizeInput(input: string | AgentMessage | AgentMessage[]): AgentMessage[] {
@@ -430,6 +458,7 @@ export class Agent {
         injectionManager: this._injectionManager,
         extensionRunner: this._extensionRunner,
         compaction: compactionWithSummarizer,
+        planningManager: this._planningManager,
       });
 
       this._state.messages = result;

package/src/index.ts

@@ -15,6 +15,7 @@ import type { SubagentConfig } from "./multi-agent/types.js";
 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";
 
 export interface CreateAgentConfig {
   // Required
@@ -41,6 +42,7 @@ export interface CreateAgentConfig {
   mcp?: { servers: MCPServerConfig[]; clientFactory: (config: MCPServerConfig) => MCPClient };
   wire?: { bufferSize?: number };
   backgroundTasks?: { factories?: Record<string, TaskFactory> };
+  planning?: PlanningConfig;
 
   // Advanced: provide your own LLM provider
   provider?: LLMProvider;
@@ -71,6 +73,7 @@ export function createAgent(config: CreateAgentConfig): Agent {
     mcp: config.mcp,
     wire: config.wire,
     backgroundTasks: config.backgroundTasks,
+    planning: config.planning,
   });
 }
 
@@ -95,12 +98,15 @@ 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";
 export { BackgroundTaskManager } from "./background/task-manager.js";
 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";
 
 // Core types
 export type {
@@ -227,3 +233,13 @@ export type {
   BackgroundTaskEvent,
   TaskFactory,
 } from "./background/types.js";
+
+// Planning types
+export type {
+  PlanningConfig,
+  PlanPhase,
+  TodoItem,
+  TodoStatus,
+} from "./planning/types.js";
+
+export { PLANNING_TOOL_NAMES } from "./planning/types.js";

package/src/planning/nag-injection.ts

@@ -0,0 +1,24 @@
+// Nag injection provider — reminds model to update todos when it hasn't for N rounds
+
+import type { DynamicInjectionProvider, DynamicInjection } from "../injection/types.js";
+import type { AgentMessage } from "../types.js";
+import type { PlanningManager } from "./planning-manager.js";
+
+export class PlanningNagProvider implements DynamicInjectionProvider {
+  constructor(private _manager: PlanningManager) {}
+
+  async getInjections(_history: AgentMessage[]): Promise<DynamicInjection[]> {
+    if (!this._manager.shouldNag()) return [];
+
+    // Reset after check so the next nag waits another N rounds.
+    // Kept here (not in shouldNag) so shouldNag() stays side-effect-free.
+    this._manager.resetRoundCounter();
+
+    return [
+      {
+        type: "planning-nag",
+        content: this._manager.getNagMessage(),
+      },
+    ];
+  }
+}

package/src/planning/planning-manager.ts

@@ -0,0 +1,133 @@
+// Planning manager — two-phase planning with structured todo tracking
+
+import type { TodoItem, TodoStatus, PlanPhase, PlanningState, PlanningConfig } from "./types.js";
+import { PLANNING_TOOL_NAMES } from "./types.js";
+import { generateId } from "../utils/id.js";
+
+export class PlanningManager {
+  private _state: PlanningState;
+  private _config: PlanningConfig;
+  private _allowedInPlanning: ReadonlySet<string>;
+
+  constructor(config: PlanningConfig = {}) {
+    this._config = config;
+    const allowed = new Set(config.readOnlyTools ?? []);
+    allowed.add(PLANNING_TOOL_NAMES.todo);
+    allowed.add(PLANNING_TOOL_NAMES.planMode);
+    this._allowedInPlanning = allowed;
+    this._state = {
+      phase: "planning",
+      todos: [],
+      roundsSinceTodoUpdate: 0,
+    };
+  }
+
+  get phase(): PlanPhase {
+    return this._state.phase;
+  }
+
+  get todos(): readonly Readonly<TodoItem>[] {
+    return this._state.todos;
+  }
+
+  get roundsSinceTodoUpdate(): number {
+    return this._state.roundsSinceTodoUpdate;
+  }
+
+  get config(): Readonly<PlanningConfig> {
+    return this._config;
+  }
+
+  /** Pre-built set of tool names allowed during planning phase. */
+  get allowedInPlanning(): ReadonlySet<string> {
+    return this._allowedInPlanning;
+  }
+
+  // --- Phase control ---
+
+  startExecution(): string {
+    if (this._state.todos.length === 0) {
+      throw new Error("Cannot start execution: no todos defined. Create a plan first.");
+    }
+    this._state.phase = "executing";
+    this.resetRoundCounter();
+    return `Switched to execution phase. ${this._state.todos.length} todo(s) to complete.\n\n${this.render()}`;
+  }
+
+  switchToPlanning(): string {
+    this._state.phase = "planning";
+    this.resetRoundCounter();
+    return `Switched to planning phase. Tools restricted to read-only.\n\n${this.render()}`;
+  }
+
+  // --- Todo CRUD ---
+
+  updateTodos(items: Array<{ id: string; text: string; status: TodoStatus }>): string {
+    const max = this._config.maxTodos ?? 50;
+    if (items.length > max) {
+      throw new Error(`Too many todos: ${items.length} exceeds limit of ${max}.`);
+    }
+
+    let inProgressCount = 0;
+    const validated: TodoItem[] = [];
+
+    for (const item of items) {
+      const status = item.status ?? "pending";
+      if (status === "in_progress") inProgressCount++;
+      validated.push({
+        id: item.id || generateId(),
+        text: item.text,
+        status,
+      });
+    }
+
+    if (inProgressCount > 1) {
+      throw new Error("Only one todo can be in_progress at a time.");
+    }
+
+    this._state.todos = validated;
+    this.resetRoundCounter();
+    return this.render();
+  }
+
+  // --- Render ---
+
+  render(): string {
+    if (this._state.todos.length === 0) {
+      return `[phase: ${this._state.phase}] No todos.`;
+    }
+
+    const lines = this._state.todos.map((t) => {
+      const icon = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[>]" : "[ ]";
+      return `${icon} ${t.id}: ${t.text}`;
+    });
+
+    const done = this._state.todos.filter((t) => t.status === "completed").length;
+    const total = this._state.todos.length;
+
+    return `[phase: ${this._state.phase}] Progress: ${done}/${total}\n${lines.join("\n")}`;
+  }
+
+  // --- Nag tracking ---
+
+  /** Call once per agent loop step (after tool execution). */
+  tickRound(): void {
+    this._state.roundsSinceTodoUpdate++;
+  }
+
+  /** Reset the round counter (called when the model updates todos). */
+  resetRoundCounter(): void {
+    this._state.roundsSinceTodoUpdate = 0;
+  }
+
+  shouldNag(): boolean {
+    if (this._state.phase !== "executing") return false;
+    if (this._state.todos.length === 0) return false;
+    const threshold = this._config.nagAfterRounds ?? 3;
+    return this._state.roundsSinceTodoUpdate >= threshold;
+  }
+
+  getNagMessage(): string {
+    return this._config.nagMessage ?? "<reminder>Update your todos to reflect current progress.</reminder>";
+  }
+}

package/src/planning/tools.ts

@@ -0,0 +1,71 @@
+// Planning tools — todo management + phase switching
+
+import { Type } from "@sinclair/typebox";
+import type { AgentTool, AgentToolResult } from "../tools/types.js";
+import type { PlanningManager } from "./planning-manager.js";
+import { PLANNING_TOOL_NAMES } from "./types.js";
+import type { TodoStatus } from "./types.js";
+
+export function createPlanningTools(manager: PlanningManager): AgentTool[] {
+  return [
+    {
+      name: PLANNING_TOOL_NAMES.todo,
+      label: "Todo",
+      description:
+        "Manage your task list. Use this tool to plan work, track progress, and stay on track. " +
+        "Only one todo can be in_progress at a time. Update todos frequently to reflect your current state.",
+      parameters: Type.Object({
+        items: Type.Array(
+          Type.Object({
+            id: Type.String({ description: "Unique ID for the todo item." }),
+            text: Type.String({ description: "Description of the task." }),
+            status: Type.Union(
+              [Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")],
+              { description: "Task status. Only one item can be in_progress at a time." },
+            ),
+          }),
+          { description: "The full updated todo list (replaces previous list)." },
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { items: Array<{ id: string; text: string; status: TodoStatus }> },
+      ): Promise<AgentToolResult> {
+        const result = manager.updateTodos(params.items);
+        return { content: [{ type: "text", text: result }] };
+      },
+    },
+    {
+      name: PLANNING_TOOL_NAMES.planMode,
+      label: "Plan Mode",
+      description:
+        "Switch between planning and execution phases. " +
+        "In planning phase, only read-only tools are available — use this time to analyze and create todos. " +
+        "In execution phase, all tools are available and nag reminders will prompt you to update todos.",
+      parameters: Type.Object({
+        action: Type.Union(
+          [Type.Literal("start_execution"), Type.Literal("switch_to_planning"), Type.Literal("status")],
+          { description: "Action to perform." },
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { action: "start_execution" | "switch_to_planning" | "status" },
+      ): Promise<AgentToolResult> {
+        let result: string;
+        switch (params.action) {
+          case "start_execution":
+            result = manager.startExecution();
+            break;
+          case "switch_to_planning":
+            result = manager.switchToPlanning();
+            break;
+          case "status":
+            result = manager.render();
+            break;
+        }
+        return { content: [{ type: "text", text: result }] };
+      },
+    },
+  ];
+}

package/src/planning/types.ts

@@ -0,0 +1,40 @@
+// Planning module types — two-phase planning + structured todo tracking
+
+export const PLANNING_TOOL_NAMES = {
+  todo: "todo",
+  planMode: "plan_mode",
+} as const;
+
+export type TodoStatus = "pending" | "in_progress" | "completed";
+
+export interface TodoItem {
+  id: string;
+  text: string;
+  status: TodoStatus;
+}
+
+export type PlanPhase = "planning" | "executing";
+
+export interface PlanningState {
+  phase: PlanPhase;
+  todos: TodoItem[];
+  roundsSinceTodoUpdate: number;
+}
+
+export interface PlanningConfig {
+  /**
+   * Tool names allowed during the planning phase (read-only tools).
+   * If omitted or empty, all tools are available during planning
+   * (phase separation is advisory only via system prompt).
+   */
+  readOnlyTools?: string[];
+
+  /** Number of rounds without a todo update before injecting a nag reminder. Default: 3. */
+  nagAfterRounds?: number;
+
+  /** Custom nag reminder text. */
+  nagMessage?: string;
+
+  /** Maximum number of todo items. Default: 50. */
+  maxTodos?: number;
+}