steerable-agent-runtime 0.6.48__tar.gz → 0.6.49__tar.gz

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.48
+Version: 0.6.49
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 License: Apache-2.0
 Requires-Python: >=3.10
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
 Requires-Dist: steerable-agent-harness<1.0.0,>=0.1.0
-Requires-Dist: steerable-agent-runtime-native==1.0.2
+Requires-Dist: steerable-agent-runtime-native==1.0.3
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy>=2.0; extra == "sqlalchemy"
 Provides-Extra: fastapi

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerable-agent-runtime"
-version = "0.6.48"
+version = "0.6.49"
 description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
 license = { text = "Apache-2.0" }
 readme = "README.md"
@@ -16,7 +16,7 @@ dependencies = [
   "pydantic>=2.10.0",
   "steerable-agent-protocol>=0.1.0,<1.0.0",
   "steerable-agent-harness>=0.1.0,<1.0.0",
-  "steerable-agent-runtime-native==1.0.2",
+  "steerable-agent-runtime-native==1.0.3",
 ]
 
 [project.optional-dependencies]

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/src/steerable_agent_runtime/__init__.py

@@ -47,6 +47,7 @@ from .todo import (
     TODO_SCHEMA,
     TODO_TOOL_NAME,
     TodoCompletionGate,
+    TodoPlanningNudge,
     TodoStore,
     make_todo_write_tool,
     todo_write_tool_descriptor,
@@ -424,6 +425,7 @@ __all__ = [
     "ToolExposure",
     "ToolRouter",
     "TodoCompletionGate",
+    "TodoPlanningNudge",
     "TodoStore",
     "TraceRecorder",
     "TranscriptAppend",

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/src/steerable_agent_runtime/reminders.py

@@ -119,6 +119,29 @@ class CompactionThrashingReminder(ContextFragment):
         return ("[system notice] Context thrashing:", "")
 
 
+class TodoPlanningReminder(ContextFragment):
+    """A turn has run many tool calls without ever writing a task list."""
+
+    content_kind = "reminder.todo_planning"
+    max_tokens = 200
+
+    def __init__(self, calls: int) -> None:
+        self._calls = calls
+
+    def body(self) -> str:
+        return (
+            f"[system notice] {self._calls} tool calls into this turn and no "
+            "task list yet. If several steps remain, call todo_write now "
+            "with the remaining steps (the current one in_progress) and keep "
+            "it updated as you go. If the work is a single step or nearly "
+            "done, ignore this notice and continue."
+        )
+
+    @classmethod
+    def type_markers(cls) -> tuple[str, str]:
+        return ("[system notice]", "ignore this notice and continue.")
+
+
 # ---------------------------------------------------------------------------
 # Catalog
 # ---------------------------------------------------------------------------
@@ -192,6 +215,11 @@ REMINDER_CATALOG: tuple[ReminderEntry, ...] = (
         failure_mode="压缩后 3 轮内又填满、连续 3 次（rapid refill）——继续压只毁缓存",
         fragment=CompactionThrashingReminder,
     ),
+    ReminderEntry(
+        id="planning.todo_missing",
+        failure_mode="多步长任务全程不建 todo 清单，进度只存在于模型的注意力里",
+        fragment=TodoPlanningReminder,
+    ),
 )
 
 

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/src/steerable_agent_runtime/todo.py

@@ -16,7 +16,15 @@ from __future__ import annotations
 from typing import Any
 
 from .errors import ToolDispatchError
-from .hooks import CompletionAction, CompletionDraft, NoopHooks
+from .hooks import (
+    CompletionAction,
+    CompletionDraft,
+    NoopHooks,
+    PreStepAction,
+    TranscriptAppend,
+)
+from .llm import LLMMessage
+from .reminders import TodoPlanningReminder, reminder_entry
 
 #: The tool name the model calls.
 TODO_TOOL_NAME = "todo_write"
@@ -278,3 +286,63 @@ class TodoCompletionGate(NoopHooks):
                 "update the list with todo_write first, then finish."
             ),
         )
+
+
+#: Non-todo tool calls in one turn before the planning reminder fires. Low
+#: enough to catch a long task early, high enough that ordinary 2-4 call
+#: lookups never see it.
+DEFAULT_TODO_NUDGE_AFTER_CALLS = 5
+
+
+class TodoPlanningNudge(NoopHooks):
+    """``pre_step`` hook: remind a long-running turn to start a task list.
+
+    The prompt alone leaves ``todo_write`` to the model's judgement, and a
+    follow-up message deep in a long chat reads as "continue", so a 40-round
+    task can run without a list — and without a list the completion gate has
+    nothing to hold the turn to. After ``after_calls`` non-todo tool calls in
+    one turn, with no ``todo_write`` call yet and no unfinished list carried
+    over for the chat, this appends one ``planning.todo_missing`` reminder at
+    the highest-recency position. It fires at most once per turn.
+
+    Per-turn state: construct one instance per run.
+    """
+
+    def __init__(
+        self, store: TodoStore, *, after_calls: int = DEFAULT_TODO_NUDGE_AFTER_CALLS
+    ) -> None:
+        self._store = store
+        self._after_calls = after_calls
+        self._calls = 0
+        self._planned = False
+        self._fired = False
+
+    async def post_tool_result(self, result: Any, call: Any, ctx: Any) -> Any:
+        if call.name == TODO_TOOL_NAME:
+            self._planned = True
+        else:
+            self._calls += 1
+        return result
+
+    async def pre_step(self, transcript: Any, ctx: Any) -> PreStepAction:
+        if self._fired or self._planned or self._calls < self._after_calls:
+            return PreStepAction(kind="proceed")
+        chat_id = str(getattr(ctx, "chat_id", None) or "")
+        if any(
+            item["status"] in _UNFINISHED_STATUSES for item in self._store.get(chat_id)
+        ):
+            return PreStepAction(kind="proceed")
+        self._fired = True
+        entry = reminder_entry("planning.todo_missing")
+        fragment = TodoPlanningReminder(self._calls)
+        return PreStepAction(
+            kind="proceed",
+            appends=[
+                TranscriptAppend(
+                    message=LLMMessage.text_of(fragment.role, fragment.render()),
+                    kind=entry.fragment.content_kind,
+                    fragment=fragment,
+                )
+            ],
+            append_action="reminder",
+        )

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/src/steerable_agent_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.48
+Version: 0.6.49
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 License: Apache-2.0
 Requires-Python: >=3.10
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
 Requires-Dist: steerable-agent-harness<1.0.0,>=0.1.0
-Requires-Dist: steerable-agent-runtime-native==1.0.2
+Requires-Dist: steerable-agent-runtime-native==1.0.3
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy>=2.0; extra == "sqlalchemy"
 Provides-Extra: fastapi

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/src/steerable_agent_runtime.egg-info/requires.txt

@@ -1,7 +1,7 @@
 pydantic>=2.10.0
 steerable-agent-protocol<1.0.0,>=0.1.0
 steerable-agent-harness<1.0.0,>=0.1.0
-steerable-agent-runtime-native==1.0.2
+steerable-agent-runtime-native==1.0.3
 
 [all]
 sqlalchemy>=2.0

{steerable_agent_runtime-0.6.48 → steerable_agent_runtime-0.6.49}/tests/test_todo_gate.py

@@ -5,9 +5,10 @@ from __future__ import annotations
 from types import SimpleNamespace
 
 import pytest
-
-from steerable_agent_runtime import TodoCompletionGate, TodoStore
+from steerable_agent_protocol.generated import ToolCall, ToolResult
+from steerable_agent_runtime import TodoCompletionGate, TodoPlanningNudge, TodoStore
 from steerable_agent_runtime.hooks import CompletionDraft
+from steerable_agent_runtime.reminders import TodoPlanningReminder
 
 
 def _draft(status: str = "completed") -> CompletionDraft:
@@ -92,3 +93,60 @@ class TestTodoCompletionGate:
         assert "15 unfinished" in action.message
         assert "task 9" in action.message
         assert "task 10" not in action.message  # listing capped at 10
+
+
+async def _call(nudge: TodoPlanningNudge, name: str, ctx: SimpleNamespace) -> None:
+    await nudge.post_tool_result(
+        ToolResult(success=True, data={}),
+        ToolCall(id=name, name=name, arguments={}),
+        ctx,
+    )
+
+
+class TestTodoPlanningNudge:
+    @pytest.mark.asyncio
+    async def test_fires_once_after_threshold(self) -> None:
+        nudge = TodoPlanningNudge(TodoStore(), after_calls=3)
+        ctx = _ctx()
+        for _ in range(2):
+            await _call(nudge, "local_read_file", ctx)
+        assert not (await nudge.pre_step([], ctx)).appends
+        await _call(nudge, "local_exec_shell", ctx)
+        action = await nudge.pre_step([], ctx)
+        assert action.appends is not None
+        assert action.append_action == "reminder"
+        fragment = action.appends[0].fragment
+        assert isinstance(fragment, TodoPlanningReminder)
+        assert "3 tool calls into this turn" in fragment.render()
+        assert fragment.matches_text(fragment.render())
+        await _call(nudge, "local_exec_shell", ctx)
+        assert not (await nudge.pre_step([], ctx)).appends
+
+    @pytest.mark.asyncio
+    async def test_todo_write_this_turn_silences(self) -> None:
+        nudge = TodoPlanningNudge(TodoStore(), after_calls=2)
+        ctx = _ctx()
+        await _call(nudge, "todo_write", ctx)
+        for _ in range(5):
+            await _call(nudge, "local_exec_shell", ctx)
+        assert not (await nudge.pre_step([], ctx)).appends
+
+    @pytest.mark.asyncio
+    async def test_unfinished_list_carried_over_silences(self) -> None:
+        store = TodoStore()
+        _seed(store, "c1", ["completed", "pending"])
+        nudge = TodoPlanningNudge(store, after_calls=2)
+        ctx = _ctx()
+        for _ in range(3):
+            await _call(nudge, "local_exec_shell", ctx)
+        assert not (await nudge.pre_step([], ctx)).appends
+
+    @pytest.mark.asyncio
+    async def test_finished_list_carried_over_still_nudges(self) -> None:
+        store = TodoStore()
+        _seed(store, "c1", ["completed", "completed"])
+        nudge = TodoPlanningNudge(store, after_calls=2)
+        ctx = _ctx()
+        for _ in range(2):
+            await _call(nudge, "local_exec_shell", ctx)
+        assert (await nudge.pre_step([], ctx)).appends