langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/hook/types.py

@@ -0,0 +1,110 @@
+"""
+types.py — Hook 子系统共享类型定义。
+
+职责：
+    定义 Hook 事件枚举、执行上下文、单 Hook 结果、聚合结果和执行记录契约。
+
+链路位置：
+    被 `loop/hook/config.py`、`loop/hook/engine.py` 与 graph wiring/observability 调用。
+
+当前裁剪范围：
+    P1 仅覆盖 callback/function 路径；command/http 执行器在 P2 引入。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+PermissionBehavior = Literal["allow", "ask", "deny", "passthrough"]
+HookOutcome = Literal["success", "blocking", "non_blocking_error", "cancelled", "trust_skipped"]
+HookSource = Literal["settings", "policy", "session", "builtin", "plugin"]
+
+
+class HookEvent(str, Enum):
+    """Hook 事件枚举（P1 + P2 预留）。"""
+
+    SESSION_START = "session_start"
+    SESSION_END = "session_end"
+    LOOP_START = "loop_start"
+    LOOP_END = "loop_end"
+    BEFORE_MODEL = "before_model"
+    AFTER_MODEL = "after_model"
+    STOP = "stop"
+    PRE_TOOL_USE = "pre_tool_use"
+    POST_TOOL_USE = "post_tool_use"
+    POST_TOOL_USE_FAILURE = "post_tool_use_failure"
+    PRE_COMPACT = "pre_compact"
+    POST_COMPACT = "post_compact"
+    SUBAGENT_START = "subagent_start"
+    SUBAGENT_STOP = "subagent_stop"
+    STOP_FAILURE = "stop_failure"
+
+
+@dataclass(frozen=True)
+class HookContext:
+    """传入 Hook 执行器的只读上下文。"""
+
+    event: HookEvent
+    state: dict[str, Any]
+    session_id: str | None = None
+    tool_name: str | None = None
+    tool_input: dict[str, Any] | None = None
+    tool_result: Any = None
+
+
+@dataclass
+class HookExecutionRecord:
+    """可观测记录最小字段契约（供 HookEventEmitter/TraceCollector 使用）。"""
+
+    hook_id: str
+    hook_event: str
+    hook_source: HookSource
+    matcher: str
+    matched: bool
+    skip_reason: str | None
+    snapshot_id: str
+    policy_source: str | None
+    outcome: HookOutcome
+    prevent_continuation: bool
+    duration_ms: float
+
+
+@dataclass
+class HookResult:
+    """单个 Hook 执行结果。"""
+
+    outcome: HookOutcome = "success"
+    prevent_continuation: bool = False
+    blocking_errors: list[str] = field(default_factory=list)
+    permission_behavior: PermissionBehavior | None = None
+    hook_permission_decision_reason: str | None = None
+    additional_context: str | None = None
+    updated_input: dict[str, Any] | None = None
+    state_patch: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AggregatedHookResult:
+    """同一事件多个 Hook 的聚合结果。"""
+
+    prevent_continuation: bool = False
+    blocking_errors: list[str] = field(default_factory=list)
+    permission_behavior: PermissionBehavior | None = None
+    hook_permission_decision_reason: str | None = None
+    additional_contexts: list[str] = field(default_factory=list)
+    updated_input: dict[str, Any] | None = None
+    state_patch: dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = [
+    "AggregatedHookResult",
+    "HookContext",
+    "HookEvent",
+    "HookExecutionRecord",
+    "HookOutcome",
+    "HookResult",
+    "HookSource",
+    "PermissionBehavior",
+]

langchain_agentx/loop/injection/__init__.py

@@ -0,0 +1,13 @@
+"""Loop 侧注入契约辅助（去重等）。"""
+
+from .dedup import (
+    collect_task_notification_command_ids,
+    extract_task_notification_command_id,
+    filter_attachment_dicts_by_task_command_id,
+)
+
+__all__ = [
+    "collect_task_notification_command_ids",
+    "extract_task_notification_command_id",
+    "filter_attachment_dicts_by_task_command_id",
+]

langchain_agentx/loop/injection/dedup.py

@@ -0,0 +1,74 @@
+"""
+工具后附件注入去重（与 `post-tools-injection-contract.md` 一致）。
+
+`task_event_reserve` 在 extend `LoopInjectionBatch.attachment_messages` 前应调用
+`filter_attachment_dicts_by_task_command_id`，避免同一 `command_id` 在 `messages` 中重复出现。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def extract_task_notification_command_id(message: Any) -> str | None:
+    """从单条消息解析 `metadata.task_notification.command_id`（dict 或 LC BaseMessage）。"""
+    if isinstance(message, dict):
+        meta = message.get("metadata")
+        if isinstance(meta, dict):
+            tn = meta.get("task_notification")
+            if isinstance(tn, dict):
+                cid = tn.get("command_id")
+                return str(cid) if cid is not None and str(cid) != "" else None
+        return None
+
+    ak = getattr(message, "additional_kwargs", None)
+    if isinstance(ak, dict):
+        meta = ak.get("metadata")
+        if isinstance(meta, dict):
+            tn = meta.get("task_notification")
+            if isinstance(tn, dict):
+                cid = tn.get("command_id")
+                return str(cid) if cid is not None and str(cid) != "" else None
+    return None
+
+
+def collect_task_notification_command_ids(messages: list[Any]) -> set[str]:
+    """扫描已有 `messages` 中已出现的 task_notification command_id 集合。"""
+    out: set[str] = set()
+    for m in messages:
+        cid = extract_task_notification_command_id(m)
+        if cid is not None:
+            out.add(cid)
+    return out
+
+
+def filter_attachment_dicts_by_task_command_id(
+    existing_messages: list[Any],
+    attachment_dicts: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """过滤待注入的 attachment dict：跳过 `command_id` 已在 `existing_messages` 中出现过的项。
+
+    无 `command_id` 的 dict **保留**（非 task 通知形状不 dedup）。
+    """
+    seen = collect_task_notification_command_ids(existing_messages)
+    added: list[dict[str, Any]] = []
+    for att in attachment_dicts:
+        if not isinstance(att, dict):
+            added.append(att)
+            continue
+        cid = extract_task_notification_command_id(att)
+        if cid is None:
+            added.append(att)
+            continue
+        if cid in seen:
+            continue
+        seen.add(cid)
+        added.append(att)
+    return added
+
+
+__all__ = [
+    "collect_task_notification_command_ids",
+    "extract_task_notification_command_id",
+    "filter_attachment_dicts_by_task_command_id",
+]

langchain_agentx/loop/loop_abort.py

@@ -0,0 +1,36 @@
+"""流式 / 工具 / hook 中断信号：由业务 middleware 或工具抛出，由内置 wrapper 转为 state 契约。"""
+
+from __future__ import annotations
+
+from .exit.reason_codes import (
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_HOOK_STOPPED,
+)
+
+
+class LoopAbortSignal(Exception):
+    """请求以 CC 式 abort 终局结束（写入 ``abort_terminal_reason``）。
+
+    - ``aborted_streaming`` / ``hook_stopped``：在 ``wrap_model_call`` / ``awrap_model_call`` 中抛出，
+      由 ``_LoopBuiltinModelControlMiddleware`` 捕获并合成 AIMessage + Command。
+    - ``aborted_tools``：在工具执行或 ``wrap_tool_call`` 中抛出，由内置 tool wrapper 捕获并
+      注入合成 ``ToolMessage`` + ``abort_terminal_reason``。
+    """
+
+    __slots__ = ("terminal_reason", "detail")
+
+    def __init__(self, terminal_reason: str, *, detail: str | None = None) -> None:
+        if terminal_reason not in (
+            TERMINAL_REASON_ABORTED_STREAMING,
+            TERMINAL_REASON_ABORTED_TOOLS,
+            TERMINAL_REASON_HOOK_STOPPED,
+        ):
+            msg = f"Invalid LoopAbortSignal terminal_reason: {terminal_reason!r}"
+            raise ValueError(msg)
+        self.terminal_reason = terminal_reason
+        self.detail = detail
+        super().__init__(detail or terminal_reason)
+
+
+__all__ = ["LoopAbortSignal"]

langchain_agentx/loop/model/__init__.py

@@ -0,0 +1 @@
+"""模型节点、绑定与 tool call 退化纠偏。"""