zero-agent-core 0.2.0__py3-none-any.whl

agent_core/callbacks/__init__.py

@@ -0,0 +1,17 @@
+"""Agent 生命周期回调。"""
+
+from agent_core.callbacks.manager import (
+    BaseCallbackHandler,
+    CallableCallbackHandler,
+    CallbackFailure,
+    CallbackHandler,
+    CallbackManager,
+)
+
+__all__ = [
+    "BaseCallbackHandler",
+    "CallableCallbackHandler",
+    "CallbackFailure",
+    "CallbackHandler",
+    "CallbackManager",
+]

agent_core/callbacks/manager.py

@@ -0,0 +1,105 @@
+"""进程内生命周期回调管理器。
+
+Callback 只观察已经发生的事件。需要修改、重试或阻止执行时，应使用 Middleware。
+EventSink 负责把事件发往进程外；CallbackManager 负责进程内订阅，两者消费同一个 RunEvent。
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from agent_core.protocol.runtime import RunEvent
+
+logger = logging.getLogger(__name__)
+
+CallbackFunction = Callable[[RunEvent], Awaitable[None] | None]
+
+
+@runtime_checkable
+class CallbackHandler(Protocol):
+    """生命周期事件处理器协议。"""
+
+    async def on_event(self, event: RunEvent) -> None: ...
+
+
+class BaseCallbackHandler:
+    """可按需继承的空回调基类。"""
+
+    async def on_event(self, event: RunEvent) -> None:
+        del event
+
+
+class CallableCallbackHandler(BaseCallbackHandler):
+    """把同步或异步函数包装为 CallbackHandler。"""
+
+    def __init__(
+        self,
+        callback: CallbackFunction,
+        *,
+        event_types: Iterable[str] | None = None,
+    ) -> None:
+        self._callback = callback
+        self._event_types = frozenset(event_types or ())
+
+    async def on_event(self, event: RunEvent) -> None:
+        if self._event_types and event.event_type not in self._event_types:
+            return
+        result = self._callback(event)
+        if inspect.isawaitable(result):
+            await result
+
+
+@dataclass(frozen=True)
+class CallbackFailure:
+    """一次回调分发失败，不改变 Agent 主流程。"""
+
+    handler_name: str
+    event_type: str
+    error: Exception
+
+
+class CallbackManager:
+    """按注册顺序分发生命周期事件并隔离订阅者故障。"""
+
+    def __init__(self, handlers: Iterable[CallbackHandler] | None = None) -> None:
+        self._handlers = list(handlers or ())
+
+    @property
+    def handlers(self) -> tuple[CallbackHandler, ...]:
+        return tuple(self._handlers)
+
+    def add(self, handler: CallbackHandler) -> None:
+        if handler not in self._handlers:
+            self._handlers.append(handler)
+
+    def remove(self, handler: CallbackHandler) -> bool:
+        try:
+            self._handlers.remove(handler)
+        except ValueError:
+            return False
+        return True
+
+    async def dispatch(self, event: RunEvent) -> tuple[CallbackFailure, ...]:
+        """向全部订阅者分发事件；单个订阅者失败不会中断其他订阅者。"""
+
+        failures: list[CallbackFailure] = []
+        for handler in tuple(self._handlers):
+            try:
+                await handler.on_event(event)
+            except Exception as exc:
+                failure = CallbackFailure(
+                    handler_name=type(handler).__name__,
+                    event_type=event.event_type,
+                    error=exc,
+                )
+                failures.append(failure)
+                logger.exception(
+                    "生命周期回调失败：handler=%s event=%s",
+                    failure.handler_name,
+                    event.event_type,
+                )
+        return tuple(failures)

agent_core/checkpoint/__init__.py

@@ -0,0 +1,19 @@
+"""Checkpoint 和历史版本管理。"""
+
+from agent_core.checkpoint.store import (
+    Checkpointer,
+    FileCheckpointer,
+    MemoryCheckpointer,
+)
+from agent_core.checkpoint.travel import (
+    CheckpointVersion,
+    TimeTravelCheckpointer,
+)
+
+__all__ = [
+    "CheckpointVersion",
+    "Checkpointer",
+    "FileCheckpointer",
+    "MemoryCheckpointer",
+    "TimeTravelCheckpointer",
+]

agent_core/checkpoint/naming.py

@@ -0,0 +1,93 @@
+"""checkpoint 文件名清洗与原子写入的底层工具。
+
+职责：
+- thread_id 与文件名之间的严格双向映射（`_sanitize_thread_id` / `_restore_thread_id`）；
+- 相关常量（`_FILENAME_*` / `_WINDOWS_RESERVED` / `_HEX_ESCAPE`）；
+- JSON 文件的临时文件 + 原子替换写入（`_atomic_write_json`）。
+
+本模块不依赖包内其他模块，供 `store` 与 `travel` 复用。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+# 文件名严格清洗：白名单字符原样保留（可读性），其余按 UTF-8 字节转义为 %XX。
+# Windows 非法字符 <>:"/\|?*、``%``（转义前缀，必须一并转义保证可逆）和控制符都要处理。
+_FILENAME_ILLEGAL_CHARS = frozenset('<>:"/\\|?*%')
+_FILENAME_ESCAPE_CHARS = _FILENAME_ILLEGAL_CHARS | {chr(code) for code in range(0x20)}
+# Windows 保留设备名（不区分大小写，且无论后缀如何都保留）：只检查文件名第一个点之前的主干。
+_WINDOWS_RESERVED = re.compile(r"CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9]", re.IGNORECASE)
+_HEX_ESCAPE = re.compile(r"%([0-9A-Fa-f]{2})")
+
+
+def _escape_char(char: str) -> str:
+    """把单个字符转义为 UTF-8 字节的 %XX 序列。"""
+    return "".join(f"%{byte:02X}" for byte in char.encode("utf-8", errors="surrogatepass"))
+
+
+def _sanitize_thread_id(thread_id: str) -> str:
+    """把 thread_id 清洗为跨平台安全且可逆的文件名主干。
+
+    规则：
+    - 白名单（可打印且不属于非法字符集）原样保留，保证可读性；
+    - 其余字符（Windows 非法字符 ``<>:"/\\|?*``、``%``、控制符、孤立代理对等）
+      按 UTF-8 字节转义为 ``%XX``。``%`` 本身也被转义，因此清洗是单射：
+      ``a/b`` 与 ``a_b`` 会得到不同文件名，不再互相覆盖；
+    - 以点/空格结尾或命中 Windows 保留设备名（CON、PRN、COM1 等）时，
+      对首个点之前主干的末字符转义规避系统特殊处理，映射仍然可逆。
+    """
+    sanitized = "".join(
+        char if char.isprintable() and char not in _FILENAME_ESCAPE_CHARS else _escape_char(char)
+        for char in thread_id
+    )
+    if sanitized.endswith((".", " ")):
+        sanitized = sanitized[:-1] + _escape_char(sanitized[-1])
+    base_name = sanitized.split(".", 1)[0]
+    if _WINDOWS_RESERVED.fullmatch(base_name):
+        sanitized = sanitized[:-1] + _escape_char(sanitized[-1])
+    return sanitized
+
+
+def _restore_thread_id(file_stem: str) -> str:
+    """`_sanitize_thread_id` 的逆映射；无法还原的历史文件名原样返回。"""
+    if "%" not in file_stem:
+        return file_stem
+    raw = bytearray()
+    index = 0
+    while index < len(file_stem):
+        match = _HEX_ESCAPE.match(file_stem, index)
+        if match is None:
+            raw.extend(file_stem[index].encode("utf-8", errors="surrogatepass"))
+            index += 1
+        else:
+            raw.append(int(match.group(1), 16))
+            index = match.end()
+    return raw.decode("utf-8", errors="surrogatepass")
+
+
+def _atomic_write_json(file_path: Path, value: Any) -> None:
+    """在目标目录写临时文件并原子替换，避免崩溃留下截断 JSON。"""
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=file_path.parent,
+            prefix=f".{file_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary:
+            temporary_path = Path(temporary.name)
+            json.dump(value, temporary, ensure_ascii=False, indent=2)
+            temporary.flush()
+            os.fsync(temporary.fileno())
+        os.replace(temporary_path, file_path)
+    finally:
+        if temporary_path is not None and temporary_path.exists():
+            temporary_path.unlink(missing_ok=True)

agent_core/checkpoint/store.py

@@ -0,0 +1,186 @@
+"""手写 checkpoint 持久化。
+
+功能：
+- 保存和加载会话状态（state）
+- 支持按 thread_id 隔离不同会话
+- 简化实现：内存存储 + 可选的 JSON 文件持久化
+
+包内职责划分：
+- `naming`：文件名清洗与原子写入（无依赖的底层工具）；
+- 本模块（`store`）：当前快照的 `Checkpointer` 协议与内存/文件两个实现；
+- `travel`：`CheckpointVersion` 与时间旅行多版本存储。
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+from pathlib import Path
+from typing import Any, Protocol
+
+from agent_core.checkpoint.naming import _atomic_write_json, _restore_thread_id, _sanitize_thread_id
+from agent_core.errors import CheckpointError
+
+logger = logging.getLogger(__name__)
+
+
+class Checkpointer(Protocol):
+    """Agent Loop 所需的最小 checkpoint 存储协议。
+
+    具体实现可以是内存、文件、SQLite 或 PostgreSQL；Core 只依赖这个协议，
+    不把数据库驱动和业务项目耦合进来。
+    """
+
+    async def save(
+        self,
+        thread_id: str,
+        state: dict[str, Any],
+        metadata: dict[str, Any] | None = None,
+    ) -> str | None:
+        """保存一个会话快照，返回实现生成的版本 ID（如有）。"""
+        ...
+
+    async def load(self, thread_id: str) -> dict[str, Any] | None:
+        """读取会话当前快照。"""
+        ...
+
+    async def delete(self, thread_id: str) -> None:
+        """删除会话当前快照。"""
+        ...
+
+
+class MemoryCheckpointer:
+    """内存 checkpoint 存储（进程内有效）。"""
+
+    def __init__(self) -> None:
+        # thread_id -> state
+        self._storage: dict[str, dict[str, Any]] = {}
+
+    async def save(
+        self,
+        thread_id: str,
+        state: dict[str, Any],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """保存会话状态。
+
+        Args:
+            thread_id: 会话 ID。
+            state: 状态字典。
+        """
+        # metadata 由版本型实现使用；内存当前快照保持原有 state 结构不变。
+        del metadata
+        self._storage[thread_id] = copy.deepcopy(state)
+        logger.debug("Saved checkpoint for thread %r (keys: %d)", thread_id, len(state))
+
+    async def load(self, thread_id: str) -> dict[str, Any] | None:
+        """加载会话状态。
+
+        Args:
+            thread_id: 会话 ID。
+
+        Returns:
+            状态字典，如果不存在则返回 None。
+        """
+        state = self._storage.get(thread_id)
+        if state is not None:
+            logger.debug("Loaded checkpoint for thread %r (keys: %d)", thread_id, len(state))
+        return copy.deepcopy(state) if state is not None else None
+
+    async def delete(self, thread_id: str) -> None:
+        """删除会话状态。
+
+        Args:
+            thread_id: 会话 ID。
+        """
+        if thread_id in self._storage:
+            del self._storage[thread_id]
+            logger.debug("Deleted checkpoint for thread %r", thread_id)
+
+    def list_threads(self) -> list[str]:
+        """列出所有会话 ID。"""
+        return list(self._storage.keys())
+
+
+class FileCheckpointer:
+    """文件系统 checkpoint 存储（JSON 格式）。
+
+    每个 thread 存储为独立的 JSON 文件。
+    """
+
+    def __init__(self, storage_dir: str | Path) -> None:
+        """
+        Args:
+            storage_dir: 存储目录路径。
+        """
+        self._storage_dir = Path(storage_dir)
+        self._storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_file_path(self, thread_id: str) -> Path:
+        """获取 thread 对应的文件路径。
+
+        文件名经 `_sanitize_thread_id` 严格清洗：单射且可逆，含 ``/``、``\\``、
+        ``:`` 等 Windows 非法字符的 thread_id 不会互相覆盖。
+        """
+        return self._storage_dir / f"{_sanitize_thread_id(thread_id)}.json"
+
+    async def save(
+        self,
+        thread_id: str,
+        state: dict[str, Any],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """保存会话状态到文件。
+
+        Args:
+            thread_id: 会话 ID。
+            state: 状态字典。
+        """
+        # 文件快照接口与内存实现保持一致，metadata 由需要版本历史的实现使用。
+        del metadata
+        file_path = self._get_file_path(thread_id)
+        try:
+            _atomic_write_json(file_path, state)
+            logger.debug("Saved checkpoint for thread %r to %s", thread_id, file_path)
+        except Exception as exc:
+            raise CheckpointError(f"Failed to save checkpoint for thread {thread_id!r}: {exc}") from exc
+
+    async def load(self, thread_id: str) -> dict[str, Any] | None:
+        """从文件加载会话状态。
+
+        Args:
+            thread_id: 会话 ID。
+
+        Returns:
+            状态字典，如果文件不存在则返回 None。
+        """
+        file_path = self._get_file_path(thread_id)
+        if not file_path.exists():
+            return None
+
+        try:
+            with file_path.open("r", encoding="utf-8") as f:
+                raw_state = json.load(f)
+            if not isinstance(raw_state, dict):
+                raise CheckpointError(f"Checkpoint {thread_id!r} 的根节点必须是对象")
+            state: dict[str, Any] = {str(key): value for key, value in raw_state.items()}
+            logger.debug("Loaded checkpoint for thread %r from %s", thread_id, file_path)
+            return state
+        except Exception as exc:
+            raise CheckpointError(f"Failed to load checkpoint for thread {thread_id!r}: {exc}") from exc
+
+    async def delete(self, thread_id: str) -> None:
+        """删除会话状态文件。
+
+        Args:
+            thread_id: 会话 ID。
+        """
+        file_path = self._get_file_path(thread_id)
+        if file_path.exists():
+            file_path.unlink()
+            logger.debug("Deleted checkpoint for thread %r at %s", thread_id, file_path)
+
+    def list_threads(self) -> list[str]:
+        """列出所有会话 ID（文件名主干经 `_restore_thread_id` 逆映射还原）。"""
+        return [_restore_thread_id(file_path.stem) for file_path in self._storage_dir.glob("*.json")]