deepy-cli 0.2.3__tar.gz → 0.2.4__tar.gz

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: deepy-cli
-Version: 0.2.3
+Version: 0.2.4
 Summary: Deepy - Vibe coding for DeepSeek models in your terminal
 Keywords: deepseek,coding-agent,terminal,cli,agents
 Author: kirineko

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepy-cli"
-version = "0.2.3"
+version = "0.2.4"
 description = "Deepy - Vibe coding for DeepSeek models in your terminal"
 readme = "README.md"
 authors = [

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 
 def main() -> None:

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/data/tools/AskUserQuestion.md

@@ -10,6 +10,12 @@
 标注 `(Recommended)` 或中文等价表达。不要为了低影响细节提问；可以合理假设时
 继续推进并简短说明假设。
 
+Agent Skills 可能使用通用说法，例如 ask the user、ask one question at a time、
+wait for the user's response、get approval、review 或 confirm before continuing。
+在 Deepy 中，除非 skill 明确要求不要使用工具，否则这些等待用户输入的步骤都应通过
+`AskUserQuestion` 完成。开放问题也必须提供选项；可加入“自定义回答”/`Custom answer`
+作为选项，让用户输入自由文本。
+
 Args: `questions` (non-empty array). Each question needs `question` and non-empty `options`;
 each option needs `label` and may include `description`. Use `multiSelect=true` only when
 multiple choices are allowed.

deepy_cli-0.2.4/src/deepy/data/tools/todo_write.md

@@ -0,0 +1,16 @@
+## todo_write
+
+Maintain a session-scoped todo list for complex work.
+
+Use `todo_write` when the user asks for several deliverables, the work touches
+multiple files, or the task naturally breaks into three or more meaningful
+steps. Do not use it for simple questions, tiny one-step edits, or routine
+commands where a todo list would add noise.
+
+Each update replaces the complete list. Keep item `id` values stable across
+updates. Use exactly one `in_progress` item at a time, mark completed work as
+`completed`, and update the list only when real progress changes. Omit `todos`
+to read the current list; pass an empty list to clear it.
+
+This tool only tracks progress. It does not delegate to subagents and it does
+not request plan approval.

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/llm/compaction.py

@@ -8,6 +8,7 @@ from typing import Any, Literal
 from deepy.config import Settings
 from deepy.prompts.compact import build_compact_prompt, build_compact_summary_message
 from deepy.sessions.jsonl import DeepyJsonlSession
+from deepy.todos import todo_state_prompt_text
 from deepy.usage import TokenUsage, usage_from_run_result
 
 from .context import estimate_tokens_for_item, estimate_tokens_for_items
@@ -81,6 +82,7 @@ async def compact_session(
         settings,
         provider=provider,
         focus_instruction=focus_instruction,
+        todo_state=session.todo_state(),
     )
     replacement = sanitize_sdk_items_for_replay(
         [build_compact_summary_message(summary), *to_preserve]
@@ -124,9 +126,7 @@ async def ensure_context_ready(
     before_tokens = state.active_tokens + additional_tokens
     latest_context_usage = session.latest_context_window_usage()
     trigger_tokens = (
-        latest_context_usage.used_tokens
-        if latest_context_usage is not None
-        else before_tokens
+        latest_context_usage.used_tokens if latest_context_usage is not None else before_tokens
     )
     compacted: CompactionResult | None = None
     if trigger_tokens >= settings.context.resolved_compact_threshold:
@@ -144,9 +144,7 @@ async def ensure_context_ready(
     else:
         after_context_usage = session.latest_context_window_usage()
         fit_tokens = (
-            after_context_usage.used_tokens
-            if after_context_usage is not None
-            else after_tokens
+            after_context_usage.used_tokens if after_context_usage is not None else after_tokens
         )
     if fit_tokens + settings.context.reserved_context_tokens >= settings.context.window_tokens:
         raise ContextCompactionError(
@@ -198,11 +196,16 @@ async def run_compaction_model(
     *,
     provider: ProviderBundle | None = None,
     focus_instruction: str | None = None,
+    todo_state: list[dict[str, str]] | None = None,
 ) -> tuple[str, TokenUsage]:
     from agents import Agent, RunConfig, Runner
 
     resolved_provider = provider or build_provider_bundle(settings)
-    prompt = build_compact_prompt(items, focus_instruction=focus_instruction)
+    prompt = build_compact_prompt(
+        items,
+        focus_instruction=focus_instruction,
+        todo_context=todo_state_prompt_text(todo_state or []),
+    )
     agent = Agent(
         name="Deepy Context Compactor",
         instructions="Create a compact continuation summary. Do not call tools.",
@@ -254,7 +257,10 @@ def _expand_preserve_start_for_tool_group(items: list[dict[str, Any]], preserve_
     if not needed_call_ids:
         return preserve_start
     for index in range(preserve_start - 1, -1, -1):
-        if items[index].get("type") == "function_call" and _call_id(items[index]) in needed_call_ids:
+        if (
+            items[index].get("type") == "function_call"
+            and _call_id(items[index]) in needed_call_ids
+        ):
             preserve_start = index
             needed_call_ids.discard(_call_id(items[index]))
             if not needed_call_ids:

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/llm/runner.py

@@ -12,6 +12,7 @@ from deepy.config import Settings, load_settings
 from deepy.sessions.jsonl import DeepyJsonlSession
 from deepy.skills import find_skill
 from deepy.mcp import DeepyMcpRuntime
+from deepy.todos import normalize_todo_items
 from deepy.tools import ToolRuntime
 from deepy.usage import TokenUsage, merge_usage, normalize_usage, usage_from_run_result
 from deepy.utils import json as json_utils
@@ -60,7 +61,15 @@ async def run_prompt_once(
     root = (project_root or Path.cwd()).resolve()
     resolved_settings = settings or load_settings()
     resolved_provider = provider or build_provider_bundle(resolved_settings)
-    runtime = ToolRuntime(cwd=root, settings=resolved_settings)
+    session = (
+        DeepyJsonlSession.open(root, session_id) if session_id else DeepyJsonlSession.create(root)
+    )
+    initial_todos, _ = normalize_todo_items(session.todo_state())
+    runtime = ToolRuntime(
+        cwd=root,
+        settings=resolved_settings,
+        todo_items=initial_todos or [],
+    )
     created_mcp_runtime: DeepyMcpRuntime | None = None
     if mcp_runtime is None:
         created_mcp_runtime = DeepyMcpRuntime(resolved_settings, project_root=root)
@@ -76,11 +85,6 @@ async def run_prompt_once(
         mcp_servers=mcp_runtime.active_servers,
         preferred_mcp_web_search_tools=mcp_runtime.preferred_web_search_tools,
     )
-    session = (
-        DeepyJsonlSession.open(root, session_id)
-        if session_id
-        else DeepyJsonlSession.create(root)
-    )
     started_at = time.time()
     try:
         readiness = await ensure_context_ready(

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/prompts/compact.py

@@ -94,6 +94,7 @@ def build_compact_prompt(
     session_messages: list[dict[str, Any]],
     *,
     focus_instruction: str | None = None,
+    todo_context: str | None = None,
 ) -> str:
     jsonl = "\n".join(_compact_message_json(message) for message in session_messages)
     focus = ""
@@ -104,7 +105,15 @@ def build_compact_prompt(
             "dropping current task state:\n"
             f"{focus_instruction.strip()}"
         )
-    return f"{COMPACT_PROMPT_BASE}{focus}\n\nconversation below:\n\n```jsonl\n{jsonl}\n```"
+    todo = ""
+    if todo_context and todo_context.strip():
+        todo = (
+            "\n\nCurrent todo state:\n"
+            "Preserve this active task plan in the summary so the next model turn can continue "
+            "or reconcile progress:\n"
+            f"{todo_context.strip()}"
+        )
+    return f"{COMPACT_PROMPT_BASE}{focus}{todo}\n\nconversation below:\n\n```jsonl\n{jsonl}\n```"
 
 
 def build_compact_summary_message(summary: str) -> dict[str, str]:

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/prompts/system.py

@@ -53,6 +53,13 @@ Core rules:
 - Ask when clarification would materially improve the result: ambiguous intent, unclear scope,
   user preferences, high-impact trade-offs, or required approval. For low-impact details,
   proceed with a reasonable assumption and state it briefly.
+- Use `todo_write` for complex multi-step work, multi-file changes, or several
+  distinct deliverables. Keep one item `in_progress`, update the complete list
+  only when real task state changes, and reconcile completed work before the
+  final answer. Skip `todo_write` for simple questions and obvious one-step
+  tasks so progress tracking does not create noise.
+- `todo_write` is only for local task tracking. Do not treat it as subagent
+  delegation, a `task` tool, or a plan approval mode.
 
 Tool protocol:
 Tool results are JSON strings: ok, name, output, error, metadata, awaitUserResponse.
@@ -63,6 +70,10 @@ Skill protocol:
 - If the user's task matches an available skill, call `load_skill` with the exact skill name before relying on that skill's detailed instructions, scripts, references, or assets.
 - If the user explicitly invoked a skill, follow the loaded skill instructions and use the user's request inside that context.
 - Skill files are standard Agent Skills. Resolve relative scripts, references, and assets from the skill root returned by `load_skill`.
+- If a loaded skill says to ask the user, ask one question at a time, wait for
+  the user's response, get approval, or have the user review or confirm before
+  continuing, satisfy that wait point with `AskUserQuestion` unless the skill
+  explicitly says to ask in the final answer without tools.
 
 Tool documentation:
 {tool_docs_block}

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/prompts/tool_docs.py

@@ -10,6 +10,7 @@ TOOL_DOC_FILES = (
     "AskUserQuestion.md",
     "WebSearch.md",
     "WebFetch.md",
+    "todo_write.md",
 )
 
 

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/sessions/jsonl.py

@@ -8,13 +8,21 @@ from typing import Any
 
 from deepy.llm.context import estimate_tokens_for_item
 from deepy.llm.replay import sanitize_sdk_items_for_replay
-from deepy.usage import ContextWindowUsage, TokenUsage, context_window_usage, merge_usage, normalize_usage
+from deepy.todos import normalize_persisted_todo_state, todo_state_from_tool_output
+from deepy.usage import (
+    ContextWindowUsage,
+    TokenUsage,
+    context_window_usage,
+    merge_usage,
+    normalize_usage,
+)
 from deepy.utils import json as json_utils
 
 SESSION_INDEX_VERSION = 2
 MAX_SESSION_INDEX_ENTRIES = 50
 CONTEXT_UNDERCOUNT_REPAIR_RATIO = 2
 CONTEXT_UNDERCOUNT_REPAIR_MIN_DELTA = 128
+_UNSET = object()
 
 
 @dataclass(frozen=True)
@@ -30,6 +38,7 @@ class SessionEntry:
     last_usage_tokens: int | None = None
     pending_tokens: int = 0
     last_usage_record_count: int | None = None
+    todo_state: list[dict[str, str]] | None = None
 
 
 def project_code(project_root: Path) -> str:
@@ -123,7 +132,9 @@ class DeepyJsonlSession:
         with self.path.open("w", encoding="utf-8") as fh:
             for record in records:
                 fh.write(json_utils.dumps(record) + "\n")
-        self._loaded_items = [item for item in (_sdk_item_from_record(record) for record in records) if item]
+        self._loaded_items = [
+            item for item in (_sdk_item_from_record(record) for record in records) if item
+        ]
         state = self.context_token_state(records)
         self._touch_index(
             active_tokens=state.active_tokens,
@@ -144,6 +155,7 @@ class DeepyJsonlSession:
             last_usage_tokens=0,
             pending_tokens=0,
             last_usage_record_count=0,
+            todo_state=[],
         )
 
     def record_usage(self, usage: TokenUsage | dict[str, Any] | None) -> None:
@@ -186,7 +198,9 @@ class DeepyJsonlSession:
                         last_usage_record_count=None,
                         estimated=True,
                     )
-                pending_tokens = sum(_estimate_record_tokens(record) for record in source[last_usage_record_count:])
+                pending_tokens = sum(
+                    _estimate_record_tokens(record) for record in source[last_usage_record_count:]
+                )
                 checkpoint_tokens = last_usage_tokens + pending_tokens
                 estimated_tokens = self._estimate_active_tokens(source)
                 active_tokens = _repair_undercounted_context_tokens(
@@ -211,7 +225,9 @@ class DeepyJsonlSession:
 
     def latest_context_window_usage(self) -> ContextWindowUsage | None:
         previous = _entry_for_session(self.path.parent / "sessions-index.json", self.session_id)
-        latest_tokens = _optional_int(previous.get("latestContextWindowTokens")) if previous else None
+        latest_tokens = (
+            _optional_int(previous.get("latestContextWindowTokens")) if previous else None
+        )
         if latest_tokens is not None:
             return ContextWindowUsage(
                 used_tokens=latest_tokens,
@@ -223,6 +239,13 @@ class DeepyJsonlSession:
             return context_window_usage(usage)
         return None
 
+    def todo_state(self) -> list[dict[str, str]]:
+        previous = _entry_for_session(self.path.parent / "sessions-index.json", self.session_id)
+        if not previous:
+            return []
+        todo_state = normalize_persisted_todo_state(previous.get("todoState"))
+        return todo_state or []
+
     async def replace_items(
         self,
         items: list[dict[str, Any]],
@@ -308,6 +331,7 @@ class DeepyJsonlSession:
         last_usage_tokens: int | None = None,
         pending_tokens: int | None = None,
         last_usage_record_count: int | None = None,
+        todo_state: object = _UNSET,
     ) -> None:
         self.path.parent.mkdir(parents=True, exist_ok=True)
         index_path = self.path.parent / "sessions-index.json"
@@ -316,61 +340,64 @@ class DeepyJsonlSession:
         sessions = _index_sessions(raw)
         previous = next((entry for entry in sessions if entry.get("id") == self.session_id), {})
         sessions = [entry for entry in sessions if entry.get("id") != self.session_id]
-        sessions.insert(
-            0,
-            {
-                "id": self.session_id,
-                "path": self.path.name,
-                "activeTokens": active_tokens
-                if active_tokens is not None
-                else _coerce_int(previous.get("activeTokens"), 0),
-                **(
-                    {"latestContextWindowTokens": latest_context_window_tokens}
-                    if latest_context_window_tokens is not None
-                    else (
-                        {"latestContextWindowTokens": previous["latestContextWindowTokens"]}
-                        if "latestContextWindowTokens" in previous
-                        else {}
-                    )
-                ),
-                **(
-                    {"lastUsageTokens": last_usage_tokens}
-                    if last_usage_tokens is not None
-                    else (
-                        {"lastUsageTokens": previous["lastUsageTokens"]}
-                        if "lastUsageTokens" in previous
-                        else {}
-                    )
-                ),
-                **(
-                    {"pendingTokens": pending_tokens}
-                    if pending_tokens is not None
-                    else (
-                        {"pendingTokens": previous["pendingTokens"]}
-                        if "pendingTokens" in previous
-                        else {}
-                    )
-                ),
-                **(
-                    {"lastUsageRecordCount": last_usage_record_count}
-                    if last_usage_record_count is not None
-                    else (
-                        {"lastUsageRecordCount": previous["lastUsageRecordCount"]}
-                        if "lastUsageRecordCount" in previous
-                        else {}
-                    )
-                ),
-                "createdAt": _coerce_int(previous.get("createdAt"), now),
-                "updatedAt": now,
-                **({"usage": usage} if usage is not None else {}),
-                **(
-                    {"usage": previous["usage"]}
-                    if usage is None and isinstance(previous.get("usage"), dict)
+        entry = {
+            "id": self.session_id,
+            "path": self.path.name,
+            "activeTokens": active_tokens
+            if active_tokens is not None
+            else _coerce_int(previous.get("activeTokens"), 0),
+            **(
+                {"latestContextWindowTokens": latest_context_window_tokens}
+                if latest_context_window_tokens is not None
+                else (
+                    {"latestContextWindowTokens": previous["latestContextWindowTokens"]}
+                    if "latestContextWindowTokens" in previous
                     else {}
-                ),
-                **({"processes": previous["processes"]} if "processes" in previous else {}),
-            },
-        )
+                )
+            ),
+            **(
+                {"lastUsageTokens": last_usage_tokens}
+                if last_usage_tokens is not None
+                else (
+                    {"lastUsageTokens": previous["lastUsageTokens"]}
+                    if "lastUsageTokens" in previous
+                    else {}
+                )
+            ),
+            **(
+                {"pendingTokens": pending_tokens}
+                if pending_tokens is not None
+                else (
+                    {"pendingTokens": previous["pendingTokens"]}
+                    if "pendingTokens" in previous
+                    else {}
+                )
+            ),
+            **(
+                {"lastUsageRecordCount": last_usage_record_count}
+                if last_usage_record_count is not None
+                else (
+                    {"lastUsageRecordCount": previous["lastUsageRecordCount"]}
+                    if "lastUsageRecordCount" in previous
+                    else {}
+                )
+            ),
+            "createdAt": _coerce_int(previous.get("createdAt"), now),
+            "updatedAt": now,
+            **({"usage": usage} if usage is not None else {}),
+            **(
+                {"usage": previous["usage"]}
+                if usage is None and isinstance(previous.get("usage"), dict)
+                else {}
+            ),
+            **({"processes": previous["processes"]} if "processes" in previous else {}),
+        }
+        if todo_state is _UNSET:
+            if "todoState" in previous:
+                entry["todoState"] = previous["todoState"]
+        elif todo_state is not None:
+            entry["todoState"] = todo_state
+        sessions.insert(0, entry)
         payload = {
             "version": SESSION_INDEX_VERSION,
             "sessions": sessions[:MAX_SESSION_INDEX_ENTRIES],
@@ -379,10 +406,13 @@ class DeepyJsonlSession:
 
     def _touch_index_after_append(self, appended_items: list[dict[str, Any]]) -> None:
         previous = _entry_for_session(self.path.parent / "sessions-index.json", self.session_id)
+        todo_state = _latest_todo_state_from_items(appended_items)
         if previous and _optional_int(previous.get("lastUsageTokens")) is not None:
             last_usage_tokens = _optional_int(previous.get("lastUsageTokens")) or 0
             previous_pending = _coerce_int(previous.get("pendingTokens"), 0)
-            pending_tokens = previous_pending + sum(estimate_tokens_for_item(item) for item in appended_items)
+            pending_tokens = previous_pending + sum(
+                estimate_tokens_for_item(item) for item in appended_items
+            )
             self._touch_index(
                 active_tokens=last_usage_tokens + pending_tokens,
                 last_usage_tokens=last_usage_tokens,
@@ -391,9 +421,13 @@ class DeepyJsonlSession:
                     previous.get("lastUsageRecordCount"),
                     max(0, len(self._load_records()) - len(appended_items)),
                 ),
+                todo_state=todo_state if todo_state is not None else _UNSET,
             )
             return
-        self._touch_index(active_tokens=self._estimate_active_tokens())
+        self._touch_index(
+            active_tokens=self._estimate_active_tokens(),
+            todo_state=todo_state if todo_state is not None else _UNSET,
+        )
 
 
 @dataclass(frozen=True)
@@ -436,6 +470,7 @@ def list_session_entries(project_root: Path, deepy_home: Path | None = None) ->
                 last_usage_tokens=_optional_int(item.get("lastUsageTokens")),
                 pending_tokens=_coerce_int(item.get("pendingTokens"), 0),
                 last_usage_record_count=_optional_int(item.get("lastUsageRecordCount")),
+                todo_state=normalize_persisted_todo_state(item.get("todoState")),
             )
         )
     return entries
@@ -460,7 +495,11 @@ def _index_sessions(raw: dict[str, Any]) -> list[dict[str, Any]]:
 
 def _entry_for_session(index_path: Path, session_id: str) -> dict[str, Any] | None:
     return next(
-        (entry for entry in _index_sessions(_read_index(index_path)) if entry.get("id") == session_id),
+        (
+            entry
+            for entry in _index_sessions(_read_index(index_path))
+            if entry.get("id") == session_id
+        ),
         None,
     )
 
@@ -473,6 +512,18 @@ def _sdk_item_from_record(record: dict[str, Any]) -> dict[str, Any] | None:
     return dict(item) if isinstance(item, dict) else None
 
 
+def _latest_todo_state_from_items(items: list[dict[str, Any]]) -> list[dict[str, str]] | None:
+    latest: list[dict[str, str]] | None = None
+    for item in items:
+        output = item.get("output")
+        if output is None and item.get("role") == "tool":
+            output = item.get("content")
+        todo_state = todo_state_from_tool_output(output)
+        if todo_state is not None:
+            latest = todo_state
+    return latest
+
+
 def _coerce_int(value: Any, default: int) -> int:
     if isinstance(value, bool):
         return default

deepy_cli-0.2.4/src/deepy/todos.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+from deepy.utils import json as json_utils
+
+
+TODO_STATUSES = {"pending", "in_progress", "completed"}
+
+
+@dataclass(frozen=True)
+class TodoItem:
+    id: str
+    content: str
+    status: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"id": self.id, "content": self.content, "status": self.status}
+
+
+def normalize_todo_items(value: object) -> tuple[list[TodoItem] | None, str | None]:
+    if not isinstance(value, list):
+        return None, "todos must be a list."
+    items: list[TodoItem] = []
+    seen_ids: set[str] = set()
+    in_progress_count = 0
+    for index, raw_item in enumerate(value):
+        if not isinstance(raw_item, Mapping):
+            return None, f"todo item {index + 1} must be an object."
+        item = cast(Mapping[str, object], raw_item)
+        todo_id = _clean_string(item.get("id"))
+        content = _clean_string(item.get("content"))
+        status = _clean_string(item.get("status"))
+        if not todo_id:
+            return None, f"todo item {index + 1} id must not be empty."
+        if todo_id in seen_ids:
+            return None, f"duplicate todo id: {todo_id}"
+        if not content:
+            return None, f"todo item {todo_id} content must not be empty."
+        if status not in TODO_STATUSES:
+            return None, f"todo item {todo_id} has unsupported status: {status or '(empty)'}"
+        if status == "in_progress":
+            in_progress_count += 1
+        seen_ids.add(todo_id)
+        items.append(TodoItem(id=todo_id, content=content, status=status))
+    if in_progress_count > 1:
+        return None, "only one todo item may be in_progress."
+    return items, None
+
+
+def todo_items_to_payload(items: list[TodoItem]) -> list[dict[str, str]]:
+    return [item.to_dict() for item in items]
+
+
+def todo_counts(items: list[TodoItem]) -> dict[str, int]:
+    return {
+        "total": len(items),
+        "pending": sum(1 for item in items if item.status == "pending"),
+        "in_progress": sum(1 for item in items if item.status == "in_progress"),
+        "completed": sum(1 for item in items if item.status == "completed"),
+    }
+
+
+def todo_state_from_tool_output(output: object) -> list[dict[str, str]] | None:
+    payload = _tool_output_payload(output)
+    if not isinstance(payload, dict):
+        return None
+    metadata = payload.get("metadata")
+    if not isinstance(metadata, dict) or metadata.get("kind") != "todo_list":
+        return None
+    todos = metadata.get("todos")
+    items, error = normalize_todo_items(todos)
+    if error is not None or items is None:
+        return None
+    return todo_items_to_payload(items)
+
+
+def normalize_persisted_todo_state(value: object) -> list[dict[str, str]] | None:
+    items, error = normalize_todo_items(value)
+    if error is not None or items is None:
+        return None
+    return todo_items_to_payload(items)
+
+
+def todo_state_prompt_text(items: list[dict[str, str]]) -> str:
+    normalized, error = normalize_todo_items(items)
+    if error is not None or normalized is None or not normalized:
+        return ""
+    counts = todo_counts(normalized)
+    lines = [
+        "Active todo plan:",
+        f"- Progress: {counts['completed']}/{counts['total']} completed",
+    ]
+    for item in normalized:
+        lines.append(f"- [{item.status}] {item.id}: {item.content}")
+    return "\n".join(lines)
+
+
+def _tool_output_payload(output: object) -> Any:
+    if isinstance(output, str):
+        try:
+            return json_utils.loads(output)
+        except json_utils.JSONDecodeError:
+            return None
+    return output
+
+
+def _clean_string(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""

{deepy_cli-0.2.3 → deepy_cli-0.2.4}/src/deepy/tools/agents.py

@@ -58,6 +58,10 @@ def build_function_tools(
         args = _tool_args(raw_input)
         return runtime.load_skill(_string_arg(args, "name"))
 
+    async def invoke_todo_write(_context: object, raw_input: str) -> str:
+        args = _tool_args(raw_input)
+        return runtime.todo_write(args.get("todos") if "todos" in args else None)
+
     web_search_description = (
         "Perform web searching using a natural language query. Use a small number of "
         "targeted searches, then stop and synthesize once enough sources are available; "
@@ -139,6 +143,17 @@ def build_function_tools(
             on_invoke_tool=invoke_load_skill,
             strict_json_schema=False,
         ),
+        FunctionTool(
+            name="todo_write",
+            description=(
+                "Create, replace, read, or clear the session todo list for complex multi-step "
+                "work. Use it for meaningful task tracking, not simple questions or one-step edits. "
+                "Provide the complete todo list when updating; omit todos only to read current state."
+            ),
+            params_json_schema=TODO_WRITE_SCHEMA,
+            on_invoke_tool=invoke_todo_write,
+            strict_json_schema=False,
+        ),
     ]
 
 
@@ -395,3 +410,35 @@ LOAD_SKILL_SCHEMA: dict[str, Any] = {
     "required": ["name"],
     "additionalProperties": False,
 }
+TODO_WRITE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "todos": {
+            "type": "array",
+            "description": (
+                "Complete replacement todo list. Omit this property to read the current todo list; "
+                "pass an empty list to clear it."
+            ),
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "Stable id for this todo item.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "User-facing task text.",
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["pending", "in_progress", "completed"],
+                    },
+                },
+                "required": ["id", "content", "status"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "additionalProperties": False,
+}