langchain-agentx-python 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

langchain_agentx/loop/hook/registry.py

@@ -11,6 +11,8 @@ registry.py — HookRegistry 用户侧入口。
 
 当前裁剪范围：
     已支持 P1/P2 执行器注册（function/callback/command/http/prompt/agent）。
+    已支持任务完成 hooks（register_task_completed/get_task_completed_hooks）。
+    已支持任务创建 hooks（register_task_created/get_task_created_hooks），与 TaskCreateRuntimeTool 对齐。
 """
 
 from __future__ import annotations
@@ -21,6 +23,33 @@ from .config import HookSpec, HooksConfigSnapshot
 from .types import HookEvent
 
 
+# ── 任务完成 Hook 类型定义 ────────────────────────────────────────
+
+TaskCompletedHook = Callable[[str, str, str, str | None], str | None]
+"""
+任务完成 hook 类型。
+
+Args:
+    task_id: 完成的任务 ID
+    subject: 任务标题
+    description: 任务描述
+    agent_id: 当前 agent ID（可能为 None）
+
+Returns:
+    str | None: 阻塞性错误消息，如果有则阻止任务完成
+
+用法：
+    def my_hook(task_id: str, subject: str, description: str, agent_id: str | None) -> str | None:
+        if "critical" in subject:
+            return "Critical task cannot be marked completed without review"
+        return None
+
+    HookRegistry.register_task_completed(my_hook)
+"""
+
+# task_id, subject, description, teammate_name, team_name → 阻塞错误信息或 None
+TaskCreatedHook = Callable[[str, str, str, str | None, str | None], str | None]
+"""任务创建 hook（v1 同步）；与 CC executeTaskCreatedHooks 阻塞语义对齐。"""
 class HookRegistry:
     """用户侧 Hook 注册入口。
 
@@ -232,6 +261,61 @@ class HookRegistry:
     def __len__(self) -> int:
         return len(self._specs)
 
+    # ── 任务完成 Hook API ────────────────────────────────────────────
+
+    # 类变量：存储所有任务完成 hooks
+    _task_completed_hooks: list[Callable] = []
+
+    @classmethod
+    def register_task_completed(cls, hook: Callable) -> None:
+        """注册任务完成 hook。
+
+        Args:
+            hook: 任务完成回调函数（TaskCompletedHook 类型）
+
+        用法：
+            def my_hook(task_id: str, subject: str, description: str, agent_id: str | None) -> str | None:
+                if "critical" in subject:
+                    return "Critical task cannot be marked completed"
+                return None
+
+            HookRegistry.register_task_completed(my_hook)
+        """
+        cls._task_completed_hooks.append(hook)
+
+    @classmethod
+    def get_task_completed_hooks(cls) -> list[Callable]:
+        """获取所有任务完成 hooks。
+
+        Returns:
+            list[Callable]: hooks 副本（避免外部修改内部列表）
+        """
+        return cls._task_completed_hooks.copy()
+
+    @classmethod
+    def clear_task_completed_hooks(cls) -> None:
+        """清空所有任务完成 hooks（主要用于测试）。"""
+        cls._task_completed_hooks.clear()
+
+    # ── 任务创建 Hook API（TaskCreateRuntimeTool）────────────────────────
+
+    _task_created_hooks: list[Callable] = []
+
+    @classmethod
+    def register_task_created(cls, hook: Callable) -> None:
+        """注册任务创建 hook（TaskCreatedHook 类型）。"""
+        cls._task_created_hooks.append(hook)
+
+    @classmethod
+    def get_task_created_hooks(cls) -> list[Callable]:
+        """获取所有任务创建 hooks 副本。"""
+        return cls._task_created_hooks.copy()
+
+    @classmethod
+    def clear_task_created_hooks(cls) -> None:
+        """清空所有任务创建 hooks（主要用于测试）。"""
+        cls._task_created_hooks.clear()
+
     def _make_spec(
         self,
         *,
@@ -259,4 +343,8 @@ class HookRegistry:
         return spec
 
 
-__all__ = ["HookRegistry"]
+__all__ = [
+    "HookRegistry",
+    "TaskCompletedHook",
+    "TaskCreatedHook",
+]

langchain_agentx/task_runtime/__init__.py

@@ -3,6 +3,19 @@
 Shared task scheduling primitives for loop and tools.
 """
 
+# CC 任务列表存储子系统（TaskListStatus：Todo JSON 状态字面量，勿与编排层 TaskStatus 枚举混淆）
+from .tasklist import (
+    ClaimResult,
+    FileLockNotAvailableError,
+    Task,
+    TaskCreate,
+    TaskFilters,
+    TaskListStatus,
+    TaskStore,
+    TaskStoreLockManager,
+    TaskUpdate,
+)
+
 from .core.interfaces import TaskExecutor
 from .orchestrator.runtime import DefaultTaskRuntime
 from .queue.in_memory import InMemoryTaskCommandQueue
@@ -61,6 +74,17 @@ from .policy import (
 )
 
 __all__ = [
+    # Tasklist (CC 任务列表)
+    "TaskStore",
+    "Task",
+    "TaskCreate",
+    "TaskUpdate",
+    "TaskFilters",
+    "TaskListStatus",
+    "ClaimResult",
+    "TaskStoreLockManager",
+    "FileLockNotAvailableError",
+    # Queued commands
     "QueuedCommandProvider",
     "encode_provider_batch_id",
     "decode_provider_batch_id",

langchain_agentx/task_runtime/tasklist/__init__.py

@@ -0,0 +1,48 @@
+"""
+task_runtime/tasklist/ — CC 任务列表存储子系统
+
+职责：
+    实现 Claude Code 对等的任务列表管理能力：
+    - 任务持久化存储（文件系统，每个任务一个 JSON 文件）
+    - 任务依赖关系管理（blocks / blockedBy 双向维护）
+    - 高水位标记机制（防止删除后 ID 重用）
+    - 文件锁保护（多进程并发安全）
+    - 任务认领与状态流转
+
+与 CC 对应：
+    CC src/utils/tasks.ts（863 行）是任务存储核心，本模块与其对等。
+"""
+
+from .models import (
+    MAX_ACTIVE_FORM_LENGTH,
+    MAX_DESCRIPTION_LENGTH,
+    MAX_SUBJECT_LENGTH,
+    ClaimResult,
+    Task,
+    TaskCreate,
+    TaskFilters,
+    TaskListStatus,
+    TaskStatus,
+    TaskUpdate,
+    TaskUpdateStatus,
+)
+from .store import TaskStore, TaskStoreSync
+from .lock import FileLockNotAvailableError, TaskStoreLockManager
+
+__all__ = [
+    "TaskStore",
+    "TaskStoreSync",
+    "Task",
+    "TaskCreate",
+    "TaskUpdate",
+    "TaskFilters",
+    "TaskStatus",
+    "TaskListStatus",
+    "TaskUpdateStatus",
+    "ClaimResult",
+    "TaskStoreLockManager",
+    "FileLockNotAvailableError",
+    "MAX_SUBJECT_LENGTH",
+    "MAX_DESCRIPTION_LENGTH",
+    "MAX_ACTIVE_FORM_LENGTH",
+]

langchain_agentx/task_runtime/tasklist/high_water_mark.py

@@ -0,0 +1,220 @@
+"""
+task_runtime/tasklist/high_water_mark.py — 高水位标记管理
+
+职责：
+    管理任务 ID 高水位标记，防止删除后 ID 重用：
+    - 读取当前高水位值
+    - 写入新的高水位值
+    - 扫描文件找出最大 ID
+
+链路位置：
+    TaskStore.create_task → HighWaterMarkManager.get_next_id
+
+与 CC 对应：
+    CC src/utils/tasks.ts 中 highWaterMark 相关函数。
+
+裁剪范围（v1）：
+    - 文件锁由调用方（TaskStore）负责
+    - 降级策略：文件损坏时扫描目录
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+
+class HighWaterMarkManager:
+    """高水位标记管理器。
+
+    确保任务 ID 单调递增，删除任务后不会重用 ID。
+
+    高水位文件路径：{tasks_dir}/.highwatermark
+    文件内容：纯数字字符串，表示已分配的最大 ID。
+    """
+
+    def __init__(self, timeout: float = 3.0) -> None:
+        """初始化高水位标记管理器。
+
+        Args:
+            timeout: 文件操作超时（秒）
+        """
+        self.timeout = timeout
+
+    def _get_highwatermark_path(self, tasks_dir: Path) -> Path:
+        """获取高水位文件路径。"""
+        return tasks_dir / ".highwatermark"
+
+    async def read(self, tasks_dir: Path) -> int:
+        """读取当前高水位值。
+
+        Args:
+            tasks_dir: 任务目录
+
+        Returns:
+            当前高水位值，文件不存在或损坏时返回 0
+        """
+        hw_path = self._get_highwatermark_path(tasks_dir)
+
+        try:
+            content = await asyncio.to_thread(hw_path.read_text, encoding="utf-8")
+            return int(content.strip())
+        except (FileNotFoundError, ValueError, OSError):
+            return 0
+
+    async def write(self, tasks_dir: Path, value: int) -> None:
+        """写入新的高水位值。
+
+        Args:
+            tasks_dir: 任务目录
+            value: 新的高水位值
+        """
+        hw_path = self._get_highwatermark_path(tasks_dir)
+
+        # 确保目录存在
+        await asyncio.to_thread(tasks_dir.mkdir, parents=True, exist_ok=True)
+
+        # 原子写入：先写临时文件，再重命名
+        temp_path = hw_path.with_suffix(".tmp")
+        content = str(value)
+
+        await asyncio.to_thread(temp_path.write_text, content, encoding="utf-8")
+
+        # Windows 需要 replace，Posix rename 可原子替换
+        try:
+            await asyncio.to_thread(temp_path.replace, hw_path)
+        except OSError:
+            # 降级：删除后重命名
+            if hw_path.exists():
+                await asyncio.to_thread(hw_path.unlink)
+            await asyncio.to_thread(temp_path.rename, hw_path)
+
+    async def find_highest_id(self, tasks_dir: Path) -> int:
+        """扫描任务文件找出最大 ID。
+
+        作为高水位文件的降级策略。
+
+        Args:
+            tasks_dir: 任务目录
+
+        Returns:
+            找到的最大 ID，目录不存在或无任务时返回 0
+        """
+        if not await asyncio.to_thread(tasks_dir.exists):
+            return 0
+
+        max_id = 0
+
+        try:
+            for entry in await asyncio.to_thread(lambda: list(tasks_dir.iterdir())):
+                if entry.suffix == ".json":
+                    # 从文件名提取 ID（如 "123.json" -> 123）
+                    try:
+                        task_id = int(entry.stem)
+                        max_id = max(max_id, task_id)
+                    except ValueError:
+                        continue
+        except OSError:
+            pass
+
+        return max_id
+
+    async def get_next_id(self, tasks_dir: Path) -> int:
+        """获取下一个可用的任务 ID。
+
+        Args:
+            tasks_dir: 任务目录
+
+        Returns:
+            下一个 ID（max(高水位文件, 文件中最大ID) + 1）
+        """
+        hw_value = await self.read(tasks_dir)
+        file_max = await self.find_highest_id(tasks_dir)
+
+        current = max(hw_value, file_max)
+        next_id = current + 1
+
+        # 更新高水位
+        await self.write(tasks_dir, next_id)
+
+        return next_id
+
+    # ------------------------------------------------------------------
+    # 同步版本（用于文件锁保护下的同步上下文）
+    # ------------------------------------------------------------------
+
+    def _read_sync(self, tasks_dir: Path) -> int:
+        """同步读取当前高水位值。"""
+        hw_path = self._get_highwatermark_path(tasks_dir)
+
+        try:
+            content = hw_path.read_text(encoding="utf-8")
+            return int(content.strip())
+        except (FileNotFoundError, ValueError, OSError):
+            return 0
+
+    def _write_sync(self, tasks_dir: Path, value: int) -> None:
+        """同步写入新的高水位值。"""
+        hw_path = self._get_highwatermark_path(tasks_dir)
+
+        # 确保目录存在
+        tasks_dir.mkdir(parents=True, exist_ok=True)
+
+        # 原子写入：先写临时文件，再重命名
+        temp_path = hw_path.with_suffix(".tmp")
+        content = str(value)
+
+        temp_path.write_text(content, encoding="utf-8")
+
+        # Windows 需要 replace，Posix rename 可原子替换
+        try:
+            temp_path.replace(hw_path)
+        except OSError:
+            # 降级：删除后重命名
+            if hw_path.exists():
+                hw_path.unlink()
+            temp_path.rename(hw_path)
+
+    def _find_highest_id_sync(self, tasks_dir: Path) -> int:
+        """同步扫描任务文件找出最大 ID。"""
+        if not tasks_dir.exists():
+            return 0
+
+        max_id = 0
+
+        try:
+            for entry in list(tasks_dir.iterdir()):
+                if entry.suffix == ".json":
+                    # 从文件名提取 ID（如 "123.json" -> 123）
+                    try:
+                        task_id = int(entry.stem)
+                        max_id = max(max_id, task_id)
+                    except ValueError:
+                        continue
+        except OSError:
+            pass
+
+        return max_id
+
+    def get_next_id_sync(self, tasks_dir: Path) -> int:
+        """同步获取下一个可用的任务 ID。
+
+        用于文件锁保护下的同步上下文。
+
+        Args:
+            tasks_dir: 任务目录
+
+        Returns:
+            下一个 ID（max(高水位文件, 文件中最大ID) + 1）
+        """
+        hw_value = self._read_sync(tasks_dir)
+        file_max = self._find_highest_id_sync(tasks_dir)
+
+        current = max(hw_value, file_max)
+        next_id = current + 1
+
+        # 更新高水位
+        self._write_sync(tasks_dir, next_id)
+
+        return next_id

langchain_agentx/task_runtime/tasklist/lock.py

@@ -0,0 +1,113 @@
+"""
+task_runtime/tasklist/lock.py — 任务存储文件锁管理
+
+职责：
+    提供文件锁保护，确保多进程并发安全：
+    - 单个任务文件锁
+    - 任务列表目录锁
+    - 软依赖处理（filelock 不存在时友好错误）
+
+链路位置：
+    TaskStore → TaskStoreLockManager → filelock.FileLock
+
+与 CC 对应：
+    CC src/utils/tasks.ts 中 withFileLock 函数。
+
+裁剪范围（v1）：
+    - 使用 filelock 库作为实现
+    - 默认超时 3.0 秒
+    - 错误信息包含锁文件路径
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from filelock import FileLock
+
+
+class FileLockNotAvailableError(RuntimeError):
+    """filelock 库未安装错误。"""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "filelock library is required for task store. "
+            "Install with: pip install filelock"
+        )
+
+
+class TaskStoreLockTimeoutError(TimeoutError):
+    """获取文件锁超时错误。"""
+
+    def __init__(self, lock_path: Path, timeout: float) -> None:
+        super().__init__(
+            f"Timeout waiting for lock after {timeout}s: {lock_path}. "
+            "Another process may be holding the lock."
+        )
+        self.lock_path = lock_path
+        self.timeout = timeout
+
+
+def _ensure_filelock() -> type[FileLock]:
+    """确保 filelock 库可用。"""
+    try:
+        from filelock import FileLock as FL
+        return FL  # type: ignore
+    except ImportError as e:
+        raise FileLockNotAvailableError() from e
+
+
+class TaskStoreLockManager:
+    """任务存储文件锁管理器。
+
+    为任务存储提供文件锁保护，防止多进程并发冲突。
+
+    锁文件路径：
+    - 任务锁：{task_path}.lock
+    - 目录锁：{tasks_dir}/.lock
+    """
+
+    def __init__(self, timeout: float = 3.0) -> None:
+        """初始化锁管理器。
+
+        Args:
+            timeout: 锁超时时间（秒），默认 3.0
+        """
+        self.timeout = timeout
+        self._filelock_class: type[FileLock] | None = None
+
+    def _get_filelock_class(self) -> type[FileLock]:
+        """延迟导入 FileLock 类（软依赖）。"""
+        if self._filelock_class is None:
+            self._filelock_class = _ensure_filelock()
+        return self._filelock_class
+
+    def get_lock(self, task_path: Path) -> "FileLock":
+        """获取单个任务的文件锁。
+
+        Args:
+            task_path: 任务文件路径
+
+        Returns:
+            FileLock 实例
+        """
+        lock_path = task_path.with_suffix(task_path.suffix + ".lock")
+        FileLock = self._get_filelock_class()
+        return FileLock(lock_path, timeout=self.timeout)
+
+    def get_list_lock(self, tasks_dir: Path) -> "FileLock":
+        """获取任务列表目录锁。
+
+        用于原子性操作（如认领任务、高水位更新）。
+
+        Args:
+            tasks_dir: 任务目录
+
+        Returns:
+            FileLock 实例
+        """
+        lock_path = tasks_dir / ".lock"
+        FileLock = self._get_filelock_class()
+        return FileLock(lock_path, timeout=self.timeout)

langchain_agentx/task_runtime/tasklist/models.py

@@ -0,0 +1,131 @@
+"""
+task_runtime/tasklist/models.py — CC 任务列表数据模型
+
+职责：
+    定义 Claude Code 对等的任务列表数据契约：
+    - TaskStatus：任务状态（pending/in_progress/committed）
+    - Task：任务完整数据结构
+    - TaskCreate：创建任务输入（不含自动生成字段）
+    - TaskUpdate：更新任务输入（全部可选）
+    - TaskFilters：列表过滤条件
+    - ClaimResult：任务认领结果
+
+链路位置：
+    TaskListRuntimeTool/TaskGetRuntimeTool → TaskStore → models
+
+与 CC 对应：
+    CC src/utils/tasks.ts 中 Task 接口、TaskStatus、ClaimResult 等。
+
+裁剪范围（v1）：
+    - 基础字段：id, subject, description, status, blocks, blockedBy
+    - metadata 支持 _internal 标记
+    - owner 字段预留（v1 简化，仅存储不校验）
+    - active_form 用于 UI 显示
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+TaskStatus = Literal["pending", "in_progress", "completed"]
+
+# 与 TaskStatus 同一对象；供 langchain_agentx.task_runtime 顶层导出为 TaskListStatus，
+# 以区别于编排层 core.types.TaskStatus 枚举。
+TaskListStatus = TaskStatus
+
+# 任务更新状态（包含 deleted，用于 TaskUpdate 工具）
+TaskUpdateStatus = Literal["pending", "in_progress", "completed", "deleted"]
+
+# 字段长度限制常量（基于用户体验与 CC 实践）
+MAX_SUBJECT_LENGTH: int = 120
+MAX_DESCRIPTION_LENGTH: int = 5000
+MAX_ACTIVE_FORM_LENGTH: int = 100
+
+
+@dataclass
+class Task:
+    """任务完整数据结构。
+
+    对应 CC Task 接口，每个任务对应一个 JSON 文件。
+
+    字段说明：
+        id: 任务唯一 ID（数字字符串，高水位标记生成）
+        subject: 任务简短标题
+        description: 任务详细描述
+        active_form: 进行中时显示的文本（如 "Fixing authentication bug"）
+        owner: 任务所有者（Agent ID 或 None）
+        status: 任务状态
+        blocks: 此任务阻塞的任务 ID 列表
+        blocked_by: 阻塞此任务的任务 ID 列表
+        metadata: 附加元数据（_internal=True 表示内部任务）
+    """
+
+    id: str
+    subject: str
+    description: str
+    active_form: Optional[str] = None
+    owner: Optional[str] = None
+    status: TaskStatus = "pending"
+    blocks: list[str] = field(default_factory=list)
+    blocked_by: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def is_internal(self) -> bool:
+        """判断是否为内部任务（不在 UI 显示）。"""
+        return self.metadata.get("_internal", False)
+
+
+@dataclass
+class TaskCreate:
+    """创建任务输入模型。
+
+    不含自动生成字段（id、默认字段）。
+    """
+
+    subject: str
+    description: str
+    active_form: Optional[str] = None
+    owner: Optional[str] = None
+    status: TaskStatus = "pending"
+    blocks: list[str] = field(default_factory=list)
+    blocked_by: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TaskUpdate:
+    """更新任务输入模型。
+
+    全部可选，仅更新提供的字段。
+    """
+
+    subject: Optional[str] = None
+    description: Optional[str] = None
+    active_form: Optional[str] = None
+    owner: Optional[str] = None
+    status: Optional[TaskStatus] = None
+    blocks: Optional[list[str]] = None
+    blocked_by: Optional[list[str]] = None
+    metadata: Optional[dict[str, Any]] = None
+
+
+@dataclass
+class TaskFilters:
+    """任务列表过滤条件。"""
+
+    status: Optional[TaskStatus] = None
+    owner: Optional[str] = None
+    exclude_internal: bool = True
+
+
+@dataclass
+class ClaimResult:
+    """任务认领结果。
+
+    对应 CC ClaimResult 接口。
+    """
+
+    success: bool
+    reason: Optional[str] = None
+    task: Optional[Task] = None