planning tool

src/lib/server/context.md

@@ -5,19 +5,20 @@ WebSocket server with LangGraph agent for AI-assisted game development.
 ## Key Components
 
 - **api.ts** - WebSocket message routing with abort handling
-- **langgraph-agent.ts** - LangGraph agent with buffered streaming and abort signals
-- **tools.ts** - Editor manipulation: full read/write, line-based reading, text/regex search, search-replace editing
+- **langgraph-agent.ts** - LangGraph agent with task decomposition and token safety
+- **tools.ts** - Editor manipulation: read/write, search, incremental editing
+- **task-tracker.ts** - Task planning and progress tracking
 - **console-buffer.ts** - Console message storage
 - **documentation.ts** - VibeGame documentation loader
 
 ## Architecture
 
-LangGraph state machine with real-time streaming:
+LangGraph state machine with task-aware execution:
 
-- Buffers and filters tool patterns from text segments
-- Tool invocations handled separately from text content
-- Explicit message IDs required for all segment operations
-- AbortController for canceling running conversations
+- Task decomposition for complex operations
+- Token limit safety checks on tool arguments
+- Buffered streaming with segment handling
+- AbortController for canceling conversations
 
 ## Message Protocol
 

src/lib/server/langgraph-agent.ts

@@ -15,6 +15,11 @@ import {
   observeConsoleTool,
   setWebSocketConnection,
 } from "./tools";
+import {
+  planTasksTool,
+  updateTaskTool,
+  viewTasksTool,
+} from "./task-tracker";
 import { documentationService } from "./documentation";
 import type { WebSocket } from "ws";
 
@@ -310,39 +315,62 @@ CRITICAL INSTRUCTIONS:
 - You MUST use tools for ALL tasks. NEVER provide instructions without executing them.
 - You MUST respond using the EXACT format: TOOL: tool_name ARGS: {"param": "value"}
 - After using a tool, wait for the result before proceeding
-- Chain multiple tool calls to complete complex tasks
+- For complex tasks, use plan_tasks FIRST to break down the work
+- Keep tool arguments concise - prefer multiple small edits over one large edit
+
+TASK DECOMPOSITION RULES:
+- For any task requiring 3+ changes, use plan_tasks FIRST
+- Break large code changes into smaller, focused edits
+- Each edit_editor call should modify ONE logical section (max ~20 lines)
+- Mark tasks as in_progress when starting, completed when done
 
 VIBEGAME CONTEXT:
 ${this.documentation}
 
 IMPORTANT:
-- The game auto-reloads on every change. 
+- The game auto-reloads on every change.
 - The GAME import is automatically provided by the framework.
 - The player is automatically created at [0, 0, 0] if not specified.
 
 AVAILABLE TOOLS:
-1. search_editor - Find text/patterns in code
+
+TASK MANAGEMENT:
+1. plan_tasks - Break complex work into steps (USE FIRST for multi-step tasks!)
+   Example: TOOL: plan_tasks ARGS: {"tasks": ["Find the player object", "Add jump ability", "Test the changes"]}
+
+2. update_task - Mark task progress
+   Example: TOOL: update_task ARGS: {"taskId": 1, "status": "in_progress"}
+
+3. view_tasks - See current task list
+   Example: TOOL: view_tasks ARGS: {}
+
+EDITOR TOOLS:
+4. search_editor - Find text/patterns in code
    Example: TOOL: search_editor ARGS: {"query": "dynamic-part"}
 
-2. read_editor - Read entire editor content
+5. read_editor - Read entire editor content
    Example: TOOL: read_editor ARGS: {}
 
-3. read_editor_lines - Read specific lines (use after search_editor)
+6. read_editor_lines - Read specific lines (use after search_editor)
    Example: TOOL: read_editor_lines ARGS: {"startLine": 10, "endLine": 20}
 
-4. edit_editor - Replace specific text
+7. edit_editor - Replace specific text (KEEP EDITS SMALL - max ~20 lines per call)
    Example: TOOL: edit_editor ARGS: {"oldText": "color='red'", "newText": "color='blue'"}
 
-5. write_editor - Replace entire content
+8. write_editor - Replace entire content (ONLY for new files or complete rewrites)
    Example: TOOL: write_editor ARGS: {"content": "<world>...</world>"}
 
-6. observe_console - Check console for errors
+9. observe_console - Check console for errors
    Example: TOOL: observe_console ARGS: {}
 
-WORKFLOW:
-- To find code: TOOL: search_editor ARGS: {"query": "search_term"}
-- To make changes: TOOL: edit_editor ARGS: {"oldText": "...", "newText": "..."}
-- After changes: TOOL: observe_console ARGS: {}
+WORKFLOW EXAMPLE:
+User: "Add jumping to the player"
+1. TOOL: plan_tasks ARGS: {"tasks": ["Search for player code", "Add jump component", "Add jump controls", "Test jumping"]}
+2. TOOL: update_task ARGS: {"taskId": 1, "status": "in_progress"}
+3. TOOL: search_editor ARGS: {"query": "player"}
+4. TOOL: edit_editor ARGS: {"oldText": "...", "newText": "..."}
+5. TOOL: update_task ARGS: {"taskId": 1, "status": "completed"}
+(continue with remaining tasks...)
 
 IMPORTANT: You are an executor. Take action immediately using tools, don't explain what you would do.`;
   }
@@ -480,6 +508,27 @@ IMPORTANT: You are an executor. Take action immediately using tools, don't expla
       const segmentId = `seg_tool_${Date.now()}_${Math.random()}`;
 
       try {
+        const argString = JSON.stringify(call.args);
+        const estimatedTokens = argString.length / 4;
+
+        if (estimatedTokens > 1000 && (call.name === "edit_editor" || call.name === "write_editor")) {
+          console.warn(`Warning: Tool ${call.name} arguments are large (${estimatedTokens} estimated tokens)`);
+
+          if (call.name === "edit_editor" && call.args.oldText) {
+            const oldText = call.args.oldText as string;
+
+            if (oldText.split('\n').length > 20) {
+              results.push(
+                new ToolMessage({
+                  content: `Error: The edit is too large (${oldText.split('\n').length} lines). Please break this into smaller edits of max 20 lines each. Use plan_tasks to organize multiple edits.`,
+                  tool_call_id: segmentId,
+                  name: call.name,
+                })
+              );
+              continue;
+            }
+          }
+        }
         if (this.ws && this.ws.readyState === this.ws.OPEN) {
           this.ws.send(
             JSON.stringify({
@@ -547,6 +596,14 @@ IMPORTANT: You are an executor. Take action immediately using tools, don't expla
           }
         } else if (call.name === "observe_console") {
           result = await observeConsoleTool.func("");
+        } else if (call.name === "plan_tasks") {
+          result = await planTasksTool.func(call.args as { tasks: string[] });
+        } else if (call.name === "update_task") {
+          result = await updateTaskTool.func(
+            call.args as { taskId: number; status: "pending" | "in_progress" | "completed" }
+          );
+        } else if (call.name === "view_tasks") {
+          result = await viewTasksTool.func({});
         } else {
           result = `Unknown tool: ${call.name}`;
         }

src/lib/server/task-tracker.ts

@@ -0,0 +1,136 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+
+interface Task {
+  id: number;
+  description: string;
+  status: "pending" | "in_progress" | "completed";
+  createdAt: Date;
+  completedAt?: Date;
+}
+
+class TaskTracker {
+  private tasks: Task[] = [];
+  private nextId = 1;
+
+  addTask(description: string): Task {
+    const task: Task = {
+      id: this.nextId++,
+      description,
+      status: "pending",
+      createdAt: new Date(),
+    };
+    this.tasks.push(task);
+    return task;
+  }
+
+  updateTaskStatus(id: number, status: Task["status"]): Task | null {
+    const task = this.tasks.find((t) => t.id === id);
+    if (task) {
+      task.status = status;
+      if (status === "completed") {
+        task.completedAt = new Date();
+      }
+      return task;
+    }
+    return null;
+  }
+
+  getTasks(): Task[] {
+    return [...this.tasks];
+  }
+
+  getActiveTasks(): Task[] {
+    return this.tasks.filter((t) => t.status !== "completed");
+  }
+
+  clear(): void {
+    this.tasks = [];
+    this.nextId = 1;
+  }
+
+  formatTaskList(): string {
+    if (this.tasks.length === 0) {
+      return "No tasks in the list.";
+    }
+
+    const statusEmoji = {
+      pending: "⏳",
+      in_progress: "🔄",
+      completed: "✅",
+    };
+
+    return this.tasks
+      .map(
+        (t) =>
+          `${statusEmoji[t.status]} [${t.id}] ${t.description} (${t.status})`,
+      )
+      .join("\n");
+  }
+}
+
+const taskTracker = new TaskTracker();
+
+export const planTasksTool = new DynamicStructuredTool({
+  name: "plan_tasks",
+  description:
+    "Plan and break down a complex task into smaller steps. Use this BEFORE starting any multi-step work to organize your approach.",
+  schema: z.object({
+    tasks: z
+      .array(z.string())
+      .min(1)
+      .describe(
+        "List of task descriptions in order of execution. Keep each task focused and achievable with a single tool call.",
+      ),
+  }),
+  func: async (input: { tasks: string[] }) => {
+    taskTracker.clear();
+    const createdTasks = input.tasks.map((desc) => taskTracker.addTask(desc));
+
+    return `Task plan created with ${createdTasks.length} tasks:\n${taskTracker.formatTaskList()}\n\nStart with task 1 and mark it as in_progress when you begin.`;
+  },
+});
+
+export const updateTaskTool = new DynamicStructuredTool({
+  name: "update_task",
+  description:
+    "Update the status of a task. Mark as 'in_progress' when starting, 'completed' when done.",
+  schema: z.object({
+    taskId: z.number().min(1).describe("The task ID to update"),
+    status: z
+      .enum(["pending", "in_progress", "completed"])
+      .describe("The new status for the task"),
+  }),
+  func: async (input: { taskId: number; status: Task["status"] }) => {
+    const task = taskTracker.updateTaskStatus(input.taskId, input.status);
+
+    if (!task) {
+      return `Error: Task ${input.taskId} not found.`;
+    }
+
+    const activeTasks = taskTracker.getActiveTasks();
+    const nextTask = activeTasks.find((t) => t.status === "pending");
+
+    let response = `Task ${task.id} marked as ${task.status}: "${task.description}"`;
+
+    if (input.status === "completed" && nextTask) {
+      response += `\n\nNext task: [${nextTask.id}] ${nextTask.description}`;
+    } else if (input.status === "completed" && activeTasks.length === 0) {
+      response += "\n\nAll tasks completed! 🎉";
+    }
+
+    response += `\n\nCurrent task list:\n${taskTracker.formatTaskList()}`;
+    return response;
+  },
+});
+
+export const viewTasksTool = new DynamicStructuredTool({
+  name: "view_tasks",
+  description: "View the current task list and their statuses.",
+  schema: z.object({}),
+  func: async () => {
+    return taskTracker.formatTaskList();
+  },
+});
+
+export const taskTrackerTools = [planTasksTool, updateTaskTool, viewTasksTool];

src/lib/server/tools.ts

@@ -92,9 +92,9 @@ export const readEditorLinesTool = new DynamicStructuredTool({
 export const editEditorTool = new DynamicStructuredTool({
   name: "edit_editor",
   description:
-    "Replace specific text in the editor - use for targeted changes after locating code with search_editor",
+    "Replace specific text in the editor - use for SMALL, targeted changes (max ~20 lines). For large changes, use multiple edit_editor calls with plan_tasks",
   schema: z.object({
-    oldText: z.string().describe("The exact text to find and replace"),
+    oldText: z.string().describe("The exact text to find and replace (keep small - max ~20 lines)"),
     newText: z.string().describe("The text to replace it with"),
   }),
   func: async (input: { oldText: string; newText: string }) => {
@@ -154,9 +154,9 @@ export const editEditorTool = new DynamicStructuredTool({
 export const writeEditorTool = new DynamicStructuredTool({
   name: "write_editor",
   description:
-    "Replace entire editor content - use for creating new files or complete rewrites",
+    "Replace entire editor content - use ONLY for creating new files or complete rewrites. For modifications, use edit_editor with plan_tasks instead",
   schema: z.object({
-    content: z.string().describe("The code content to write to the editor"),
+    content: z.string().describe("The complete code content to write to the editor"),
   }),
   func: async (input: { content: string }) => {
     currentEditorContent = input.content;
@@ -320,6 +320,8 @@ export const observeConsoleTool = new DynamicTool({
   },
 });
 
+import { taskTrackerTools } from "./task-tracker";
+
 export const tools = [
   readEditorTool,
   readEditorLinesTool,
@@ -327,4 +329,5 @@ export const tools = [
   editEditorTool,
   writeEditorTool,
   observeConsoleTool,
+  ...taskTrackerTools,
 ];