add ChecklistTool; implement stateful checklist for task management and progress tracking

Author: dcloud347

argus/tools/checklist.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import Any
+
+from argus.data.content import Content
+from argus.tools.base import Tool
+
+
+class ChecklistTool(Tool):
+    """Stateful checklist tool for tracking task progress across a run."""
+
+    name = "checklist"
+    description = (
+        "Manage a task checklist to plan and track your progress. "
+        "Use action='init' at the start to list all planned steps, "
+        "'complete' to mark a step done by its index, "
+        "'add' to append a new step discovered mid-task, "
+        "and 'view' to see current state."
+    )
+    parameters: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["init", "complete", "add", "view"],
+                "description": (
+                    "'init': create a new checklist (replaces any existing one); "
+                    "'complete': mark the item at the given index as done; "
+                    "'add': append a new item; "
+                    "'view': display current checklist state."
+                ),
+            },
+            "items": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Ordered list of step descriptions. Required for action='init'.",
+            },
+            "index": {
+                "type": "integer",
+                "description": "0-based index of the item to complete. Required for action='complete'.",
+            },
+            "item": {
+                "type": "string",
+                "description": "Description of the new step to append. Required for action='add'.",
+            },
+        },
+        "required": ["action"],
+    }
+
+    def __init__(self) -> None:
+        self._items: list[dict[str, Any]] = []  # {"text": str, "done": bool}
+
+    def reset(self) -> None:
+        """Clear checklist state at the start of a new run."""
+        self._items = []
+
+    def render(self) -> str:
+        if not self._items:
+            return "Checklist is empty."
+        lines = ["=== Task Checklist ==="]
+        for i, it in enumerate(self._items):
+            mark = "x" if it["done"] else " "
+            lines.append(f"  [{mark}] {i}. {it['text']}")
+        done = sum(1 for it in self._items if it["done"])
+        lines.append(f"\nProgress: {done}/{len(self._items)} completed")
+        return "\n".join(lines)
+
+    def execute(
+        self,
+        action: str,
+        items: list[str] | None = None,
+        index: int | None = None,
+        item: str | None = None,
+    ) -> Content:
+        if action == "init":
+            if not items:
+                return Content(text="[error: 'items' is required for action='init']")
+            self._items = [{"text": t, "done": False} for t in items]
+            return Content(
+                text=f"Checklist initialized with {len(self._items)} items.\n\n{self.render()}"
+            )
+
+        if action == "complete":
+            if index is None:
+                return Content(text="[error: 'index' is required for action='complete']")
+            if index < 0 or index >= len(self._items):
+                return Content(
+                    text=f"[error: index {index} out of range (valid: 0–{len(self._items) - 1})]"
+                )
+            self._items[index]["done"] = True
+            return Content(text=f"Item {index} marked as done.\n\n{self.render()}")
+
+        if action == "add":
+            if not item:
+                return Content(text="[error: 'item' is required for action='add']")
+            self._items.append({"text": item, "done": False})
+            return Content(text=f"Item added at index {len(self._items) - 1}.\n\n{self.render()}")
+
+        if action == "view":
+            return Content(text=self.render())
+
+        return Content(text=f"[error: unknown action '{action}']")