sparkecoder 0.1.81 → 0.1.83

package/dist/agent/index.js

@@ -683,9 +683,9 @@ __export(skills_exports, {
   loadSkillContent: () => loadSkillContent,
   loadSkillsFromDirectory: () => loadSkillsFromDirectory
 });
-import { readFile as readFile6, readdir } from "fs/promises";
+import { readFile as readFile7, readdir } from "fs/promises";
 import { resolve as resolve6, basename, extname as extname4, relative as relative4 } from "path";
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 import { minimatch } from "minimatch";
 function parseSkillFrontmatter(content) {
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
@@ -763,7 +763,7 @@ async function loadSkillsFromDirectory(directory, options = {}) {
     defaultLoadType = "on_demand",
     forceAlwaysApply = false
   } = options;
-  if (!existsSync9(directory)) {
+  if (!existsSync10(directory)) {
     return [];
   }
   const skills = [];
@@ -773,7 +773,7 @@ async function loadSkillsFromDirectory(directory, options = {}) {
     let fileName;
     if (entry.isDirectory()) {
       const skillMdPath = resolve6(directory, entry.name, "SKILL.md");
-      if (existsSync9(skillMdPath)) {
+      if (existsSync10(skillMdPath)) {
         filePath = skillMdPath;
         fileName = entry.name;
       } else {
@@ -785,7 +785,7 @@ async function loadSkillsFromDirectory(directory, options = {}) {
     } else {
       continue;
     }
-    const content = await readFile6(filePath, "utf-8");
+    const content = await readFile7(filePath, "utf-8");
     const parsed = parseSkillFrontmatter(content);
     if (parsed) {
       const alwaysApply = forceAlwaysApply || parsed.metadata.alwaysApply;
@@ -864,7 +864,7 @@ async function loadAllSkillsFromDiscovered(discovered) {
   const onDemandSkills = allSkills.filter((s) => !s.alwaysApply && s.loadType !== "always");
   const alwaysWithContent = await Promise.all(
     alwaysSkills.map(async (skill) => {
-      const content = await readFile6(skill.filePath, "utf-8");
+      const content = await readFile7(skill.filePath, "utf-8");
       const parsed = parseSkillFrontmatter(content);
       return {
         ...skill,
@@ -901,7 +901,7 @@ async function getGlobMatchedSkills(skills, activeFiles, workingDirectory) {
   });
   const matchedWithContent = await Promise.all(
     matchedSkills.map(async (skill) => {
-      const content = await readFile6(skill.filePath, "utf-8");
+      const content = await readFile7(skill.filePath, "utf-8");
       const parsed = parseSkillFrontmatter(content);
       return {
         ...skill,
@@ -913,10 +913,10 @@ async function getGlobMatchedSkills(skills, activeFiles, workingDirectory) {
   return matchedWithContent;
 }
 async function loadAgentsMd(agentsMdPath) {
-  if (!agentsMdPath || !existsSync9(agentsMdPath)) {
+  if (!agentsMdPath || !existsSync10(agentsMdPath)) {
     return null;
   }
-  const content = await readFile6(agentsMdPath, "utf-8");
+  const content = await readFile7(agentsMdPath, "utf-8");
   return content;
 }
 async function loadSkillContent(skillName, directories) {
@@ -927,7 +927,7 @@ async function loadSkillContent(skillName, directories) {
   if (!skill) {
     return null;
   }
-  const content = await readFile6(skill.filePath, "utf-8");
+  const content = await readFile7(skill.filePath, "utf-8");
   const parsed = parseSkillFrontmatter(content);
   return {
     ...skill,
@@ -1188,7 +1188,7 @@ var init_client = __esm({
 });
 
 // src/semantic/indexer.ts
-import { readFileSync as readFileSync4, statSync } from "fs";
+import { readFileSync as readFileSync5, statSync } from "fs";
 import { relative as relative6 } from "path";
 import { minimatch as minimatch2 } from "minimatch";
 async function getIndexStatus(workingDirectory) {
@@ -1273,8 +1273,8 @@ __export(semantic_search_exports, {
 });
 import { tool as tool8 } from "ai";
 import { z as z9 } from "zod";
-import { existsSync as existsSync12, readFileSync as readFileSync5 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync6 } from "fs";
+import { join as join6 } from "path";
 import { minimatch as minimatch3 } from "minimatch";
 function createSemanticSearchTool(options) {
   return tool8({
@@ -1341,13 +1341,13 @@ Returns matching code snippets with file paths, line numbers, and relevance scor
             if (language && matchLanguage !== language.toLowerCase()) {
               continue;
             }
-            const fullPath = join5(options.workingDirectory, filePath);
-            if (!existsSync12(fullPath)) {
+            const fullPath = join6(options.workingDirectory, filePath);
+            if (!existsSync13(fullPath)) {
               continue;
             }
             let snippet = "";
             try {
-              const content = readFileSync5(fullPath, "utf-8");
+              const content = readFileSync6(fullPath, "utf-8");
               const lines = content.split("\n");
               const snippetLines = lines.slice(
                 Math.max(0, startLine - 1),
@@ -1614,8 +1614,8 @@ __export(recorder_exports, {
 });
 import { exec as exec5 } from "child_process";
 import { promisify as promisify5 } from "util";
-import { writeFile as writeFile4, mkdir as mkdir4, readFile as readFile10, unlink as unlink2, readdir as readdir5, rm } from "fs/promises";
-import { join as join7 } from "path";
+import { writeFile as writeFile5, mkdir as mkdir4, readFile as readFile11, unlink as unlink2, readdir as readdir5, rm } from "fs/promises";
+import { join as join8 } from "path";
 import { tmpdir } from "os";
 import { nanoid as nanoid3 } from "nanoid";
 async function checkFfmpeg() {
@@ -1672,21 +1672,21 @@ var init_recorder = __esm({
        */
       async encode() {
         if (this.frames.length === 0) return null;
-        const workDir = join7(tmpdir(), `sparkecoder-recording-${nanoid3(8)}`);
+        const workDir = join8(tmpdir(), `sparkecoder-recording-${nanoid3(8)}`);
         await mkdir4(workDir, { recursive: true });
         try {
           for (let i = 0; i < this.frames.length; i++) {
-            const framePath = join7(workDir, `frame_${String(i).padStart(6, "0")}.jpg`);
-            await writeFile4(framePath, this.frames[i].data);
+            const framePath = join8(workDir, `frame_${String(i).padStart(6, "0")}.jpg`);
+            await writeFile5(framePath, this.frames[i].data);
           }
           const duration = (this.frames[this.frames.length - 1].timestamp - this.frames[0].timestamp) / 1e3;
           const fps = duration > 0 ? Math.round(this.frames.length / duration) : 10;
           const clampedFps = Math.max(1, Math.min(fps, 30));
-          const outputPath = join7(workDir, `recording_${this.sessionId}.mp4`);
+          const outputPath = join8(workDir, `recording_${this.sessionId}.mp4`);
           const hasFfmpeg = await checkFfmpeg();
           if (hasFfmpeg) {
             await execAsync5(
-              `ffmpeg -y -framerate ${clampedFps} -i "${join7(workDir, "frame_%06d.jpg")}" -c:v libx264 -pix_fmt yuv420p -preset fast -crf 23 "${outputPath}"`,
+              `ffmpeg -y -framerate ${clampedFps} -i "${join8(workDir, "frame_%06d.jpg")}" -c:v libx264 -pix_fmt yuv420p -preset fast -crf 23 "${outputPath}"`,
               { timeout: 12e4 }
             );
           } else {
@@ -1694,11 +1694,11 @@ var init_recorder = __esm({
             await cleanup(workDir);
             return null;
           }
-          const outputBuf = await readFile10(outputPath);
+          const outputBuf = await readFile11(outputPath);
           const files = await readdir5(workDir);
           for (const f of files) {
             if (f.startsWith("frame_")) {
-              await unlink2(join7(workDir, f)).catch(() => {
+              await unlink2(join8(workDir, f)).catch(() => {
               });
             }
           }
@@ -3599,8 +3599,34 @@ Working directory: ${options.workingDirectory}`,
 init_db();
 import { tool as tool4 } from "ai";
 import { z as z5 } from "zod";
+import { existsSync as existsSync9, mkdirSync as mkdirSync4, readdirSync, unlinkSync, readFileSync as readFileSync3, appendFileSync } from "fs";
+import { readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
+import { join as join4 } from "path";
+function getPlansDir(workingDirectory, sessionId) {
+  return join4(workingDirectory, ".sparkecoder", "plans", sessionId);
+}
+function ensurePlansDir(workingDirectory, sessionId) {
+  const dir = getPlansDir(workingDirectory, sessionId);
+  if (!existsSync9(dir)) {
+    mkdirSync4(dir, { recursive: true });
+  }
+  const gitignorePath = join4(workingDirectory, ".gitignore");
+  if (existsSync9(gitignorePath)) {
+    try {
+      const content = readFileSync3(gitignorePath, "utf-8");
+      if (!content.includes(".sparkecoder")) {
+        appendFileSync(gitignorePath, "\n.sparkecoder/\n");
+      }
+    } catch {
+    }
+  }
+  return dir;
+}
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "plan";
+}
 var todoInputSchema = z5.object({
-  action: z5.enum(["add", "list", "mark", "clear"]).describe("The action to perform on the todo list"),
+  action: z5.enum(["add", "list", "mark", "clear", "save_plan", "list_plans", "get_plan", "delete_plan"]).describe("The action to perform"),
   items: z5.array(
     z5.object({
       content: z5.string().describe("Description of the task"),
@@ -3608,27 +3634,67 @@ var todoInputSchema = z5.object({
     })
   ).optional().describe('For "add" action: Array of todo items to add'),
   todoId: z5.string().optional().describe('For "mark" action: The ID of the todo item to update'),
-  status: z5.enum(["pending", "in_progress", "completed", "cancelled"]).optional().describe('For "mark" action: The new status for the todo item')
+  status: z5.enum(["pending", "in_progress", "completed", "cancelled"]).optional().describe('For "mark" action: The new status for the todo item'),
+  planName: z5.string().optional().describe('For plan actions: Name of the plan (e.g. "auth-system", "db-migration")'),
+  planContent: z5.string().optional().describe('For "save_plan": Full plan content as markdown with hierarchical tasks using checkboxes')
 });
 function createTodoTool(options) {
   return tool4({
-    description: `Manage your task list for the current session. Use this to:
-- Break down complex tasks into smaller steps
-- Track progress on multi-step operations
-- Organize your work systematically
+    description: `Manage your task list and persistent plans for the current session.
 
-Available actions:
+## Todo Actions (for tracking current work)
 - "add": Add one or more new todo items to the list
 - "list": View all current todo items and their status
 - "mark": Update the status of a todo item (pending, in_progress, completed, cancelled)
 - "clear": Remove all todo items from the list
 
-Best practices:
-- Add todos before starting complex tasks
-- Mark items as "in_progress" when actively working on them
-- Update status as you complete each step`,
+## Plan Actions (for complex, multi-phase work)
+- "save_plan": Create or update a named plan \u2014 a persistent markdown document with hierarchical tasks, subtasks, and notes. Plans survive context compaction and are always available.
+- "list_plans": List all plans for this session
+- "get_plan": Read a specific plan by name
+- "delete_plan": Remove a plan
+
+## Plans vs Todos
+- **Plans** are the big picture \u2014 the full spec with phases, subtasks, notes, and decisions. They persist on disk and are always injected into your context, even after old messages are summarized.
+- **Todos** are your current focus \u2014 the immediate steps you're working on right now.
+
+## Workflow for complex tasks
+1. Create a plan with phases and subtasks (save_plan)
+2. Create todos from the first uncompleted phase (add)
+3. Work through the todos, marking them as you go
+4. When all current todos are done, update the plan (mark completed sections with [x]) and save it
+5. Create new todos from the next uncompleted phase
+6. Repeat until the plan is fully complete
+
+## Plan format
+Plans should be markdown with this structure:
+\`\`\`markdown
+# Plan: [Title]
+
+## Overview
+[What we're doing and why]
+
+## Phase 1: [Name] [completed]
+- [x] Task 1
+- [x] Task 2
+
+## Phase 2: [Name] [in_progress]
+- [x] Subtask 2.1
+- [ ] Subtask 2.2
+  - [ ] Sub-subtask 2.2.1
+  - [ ] Sub-subtask 2.2.2
+- [ ] Subtask 2.3
+
+## Phase 3: [Name] [pending]
+- [ ] Task 1
+- [ ] Task 2
+
+## Notes
+- Key decisions and context to preserve
+- Important file paths discovered
+\`\`\``,
     inputSchema: todoInputSchema,
-    execute: async ({ action, items, todoId, status }) => {
+    execute: async ({ action, items, todoId, status, planName, planContent }) => {
       try {
         switch (action) {
           case "add": {
@@ -3696,6 +3762,81 @@ Best practices:
               itemsRemoved: count
             };
           }
+          // ── Plan actions ─────────────────────────────────────────
+          case "save_plan": {
+            if (!planName) {
+              return { success: false, error: 'planName is required for "save_plan"' };
+            }
+            if (!planContent) {
+              return { success: false, error: 'planContent is required for "save_plan"' };
+            }
+            const dir = ensurePlansDir(options.workingDirectory, options.sessionId);
+            const filename = `${slugify(planName)}.md`;
+            const filePath = join4(dir, filename);
+            await writeFile4(filePath, planContent, "utf-8");
+            return {
+              success: true,
+              action: "save_plan",
+              planName,
+              filename,
+              path: filePath,
+              sizeChars: planContent.length
+            };
+          }
+          case "list_plans": {
+            const dir = getPlansDir(options.workingDirectory, options.sessionId);
+            if (!existsSync9(dir)) {
+              return { success: true, action: "list_plans", plans: [], count: 0 };
+            }
+            const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+            const plans = [];
+            for (const f of files) {
+              try {
+                const content = await readFile6(join4(dir, f), "utf-8");
+                const titleMatch = content.match(/^#\s+(?:Plan:\s*)?(.+)/m);
+                plans.push({
+                  name: f.replace(/\.md$/, ""),
+                  title: titleMatch?.[1]?.trim() || f.replace(/\.md$/, ""),
+                  filename: f,
+                  sizeChars: content.length
+                });
+              } catch {
+              }
+            }
+            return { success: true, action: "list_plans", plans, count: plans.length };
+          }
+          case "get_plan": {
+            if (!planName) {
+              return { success: false, error: 'planName is required for "get_plan"' };
+            }
+            const dir = getPlansDir(options.workingDirectory, options.sessionId);
+            const filename = `${slugify(planName)}.md`;
+            const filePath = join4(dir, filename);
+            if (!existsSync9(filePath)) {
+              return { success: false, error: `Plan not found: "${planName}" (looked for ${filename})` };
+            }
+            const content = await readFile6(filePath, "utf-8");
+            return {
+              success: true,
+              action: "get_plan",
+              planName,
+              content,
+              sizeChars: content.length
+            };
+          }
+          case "delete_plan": {
+            if (!planName) {
+              return { success: false, error: 'planName is required for "delete_plan"' };
+            }
+            const dir = getPlansDir(options.workingDirectory, options.sessionId);
+            const filename = `${slugify(planName)}.md`;
+            const filePath = join4(dir, filename);
+            if (!existsSync9(filePath)) {
+              return { success: false, error: `Plan not found: "${planName}"` };
+            }
+            unlinkSync(filePath);
+            return { success: true, action: "delete_plan", planName, deleted: true };
+          }
           default:
             return {
               success: false,
@@ -3720,6 +3861,21 @@ function formatTodoItem(item) {
     createdAt: item.createdAt.toISOString()
   };
 }
+async function readSessionPlans(workingDirectory, sessionId) {
+  const dir = getPlansDir(workingDirectory, sessionId);
+  if (!existsSync9(dir)) return [];
+  const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+  if (files.length === 0) return [];
+  const plans = [];
+  for (const f of files) {
+    try {
+      const content = await readFile6(join4(dir, f), "utf-8");
+      plans.push({ name: f.replace(/\.md$/, ""), content });
+    } catch {
+    }
+  }
+  return plans;
+}
 
 // src/tools/load-skill.ts
 init_skills();
@@ -3809,7 +3965,7 @@ Once loaded, a skill's content will be available in the conversation context.`,
 import { tool as tool6 } from "ai";
 import { z as z7 } from "zod";
 import { resolve as resolve7, relative as relative5, isAbsolute as isAbsolute3, extname as extname5 } from "path";
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync11 } from "fs";
 import { readdir as readdir2, stat as stat2 } from "fs/promises";
 var linterInputSchema = z7.object({
   paths: z7.array(z7.string()).optional().describe("File or directory paths to check for lint errors. If not provided, returns diagnostics for all recently touched files."),
@@ -3877,7 +4033,7 @@ Working directory: ${options.workingDirectory}`,
         const filesToCheck = [];
         for (const path of paths) {
           const absolutePath = isAbsolute3(path) ? path : resolve7(options.workingDirectory, path);
-          if (!existsSync10(absolutePath)) {
+          if (!existsSync11(absolutePath)) {
             continue;
           }
           const stats = await stat2(absolutePath);
@@ -4189,17 +4345,17 @@ import { tool as tool9 } from "ai";
 import { z as z10 } from "zod";
 import { exec as exec4 } from "child_process";
 import { promisify as promisify4 } from "util";
-import { readFile as readFile8, stat as stat3, readdir as readdir4 } from "fs/promises";
+import { readFile as readFile9, stat as stat3, readdir as readdir4 } from "fs/promises";
 import { resolve as resolve9, relative as relative8, isAbsolute as isAbsolute5 } from "path";
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync14 } from "fs";
 init_semantic();
 
 // src/tools/code-graph.ts
 import { tool as tool7 } from "ai";
 import { z as z8 } from "zod";
 import { resolve as resolve8, relative as relative7, isAbsolute as isAbsolute4, basename as basename3 } from "path";
-import { readFile as readFile7, readdir as readdir3 } from "fs/promises";
-import { existsSync as existsSync11 } from "fs";
+import { readFile as readFile8, readdir as readdir3 } from "fs/promises";
+import { existsSync as existsSync12 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { execFileSync } from "child_process";
 var codeGraphInputSchema = z8.object({
@@ -4336,7 +4492,7 @@ async function grepForSymbol(symbol, workingDirectory) {
           const ext = entry.name.substring(entry.name.lastIndexOf("."));
           if (!SUPPORTED_EXTS.has(ext)) continue;
           remaining--;
-          const content = await readFile7(fullPath, "utf-8");
+          const content = await readFile8(fullPath, "utf-8");
           const lines = content.split("\n");
           for (let i = 0; i < lines.length; i++) {
             if (defPattern.test(lines[i])) {
@@ -4385,7 +4541,7 @@ Working directory: ${options.workingDirectory}`,
         let defSymbol = null;
         if (filePath) {
           const absPath = isAbsolute4(filePath) ? filePath : resolve8(options.workingDirectory, filePath);
-          if (!existsSync11(absPath)) {
+          if (!existsSync12(absPath)) {
             return { success: false, error: `File not found: ${filePath}` };
           }
           if (!isSupported(absPath)) {
@@ -4399,7 +4555,7 @@ Working directory: ${options.workingDirectory}`,
             defLine = defSymbol.selectionRange.start.line;
             defChar = defSymbol.selectionRange.start.character;
           } else {
-            const content = await readFile7(absPath, "utf-8");
+            const content = await readFile8(absPath, "utf-8");
             const lines2 = content.split("\n");
             const defPattern = new RegExp(
               `(export|function|const|let|var|class|interface|type|enum)\\s+.*\\b${symbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`
@@ -4812,7 +4968,7 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
         execute: async ({ path, startLine, endLine }) => {
           try {
             const absolutePath = isAbsolute5(path) ? path : resolve9(workingDirectory, path);
-            if (!existsSync13(absolutePath)) {
+            if (!existsSync14(absolutePath)) {
               return {
                 success: false,
                 error: `File not found: ${path}`
@@ -4825,7 +4981,7 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
                 error: `File too large (${(stats.size / 1024 / 1024).toFixed(2)}MB). Use startLine/endLine to read portions.`
               };
             }
-            let content = await readFile8(absolutePath, "utf-8");
+            let content = await readFile9(absolutePath, "utf-8");
             if (startLine !== void 0 || endLine !== void 0) {
               const lines = content.split("\n");
               const start = (startLine ?? 1) - 1;
@@ -4856,7 +5012,7 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
         execute: async ({ path, recursive, maxDepth }) => {
           try {
             const absolutePath = isAbsolute5(path) ? path : resolve9(workingDirectory, path);
-            if (!existsSync13(absolutePath)) {
+            if (!existsSync14(absolutePath)) {
               return {
                 success: false,
                 error: `Directory not found: ${path}`
@@ -5223,8 +5379,8 @@ function createTaskFailedTool(options) {
 // src/tools/upload-file.ts
 import { tool as tool12 } from "ai";
 import { z as z13 } from "zod";
-import { readFile as readFile9, stat as stat4 } from "fs/promises";
-import { join as join6, basename as basename4, extname as extname7 } from "path";
+import { readFile as readFile10, stat as stat4 } from "fs/promises";
+import { join as join7, basename as basename4, extname as extname7 } from "path";
 var MIME_TYPES = {
   ".txt": "text/plain",
   ".md": "text/markdown",
@@ -5266,7 +5422,7 @@ function createUploadFileTool(options) {
             error: "File upload is not available \u2014 remote server with GCS is not configured."
           };
         }
-        const fullPath = input.path.startsWith("/") ? input.path : join6(options.workingDirectory, input.path);
+        const fullPath = input.path.startsWith("/") ? input.path : join7(options.workingDirectory, input.path);
         try {
           await stat4(fullPath);
         } catch {
@@ -5284,7 +5440,7 @@ function createUploadFileTool(options) {
           contentType,
           "general"
         );
-        const fileData = await readFile9(fullPath);
+        const fileData = await readFile10(fullPath);
         const putRes = await fetch(uploadInfo.uploadUrl, {
           method: "PUT",
           headers: { "Content-Type": contentType },
@@ -5339,7 +5495,8 @@ async function createTools(options) {
       onProgress: options.onWriteFileProgress
     }),
     todo: createTodoTool({
-      sessionId: options.sessionId
+      sessionId: options.sessionId,
+      workingDirectory: options.workingDirectory
     }),
     load_skill: createLoadSkillTool({
       sessionId: options.sessionId,
@@ -5437,6 +5594,8 @@ async function buildSystemPrompt(options) {
   }
   const todos = await todoQueries.getBySession(sessionId);
   const todosContext = formatTodosForContext(todos);
+  const plans = await readSessionPlans(workingDirectory, sessionId);
+  const plansContext = formatPlansForContext(plans);
   const platform2 = process.platform === "win32" ? "Windows" : process.platform === "darwin" ? "macOS" : "Linux";
   const currentDate = (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" });
   const searchInstructions = getSearchInstructions();
@@ -5453,7 +5612,7 @@ You have access to powerful tools for:
 - **read_file**: Read file contents to understand code and context
 - **write_file**: Create new files or edit existing ones (supports targeted string replacement)
 - **linter**: Check files for type errors and lint issues (TypeScript, JavaScript, TSX, JSX)
-- **todo**: Manage your task list to track progress on complex operations
+- **todo**: Manage your task list AND persistent plans for complex multi-phase operations
 - **load_skill**: Load specialized knowledge documents for specific tasks
 - **explore_agent**: Explore agent for semantic discovery - for exploratory questions and finding code by meaning
 - **code_graph**: Inspect a symbol's type hierarchy and usage graph via the TypeScript language server
@@ -5462,9 +5621,23 @@ You have access to powerful tools for:
 
 IMPORTANT: If you have zero context of where you are working, always explore it first to understand the structure before doing things for the user.
 
-Use the TODO tool to manage your task list to track progress on complex operations. Always ask the user what they want to do specifically before doing it, and make a plan. 
-Step 1 of the plan should be researching files and understanding the components/structure of what you're working on (if you don't already have context), then after u have done that, plan out the rest of the tasks u need to do. 
-You can clear the todo and restart it, and do multiple things inside of one session.
+### Planning & Task Management
+Use the **todo tool** to manage both immediate tasks AND persistent plans:
+
+**For simple tasks (< 5 steps):** Just use regular todos (add/mark/clear).
+
+**For complex, multi-phase tasks:** Create a persistent **plan** first.
+1. Research the codebase to understand what you're working with
+2. Create a plan with save_plan \u2014 a structured markdown document with phases and subtasks
+3. Create todos from the first uncompleted phase
+4. Work through the todos
+5. When done, update the plan (mark completed phases with [x]), save it again
+6. Create new todos from the next uncompleted phase
+7. Repeat until the plan is fully complete
+
+Plans persist on disk and are always injected into your context \u2014 they survive context compaction even in very long sessions. You can have multiple plans active at once (e.g., one for frontend, one for backend).
+
+You can clear the todo list and restart it, and do multiple things inside of one session.
 
 ### bash Tool
 The bash tool runs commands in the terminal. Every command runs in its own session with logs saved to disk.
@@ -5688,6 +5861,8 @@ ${onDemandSkillsContext}
 ## Current Task List
 ${todosContext}
 
+${plansContext}
+
 ${customInstructions ? `## Custom Instructions
 ${customInstructions}` : ""}
 
@@ -5711,6 +5886,37 @@ function formatTodosForContext(todos) {
   }
   return lines.join("\n");
 }
+var MAX_PLAN_CHARS = 3e4;
+var MAX_TOTAL_PLANS_CHARS = 6e4;
+function formatPlansForContext(plans) {
+  if (plans.length === 0) return "";
+  let totalChars = 0;
+  const sections = [];
+  sections.push(`## Persistent Plans (${plans.length})`);
+  sections.push("");
+  sections.push("These plans persist across context compaction \u2014 they are always available.");
+  sections.push("When you finish your current todos, check these plans for the next uncompleted phase,");
+  sections.push("update the plan (mark completed items with [x]), then create new todos for the next phase.");
+  sections.push("");
+  for (const plan of plans) {
+    let content = plan.content;
+    if (content.length > MAX_PLAN_CHARS) {
+      content = content.slice(0, MAX_PLAN_CHARS) + `
+
+... [plan truncated \u2014 ${content.length - MAX_PLAN_CHARS} chars omitted. Use get_plan to read the full plan.]`;
+    }
+    if (totalChars + content.length > MAX_TOTAL_PLANS_CHARS) {
+      sections.push(`### \u{1F4CB} Plan: ${plan.name} [truncated \u2014 use get_plan("${plan.name}") to read]`);
+      continue;
+    }
+    sections.push(`### \u{1F4CB} Plan: ${plan.name}`);
+    sections.push("");
+    sections.push(content);
+    sections.push("");
+    totalChars += content.length;
+  }
+  return sections.join("\n");
+}
 function buildTaskPromptAddendum(outputSchema) {
   return `
 ## Task Mode
@@ -5782,7 +5988,7 @@ Before calling \`complete_task\`, you MUST verify your work completely. Do not j
 - **load_skill**: Load specialized skills/knowledge relevant to the task. Check what skills are available and use them.
 - **explore_agent**: Use for codebase exploration and understanding before making changes.
 - **code_graph**: Use to understand type hierarchies, references, and impact before refactoring.
-- **todo**: Track your progress on multi-step tasks so you don't miss steps.
+- **todo**: Track your progress on multi-step tasks so you don't miss steps. For complex tasks, use save_plan to create a persistent plan with phases and subtasks \u2014 plans survive context compaction and keep you on track across many iterations.
 - **bash**: Full shell access \u2014 run builds, tests, dev servers, open browsers, curl endpoints, anything.
 - **upload_file**: Upload files (screenshots, reports, exports) to cloud storage. Use this to include screenshots of completed work in your task result \u2014 visual proof is very helpful.
 
@@ -6289,7 +6495,7 @@ async function sendWebhook(url, event) {
   try {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 5e3);
-    await fetch(url, {
+    const response = await fetch(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -6299,7 +6505,12 @@ async function sendWebhook(url, event) {
       signal: controller.signal
     });
     clearTimeout(timeout);
-  } catch {
+    if (!response.ok) {
+      console.warn(`[WEBHOOK] ${event.type} to ${url} returned HTTP ${response.status}`);
+    }
+  } catch (err) {
+    const reason = err.name === "AbortError" ? "timeout (5s)" : err.message;
+    console.warn(`[WEBHOOK] ${event.type} to ${url} failed: ${reason}`);
   }
 }
 
@@ -6553,12 +6764,14 @@ ${prompt}` });
     const config = getConfig();
     const maxIterations = options.taskConfig.maxIterations ?? 50;
     const webhookUrl = options.taskConfig.webhookUrl;
+    const parentTaskId = options.taskConfig.parentTaskId;
     const fireWebhook = (type, data) => {
       if (!webhookUrl) return;
       sendWebhook(webhookUrl, {
         type,
         taskId: this.session.id,
         sessionId: this.session.id,
+        ...parentTaskId ? { parentTaskId } : {},
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         data
       });
@@ -6751,14 +6964,14 @@ ${taskAddendum}`;
       for (const step of resultSteps) {
         if (step.toolCalls) {
           for (const tc of step.toolCalls) {
-            options.onToolCall?.({ toolCallId: tc.toolCallId, toolName: tc.toolName, input: tc.args });
-            fireWebhook("task.tool_call", { iteration, toolName: tc.toolName, toolCallId: tc.toolCallId, input: tc.args });
+            options.onToolCall?.({ toolCallId: tc.toolCallId, toolName: tc.toolName, input: tc.input });
+            fireWebhook("task.tool_call", { iteration, toolName: tc.toolName, toolCallId: tc.toolCallId, input: tc.input });
           }
         }
         if (step.toolResults) {
           for (const tr of step.toolResults) {
-            options.onToolResult?.({ toolCallId: tr.toolCallId, toolName: tr.toolName, output: tr.result });
-            fireWebhook("task.tool_result", { iteration, toolName: tr.toolName, toolCallId: tr.toolCallId, output: tr.result });
+            options.onToolResult?.({ toolCallId: tr.toolCallId, toolName: tr.toolName, output: tr.output });
+            fireWebhook("task.tool_result", { iteration, toolName: tr.toolName, toolCallId: tr.toolCallId, output: tr.output });
           }
         }
       }
@@ -6850,14 +7063,14 @@ ${taskAddendum}`;
       const result = await recorder.encode();
       recorder.clear();
       if (!result) return [];
-      const { readFile: readFile11, unlink: unlink3 } = await import("fs/promises");
+      const { readFile: readFile12, unlink: unlink3 } = await import("fs/promises");
       const uploadInfo = await storageQueries2.getUploadUrl(
         this.session.id,
         `browser-recording-${Date.now()}.mp4`,
         "video/mp4",
         "browser-recording"
       );
-      const fileData = await readFile11(result.path);
+      const fileData = await readFile12(result.path);
       await fetch(uploadInfo.uploadUrl, {
         method: "PUT",
         headers: { "Content-Type": "video/mp4" },
@@ -6883,12 +7096,12 @@ ${taskAddendum}`;
     try {
       const { isRemoteConfigured: isRemoteConfigured2, storageQueries: storageQueries2 } = await Promise.resolve().then(() => (init_remote(), remote_exports));
       if (!isRemoteConfigured2()) return [];
-      const { readFile: readFile11 } = await import("fs/promises");
-      const { join: join8, basename: basename5 } = await import("path");
+      const { readFile: readFile12 } = await import("fs/promises");
+      const { join: join9, basename: basename5 } = await import("path");
       const urls = [];
       for (const filePath of filePaths) {
         try {
-          const fullPath = filePath.startsWith("/") ? filePath : join8(this.session.workingDirectory, filePath);
+          const fullPath = filePath.startsWith("/") ? filePath : join9(this.session.workingDirectory, filePath);
           const fileName = basename5(fullPath);
           const ext = fileName.split(".").pop()?.toLowerCase() || "";
           const mimeMap = {
@@ -6913,7 +7126,7 @@ ${taskAddendum}`;
             contentType,
             "task-output"
           );
-          const fileData = await readFile11(fullPath);
+          const fileData = await readFile12(fullPath);
           await fetch(uploadInfo.uploadUrl, {
             method: "PUT",
             headers: { "Content-Type": contentType },