todo_tool.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336
  1. """Todo tool: in-memory, revisioned task list for multi-step work. State lives on the
  2. AIAgent (one per session), is re-injected after context compression, and every write bumps
  3. a monotonic revision so UI clients can reject stale updates. One ``todo_list`` tool: pass
  4. ``todos`` to write, omit to read; every call returns the full list. No system-prompt mutation."""
  5. import json
  6. from typing import Any, Dict, List, Optional
  7. VALID_STATUSES = {"pending", "in_progress", "completed", "cancelled"}
  8. # The list is re-read after every compression (format_for_injection), so unbounded
  9. # content/count would defeat the compression it rides through. Caps apply equally to
  10. # model-authored items and caller-replayed API history.
  11. MAX_TODO_CONTENT_CHARS = 4000
  12. MAX_TODO_ITEMS = 256
  13. # Max single todo tool-result payload accepted during history hydration, so a forged
  14. # oversized result is dropped before parsing (AIAgent._hydrate_todo_store).
  15. MAX_TODO_RESULT_CHARS = 512_000
  16. _TRUNCATION_MARKER = "… [truncated]"
  17. # Persisted as ordinary message content; ContextCompressor keys on this stable header to
  18. # tell the synthetic post-compaction row from a real user message.
  19. TODO_INJECTION_HEADER = "[Your active task list was preserved across context compression]"
  20. _STATUS_MARKERS = {"completed": "[x]", "in_progress": "[>]", "pending": "[ ]", "cancelled": "[~]"}
  21. _ACTIVE_STATUSES = {"pending", "in_progress"}
  22. class TodoStore:
  23. """In-memory todo list, one per AIAgent. List position is priority; items are
  24. ``{id, content, status, parent?}`` — ``parent`` nests a subtask."""
  25. def __init__(self):
  26. self._items: list[dict[str, str]] = []
  27. self._revision = 0
  28. def _fresh_items(self, todos: list[dict[str, Any]]) -> list[dict[str, str]]:
  29. """Validate, dedupe and order a whole new list (replace / restore)."""
  30. return self._normalize_order([self._validate(t) for t in self._dedupe_by_id(todos)])
  31. def write(self, todos: list[dict[str, Any]], merge: bool = False) -> list[dict[str, str]]:
  32. """Replace the list (default) or merge by id; returns the full list after writing.
  33. Raises ValueError (leaving the list untouched) if any item is invalid."""
  34. before = self.read()
  35. try:
  36. if merge:
  37. self._merge(todos)
  38. else:
  39. self._items = self._fresh_items(todos)
  40. except ValueError:
  41. self._items = before # rejected write must not leave a partial list behind
  42. raise
  43. del self._items[MAX_TODO_ITEMS:] # keep the priority head; replays can't grow unbounded
  44. self._sanitize_parents(self._items)
  45. if self._items != before:
  46. self._revision += 1
  47. return self.read()
  48. def _merge(self, todos: list[dict[str, Any]]) -> None:
  49. """Update existing items only in the fields provided; append new ones (validated)."""
  50. existing = {item["id"]: item for item in self._items}
  51. for t in self._dedupe_by_id(todos):
  52. item_id = str(t.get("id", "")).strip()
  53. if not item_id:
  54. continue # can't merge without an id
  55. cur = existing.get(item_id)
  56. if cur is None:
  57. validated = self._validate(t)
  58. existing[validated["id"]] = validated
  59. self._items.append(validated)
  60. continue
  61. if t.get("content"):
  62. cur["content"] = self._cap_content(str(t["content"]).strip())
  63. if t.get("status") and str(t["status"]).strip().lower() in VALID_STATUSES:
  64. cur["status"] = str(t["status"]).strip().lower()
  65. if "parent" in t:
  66. parent = str(t["parent"] or "").strip()
  67. if parent:
  68. cur["parent"] = parent
  69. else:
  70. cur.pop("parent", None)
  71. # Rebuild preserving original order for existing items (first occurrence wins).
  72. rebuilt = {item["id"]: existing.get(item["id"], item) for item in self._items}
  73. self._items = self._normalize_order(list(rebuilt.values()))
  74. def read(self) -> list[dict[str, str]]:
  75. return [item.copy() for item in self._items]
  76. def has_items(self) -> bool:
  77. return bool(self._items)
  78. def snapshot(self) -> dict[str, Any]:
  79. """Full state clients can reconcile atomically."""
  80. return {"todos": self.read(), "revision": self._revision}
  81. def restore(self, todos: list[dict[str, Any]], *, revision: Any = 0) -> list[dict[str, str]]:
  82. """Restore a trusted snapshot without manufacturing a new revision."""
  83. self._items = self._fresh_items(todos)[:MAX_TODO_ITEMS]
  84. try:
  85. self._revision = max(0, int(revision or 0))
  86. except (TypeError, ValueError):
  87. self._revision = 0
  88. return self.read()
  89. def format_for_injection(self) -> Optional[str]:
  90. """Render the list for post-compression injection, or None if nothing active. Only
  91. pending/in_progress items are injected — finished ones make the model re-do work after
  92. compression. A parent is kept (with its real status marker) when any descendant is
  93. active so subtasks keep context."""
  94. if not self._items:
  95. return None
  96. children: dict[str, list[dict[str, str]]] = {}
  97. for item in self._items:
  98. if item.get("parent"):
  99. children.setdefault(item["parent"], []).append(item)
  100. def render(item: dict[str, str], depth: int, out: list[str]) -> bool:
  101. kid_lines: list[str] = []
  102. has_active_kid = False
  103. for kid in children.get(item["id"], []):
  104. has_active_kid |= render(kid, depth + 1, kid_lines)
  105. keep = item["status"] in _ACTIVE_STATUSES or has_active_kid
  106. if keep:
  107. marker = _STATUS_MARKERS.get(item["status"], "[?]")
  108. out.append(f"{' ' * depth}- {marker} {item['id']}. "
  109. f"{item['content']} ({item['status']})")
  110. out.extend(kid_lines)
  111. return keep
  112. lines = [TODO_INJECTION_HEADER]
  113. for item in self._items:
  114. if not item.get("parent"):
  115. render(item, 0, lines)
  116. return "\n".join(lines) if len(lines) > 1 else None
  117. @staticmethod
  118. def _cap_content(content: str) -> str:
  119. """Truncate to MAX_TODO_CONTENT_CHARS keeping the head (the actionable part) + marker."""
  120. if len(content) > MAX_TODO_CONTENT_CHARS:
  121. return content[:MAX_TODO_CONTENT_CHARS - len(_TRUNCATION_MARKER)] + _TRUNCATION_MARKER
  122. return content
  123. @staticmethod
  124. def _validate(item: dict[str, Any]) -> dict[str, str]:
  125. """Normalize one item to ``{id, content, status, parent?}`` (placeholders when missing)."""
  126. if not isinstance(item, dict):
  127. return {"id": "?", "content": "(invalid item)", "status": "pending"}
  128. item_id = str(item.get("id", "")).strip() or "?"
  129. content = str(item.get("content", "")).strip()
  130. if not content:
  131. raise ValueError(
  132. f"Todo item '{item_id}' has empty or missing content. "
  133. "Each item must have a non-empty description."
  134. )
  135. status = str(item.get("status", "pending")).strip().lower()
  136. result = {"id": item_id,
  137. "content": TodoStore._cap_content(content),
  138. "status": status if status in VALID_STATUSES else "pending"}
  139. parent = str(item.get("parent") or "").strip()
  140. if parent and parent != item_id:
  141. result["parent"] = parent
  142. return result
  143. @staticmethod
  144. def _sanitize_parents(items: list[dict[str, str]]) -> None:
  145. """Drop dangling parent refs and break cycles in place (such items become roots)."""
  146. by_id = {item["id"]: item for item in items}
  147. for item in items:
  148. if item.get("parent") and item["parent"] not in by_id:
  149. item.pop("parent", None)
  150. for item in items:
  151. seen, node = {item["id"]}, item
  152. while node.get("parent"):
  153. if node["parent"] in seen:
  154. item.pop("parent", None)
  155. break
  156. seen.add(node["parent"])
  157. node = by_id[node["parent"]]
  158. @staticmethod
  159. def _dedupe_by_id(todos: list[dict[str, Any]]) -> list[dict[str, Any]]:
  160. """Collapse duplicate ids, keeping the last occurrence in its position."""
  161. last_index: dict[str, int] = {}
  162. for i, item in enumerate(todos): # non-dicts get a synthetic key; _validate handles them
  163. key = str(item.get("id", "")).strip() if isinstance(item, dict) else f"__invalid_{i}"
  164. last_index[key or "?"] = i
  165. return [todos[i] for i in sorted(last_index.values())]
  166. @staticmethod
  167. def _normalize_order(items: list[dict[str, str]]) -> list[dict[str, str]]:
  168. """Lift the in_progress step ahead of any earlier pending placeholder. Nested lists
  169. keep authored order — reordering would tear a subtask from its siblings."""
  170. statuses = [item["status"] for item in items]
  171. if any(item.get("parent") for item in items) or "in_progress" not in statuses:
  172. return items
  173. active_index = statuses.index("in_progress")
  174. if "pending" not in statuses[:active_index]:
  175. return items
  176. normalized = items.copy()
  177. normalized.insert(statuses.index("pending"), normalized.pop(active_index))
  178. return normalized
  179. def todo_tool(todos: Optional[list[dict[str, Any]]] = None, merge: bool = False,
  180. store: Optional[TodoStore] = None) -> str:
  181. """Write ``todos`` (replace, or ``merge`` by id) or read when None -> list + summary JSON."""
  182. if store is None:
  183. return tool_error("TodoStore not initialized")
  184. if todos is None:
  185. items = store.read()
  186. else:
  187. if not isinstance(todos, list):
  188. return tool_error(f"todos must be a list, got {type(todos).__name__}")
  189. try:
  190. items = store.write(todos, merge)
  191. except ValueError as e:
  192. return tool_error(str(e))
  193. summary = {"total": len(items)}
  194. for status in ("pending", "in_progress", "completed", "cancelled"):
  195. summary[status] = sum(1 for i in items if i["status"] == status)
  196. return json.dumps({"todos": items, "revision": store.snapshot()["revision"],
  197. "summary": summary}, ensure_ascii=False)
  198. def check_todo_requirements() -> bool:
  199. """Todo tool has no external requirements -- always available."""
  200. return True
  201. # Behavioral guidance is baked into the (static, cached) description; item shape and merge
  202. # semantics live ONLY in the parameter schema.
  203. TODO_SCHEMA = {
  204. "name": "todo_list",
  205. "description": (
  206. # See #95681.
  207. "Track a task list for multi-step work (3+ steps). Use for complex tasks "
  208. "with 3+ steps or when the user provides multiple tasks. "
  209. "For 'all N items' tasks, enumerate every instance as its own checklist "
  210. "item so none are silently dropped. "
  211. "Call with no parameters to read the current list.\n"
  212. "List order is priority. Only ONE item in_progress at a time. "
  213. "Break large phases into subtasks via parent. "
  214. "Mark an item completed only after the work is verified done, never "
  215. "based on intent. If something fails, cancel it and add a revised "
  216. "item. Always returns the full current list."
  217. ),
  218. "parameters": {
  219. "type": "object",
  220. "properties": {
  221. "todos": {
  222. "type": "array",
  223. "description": "Task items to write.",
  224. "items": {
  225. "type": "object",
  226. "properties": {
  227. "id": {
  228. "type": "string"
  229. },
  230. "content": {
  231. "type": "string",
  232. "description": "Task description"
  233. },
  234. "status": {
  235. "type": "string",
  236. "enum": ["pending", "in_progress", "completed", "cancelled"]
  237. },
  238. "parent": {
  239. "type": "string",
  240. "description": "Optional id of another item, making this a nested subtask. Omit for top-level."
  241. }
  242. },
  243. "required": ["id", "content", "status"]
  244. }
  245. },
  246. "merge": {
  247. "type": "boolean",
  248. "description": (
  249. "true: update existing items by id, add new ones. "
  250. "false (default): replace the entire list with a fresh plan."
  251. ),
  252. "default": False
  253. }
  254. },
  255. "required": []
  256. }
  257. }
  258. # Pre-rename names that replay as the Todo tool. model_tools._LEGACY_TOOL_ALIASES derives its todo
  259. # entries from this, so the alias map and the transcript/TUI predicates below cannot drift.
  260. TODO_LEGACY_ALIASES = ("todo",)
  261. TODO_TOOL_NAMES = frozenset((TODO_SCHEMA["name"], *TODO_LEGACY_ALIASES))
  262. def is_todo_tool_name(name: Any) -> bool:
  263. """True for the Todo tool's current name or a legacy alias (an already-unwrapped dispatch name)."""
  264. return isinstance(name, str) and name in TODO_TOOL_NAMES
  265. def is_todo_tool_call(tool_call: Any) -> bool:
  266. """True when a transcript tool_call entry (dict or object) invoked the Todo tool.
  267. Covers the current name, legacy aliases, and the ``tool_call`` bridge (``todo_list`` is deferred by
  268. default, and the transcript keeps the bridge name). The bridge is peeled from the recorded arguments
  269. only, never live tool-search config, and must wrap exactly one call. Keep this module free of model_tools / agent.tool_executor
  270. imports: TUI resume and run_agent call this without loading either.
  271. """
  272. from agent.message_sanitization import _tc_field
  273. fn = _tc_field(tool_call, "function")
  274. name, raw_args = _tc_field(fn, "name") or "", _tc_field(fn, "arguments")
  275. if is_todo_tool_name(name):
  276. return True
  277. # Cheap heuristic before the bridge modules load: skip args without a literal "todo". Only a
  278. # unicode-escaped name slips past, which json.dumps never writes for ASCII.
  279. if isinstance(raw_args, str) and "todo" not in raw_args:
  280. return False
  281. from tools.tool_search_catalog import TOOL_CALL_NAME
  282. if name != TOOL_CALL_NAME:
  283. return False
  284. try:
  285. args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
  286. except json.JSONDecodeError:
  287. return False
  288. if not isinstance(args, dict):
  289. return False
  290. from tools.tool_search_validation import normalize_tool_call_entries
  291. entries, error = normalize_tool_call_entries(args)
  292. return not error and len(entries) == 1 and is_todo_tool_name(entries[0]["name"])
  293. from tools.registry import registry, tool_error
  294. registry.register(
  295. name="todo_list", toolset="todo", schema=TODO_SCHEMA, check_fn=check_todo_requirements,
  296. handler=lambda args, **kw: todo_tool(
  297. todos=args.get("todos"), merge=args.get("merge", False), store=kw.get("store")),
  298. emoji="📋")