my-pi-agent 0.1.0

package/src/my_agent_core/task_store.py

@@ -0,0 +1,248 @@
+"""TaskItem 数据模型与 TaskStore DAG 依赖状态机。"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+TaskStatus = Literal["pending", "in_progress", "completed", "deleted"]
+
+
+@dataclass
+class TaskItem:
+    """单个结构化工单项（对标 OpenHands TaskItem 与 trpc-agent TaskRecord）。"""
+
+    id: str
+    subject: str
+    description: str = ""
+    status: TaskStatus = "pending"
+    owner: str | None = None
+    active_form: str | None = None
+    blocked_by: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class TaskStore:
+    """基于 DAG 依赖图与原子持久化的项目任务仓库。"""
+
+    def __init__(
+        self,
+        workspace: Path | str,
+        enforce_single_in_progress: bool = True,
+        allow_parallel: bool = False,
+    ) -> None:
+        self.workspace = Path(workspace).resolve()
+        self.store_dir = self.workspace / ".my_agent_core"
+        self.file_path = self.store_dir / "tasks.json"
+        self.enforce_single_in_progress = (
+            False if allow_parallel else enforce_single_in_progress
+        )
+        self.tasks: dict[str, TaskItem] = {}
+        self._next_id = 1
+        self._load_from_disk()
+
+    def _load_from_disk(self) -> None:
+        if not self.file_path.exists():
+            return
+        try:
+            data = json.loads(self.file_path.read_text(encoding="utf-8"))
+            self._next_id = data.get("next_id", 1)
+            for item in data.get("tasks", []):
+                task = TaskItem(**item)
+                self.tasks[task.id] = task
+        except (json.JSONDecodeError, OSError, TypeError, ValueError):
+            # 损坏文件或空文件容错，保留初始空状态
+            pass
+
+    def _save_to_disk(self) -> None:
+        self.store_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "next_id": self._next_id,
+            "tasks": [asdict(t) for t in self.tasks.values()],
+        }
+        content = json.dumps(payload, ensure_ascii=False, indent=2)
+        fd, tmp_path = tempfile.mkstemp(
+            dir=self.store_dir, prefix="tasks_", suffix=".tmp"
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(content)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp_path, self.file_path)
+        except Exception:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+            raise
+
+    def _depends_on(self, task_id: str, target_id: str) -> bool:
+        """检查 task_id 是否传递性依赖于 target_id。"""
+        visited = set()
+        queue = [task_id]
+        while queue:
+            curr = queue.pop(0)
+            if curr == target_id:
+                return True
+            if curr in visited:
+                continue
+            visited.add(curr)
+            if curr in self.tasks:
+                queue.extend(self.tasks[curr].blocked_by)
+        return False
+
+    async def create(
+        self,
+        subject: str,
+        description: str = "",
+        active_form: str | None = None,
+        metadata: dict | None = None,
+    ) -> TaskItem:
+        """创建新任务，自动分配递增 ID。"""
+        sub = subject.strip()
+        if not sub:
+            raise ValueError("Task subject cannot be empty")
+        task_id = f"task_{self._next_id}"
+        self._next_id += 1
+        task = TaskItem(
+            id=task_id,
+            subject=sub,
+            description=description,
+            status="pending",
+            active_form=active_form,
+            metadata=metadata or {},
+        )
+        self.tasks[task_id] = task
+        self._save_to_disk()
+        return task
+
+    async def update(
+        self,
+        task_id: str,
+        status: TaskStatus | None = None,
+        subject: str | None = None,
+        description: str | None = None,
+        active_form: str | None = None,
+        owner: str | None = None,
+        metadata: dict | None = None,
+        add_blocked_by: list[str] | None = None,
+        remove_blocked_by: list[str] | None = None,
+    ) -> tuple[TaskItem, list[str]]:
+        """局部增量更新任务字段与 DAG 依赖，并计算自动解锁列表。"""
+        if task_id not in self.tasks:
+            raise KeyError(f"Task '{task_id}' not found")
+        task = self.tasks[task_id]
+
+        if status == "in_progress" and self.enforce_single_in_progress:
+            for other_id, other in self.tasks.items():
+                if other_id != task_id and other.status == "in_progress":
+                    raise ValueError(f"Task '{other_id}' is already in progress")
+
+        if add_blocked_by:
+            for dep in add_blocked_by:
+                if dep == task_id:
+                    raise ValueError("Task cannot depend on itself")
+                if dep not in self.tasks:
+                    raise KeyError(f"Dependency task '{dep}' not found")
+                if self._depends_on(dep, task_id):
+                    raise ValueError(f"Cycle detected: {task_id} -> {dep} -> {task_id}")
+                if dep not in task.blocked_by:
+                    task.blocked_by.append(dep)
+
+        if remove_blocked_by:
+            task.blocked_by = [d for d in task.blocked_by if d not in remove_blocked_by]
+
+        if status is not None:
+            task.status = status
+        if subject is not None:
+            task.subject = subject.strip()
+        if description is not None:
+            task.description = description
+        if active_form is not None:
+            task.active_form = active_form
+        if owner is not None:
+            task.owner = owner
+        if metadata is not None:
+            task.metadata.update(metadata)
+
+        unblocked: list[str] = []
+        if status == "completed":
+            for other_id, other in self.tasks.items():
+                if other.status == "pending" and task_id in other.blocked_by:
+                    other.blocked_by.remove(task_id)
+                    if len(other.blocked_by) == 0:
+                        unblocked.append(other_id)
+
+        self._save_to_disk()
+        return task, unblocked
+
+    def get(self, task_id: str) -> TaskItem:
+        """获取单个任务详情。"""
+        if task_id not in self.tasks:
+            raise KeyError(f"Task '{task_id}' not found")
+        return self.tasks[task_id]
+
+    def list(self, include_deleted: bool = False) -> list[TaskItem]:
+        """列出所有活跃任务。"""
+        return [
+            t for t in self.tasks.values() if include_deleted or t.status != "deleted"
+        ]
+
+    async def batch_write(self, todos: list[dict[str, Any]]) -> list[TaskItem]:
+        """批量/便签覆盖写入。"""
+        for item in todos:
+            t_id = item.get("id")
+            if t_id and t_id in self.tasks:
+                t = self.tasks[t_id]
+                if "subject" in item:
+                    t.subject = str(item["subject"]).strip()
+                if "status" in item and item["status"] in (
+                    "pending",
+                    "in_progress",
+                    "completed",
+                    "deleted",
+                ):
+                    t.status = item["status"]
+            else:
+                new_id = f"task_{self._next_id}"
+                self._next_id += 1
+                self.tasks[new_id] = TaskItem(
+                    id=new_id,
+                    subject=str(item.get("subject", "Untitled")).strip(),
+                    description=str(item.get("description", "")),
+                    status=item.get("status", "pending"),
+                )
+        self._save_to_disk()
+        return self.list()
+
+    def clear(self) -> None:
+        """清空所有工单并落盘。"""
+        self.tasks.clear()
+        self._next_id = 1
+        self._save_to_disk()
+
+    def render_board(self) -> str:
+        """渲染紧凑 Markdown 看板。"""
+        tasks = self.list()
+        if not tasks:
+            return "(No active tasks)"
+        lines: list[str] = []
+        for t in tasks:
+            if t.status == "completed":
+                icon = "[x]"
+            elif t.status == "in_progress":
+                icon = "[>]"
+            else:
+                icon = "[ ]"
+
+            status_desc = f"{t.status}"
+            if t.active_form and t.status == "in_progress":
+                status_desc += f" - {t.active_form}"
+            if t.blocked_by:
+                status_desc += f", blocked by: {t.blocked_by}"
+
+            lines.append(f"{icon} {t.id}: {t.subject} ({status_desc})")
+        return "\n".join(lines)

package/src/my_agent_core/tool_history.py

@@ -0,0 +1,189 @@
+"""对话转录本自愈与断头保护引擎：保证每一条 Assistant 工具调用均有且仅有一条紧邻的工具结果。
+
+对齐 Tau (tau_agent.tool_history) 与 Pi 架构，采用三阶段状态机：
+1. Phase 1: 预留就近配对（防止同名 ID 误抢夺）；
+2. Phase 2: 贪心匹配或合成中断结果（"Tool call interrupted by user"）；
+3. Phase 2.5: 真实结果反超合成中断；
+4. Phase 3: 重构转录本、孤儿结果丢弃与保序重排。
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from my_agent_llm.models import Message
+
+_INTERRUPTED_TOOL_RESULT = "Tool call interrupted by user"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolHistoryRepair:
+    """修复后的合法转录本以及结构化诊断计数。"""
+
+    messages: tuple[Message, ...]
+    changed: bool = False
+    synthesized_results: int = 0
+    dropped_orphan_results: int = 0
+    dropped_duplicate_results: int = 0
+    reordered_results: int = 0
+
+    def diagnostic_data(self) -> dict[str, int]:
+        """返回 JSON 友好的诊断计数字典。"""
+        return {
+            "synthesizedResults": self.synthesized_results,
+            "droppedOrphanResults": self.dropped_orphan_results,
+            "droppedDuplicateResults": self.dropped_duplicate_results,
+            "reorderedResults": self.reordered_results,
+        }
+
+
+def _get_tool_calls(msg: Message) -> list[dict[str, Any]]:
+    """提取 assistant 消息中包含的 tool_calls 列表。"""
+    if msg.role == "assistant" and msg.metadata:
+        calls = msg.metadata.get("tool_calls")
+        if isinstance(calls, list):
+            out: list[dict[str, Any]] = []
+            for c in calls:
+                if isinstance(c, dict):
+                    out.append(c)
+                elif hasattr(c, "model_dump"):
+                    out.append(c.model_dump())
+            return out
+    return []
+
+
+def _get_tool_call_id(msg: Message) -> str | None:
+    """提取 tool 消息绑定的 tool_call_id。"""
+    if msg.role == "tool" and msg.metadata:
+        tid = msg.metadata.get("tool_call_id")
+        if tid is not None:
+            return str(tid)
+    return None
+
+
+def repair_tool_history(messages: Sequence[Message]) -> ToolHistoryRepair:
+    """对会话历史进行确定性拓扑自愈，确保所有工具调用均合法闭合。"""
+    call_occurrences: list[tuple[tuple[int, int], dict[str, Any], int]] = []
+    for msg_idx, message in enumerate(messages):
+        calls = _get_tool_calls(message)
+        for offset, call in enumerate(calls, start=1):
+            call_occurrences.append(((msg_idx, offset), call, msg_idx + offset))
+
+    results_by_id: dict[str, list[tuple[int, Message]]] = defaultdict(list)
+    for msg_idx, message in enumerate(messages):
+        tid = _get_tool_call_id(message)
+        if tid is not None:
+            results_by_id[tid].append((msg_idx, message))
+
+    selected_results: dict[tuple[int, int], tuple[int | None, Message]] = {}
+    used_result_positions: set[int] = set()
+    synthesized_results = 0
+
+    # ── Phase 1: 预留已就近配对的调用 (Reserve already-adjacent pairs) ──
+    for occurrence, call, expected_pos in call_occurrences:
+        if expected_pos >= len(messages):
+            continue
+        candidate = messages[expected_pos]
+        if _get_tool_call_id(candidate) == call.get("id"):
+            selected_results[occurrence] = (expected_pos, candidate)
+            used_result_positions.add(expected_pos)
+
+    # ── Phase 2: 剩余调用贪心匹配或补齐中断结果 (Match remaining or synthesize) ──
+    for occurrence, call, _ in call_occurrences:
+        if occurrence in selected_results:
+            continue
+        call_id = str(call.get("id", ""))
+        candidates = results_by_id.get(call_id, [])
+
+        matched_pos: int | None = None
+        matched_msg: Message | None = None
+
+        # 优先在调用之后寻找未被使用的真实结果
+        for cand_pos, cand_msg in candidates:
+            if cand_pos in used_result_positions:
+                continue
+            if (
+                cand_pos > occurrence[0]
+                and cand_msg.content != _INTERRUPTED_TOOL_RESULT
+            ):
+                matched_pos, matched_msg = cand_pos, cand_msg
+                break
+
+        # 次优：任意未使用的结果
+        if matched_msg is None:
+            for cand_pos, cand_msg in candidates:
+                if cand_pos not in used_result_positions:
+                    matched_pos, matched_msg = cand_pos, cand_msg
+                    break
+
+        if matched_msg is not None and matched_pos is not None:
+            selected_results[occurrence] = (matched_pos, matched_msg)
+            used_result_positions.add(matched_pos)
+        else:
+            # 补齐中断结果
+            synthetic = Message(
+                role="tool",
+                content=_INTERRUPTED_TOOL_RESULT,
+                metadata={"tool_call_id": call_id, "is_error": True},
+            )
+            selected_results[occurrence] = (None, synthetic)
+            synthesized_results += 1
+
+    # ── Phase 2.5: 真实结果反超合成中断 ──
+    for occurrence, call, _ in call_occurrences:
+        pos, _ = selected_results[occurrence]
+        if pos is not None:
+            continue
+        call_id = str(call.get("id", ""))
+        for cand_pos, cand_msg in results_by_id.get(call_id, []):
+            if cand_pos not in used_result_positions:
+                selected_results[occurrence] = (cand_pos, cand_msg)
+                used_result_positions.add(cand_pos)
+                synthesized_results -= 1
+                break
+
+    # ── Phase 3: 重建转录本、孤儿丢弃与保序重排 ──
+    repaired: list[Message] = []
+    all_called_ids = {str(call.get("id", "")) for _, call, _ in call_occurrences}
+    dropped_orphan_results = 0
+    dropped_duplicate_results = 0
+    reordered_results = 0
+
+    for msg_idx, message in enumerate(messages):
+        if message.role == "tool":
+            tid = _get_tool_call_id(message)
+            if msg_idx not in used_result_positions:
+                if tid not in all_called_ids:
+                    dropped_orphan_results += 1
+                else:
+                    dropped_duplicate_results += 1
+                continue
+            # 已使用的工具结果将在对应的 assistant 消息之后紧跟插入，此处跳过
+            continue
+
+        repaired.append(message)
+        if message.role == "assistant":
+            calls = _get_tool_calls(message)
+            for offset, _ in enumerate(calls, start=1):
+                occ = (msg_idx, offset)
+                orig_pos, tool_res = selected_results[occ]
+                expected_pos = msg_idx + offset
+                if orig_pos != expected_pos:
+                    reordered_results += 1
+                repaired.append(tool_res)
+
+    changed = len(repaired) != len(messages) or any(
+        r != o for r, o in zip(repaired, messages, strict=False)
+    )
+
+    return ToolHistoryRepair(
+        messages=tuple(repaired),
+        changed=changed,
+        synthesized_results=synthesized_results,
+        dropped_orphan_results=dropped_orphan_results,
+        dropped_duplicate_results=dropped_duplicate_results,
+        reordered_results=reordered_results,
+    )

package/src/my_agent_core/tools/__init__.py

@@ -0,0 +1,5 @@
+"""工具声明与分发 —— 上行翻译层。"""
+
+from .core import Tool, ToolResult, tool
+
+__all__ = ["Tool", "ToolResult", "tool"]

package/src/my_agent_core/tools/builtin/__init__.py

@@ -0,0 +1,5 @@
+"""内置工具：框架层提供的默认工具工厂。"""
+from .task import make_task_tool
+from .task_tools import make_task_tools  # pyright: ignore[reportMissingImports]
+
+__all__ = ["make_task_tool", "make_task_tools"]

package/src/my_agent_core/tools/builtin/task.py

@@ -0,0 +1,30 @@
+"""内置工具：task（subagent 委派）工厂。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from my_agent_core.subagent_tasks import (  # pyright: ignore[reportMissingImports]
+    SubagentTaskManager,
+    SubagentTaskStatus,
+)
+from my_agent_core.subagents import SubagentManager
+from my_agent_core.tools import Tool
+
+if TYPE_CHECKING:
+    from my_agent_core.agent import Agent
+
+
+def make_task_tool(manager: SubagentManager, parent: Agent) -> Tool:
+    """产出内置 `task` 委派工具（工具桥：调 SubagentTaskManager.start_task → 转字符串）。"""
+    task_manager = SubagentTaskManager(manager, parent)
+
+    async def task(prompt: str, agent_type: str = "default") -> str:
+        """Spawn a subagent with fresh context to complete the given prompt.
+        agent_type: name of the subagent definition (see available agents)."""
+        t = await task_manager.start_task(prompt, agent_type)
+        if t.status is SubagentTaskStatus.COMPLETED:
+            return str(t.result) if t.result is not None else "(no summary)"
+        return str(t.error) if t.error is not None else "(no summary)"
+
+    return Tool(func=task, name="task", is_parallel_safe=True)

package/src/my_agent_core/tools/builtin/task_tools.py

@@ -0,0 +1,215 @@
+"""统一待办任务工具：基于 TaskStore 的单一标准 todo 工具与 discrete 工具族。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any, Literal
+
+from my_agent_core.events import AgentStart, TurnEnd
+from my_agent_core.tools.core import Tool, ToolResult, tool
+
+if TYPE_CHECKING:
+    from my_agent_core.task_store import (  # pyright: ignore[reportMissingImports]
+        TaskStore,
+    )
+
+
+TODO_GUIDELINES = """\
+Manage a task list for tracking multi-step progress.
+Actions:
+- create: add a new task with subject (and optional description, active_form)
+- update: change task status, fields, or add/remove dependencies
+- list: review all active tasks and current board
+- get: get full details of a specific task by task_id
+- clear: clear all tasks from the board
+- write: batch overwrite scratchpad todo items
+
+Rules:
+- Keep exactly one task in_progress at a time.
+- Mark completed immediately when done.
+- Upstream task must complete before blocked downstream tasks can start.
+"""
+
+
+def make_todo_tool(store: TaskStore) -> Tool:
+    """生成单一统一的标准 todo 工具（对标 Pi & Hermes-Agent）。"""
+
+    @tool(
+        name="todo",
+        description=TODO_GUIDELINES,
+        is_parallel_safe=False,
+    )
+    async def todo(
+        action: Literal["create", "update", "list", "get", "clear", "write"],
+        subject: str | None = None,
+        task_id: str | None = None,
+        status: Literal["pending", "in_progress", "completed", "deleted"] | None = None,
+        description: str | None = None,
+        active_form: str | None = None,
+        owner: str | None = None,
+        add_blocked_by: list[str] | None = None,
+        remove_blocked_by: list[str] | None = None,
+        todos: list[dict[str, Any]] | None = None,
+        include_deleted: bool = False,
+    ) -> ToolResult:
+        try:
+            if action == "create":
+                if not subject:
+                    return ToolResult(
+                        ok=False,
+                        error="Parameter 'subject' is required for action 'create'",
+                    )
+                task = await store.create(
+                    subject=subject,
+                    description=description or "",
+                    active_form=active_form,
+                )
+                return ToolResult(
+                    ok=True,
+                    data={
+                        "action": "create",
+                        "task": {
+                            "id": task.id,
+                            "subject": task.subject,
+                            "status": task.status,
+                        },
+                        "board": store.render_board(),
+                        "message": f"Created {task.id}",
+                    },
+                )
+
+            elif action == "update":
+                if not task_id:
+                    return ToolResult(
+                        ok=False,
+                        error="Parameter 'task_id' is required for action 'update'",
+                    )
+                task, unblocked = await store.update(
+                    task_id=task_id,
+                    status=status,
+                    subject=subject,
+                    description=description,
+                    active_form=active_form,
+                    owner=owner,
+                    add_blocked_by=add_blocked_by,
+                    remove_blocked_by=remove_blocked_by,
+                )
+                return ToolResult(
+                    ok=True,
+                    data={
+                        "action": "update",
+                        "task": {
+                            "id": task.id,
+                            "subject": task.subject,
+                            "status": task.status,
+                            "blocked_by": task.blocked_by,
+                        },
+                        "unblocked": unblocked,
+                        "board": store.render_board(),
+                        "message": f"Updated {task.id}",
+                    },
+                )
+
+            elif action == "list":
+                tasks = store.list(include_deleted=include_deleted)
+                return ToolResult(
+                    ok=True,
+                    data={
+                        "action": "list",
+                        "tasks": [
+                            {
+                                "id": t.id,
+                                "subject": t.subject,
+                                "status": t.status,
+                                "owner": t.owner,
+                                "active_form": t.active_form,
+                                "blocked_by": t.blocked_by,
+                            }
+                            for t in tasks
+                        ],
+                        "board": store.render_board(),
+                    },
+                )
+
+            elif action == "get":
+                if not task_id:
+                    return ToolResult(
+                        ok=False,
+                        error="Parameter 'task_id' is required for action 'get'",
+                    )
+                task = store.get(task_id)
+                return ToolResult(
+                    ok=True,
+                    data={"action": "get", "task": asdict(task)},
+                )
+
+            elif action == "clear":
+                store.clear()
+                return ToolResult(
+                    ok=True,
+                    data={
+                        "action": "clear",
+                        "message": "Cleared all tasks",
+                        "board": "(No active tasks)",
+                    },
+                )
+
+            elif action == "write":
+                if todos is None:
+                    return ToolResult(
+                        ok=False,
+                        error="Parameter 'todos' is required for action 'write'",
+                    )
+                items = await store.batch_write(todos)
+                return ToolResult(
+                    ok=True,
+                    data={
+                        "action": "write",
+                        "tasks": [
+                            {"id": t.id, "subject": t.subject, "status": t.status}
+                            for t in items
+                        ],
+                        "board": store.render_board(),
+                    },
+                )
+
+            return ToolResult(ok=False, error=f"Unknown action: {action}")
+        except Exception as e:
+            return ToolResult(ok=False, error=str(e))
+
+    return todo
+
+
+def make_task_tools(store: TaskStore) -> list[Tool]:
+    """导出单一 todo 标准工具（对标 Pi & Hermes）。"""
+    return [make_todo_tool(store)]
+
+
+class TaskGuardHook:
+    """任务收尾早退守卫钩子（对标 Pi 扩展架构）：在 TurnEnd 时检查未结清工单，通过 steer 提醒大模型。"""
+
+    def __init__(self, task_store: TaskStore, steer_fn: Callable[[str], None]) -> None:
+        self.task_store = task_store
+        self.steer_fn = steer_fn
+        self.nudged_ids: set[str] = set()
+
+    def on_agent_start(self, event: AgentStart) -> None:
+        """会话开始时重置已提醒集合。"""
+        self.nudged_ids.clear()
+
+    def on_turn_end(self, event: TurnEnd) -> None:
+        """Turn 结束时检查：若无工具调用且仍有 in_progress 任务，发起 steer 提醒。"""
+        if event.tool_results:
+            return
+
+        in_progress = [t for t in self.task_store.list() if t.status == "in_progress"]
+        for t in in_progress:
+            if t.id not in self.nudged_ids:
+                self.nudged_ids.add(t.id)
+                self.steer_fn(
+                    f"Task '{t.id}' ({t.subject}) is still marked as 'in_progress'. "
+                    f"If you have completed it, please call todo(action='update', task_id='{t.id}', status='completed') "
+                    f"to update your progress before concluding."
+                )
+                break