{"version":3,"file":"todo.d.ts","sourceRoot":"","sources":["../../../src/core/tools/todo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAa,KAAK,UAAU,EAAa,MAAM,kBAAkB,CAAC;AAmCzE,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CAClB;AA2CD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAAC,GAAG,MAAM,CAWlG;AAED,qFAAqF;AACrF,wBAAgB,6BAA6B,IAAI,cAAc,CAyG9D","sourcesContent":["/**\n * TodoWrite tool: let the main agent maintain a visible todo list for the\n * current task.\n *\n * hoocode already has all the infrastructure this needs — the task store models\n * `{ title, status }` items with a per-turn lifecycle, and the TUI task panel\n * renders them. The only missing piece was a tool the model can call; this is\n * that thin adapter over `taskStore`.\n *\n * Semantics mirror Claude Code's TodoWrite: each call sends the FULL list and\n * REPLACES the previous one. Because the store is incremental (numeric ids), we\n * reconcile the incoming list against the existing main-agent tasks by position:\n * update items that are still there, create new ones, and drop the tail that was\n * removed. Reconciling (rather than clear-and-recreate) keeps ids stable so the\n * panel does not flicker and in-progress rows stay put.\n *\n * It is an optional, opt-in tool (enabled via the `enableTodoWrite` setting) and\n * is never registered inside a spawned subagent, so a subagent's todos cannot\n * leak into the parent's \"main\" task group.\n */\n\nimport { type Static, Type } from \"typebox\";\nimport { TODO_WRITE_TOOL_NAME } from \"../agent-frontmatter.js\";\nimport { defineTool, type ToolDefinition } from \"../extensions/types.js\";\nimport { type Task, type TaskStatus, taskStore } from \"../task-store.js\";\n\nconst todoStatusSchema = Type.Union([Type.Literal(\"pending\"), Type.Literal(\"in_progress\"), Type.Literal(\"completed\")], {\n\tdescription: \"pending = not started, in_progress = actively being worked on, completed = finished.\",\n});\n\nconst todoItemSchema = Type.Object(\n\t{\n\t\tcontent: Type.String({\n\t\t\tdescription: \"The task, in imperative form (e.g. 'Add tests for the parser').\",\n\t\t}),\n\t\tstatus: todoStatusSchema,\n\t\tactiveForm: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription:\n\t\t\t\t\t\"Optional present-tense form shown while the item is in_progress (e.g. 'Adding tests for the parser').\",\n\t\t\t}),\n\t\t),\n\t},\n\t{ additionalProperties: false },\n);\n\nconst todoWriteParams = Type.Object(\n\t{\n\t\ttodos: Type.Array(todoItemSchema, {\n\t\t\tdescription:\n\t\t\t\t\"The complete todo list. This REPLACES the previous list on every call, so always send every item with its current status — omitting an item removes it.\",\n\t\t}),\n\t},\n\t{ additionalProperties: false },\n);\n\ntype TodoWriteParams = Static<typeof todoWriteParams>;\ntype IncomingStatus = TodoWriteParams[\"todos\"][number][\"status\"];\n\nexport interface TodoWriteDetails {\n\ttotal: number;\n\tpending: number;\n\tinProgress: number;\n\tcompleted: number;\n}\n\n/** Map the model-facing status vocabulary onto the task store's. */\nfunction toTaskStatus(status: IncomingStatus): TaskStatus {\n\treturn status === \"completed\" ? \"done\" : status;\n}\n\nconst STATUS_GLYPH: Record<TaskStatus, string> = {\n\tpending: \"[ ]\",\n\tin_progress: \"[~]\",\n\tdone: \"[x]\",\n\tfailed: \"[!]\",\n\t// TodoWrite never produces cancelled items; present for Record exhaustiveness.\n\tcancelled: \"[-]\",\n};\n\n/** Title to display: the active-form while in progress, otherwise the content. */\nfunction displayTitle(item: TodoWriteParams[\"todos\"][number]): string {\n\tif (item.status === \"in_progress\" && item.activeForm?.trim()) return item.activeForm.trim();\n\treturn item.content.trim();\n}\n\n/**\n * A root task the main agent itself owns, i.e. a TodoWrite plan item: no\n * `source` (excludes \"subagent\"/MCP rows), no `agent` (excludes delegated rows),\n * and no `parentTaskId` (excludes merged child trees). `taskOwnerId()` would\n * fold MCP-sourced and delegated rows under \"main\", so reconciling against it\n * could overwrite or drop those rows when the TodoWrite list is shorter than the\n * combined count.\n */\nfunction isMainPlanTask(task: Task): boolean {\n\treturn task.source === undefined && task.agent === undefined && task.parentTaskId === undefined;\n}\n\n/** Current main-agent plan tasks, in stable creation order. */\nfunction mainTasks(): Task[] {\n\treturn taskStore.list().filter(isMainPlanTask);\n}\n\nfunction isActive(task: Task): boolean {\n\treturn task.status === \"pending\" || task.status === \"in_progress\";\n}\n\n/**\n * Settle plan items the model left pinned at `in_progress` when a request ends.\n *\n * TodoWrite is bookkeeping the model performs by hand, and even strong models\n * routinely drop the final call that flips the last item to completed. Nothing\n * else writes main-plan rows, so without this the panel would keep claiming the\n * work is in flight until the next user message triggers `taskStore.reset()`.\n * The request is over, so the row is wrong either way — settle it to the honest\n * outcome instead of leaving it lying.\n *\n * Scope is deliberately narrow:\n * - Only `in_progress` main-plan items. `pending` rows are left alone: \"never\n *   started\" is already an accurate reading of an item the model skipped.\n * - Only main-plan items. Subagent- and MCP-sourced rows settle through their\n *   own lifecycles (subagent.ts, mcp-loader.ts) and must not be second-guessed\n *   here.\n * - Nothing settles while any delegated task is still pending/in_progress: a\n *   subagent outliving the parent's agent_end is still working the plan, so its\n *   plan item is genuinely in progress.\n *\n * Returns the number of tasks settled.\n */\nexport function settleDanglingMainTasks(outcome: Extract<TaskStatus, \"done\" | \"cancelled\">): number {\n\tconst all = taskStore.list();\n\tif (all.some((t) => !isMainPlanTask(t) && isActive(t))) return 0;\n\tconst dangling = all.filter((t) => isMainPlanTask(t) && t.status === \"in_progress\");\n\tif (dangling.length === 0) return 0;\n\ttaskStore.batch(() => {\n\t\tfor (const task of dangling) {\n\t\t\ttaskStore.update(task.id, { status: outcome });\n\t\t}\n\t});\n\treturn dangling.length;\n}\n\n/** Create the TodoWrite tool definition. Registered as a customTool when enabled. */\nexport function createTodoWriteToolDefinition(): ToolDefinition {\n\treturn defineTool<typeof todoWriteParams, TodoWriteDetails>({\n\t\tname: TODO_WRITE_TOOL_NAME,\n\t\tlabel: TODO_WRITE_TOOL_NAME,\n\t\tdescription: [\n\t\t\t\"Maintain a structured todo list for the current task, shown live in the task panel.\",\n\t\t\t\"Write the full plan as todos before starting multi-step or non-trivial work, and keep it current; skip only trivial single-step tasks.\",\n\t\t\t\"Mark exactly ONE item in_progress at a time, and flip an item to completed immediately after finishing it.\",\n\t\t\t\"Each call sends the FULL list and REPLACES the previous one — include every item with its current status; omitting an item removes it.\",\n\t\t].join(\"\\n\"),\n\t\tpromptSnippet:\n\t\t\t\"Plan and track multi-step work as a live todo list (use proactively; replaces the whole list each call)\",\n\t\t// Only the \"reach for it at all\" cue lives here — that is the system-prompt's\n\t\t// job. The calling contract (one in_progress, full-list replacement, when to\n\t\t// skip) is already stated in `description` and in the `todos` schema, both of\n\t\t// which ship on every turn alongside this. Same rule three times spent the\n\t\t// tokens three times.\n\t\tpromptGuidelines: [\n\t\t\t\"Use TodoWrite proactively for multi-step or non-trivial work; skip trivial single-step tasks.\",\n\t\t],\n\t\tparameters: todoWriteParams,\n\t\tasync execute(_toolCallId, params: TodoWriteParams) {\n\t\t\tconst todos = params.todos ?? [];\n\t\t\tconst existing = mainTasks();\n\n\t\t\t// Reconcile by item identity first, position second, batched so the panel\n\t\t\t// renders once. Each task stores its item's canonical `content`\n\t\t\t// (todoContent) — the display title flips between content and activeForm\n\t\t\t// with status, so it can't identify an item. Matching by content keeps a\n\t\t\t// task's id pinned to the same plan item when the list is reordered or\n\t\t\t// shrunk; a purely positional reconcile re-labeled the surviving slots,\n\t\t\t// which silently re-pointed the subagent runs linked to those ids\n\t\t\t// (linkedTaskId) at the wrong plan items. Unmatched incoming items then\n\t\t\t// consume the leftover slots in order (a rename keeps its id and its\n\t\t\t// linked runs); any remaining leftovers were removed from the plan.\n\t\t\ttaskStore.batch(() => {\n\t\t\t\tconst content = (item: TodoWriteParams[\"todos\"][number]) => item.content.trim();\n\t\t\t\tconst matchedExisting = new Set<number>();\n\t\t\t\tconst assigned = new Array<Task | undefined>(todos.length);\n\t\t\t\tfor (let i = 0; i < todos.length; i++) {\n\t\t\t\t\tconst idx = existing.findIndex(\n\t\t\t\t\t\t(t, j) => !matchedExisting.has(j) && (t.todoContent ?? t.title) === content(todos[i]!),\n\t\t\t\t\t);\n\t\t\t\t\tif (idx !== -1) {\n\t\t\t\t\t\tmatchedExisting.add(idx);\n\t\t\t\t\t\tassigned[i] = existing[idx];\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tconst leftovers = existing.filter((_, j) => !matchedExisting.has(j));\n\t\t\t\tlet nextLeftover = 0;\n\t\t\t\tfor (let i = 0; i < todos.length; i++) {\n\t\t\t\t\tif (!assigned[i]) assigned[i] = leftovers[nextLeftover++];\n\t\t\t\t}\n\n\t\t\t\tconst finalIds: number[] = [];\n\t\t\t\tfor (let i = 0; i < todos.length; i++) {\n\t\t\t\t\tconst item = todos[i]!;\n\t\t\t\t\tconst status = toTaskStatus(item.status);\n\t\t\t\t\tconst title = displayTitle(item);\n\t\t\t\t\tconst current = assigned[i];\n\t\t\t\t\tif (current) {\n\t\t\t\t\t\ttaskStore.update(current.id, { title, status, todoContent: content(item) });\n\t\t\t\t\t\tfinalIds.push(current.id);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst created = taskStore.create(title);\n\t\t\t\t\t\ttaskStore.update(created.id, { status, todoContent: content(item) });\n\t\t\t\t\t\tfinalIds.push(created.id);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tfor (let j = nextLeftover; j < leftovers.length; j++) {\n\t\t\t\t\ttaskStore.remove(leftovers[j]!.id);\n\t\t\t\t}\n\t\t\t\t// Identity matching keeps ids, but the panel must still show the plan\n\t\t\t\t// in the list's order — permute the plan tasks into it.\n\t\t\t\ttaskStore.arrange(finalIds);\n\t\t\t});\n\n\t\t\tconst counts = todos.reduce(\n\t\t\t\t(acc, t) => {\n\t\t\t\t\tif (t.status === \"in_progress\") acc.inProgress++;\n\t\t\t\t\telse if (t.status === \"completed\") acc.completed++;\n\t\t\t\t\telse acc.pending++;\n\t\t\t\t\treturn acc;\n\t\t\t\t},\n\t\t\t\t{ pending: 0, inProgress: 0, completed: 0 },\n\t\t\t);\n\n\t\t\tconst lines = todos.map((t) => `${STATUS_GLYPH[toTaskStatus(t.status)]} ${displayTitle(t)}`);\n\t\t\tconst header =\n\t\t\t\ttodos.length === 0\n\t\t\t\t\t? \"Todo list cleared.\"\n\t\t\t\t\t: `Todos updated (${counts.inProgress} in progress, ${counts.pending} pending, ${counts.completed} completed):`;\n\t\t\tconst text = todos.length === 0 ? header : `${header}\\n${lines.join(\"\\n\")}`;\n\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\" as const, text }],\n\t\t\t\tdetails: {\n\t\t\t\t\ttotal: todos.length,\n\t\t\t\t\tpending: counts.pending,\n\t\t\t\t\tinProgress: counts.inProgress,\n\t\t\t\t\tcompleted: counts.completed,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t});\n}\n"]}