langchain-agentx-python 1.1.2__tar.gz → 1.1.4__tar.gz

{langchain-agentx-python-1.1.2/langchain_agentx_python.egg-info → langchain-agentx-python-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 1.1.2
+Version: 1.1.4
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-1.1.2 → langchain-agentx-python-1.1.4}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "1.1.2"
+__version__ = "1.1.4"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-1.1.2 → langchain-agentx-python-1.1.4}/langchain_agentx/task_runtime/__init__.py

@@ -29,8 +29,8 @@ from .tasklist import (
 from .core.interfaces import TaskExecutor
 from .orchestrator.runtime import DefaultTaskRuntime
 from .queue.in_memory import InMemoryTaskCommandQueue
+from .store import FileTaskStore
 from .store.in_memory import InMemoryTaskStore
-from .store.sqlite_store import SqliteTaskStore
 from .tasks import (
     CUSTOM_SEMANTIC,
     CustomTaskExecutor,
@@ -109,8 +109,8 @@ __all__ = [
     "encode_provider_batch_id",
     "decode_provider_batch_id",
     "DefaultTaskRuntime",
+    "FileTaskStore",
     "InMemoryTaskStore",
-    "SqliteTaskStore",
     "InMemoryTaskCommandQueue",
     "TaskExecutor",
     "LocalBashExecutor",

langchain-agentx-python-1.1.4/langchain_agentx/task_runtime/store/__init__.py

@@ -0,0 +1,6 @@
+"""Task record persistence implementations."""
+
+from .file_store import FileTaskStore
+from .in_memory import InMemoryTaskStore
+
+__all__ = ["FileTaskStore", "InMemoryTaskStore"]

langchain-agentx-python-1.1.4/langchain_agentx/task_runtime/store/file_store.py

@@ -0,0 +1,424 @@
+"""
+task_runtime/store/file_store.py — Task Runtime 文件持久化存储（CC 风格）
+
+职责：
+    提供 TaskStore 的文件持久化实现：
+    1. 使用 CC 风格临时目录结构（/tmp/claude-{uid}/{sanitized-cwd}/{session_id}/tasks/）
+    2. 任务记录序列化为 JSON 文件（.runtime 扩展名，与 tasklist 的 .json 区分）
+    3. 跨平台文件锁支持（Unix: fcntl, Windows: msvcrt）
+    4. 完整实现 TaskStore 协议方法
+
+链路位置：
+    TaskRuntime → FileTaskStore → CC 风格文件系统
+
+与 CC 对应：
+    CC src/utils/task/diskOutput.ts 中文件存储逻辑。
+
+当前裁剪范围：
+    - 单机文件存储，不支持分布式
+    - 文件锁仅保护单进程内的多线程安全
+    - 不支持复杂查询（仅支持 list 全量读取）
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+if sys.platform == "win32":
+    import msvcrt  # noqa: F401 (仅 Windows 使用)
+else:
+    import fcntl  # noqa: F401 (Unix 文件锁)
+from dataclasses import asdict
+from pathlib import Path
+from threading import RLock
+from typing import Iterable, Optional
+
+from ..core.interfaces import TaskStore
+from ..core.types import TaskRecord, TaskScope, TaskStatus, TaskType
+from ...utils import task_output_dir
+
+
+class FileTaskStore(TaskStore):
+    """CC 风格文件任务存储。
+
+    使用临时目录存储任务记录，支持多 CLI 实例隔离。
+    每个任务记录存储为独立的 JSON 文件，文件名为 {task_id}.runtime。
+
+    Attributes:
+        tasks_dir: 任务存储目录路径
+    """
+
+    def __init__(self, cwd: str, session_id: str) -> None:
+        """初始化文件任务存储。
+
+        Args:
+            cwd: 当前工作目录（用于路径安全化）
+            session_id: 会话 ID（用于多 CLI 隔离）
+        """
+        self._lock = RLock()
+        self._cwd = cwd
+        self._session_id = session_id
+        self._tasks_dir = task_output_dir(cwd, session_id)
+        self._ensure_dir()
+
+    @property
+    def tasks_dir(self) -> Path:
+        """获取任务存储目录。"""
+        return self._tasks_dir
+
+    def _ensure_dir(self) -> None:
+        """确保任务存储目录存在。"""
+        self._tasks_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_task_path(self, task_id: str) -> Path:
+        """获取任务文件路径。
+
+        Args:
+            task_id: 任务 ID
+
+        Returns:
+            任务文件路径
+        """
+        return self._tasks_dir / f"{task_id}.runtime"
+
+    def _serialize(self, record: TaskRecord) -> str:
+        """序列化任务记录为 JSON 字符串。
+
+        Args:
+            record: 任务记录
+
+        Returns:
+            JSON 字符串
+        """
+        data = {
+            "task_id": record.task_id,
+            "task_type": record.task_type.value,
+            "status": record.status.value,
+            "description": record.description,
+            "scope": {"agent_id": record.scope.agent_id},
+            "input": record.input,
+            "metadata": record.metadata,
+            "created_at": record.created_at,
+            "updated_at": record.updated_at,
+            "output_file": record.output_file,
+            "terminal_emitted_statuses": [s.value for s in record.terminal_emitted_statuses],
+            "notification_consumed": record.notification_consumed,
+            "run_id": record.run_id,
+            "external_ref": record.external_ref,
+            "lease_until_ts": record.lease_until_ts,
+            "last_heartbeat_ts": record.last_heartbeat_ts,
+            "worker_id": record.worker_id,
+        }
+        return json.dumps(data, ensure_ascii=True)
+
+    def _deserialize(self, content: str) -> TaskRecord:
+        """从 JSON 字符串反序列化任务记录。
+
+        Args:
+            content: JSON 字符串
+
+        Returns:
+            任务记录
+        """
+        data = json.loads(content)
+        return TaskRecord(
+            task_id=data["task_id"],
+            task_type=TaskType(data["task_type"]),
+            status=TaskStatus(data["status"]),
+            description=data["description"],
+            scope=TaskScope(agent_id=data["scope"].get("agent_id")),
+            input=data.get("input", {}),
+            metadata=data.get("metadata", {}),
+            created_at=float(data["created_at"]),
+            updated_at=float(data["updated_at"]),
+            output_file=data.get("output_file"),
+            terminal_emitted_statuses=set(
+                TaskStatus(s) for s in data.get("terminal_emitted_statuses", [])
+            ),
+            notification_consumed=bool(data.get("notification_consumed", False)),
+            run_id=data.get("run_id"),
+            external_ref=data.get("external_ref"),
+            lease_until_ts=_optional_float(data.get("lease_until_ts")),
+            last_heartbeat_ts=_optional_float(data.get("last_heartbeat_ts")),
+            worker_id=data.get("worker_id"),
+        )
+
+    def _write_file(self, path: Path, content: str) -> None:
+        """写入文件（带文件锁）。
+
+        Args:
+            path: 文件路径
+            content: 文件内容
+        """
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            _lock_file(f)
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+            _unlock_file(f)
+
+    def _read_file(self, path: Path) -> Optional[str]:
+        """读取文件（带文件锁）。
+
+        Args:
+            path: 文件路径
+
+        Returns:
+            文件内容，如果文件不存在则返回 None
+        """
+        if not path.exists():
+            return None
+        with open(path, "r", encoding="utf-8") as f:
+            _lock_file(f, shared=True)
+            try:
+                return f.read()
+            finally:
+                _unlock_file(f)
+
+    def create(self, record: TaskRecord) -> None:
+        """创建任务记录。
+
+        Args:
+            record: 任务记录
+        """
+        path = self._get_task_path(record.task_id)
+        content = self._serialize(record)
+        with self._lock:
+            self._write_file(path, content)
+
+    def get(self, task_id: str) -> Optional[TaskRecord]:
+        """读取任务记录。
+
+        Args:
+            task_id: 任务 ID
+
+        Returns:
+            任务记录，如果不存在则返回 None
+        """
+        path = self._get_task_path(task_id)
+        with self._lock:
+            content = self._read_file(path)
+            if content is None:
+                return None
+            return self._deserialize(content)
+
+    def update(self, task_id: str, patch: dict) -> Optional[TaskRecord]:
+        """更新任务记录。
+
+        Args:
+            task_id: 任务 ID
+            patch: 更新字段字典
+
+        Returns:
+            更新后的任务记录，如果不存在则返回 None
+        """
+        with self._lock:
+            current = self.get(task_id)
+            if current is None:
+                return None
+
+            # 构建更新后的记录
+            data = asdict(current)
+            data.update(patch)
+
+            # 处理特殊字段
+            updated = TaskRecord(
+                task_id=data["task_id"],
+                task_type=_coerce_task_type(data["task_type"]),
+                status=_coerce_task_status(data["status"]),
+                description=data["description"],
+                scope=_coerce_task_scope(data["scope"]),
+                input=data.get("input", {}),
+                metadata=data.get("metadata", {}),
+                created_at=float(data["created_at"]),
+                updated_at=float(data["updated_at"]),
+                output_file=data.get("output_file"),
+                terminal_emitted_statuses=set(
+                    _coerce_task_status(s)
+                    for s in data.get("terminal_emitted_statuses", set())
+                ),
+                notification_consumed=bool(data.get("notification_consumed", False)),
+                run_id=data.get("run_id"),
+                external_ref=data.get("external_ref"),
+                lease_until_ts=_optional_float(data.get("lease_until_ts")),
+                last_heartbeat_ts=_optional_float(data.get("last_heartbeat_ts")),
+                worker_id=data.get("worker_id"),
+            )
+            self.create(updated)
+            return updated
+
+    def list(self) -> Iterable[TaskRecord]:
+        """列出所有任务记录。
+
+        Returns:
+            任务记录迭代器
+        """
+        with self._lock:
+            if not self._tasks_dir.exists():
+                return []
+            records = []
+            for path in self._tasks_dir.glob("*.runtime"):
+                content = self._read_file(path)
+                if content:
+                    try:
+                        records.append(self._deserialize(content))
+                    except (json.JSONDecodeError, KeyError, ValueError):
+                        # 跳过损坏的文件
+                        continue
+            return records
+
+    def delete(self, task_id: str) -> None:
+        """删除任务记录。
+
+        Args:
+            task_id: 任务 ID
+        """
+        path = self._get_task_path(task_id)
+        with self._lock:
+            if path.exists():
+                path.unlink()
+
+    def evict_expired(self, *, now_ts: float, ttl_sec: float) -> int:
+        """清理过期任务记录。
+
+        Args:
+            now_ts: 当前时间戳
+            ttl_sec: TTL 秒数
+
+        Returns:
+            删除的记录数
+        """
+        if ttl_sec <= 0:
+            return 0
+
+        cutoff = float(now_ts) - float(ttl_sec)
+        terminal_statuses = {TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED}
+
+        with self._lock:
+            count = 0
+            if not self._tasks_dir.exists():
+                return 0
+
+            for path in self._tasks_dir.glob("*.runtime"):
+                content = self._read_file(path)
+                if content:
+                    try:
+                        data = json.loads(content)
+                        status = TaskStatus(data.get("status", TaskStatus.PENDING.value))
+                        updated_at = float(data.get("updated_at", 0))
+
+                        if status in terminal_statuses and updated_at <= cutoff:
+                            path.unlink()
+                            count += 1
+                    except (json.JSONDecodeError, KeyError, ValueError):
+                        # 跳过损坏的文件
+                        continue
+
+            return count
+
+    def evict_over_capacity(self, *, max_records: int) -> int:
+        """清理超过容量限制的任务记录。
+
+        Args:
+            max_records: 最大记录数
+
+        Returns:
+            删除的记录数
+        """
+        if max_records < 0:
+            return 0
+
+        terminal_statuses = {TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED}
+
+        with self._lock:
+            all_records = list(self.list())
+            total = len(all_records)
+            overflow = total - max_records
+
+            if overflow <= 0:
+                return 0
+
+            # 筛选终态任务并按更新时间排序
+            terminal_records = [
+                r for r in all_records if r.status in terminal_statuses
+            ]
+            terminal_records.sort(key=lambda r: r.updated_at)
+
+            to_delete = terminal_records[:overflow]
+            for record in to_delete:
+                self.delete(record.task_id)
+
+            return len(to_delete)
+
+
+def _lock_file(file_obj, shared: bool = False) -> None:
+    """对文件对象加锁（跨平台）。
+
+    Args:
+        file_obj: 文件对象
+        shared: 是否为共享锁（读锁）
+    """
+    if sys.platform == "win32":
+        # Windows 字节范围锁：须在锁定位置解锁；读写后 seek 回 0
+        file_obj.seek(0)
+        try:
+            msvcrt.locking(file_obj.fileno(), msvcrt.LK_NBLCK, 1)
+        except OSError:
+            time.sleep(0.01)
+            file_obj.seek(0)
+            msvcrt.locking(file_obj.fileno(), msvcrt.LK_NBLCK, 1)
+    else:
+        # Unix: 使用 fcntl
+        lock_type = fcntl.LOCK_SH if shared else fcntl.LOCK_EX
+        fcntl.flock(file_obj.fileno(), lock_type)
+
+
+def _unlock_file(file_obj) -> None:
+    """对文件对象解锁（跨平台）。
+
+    Args:
+        file_obj: 文件对象
+    """
+    if sys.platform == "win32":
+        file_obj.seek(0)
+        try:
+            msvcrt.locking(file_obj.fileno(), msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+    else:
+        # Unix: 使用 fcntl
+        fcntl.flock(file_obj.fileno(), fcntl.LOCK_UN)
+
+
+def _optional_float(value) -> Optional[float]:
+    """安全转换为 float，None 返回 None。"""
+    if value is None:
+        return None
+    return float(value)
+
+
+def _coerce_task_type(value) -> TaskType:
+    """强制转换为 TaskType。"""
+    if isinstance(value, TaskType):
+        return value
+    return TaskType(str(value))
+
+
+def _coerce_task_status(value) -> TaskStatus:
+    """强制转换为 TaskStatus。"""
+    if isinstance(value, TaskStatus):
+        return value
+    return TaskStatus(str(value))
+
+
+def _coerce_task_scope(value) -> TaskScope:
+    """强制转换为 TaskScope。"""
+    if isinstance(value, TaskScope):
+        return value
+    if isinstance(value, dict):
+        return TaskScope(agent_id=value.get("agent_id"))
+    return TaskScope(agent_id=None)

{langchain-agentx-python-1.1.2 → langchain-agentx-python-1.1.4}/langchain_agentx/task_runtime/tasklist/__init__.py

@@ -27,6 +27,8 @@ from .models import (
     TaskUpdateStatus,
 )
 from .path_resolver import (
+    get_highwatermark_path,
+    get_task_list_lock_path,
     get_task_path,
     get_tasks_dir,
     resolve_task_list_id,
@@ -54,6 +56,8 @@ __all__ = [
     "on_tasks_updated",
     "get_tasks_dir",
     "get_task_path",
+    "get_highwatermark_path",
+    "get_task_list_lock_path",
     "resolve_task_list_id",
     "resolve_task_list_paths",
     "sanitize_path_component",

langchain-agentx-python-1.1.4/langchain_agentx/task_runtime/tasklist/config_home_paths.py

@@ -0,0 +1,93 @@
+"""
+task_runtime/tasklist/config_home_paths.py — config home 任务路径解析
+
+职责：
+    按 CC getClaudeConfigHomeDir + getTasksDir 公式解析任务列表物理路径：
+    {config_home}/tasks/{taskListId}/{taskId}.json
+
+链路位置：
+    path_resolver → ConfigHomeTaskPaths → workspace/project_key.resolve_config_home_dir
+
+与 CC 对应：
+    src/utils/envUtils.ts#getClaudeConfigHomeDir
+    src/utils/tasks.ts#getTasksDir / getTaskPath / getHighWaterMarkPath
+
+当前裁剪范围（Phase 7）：
+    - 不含 taskListId 5 级解析（Phase 8）
+    - 不含 /tmp 数据迁移（Phase 7 可选工具未在本模块）
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from langchain_agentx.workspace import ResolvedAgentStateConfig
+from langchain_agentx.workspace.project_key import resolve_config_home_dir
+from langchain_agentx.workspace.resolver import resolve_agent_home_string
+
+HIGH_WATERMARK_FILE = ".highwatermark"
+TASK_LIST_LOCK_FILE = ".lock"
+
+
+def sanitize_path_component(s: str) -> str:
+    """路径组件安全化（对齐 CC sanitizePathComponent）。"""
+    sanitized = re.sub(r"[^a-zA-Z0-9_-]", "-", s)
+    sanitized = sanitized.strip(". ")
+    if len(sanitized) > 255:
+        sanitized = sanitized[:255]
+    return sanitized or "unnamed"
+
+
+def resolve_config_home(agent_home_segment: str | None = None) -> Path:
+    """解析 config home 目录（对齐 CC getClaudeConfigHomeDir）。
+
+    优先级与 workspace resolver 一致：显式 segment → 环境变量 → 默认 .langchain_agentx。
+    """
+    segment = resolve_agent_home_string(agent_home_segment)
+    return resolve_config_home_dir(segment)
+
+
+def get_config_home(config: ResolvedAgentStateConfig) -> Path:
+    """从已解析工作区配置派生 config home（禁止业务模块自行拼接 Path.home()）。"""
+    return resolve_config_home_dir(config.agent_home_segment)
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigHomeTaskPaths:
+    """config home 下任务列表路径 Facade（OOP 单一职责）。"""
+
+    config_home: Path
+
+    @classmethod
+    def from_agent_home_segment(cls, agent_home_segment: str | None = None) -> ConfigHomeTaskPaths:
+        return cls(config_home=resolve_config_home(agent_home_segment))
+
+    @classmethod
+    def from_workspace_config(cls, config: ResolvedAgentStateConfig) -> ConfigHomeTaskPaths:
+        return cls(config_home=get_config_home(config))
+
+    def tasks_dir(self, task_list_id: str) -> Path:
+        safe_id = sanitize_path_component(task_list_id)
+        return self.config_home / "tasks" / safe_id
+
+    def task_path(self, task_list_id: str, task_id: str) -> Path:
+        safe_task_id = sanitize_path_component(task_id)
+        return self.tasks_dir(task_list_id) / f"{safe_task_id}.json"
+
+    def highwatermark_path(self, task_list_id: str) -> Path:
+        return self.tasks_dir(task_list_id) / HIGH_WATERMARK_FILE
+
+    def task_list_lock_path(self, task_list_id: str) -> Path:
+        return self.tasks_dir(task_list_id) / TASK_LIST_LOCK_FILE
+
+
+__all__ = [
+    "HIGH_WATERMARK_FILE",
+    "TASK_LIST_LOCK_FILE",
+    "ConfigHomeTaskPaths",
+    "get_config_home",
+    "resolve_config_home",
+    "sanitize_path_component",
+]

{langchain-agentx-python-1.1.2 → langchain-agentx-python-1.1.4}/langchain_agentx/task_runtime/tasklist/high_water_mark.py

@@ -22,7 +22,8 @@ from __future__ import annotations
 
 import asyncio
 from pathlib import Path
-from typing import Optional
+
+from .config_home_paths import HIGH_WATERMARK_FILE
 
 
 class HighWaterMarkManager:
@@ -43,8 +44,8 @@ class HighWaterMarkManager:
         self.timeout = timeout
 
     def _get_highwatermark_path(self, tasks_dir: Path) -> Path:
-        """获取高水位文件路径。"""
-        return tasks_dir / ".highwatermark"
+        """获取高水位文件路径（与 path_resolver.get_highwatermark_path 文件名一致）。"""
+        return tasks_dir / HIGH_WATERMARK_FILE
 
     async def read(self, tasks_dir: Path) -> int:
         """读取当前高水位值。
@@ -218,3 +219,9 @@ class HighWaterMarkManager:
         self._write_sync(tasks_dir, next_id)
 
         return next_id
+
+    def maybe_raise_mark_sync(self, tasks_dir: Path, task_id: int) -> None:
+        """若 task_id 高于当前 mark 则提升 mark（对齐 CC deleteTask L400–407）。"""
+        current = self._read_sync(tasks_dir)
+        if task_id > current:
+            self._write_sync(tasks_dir, task_id)

{langchain-agentx-python-1.1.2 → langchain-agentx-python-1.1.4}/langchain_agentx/task_runtime/tasklist/notifier.py

@@ -2,15 +2,17 @@
 task_runtime/tasklist/notifier.py — 任务列表更新通知
 
 职责：
-    提供进程内任务列表变更订阅/广播，对齐 CC notifyTasksUpdated / onTasksUpdated。
+    提供进程内任务列表变更订阅/广播。
 
-链路位置：
-    TaskStore create/update/delete/reset 落盘成功 → notify_tasks_updated()
-    → CLI 可选 on_tasks_updated 加速刷新（不替代 fs.watch）
+链路位置（SDK 设计，与 CC 分层不同）：
+    TaskStore 落盘成功 → notify_tasks_updated()（唯一 emit 源）
+    → CLI on_tasks_updated 回调内调用 TaskListReader.list_tasks() 刷新
+    TaskListReader / paths 只读，不得再次 emit。
 
 当前裁剪范围：
     - 仅同进程通知；跨进程变更靠 CLI 目录 watch / poll
     - listener 异常吞掉，写盘/reset 不受通知失败影响
+    - 单次 store 变更操作只 notify 一次（内部子步骤 suppress）
 """
 
 from __future__ import annotations