steerable-agent-runtime 0.6.3__tar.gz → 0.6.4__tar.gz

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.3
+Version: 0.6.4
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerable-agent-runtime"
-version = "0.6.3"
+version = "0.6.4"
 description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
 readme = "README.md"
 requires-python = ">=3.10"

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/__init__.py

@@ -35,6 +35,13 @@ from .ask_user import (
     AskUserHandler,
     make_ask_user_tool,
 )
+from .todo import (
+    TODO_SCHEMA,
+    TODO_TOOL_NAME,
+    TodoStore,
+    make_todo_write_tool,
+    todo_write_tool_descriptor,
+)
 from .config import (
     DEFAULT_CONFIG_PATH,
     ConfigError,
@@ -262,6 +269,8 @@ __all__ = [
     "TOOL_SEARCH_NAME",
     "ASK_USER_SCHEMA",
     "ASK_USER_TOOL_NAME",
+    "TODO_SCHEMA",
+    "TODO_TOOL_NAME",
     "STEERABLE_TOOLS_ENTRY_POINT_GROUP",
     "AgentPool",
     "AntiHallucinationConfig",
@@ -382,6 +391,7 @@ __all__ = [
     "ToolExecutor",
     "ToolExposure",
     "ToolRouter",
+    "TodoStore",
     "TraceRecorder",
     "TranscriptAppend",
     "TransportAdapter",
@@ -423,6 +433,7 @@ __all__ = [
     "load_recorded_requests",
     "load_transcript",
     "make_ask_user_tool",
+    "make_todo_write_tool",
     "matches_conditions",
     "mcp_invoker",
     "merge_patch",
@@ -456,6 +467,7 @@ __all__ = [
     "system_blocks_with_cache",
     "text_parts",
     "to_otlp_json",
+    "todo_write_tool_descriptor",
     "tool",
     "tool_search_descriptor",
     "upgrade_entry_dict",

steerable_agent_runtime-0.6.4/src/steerable_agent_runtime/todo.py

@@ -0,0 +1,213 @@
+"""Session task list — the ``todo_write`` tool.
+
+The model maintains one ordered task list per chat (Claude Code
+``TodoWrite`` parity): multi-step work stays legible across rounds because
+the model rewrites the list as it progresses, and every rewrite lands in the
+durable message record as the tool result, so a resumed session rebuilds the
+list from the transcript.
+
+Semantics are full-replace: each call carries the complete list, not a diff.
+The store keys lists by ``chat_id`` from the dispatch context, so concurrent
+chats in one sidecar process never see each other's tasks.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import ToolDispatchError
+
+#: The tool name the model calls.
+TODO_TOOL_NAME = "todo_write"
+
+#: Valid task states, in lifecycle order.
+TODO_STATUSES = ("pending", "in_progress", "completed")
+
+#: Bounds on the list itself. The list is a working set, not a backlog —
+#: past ~50 items the model is planning, not tracking, and the rendered
+#: result starts to lean on the fragment budget.
+_MIN_TODOS = 1
+_MAX_TODOS = 50
+
+#: Model-facing description, shared by the registration metadata and the
+#: OpenAI descriptor.
+_DESCRIPTION = (
+    "Track multi-step work as an ordered task list. Create the list when a "
+    "task needs several steps; rewrite it as you progress — mark the task "
+    "you are working on in_progress (at most one) and completed the moment "
+    "it is done. Each call replaces the whole list. Skip it for single-step "
+    "requests."
+)
+
+#: JSON Schema for the tool's arguments — one full-replace list.
+TODO_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "todos": {
+            "type": "array",
+            "minItems": _MIN_TODOS,
+            "maxItems": _MAX_TODOS,
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "Stable identifier for this task.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "One line describing the task.",
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": list(TODO_STATUSES),
+                    },
+                },
+                "required": ["id", "content", "status"],
+            },
+            "description": (
+                "The complete task list, replacing the previous one. "
+                "Mark exactly the task you are working on as in_progress; "
+                "keep at most one in_progress at a time."
+            ),
+        },
+    },
+    "required": ["todos"],
+}
+
+
+class TodoStore:
+    """Process-local task lists keyed by chat id.
+
+    Persistence comes for free from the message record — every rewrite is a
+    tool result in the transcript, and full-replace semantics make the state
+    self-healing: after a restart the model's next call rewrites the whole
+    list from what it sees in the resumed history.
+    """
+
+    def __init__(self) -> None:
+        self._by_chat: dict[str, list[dict[str, Any]]] = {}
+
+    def get(self, chat_id: str) -> list[dict[str, Any]]:
+        return [dict(item) for item in self._by_chat.get(chat_id, [])]
+
+    def set(self, chat_id: str, todos: list[dict[str, Any]]) -> None:
+        self._by_chat[chat_id] = [dict(item) for item in todos]
+
+
+def _normalize_todos(todos: Any) -> list[dict[str, Any]]:
+    """Validate one full-replace list and return it in canonical shape.
+
+    A violation raises ``ToolDispatchError`` — the router wraps it as the
+    tool result, so the model sees exactly what to fix and retries within
+    the same turn.
+    """
+    if not isinstance(todos, list):
+        raise ToolDispatchError(
+            f"todo_write: todos must be an array, got {type(todos).__name__}"
+        )
+    if not (_MIN_TODOS <= len(todos) <= _MAX_TODOS):
+        raise ToolDispatchError(
+            f"todo_write: todos must contain {_MIN_TODOS}-{_MAX_TODOS} items, "
+            f"got {len(todos)}. Track the current working set, not a backlog."
+        )
+    seen_ids: set[str] = set()
+    in_progress = 0
+    normalized: list[dict[str, Any]] = []
+    for index, item in enumerate(todos):
+        if not isinstance(item, dict):
+            raise ToolDispatchError(
+                f"todo_write: todos[{index}] must be an object, "
+                f"got {type(item).__name__}"
+            )
+        task_id = item.get("id")
+        if not isinstance(task_id, str) or not task_id:
+            raise ToolDispatchError(
+                f"todo_write: todos[{index}] is missing a non-empty string "
+                '"id".'
+            )
+        if task_id in seen_ids:
+            raise ToolDispatchError(
+                f'todo_write: duplicate id "{task_id}" — ids must be unique.'
+            )
+        seen_ids.add(task_id)
+        content = item.get("content")
+        if not isinstance(content, str) or not content.strip():
+            raise ToolDispatchError(
+                f'todo_write: todos[{index}] ("{task_id}") is missing a '
+                'non-empty string "content".'
+            )
+        status = item.get("status")
+        if status not in TODO_STATUSES:
+            raise ToolDispatchError(
+                f'todo_write: todos[{index}] ("{task_id}") has invalid status '
+                f"{status!r}; expected one of {', '.join(TODO_STATUSES)}."
+            )
+        if status == "in_progress":
+            in_progress += 1
+        normalized.append({"id": task_id, "content": content, "status": status})
+    if in_progress > 1:
+        raise ToolDispatchError(
+            f"todo_write: {in_progress} tasks are in_progress; keep at most "
+            "one — mark the rest pending or completed."
+        )
+    return normalized
+
+
+def make_todo_write_tool(store: TodoStore) -> Any:
+    """Build the ``todo_write`` tool handler bound to ``store``.
+
+    The returned coroutine function carries the registration metadata the
+    router reads (name, description, schema) so a host registers it with one
+    call. Marked ``concurrency_safe=False``: two rewrites of the same chat's
+    list would race, and last-writer-wins is the wrong resolution for a
+    full-replace update.
+    """
+
+    async def todo_write(
+        todos: list[dict[str, Any]], context: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        normalized = _normalize_todos(todos)
+        chat_id = str((context or {}).get("chat_id") or "")
+        store.set(chat_id, normalized)
+        counts = {status: 0 for status in TODO_STATUSES}
+        for item in normalized:
+            counts[item["status"]] += 1
+        return {
+            "todos": normalized,
+            "summary": {
+                "total": len(normalized),
+                "pending": counts["pending"],
+                "inProgress": counts["in_progress"],
+                "completed": counts["completed"],
+            },
+        }
+
+    todo_write.__steerable_tool_meta__ = {  # type: ignore[attr-defined]
+        "name": TODO_TOOL_NAME,
+        "mode": "read",  # session state only; no workspace side effects
+        "description": _DESCRIPTION,
+        "schema": TODO_SCHEMA,
+        "require_consent": False,
+        "concurrency_safe": False,
+        "exposure": "direct",
+    }
+    return todo_write
+
+
+def todo_write_tool_descriptor() -> dict[str, Any]:
+    """OpenAI tool schema to append to the model's tools list.
+
+    The sidecar registers ``todo_write`` on its router (so dispatch works on
+    both the host path and the sidecar-local path) but the model only sees it
+    when the descriptor is appended to the ``tools`` array — mirroring how
+    run_code advertises itself.
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": TODO_TOOL_NAME,
+            "description": _DESCRIPTION,
+            "parameters": TODO_SCHEMA,
+        },
+    }

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.3
+Version: 0.6.4
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ src/steerable_agent_runtime/sandboxed.py
 src/steerable_agent_runtime/skills.py
 src/steerable_agent_runtime/spill.py
 src/steerable_agent_runtime/subagent.py
+src/steerable_agent_runtime/todo.py
 src/steerable_agent_runtime/tokens.py
 src/steerable_agent_runtime/tool_schema.py
 src/steerable_agent_runtime/tool_search.py
@@ -126,6 +127,7 @@ tests/test_storage_contract.py
 tests/test_stream_strip.py
 tests/test_subagent.py
 tests/test_system_proxy.py
+tests/test_todo.py
 tests/test_tokens.py
 tests/test_tool_exposure.py
 tests/test_tool_hygiene.py

steerable_agent_runtime-0.6.4/tests/test_todo.py

@@ -0,0 +1,156 @@
+"""The todo_write tool: full-replace semantics, validation, chat scoping."""
+
+from __future__ import annotations
+
+import pytest
+from steerable_agent_protocol.generated import ToolCall
+
+from steerable_agent_runtime import (
+    TODO_TOOL_NAME,
+    TodoStore,
+    ToolRouter,
+    make_todo_write_tool,
+)
+from steerable_agent_runtime.errors import ToolDispatchError
+
+
+def _make() -> tuple[TodoStore, ToolRouter]:
+    store = TodoStore()
+    router = ToolRouter()
+    tool = make_todo_write_tool(store)
+    meta = tool.__steerable_tool_meta__
+    router.register(
+        tool,
+        name=meta["name"],
+        mode=meta["mode"],
+        description=meta["description"],
+        schema=meta["schema"],
+        require_consent=meta["require_consent"],
+        concurrency_safe=meta["concurrency_safe"],
+        exposure=meta["exposure"],
+    )
+    return store, router
+
+
+def _call(todos: object) -> ToolCall:
+    return ToolCall(id="c1", name=TODO_TOOL_NAME, arguments={"todos": todos})
+
+
+def _todos(*specs: tuple[str, str]) -> list[dict[str, str]]:
+    return [
+        {"id": f"t{i}", "content": content, "status": status}
+        for i, (content, status) in enumerate(specs)
+    ]
+
+
+async def test_full_replace_returns_list_and_summary() -> None:
+    store, router = _make()
+    result = await router.dispatch(
+        _call(_todos(("read code", "completed"), ("patch it", "in_progress"))),
+        context={"chat_id": "chat-1"},
+    )
+    assert result.success, result.error
+    data = result.data["value"]
+    assert [t["id"] for t in data["todos"]] == ["t0", "t1"]
+    assert data["summary"] == {
+        "total": 2,
+        "pending": 0,
+        "inProgress": 1,
+        "completed": 1,
+    }
+    # The store holds the new list for the chat.
+    assert [t["content"] for t in store.get("chat-1")] == ["read code", "patch it"]
+
+
+async def test_second_call_replaces_the_first() -> None:
+    store, router = _make()
+    await router.dispatch(
+        _call(_todos(("old task", "pending"))), context={"chat_id": "chat-1"}
+    )
+    result = await router.dispatch(
+        _call(_todos(("new task", "in_progress"))), context={"chat_id": "chat-1"}
+    )
+    assert result.success, result.error
+    assert [t["content"] for t in store.get("chat-1")] == ["new task"]
+
+
+async def test_chats_are_isolated() -> None:
+    store, router = _make()
+    await router.dispatch(
+        _call(_todos(("chat one task", "pending"))), context={"chat_id": "chat-1"}
+    )
+    await router.dispatch(
+        _call(_todos(("chat two task", "in_progress"))),
+        context={"chat_id": "chat-2"},
+    )
+    assert [t["content"] for t in store.get("chat-1")] == ["chat one task"]
+    assert [t["content"] for t in store.get("chat-2")] == ["chat two task"]
+
+
+async def test_missing_context_uses_the_default_bucket() -> None:
+    store, router = _make()
+    result = await router.dispatch(_call(_todos(("orphan", "pending"))))
+    assert result.success, result.error
+    assert [t["content"] for t in store.get("")] == ["orphan"]
+
+
+@pytest.mark.parametrize(
+    ("todos", "fragment"),
+    [
+        ("not-a-list", "must be an array"),
+        ([], "must contain 1-50 items"),
+        (["not-an-object"], "must be an object"),
+        ([{"content": "x", "status": "pending"}], 'non-empty string "id"'),
+        (
+            [
+                {"id": "a", "content": "one", "status": "pending"},
+                {"id": "a", "content": "two", "status": "pending"},
+            ],
+            'duplicate id "a"',
+        ),
+        ([{"id": "a", "content": "  ", "status": "pending"}], '"content"'),
+        (
+            [{"id": "a", "content": "x", "status": "doing"}],
+            "invalid status",
+        ),
+        (
+            [
+                {"id": "a", "content": "one", "status": "in_progress"},
+                {"id": "b", "content": "two", "status": "in_progress"},
+            ],
+            "at most one",
+        ),
+    ],
+)
+async def test_invalid_lists_are_rejected_without_touching_state(
+    todos: object, fragment: str
+) -> None:
+    store, router = _make()
+    await router.dispatch(
+        _call(_todos(("kept", "pending"))), context={"chat_id": "chat-1"}
+    )
+    result = await router.dispatch(_call(todos), context={"chat_id": "chat-1"})
+    assert not result.success
+    assert fragment in (result.error or "")
+    # A rejected rewrite leaves the previous list intact.
+    assert [t["content"] for t in store.get("chat-1")] == ["kept"]
+
+
+def test_normalize_rejects_overlong_lists() -> None:
+    todos = [
+        {"id": f"t{i}", "content": f"task {i}", "status": "pending"}
+        for i in range(51)
+    ]
+    with pytest.raises(ToolDispatchError, match="1-50"):
+        from steerable_agent_runtime.todo import _normalize_todos
+
+        _normalize_todos(todos)
+
+
+def test_meta_advertises_direct_exposure() -> None:
+    tool = make_todo_write_tool(TodoStore())
+    meta = tool.__steerable_tool_meta__
+    assert meta["name"] == "todo_write"
+    assert meta["exposure"] == "direct"
+    assert meta["require_consent"] is False
+    assert meta["concurrency_safe"] is False