klaus-agent 0.2.2 → 0.3.0

package/dist/planning/nag-injection.js

@@ -0,0 +1,21 @@
+// Nag injection provider — reminds model to update todos when it hasn't for N rounds
+export class PlanningNagProvider {
+    _manager;
+    constructor(_manager) {
+        this._manager = _manager;
+    }
+    async getInjections(_history) {
+        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(),
+            },
+        ];
+    }
+}
+//# sourceMappingURL=nag-injection.js.map

package/dist/planning/nag-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nag-injection.js","sourceRoot":"","sources":["../../src/planning/nag-injection.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAMrF,MAAM,OAAO,mBAAmB;IACV;IAApB,YAAoB,QAAyB;QAAzB,aAAQ,GAAR,QAAQ,CAAiB;IAAG,CAAC;IAEjD,KAAK,CAAC,aAAa,CAAC,QAAwB;QAC1C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE;YAAE,OAAO,EAAE,CAAC;QAE1C,4DAA4D;QAC5D,sEAAsE;QACtE,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;QAElC,OAAO;YACL;gBACE,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE;aACvC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/planning/planning-manager.d.ts

@@ -0,0 +1,27 @@
+import type { TodoItem, TodoStatus, PlanPhase, PlanningConfig } from "./types.js";
+export declare class PlanningManager {
+    private _state;
+    private _config;
+    private _allowedInPlanning;
+    constructor(config?: PlanningConfig);
+    get phase(): PlanPhase;
+    get todos(): readonly Readonly<TodoItem>[];
+    get roundsSinceTodoUpdate(): number;
+    get config(): Readonly<PlanningConfig>;
+    /** Pre-built set of tool names allowed during planning phase. */
+    get allowedInPlanning(): ReadonlySet<string>;
+    startExecution(): string;
+    switchToPlanning(): string;
+    updateTodos(items: Array<{
+        id: string;
+        text: string;
+        status: TodoStatus;
+    }>): string;
+    render(): string;
+    /** Call once per agent loop step (after tool execution). */
+    tickRound(): void;
+    /** Reset the round counter (called when the model updates todos). */
+    resetRoundCounter(): void;
+    shouldNag(): boolean;
+    getNagMessage(): string;
+}

package/dist/planning/planning-manager.js

@@ -0,0 +1,109 @@
+// Planning manager — two-phase planning with structured todo tracking
+import { PLANNING_TOOL_NAMES } from "./types.js";
+import { generateId } from "../utils/id.js";
+export class PlanningManager {
+    _state;
+    _config;
+    _allowedInPlanning;
+    constructor(config = {}) {
+        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() {
+        return this._state.phase;
+    }
+    get todos() {
+        return this._state.todos;
+    }
+    get roundsSinceTodoUpdate() {
+        return this._state.roundsSinceTodoUpdate;
+    }
+    get config() {
+        return this._config;
+    }
+    /** Pre-built set of tool names allowed during planning phase. */
+    get allowedInPlanning() {
+        return this._allowedInPlanning;
+    }
+    // --- Phase control ---
+    startExecution() {
+        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() {
+        this._state.phase = "planning";
+        this.resetRoundCounter();
+        return `Switched to planning phase. Tools restricted to read-only.\n\n${this.render()}`;
+    }
+    // --- Todo CRUD ---
+    updateTodos(items) {
+        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 = [];
+        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() {
+        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() {
+        this._state.roundsSinceTodoUpdate++;
+    }
+    /** Reset the round counter (called when the model updates todos). */
+    resetRoundCounter() {
+        this._state.roundsSinceTodoUpdate = 0;
+    }
+    shouldNag() {
+        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() {
+        return this._config.nagMessage ?? "<reminder>Update your todos to reflect current progress.</reminder>";
+    }
+}
+//# sourceMappingURL=planning-manager.js.map

package/dist/planning/planning-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-manager.js","sourceRoot":"","sources":["../../src/planning/planning-manager.ts"],"names":[],"mappings":"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"}

package/dist/planning/tools.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from "../tools/types.js";
+import type { PlanningManager } from "./planning-manager.js";
+export declare function createPlanningTools(manager: PlanningManager): AgentTool[];

package/dist/planning/tools.js

@@ -0,0 +1,50 @@
+// Planning tools — todo management + phase switching
+import { Type } from "@sinclair/typebox";
+import { PLANNING_TOOL_NAMES } from "./types.js";
+export function createPlanningTools(manager) {
+    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, params) {
+                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, params) {
+                let result;
+                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 }] };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/dist/planning/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/planning/tools.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAGzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,MAAM,UAAU,mBAAmB,CAAC,OAAwB;IAC1D,OAAO;QACL;YACE,IAAI,EAAE,mBAAmB,CAAC,IAAI;YAC9B,KAAK,EAAE,MAAM;YACb,WAAW,EACT,wFAAwF;gBACxF,oGAAoG;YACtG,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;gBACtB,KAAK,EAAE,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,MAAM,CAAC;oBACV,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,8BAA8B,EAAE,CAAC;oBAChE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,0BAA0B,EAAE,CAAC;oBAC9D,MAAM,EAAE,IAAI,CAAC,KAAK,CAChB,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,EACjF,EAAE,WAAW,EAAE,0DAA0D,EAAE,CAC5E;iBACF,CAAC,EACF,EAAE,WAAW,EAAE,sDAAsD,EAAE,CACxE;aACF,CAAC;YACF,KAAK,CAAC,OAAO,CACX,WAAmB,EACnB,MAA0E;gBAE1E,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACjD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YACvD,CAAC;SACF;QACD;YACE,IAAI,EAAE,mBAAmB,CAAC,QAAQ;YAClC,KAAK,EAAE,WAAW;YAClB,WAAW,EACT,gDAAgD;gBAChD,qGAAqG;gBACrG,gGAAgG;YAClG,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;gBACtB,MAAM,EAAE,IAAI,CAAC,KAAK,CAChB,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAC7F,EAAE,WAAW,EAAE,oBAAoB,EAAE,CACtC;aACF,CAAC;YACF,KAAK,CAAC,OAAO,CACX,WAAmB,EACnB,MAAuE;gBAEvE,IAAI,MAAc,CAAC;gBACnB,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;oBACtB,KAAK,iBAAiB;wBACpB,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;wBAClC,MAAM;oBACR,KAAK,oBAAoB;wBACvB,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;wBACpC,MAAM;oBACR,KAAK,QAAQ;wBACX,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;wBAC1B,MAAM;gBACV,CAAC;gBACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YACvD,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/planning/types.d.ts

@@ -0,0 +1,30 @@
+export declare const PLANNING_TOOL_NAMES: {
+    readonly todo: "todo";
+    readonly planMode: "plan_mode";
+};
+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;
+}

package/dist/planning/types.js

@@ -0,0 +1,6 @@
+// Planning module types — two-phase planning + structured todo tracking
+export const PLANNING_TOOL_NAMES = {
+    todo: "todo",
+    planMode: "plan_mode",
+};
+//# sourceMappingURL=types.js.map

package/dist/planning/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/planning/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,WAAW;CACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaus-agent",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Universal agent framework",
   "type": "module",
   "main": "dist/index.js",

package/src/core/agent-loop.ts

@@ -22,6 +22,8 @@ import type { CheckpointManager } from "../checkpoint/checkpoint-manager.js";
 import type { InjectionManager } from "../injection/injection-manager.js";
 import type { ExtensionRunner } from "../extensions/runner.js";
 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 { normalizeHistory } from "../injection/history-normalizer.js";
@@ -50,6 +52,7 @@ export interface AgentLoopConfig {
   injectionManager?: InjectionManager;
   extensionRunner?: ExtensionRunner;
   compaction?: CompactionConfig & { summarize?: (messages: AgentMessage[]) => Promise<string> };
+  planningManager?: PlanningManager;
   modelCost?: ModelCost;
 }
 
@@ -248,8 +251,14 @@ export async function runAgentLoop(
           llmMessages = stripImages(llmMessages);
         }
 
+        // --- Phase-aware tool filtering ---
+        let visibleTools = allTools;
+        if (config.planningManager?.phase === "planning" && config.planningManager.allowedInPlanning.size > 2) {
+          visibleTools = allTools.filter((t) => config.planningManager!.allowedInPlanning.has(t.name));
+        }
+
         // --- Stream LLM response ---
-        const toolDefs = toolsToDefinitions(allTools);
+        const toolDefs = toolsToDefinitions(visibleTools);
         let requestOptions: LLMRequestOptions = {
           model: modelId,
           systemPrompt,
@@ -319,7 +328,7 @@ export async function runAgentLoop(
 
         if (toolCalls.length > 0) {
           const results = await executeToolCalls(toolCalls, {
-            tools: allTools,
+            tools: visibleTools,
             mode: config.toolExecution,
             approval: config.approval,
             agentName: config.agentName,
@@ -360,6 +369,14 @@ export async function runAgentLoop(
             await sessionManager?.appendMessage(rm);
           }
 
+          // --- Planning: tick round counter (reset happens inside updateTodos when todo tool is called) ---
+          if (config.planningManager) {
+            const calledTodo = toolCalls.some((tc) => tc.name === PLANNING_TOOL_NAMES.todo);
+            if (!calledTodo) {
+              config.planningManager.tickRound();
+            }
+          }
+
           hasMoreWork = true;
         }
 

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,
   });
 }
 
@@ -101,6 +104,9 @@ 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>";
+  }
+}