Initial commit

2026-07-01 17:56:31 +08:00
commit d78931979d
731 changed files with 311088 additions and 0 deletions
@@ -0,0 +1,83 @@
+"""TODO tool — structured task tracking for agents.
+
+Schema definitions only. Execution is intercepted by NativeRuntimeV2, which
+persists the task ledger in runtime session state for resume and verification.
+"""
+
+from __future__ import annotations
+
+from opc.layer4_tools.registry import ToolDefinition
+
+
+async def _todo_noop(**kwargs):  # type: ignore[no-untyped-def]
+    """Placeholder — never called; NativeRuntimeV2 intercepts todo_* calls."""
+    return {"error": "todo tool must be intercepted by NativeRuntimeV2", "success": False}
+
+
+def create_todo_tools() -> list[ToolDefinition]:
+    """Return the two TODO tool definitions (todo_write, todo_read)."""
+    todo_write = ToolDefinition(
+        name="todo_write",
+        description=(
+            "Create or update a structured TODO list for tracking multi-step tasks. "
+            "Pass either a JSON string or a real array of items. "
+            "Preferred OpenOPC task-ledger fields are 'content', 'active_form', and "
+            "'status' ('pending' | 'in_progress' | 'completed'). "
+            "Fields 'id'/'title'/'status' are also accepted. "
+            "Keep only ONE item 'in_progress' at a time and add new items dynamically. "
+            "The runtime persists this ledger across pause/resume and verification."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "todos": {
+                    "oneOf": [
+                        {
+                            "type": "string",
+                            "description": "JSON array of todo items.",
+                        },
+                        {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "id": {"type": "string"},
+                                    "title": {"type": "string"},
+                                    "content": {"type": "string"},
+                                    "active_form": {"type": "string"},
+                                    "status": {
+                                        "type": "string",
+                                        "enum": ["pending", "in_progress", "completed", "done"],
+                                    },
+                                },
+                            },
+                        },
+                    ],
+                    "description": "TODO items, e.g. "
+                    '[{"content":"Inspect runtime_v2","active_form":"Inspecting runtime_v2","status":"in_progress"}]',
+                },
+            },
+            "required": ["todos"],
+        },
+        func=_todo_noop,
+        category="planning",
+        concurrency_safe=False,
+        read_only=False,
+        runtime_managed=True,
+    )
+
+    todo_read = ToolDefinition(
+        name="todo_read",
+        description="Read the current runtime task ledger snapshot. Returns all items with their statuses.",
+        parameters={
+            "type": "object",
+            "properties": {},
+        },
+        func=_todo_noop,
+        category="planning",
+        concurrency_safe=True,
+        read_only=True,
+        runtime_managed=True,
+    )
+
+    return [todo_write, todo_read]