langchain-agentx-python 2.2.0__py3-none-any.whl → 2.2.2__py3-none-any.whl

langchain_agentx/__init__.py

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

langchain_agentx/observability/events/agent_event_projector.py

@@ -51,6 +51,12 @@ from langchain_agentx.observability.events.agent_defaults import DEFAULT_AGENT_T
 from langchain_agentx.observability.events.subagent_window_text_guard import (
     SubagentWindowTextGuard,
 )
+from langchain_agentx.observability.events.compact_event_gate import (
+    beneficial_light_stage_names,
+    extract_compaction_meta_from_chain_end_data,
+    is_user_visible_compact,
+    light_only_with_benefit,
+)
 from langchain_agentx.observability.events.tool_call_id_resolver import (
     ToolCallIdResolver,
 )
@@ -121,8 +127,7 @@ class LangchainAgentEventType(Enum):
     FINISH_STEP = "finish-step"
     HOOK_PROGRESS = "hook-progress"
     HOOK_FINISHED = "hook-finished"
-    COMPACT_START = "compact-start"
-    COMPACT_END = "compact-end"
+    COMPACT_BOUNDARY = "compact-boundary"
     MEMORY_SAVED = "memory-saved"
     SUBAGENT_START = "subagent-start"
     SUBAGENT_END = "subagent-end"
@@ -396,12 +401,7 @@ class AgentEventProjector:
                 step_index=self.state.step_index or None,
             )
 
-        if self.enable_compact_events and self._is_compact_node(name):
-            yield self._event(
-                event_type=LangchainAgentEventType.COMPACT_START,
-                data={},
-                step_index=self.state.step_index or None,
-            )
+        # D-CMP-EVT：不在 start 发 compact（CC 无 start/end；事后单边界）
 
     def _build_loop_observation_payload(self) -> Dict[str, Any]:
         snap = self.state.last_loop_snapshot or {}
@@ -752,7 +752,6 @@ class AgentEventProjector:
             result["tokens_freed"] = meta.get("tokens_freed_sum")
 
             stages = meta.get("stages")
-            autocompact_found = False
             microcompact_found = False
 
             if isinstance(stages, list):
@@ -761,7 +760,6 @@ class AgentEventProjector:
                         name = s.get("name")
                         extra = s.get("extra") or {}
                         if name == "autocompact":
-                            autocompact_found = True
                             result["autocompact_mode"] = extra.get("autocompact_mode")
                             result["folded_messages"] = extra.get("folded_messages")
                             result["messages_summarized"] = extra.get("folded_messages")
@@ -782,10 +780,12 @@ class AgentEventProjector:
                                 break
 
                 if "compact_type" not in result:
-                    if autocompact_found or not microcompact_found:
+                    mode = result.get("autocompact_mode")
+                    if isinstance(mode, str) and mode:
                         result["compact_type"] = "autocompact"
-                    else:
+                    elif microcompact_found:
                         result["compact_type"] = "microcompact"
+                    # 不再用「stages 出现过 autocompact 名」回落为 autocompact（假阳性）
 
         if "summary" not in result:
             messages = output.get("messages")
@@ -848,13 +848,30 @@ class AgentEventProjector:
                 step_index=self.state.step_index or None,
             )
 
-        if self.enable_compact_events and self._is_compact_node(name):
-            compact_data = self._extract_compact_summary(data)
-            yield self._event(
-                event_type=LangchainAgentEventType.COMPACT_END,
-                data=compact_data,
-                step_index=self.state.step_index or None,
-            )
+        if self._is_compact_node(name):
+            meta = extract_compaction_meta_from_chain_end_data(data)
+            if is_user_visible_compact(meta):
+                if self.enable_compact_events:
+                    compact_data = self._extract_compact_summary(data)
+                    if "trigger" not in compact_data:
+                        compact_data["trigger"] = "auto"
+                    yield self._event(
+                        event_type=LangchainAgentEventType.COMPACT_BOUNDARY,
+                        data=compact_data,
+                        step_index=self.state.step_index or None,
+                    )
+            elif light_only_with_benefit(meta):
+                # D-CMP-EVT-7：对齐 CC logForDebugging；不受 enable_compact_events 关闭影响
+                freed = None
+                if isinstance(meta, dict):
+                    freed = meta.get("tokens_freed_sum")
+                stages = beneficial_light_stage_names(meta)
+                logger.debug(
+                    "compact light-only: tokens_freed_sum=%s stages=%s "
+                    "(no public compact-boundary; align CC logForDebugging)",
+                    freed,
+                    stages or None,
+                )
 
         if name == self.state.graph_name:
             if self.enable_reasoning_events and self.state.is_reasoning_active:

langchain_agentx/observability/events/compact_event_gate.py

@@ -0,0 +1,152 @@
+"""
+compact_event_gate.py — compact 公共事件门闩（对齐 CC compact_boundary）
+
+职责：
+    - 从 compaction_pipeline_meta 判定是否用户可见真压缩 / light-only 有收益
+    - 供 agent_event_projector 发射 compact-boundary 或 logger.debug
+
+链路位置：
+    - Layer 3: observability/events 投影门闩（不改 L0 压缩流水线）
+
+当前裁剪范围：
+    - 仅 meta 谓词；不创建 SSE 以外的事件类型
+    - session_memory applied 仅识别显式标记（字段可后续扩展）
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_agentx.loop.exit.query_source import QuerySource
+
+# 实际折叠上下文的 autocompact_mode（不含仅 skipped）
+APPLIED_AUTOCOMPACT_MODES: frozenset[str] = frozenset(
+    {
+        "llm",
+        "prune",
+        "prune_blocked_llm",
+    }
+)
+
+_LIGHT_STAGE_NAMES: frozenset[str] = frozenset(
+    {
+        "tool_result_budget",
+        "snip",
+        "microcompact",
+        "collapse",
+    }
+)
+
+
+def _as_dict(meta: Any) -> Optional[dict[str, Any]]:
+    return meta if isinstance(meta, dict) else None
+
+
+def _stage_extra(stage: dict[str, Any]) -> dict[str, Any]:
+    extra = stage.get("extra")
+    return extra if isinstance(extra, dict) else {}
+
+
+def _positive_number(value: Any) -> bool:
+    if value is None:
+        return False
+    try:
+        return float(value) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def is_user_visible_compact(meta: Any) -> bool:
+    """真压缩已应用 → 应对齐 CC 发一条 compact-boundary。
+
+    禁止用 tokens_freed_sum / stages 仅出现 autocompact 名 / compact_type 回落判定。
+    """
+    m = _as_dict(meta)
+    if m is None:
+        return False
+
+    # Session / 手动：L0 现网键（factory session_memory 路径无 stages[]）
+    if m.get("session_memory_compact_applied") is True:
+        return True
+    if m.get("manual_compact_applied") is True:
+        return True
+    if m.get("session_memory_compaction") == "applied":
+        return True
+    if m.get("autocompact_mode") == QuerySource.SESSION_MEMORY:
+        return True
+
+    stages = m.get("stages")
+    if not isinstance(stages, list):
+        return False
+
+    for stage in stages:
+        if not isinstance(stage, dict):
+            continue
+        name = stage.get("name")
+        extra = _stage_extra(stage)
+        if name == "autocompact":
+            mode = extra.get("autocompact_mode")
+            if isinstance(mode, str) and mode in APPLIED_AUTOCOMPACT_MODES:
+                return True
+        if name == QuerySource.SESSION_MEMORY and extra.get("applied") is True:
+            return True
+    return False
+
+
+def light_only_with_benefit(meta: Any) -> bool:
+    """非用户可见，但有轻量 stage（或 sum）释放 token → 应对齐 CC logForDebugging。"""
+    if is_user_visible_compact(meta):
+        return False
+    m = _as_dict(meta)
+    if m is None:
+        return False
+
+    stages = m.get("stages")
+    if isinstance(stages, list):
+        for stage in stages:
+            if not isinstance(stage, dict):
+                continue
+            if _positive_number(stage.get("tokens_freed")):
+                return True
+            # micro 规范化标记但 tokens 估计可能为 0：仍视为有 light 动作时可记
+            name = stage.get("name")
+            extra = _stage_extra(stage)
+            if name == "microcompact" and extra.get("microcompact_normalized"):
+                return True
+
+    return _positive_number(m.get("tokens_freed_sum"))
+
+
+def beneficial_light_stage_names(meta: Any) -> list[str]:
+    """有收益的轻量 stage 名（供 debug 文案）。"""
+    m = _as_dict(meta)
+    if m is None:
+        return []
+    names: list[str] = []
+    stages = m.get("stages")
+    if not isinstance(stages, list):
+        return names
+    for stage in stages:
+        if not isinstance(stage, dict):
+            continue
+        name = stage.get("name")
+        if not isinstance(name, str):
+            continue
+        extra = _stage_extra(stage)
+        freed = _positive_number(stage.get("tokens_freed"))
+        micro = name == "microcompact" and bool(extra.get("microcompact_normalized"))
+        if freed or micro:
+            if name in _LIGHT_STAGE_NAMES or freed or micro:
+                names.append(name)
+    return names
+
+
+def extract_compaction_meta_from_chain_end_data(data: Any) -> Optional[dict[str, Any]]:
+    """从 on_chain_end data 取出 compaction_pipeline_meta。"""
+    if not isinstance(data, dict):
+        return None
+    output = data.get("output")
+    if not isinstance(output, dict):
+        return None
+    meta = output.get("compaction_pipeline_meta")
+    return meta if isinstance(meta, dict) else None

langchain_agentx/workflow/event_adapter/scope_resolver.py

@@ -3,8 +3,8 @@ scope_resolver.py — Workflow event adapter active scope 解析
 
 职责：
     - 根据 WorkflowStack.build_path() 从 flat scopes[path] registry 解析当前 active scope
-    - public orphan path miss 时 hard-fail
-    - internal 尾段 path miss 时 warn + registered ancestor 回退（A00 P-LOSSY / P-EXEC）
+    - miss 时按 D-SCOPE-A′ 降级到最近非 root / 非 workflow_root 已注册祖先
+    - 无非 root 祖先时 hard-fail（禁 blanket root）
 
 链路位置：
     - Layer 3: Workflow 事件适配器
@@ -14,18 +14,18 @@ scope_resolver.py — Workflow event adapter active scope 解析
     - 仅 dict lookup，不扫描 workflow 实例或 graph
     - scope key 与 WorkflowStack.build_path() / RuntimeScopePath.key() 一致
     - legacy config 无 scopes 时由 root 字段合成仅含 root 的 registry
-    - 禁止 blanket root 兜底；无 registered 祖先时仍 raise
+    - 禁止把 root 当 degrade 目标；与 SessionRouter 共享 nearest_degrade_ancestor
 """
 
 from __future__ import annotations
 
 import logging
+from collections.abc import Callable
 from typing import Any
 
 from langchain_agentx.workflow.runtime_scope_registry import resolve_effective_scopes
 from langchain_agentx.workflow.structure_errors import WorkflowScopeResolutionError
 
-from .depth_resolver import LANGGRAPH_INTERNAL_LOOP_NODE_NAMES
 from .stack import WorkflowStack
 
 logger = logging.getLogger(__name__)
@@ -34,9 +34,30 @@ _SCOPE_METADATA_FIELDS = frozenset(
     {"workflow_id", "scope_key", "scope_kind", "scope_origin", "graph_key"}
 )
 
+ScopeLookup = Callable[[str], dict[str, Any] | None]
 
-def _path_tail_segment(scope_key: str) -> str:
-    return scope_key.rsplit(">", 1)[-1]
+
+def nearest_degrade_ancestor(
+    path: str,
+    *,
+    root_scope: str,
+    lookup: ScopeLookup,
+) -> dict[str, Any] | None:
+    """沿 '>' 前缀向上；跳过 root_scope / workflow_root（D-SCOPE-A′ · 禁 blanket root）。"""
+    if ">" not in path:
+        return None
+    parts = path.split(">")
+    for depth in range(len(parts) - 1, 0, -1):
+        prefix = ">".join(parts[:depth])
+        if prefix == root_scope:
+            continue
+        entry = lookup(prefix)
+        if entry is None:
+            continue
+        if entry.get("scope_kind") == "workflow_root":
+            continue
+        return entry
+    return None
 
 
 class WorkflowScopeResolver:
@@ -51,6 +72,12 @@ class WorkflowScopeResolver:
             root_scope=self._root_scope,
         )
         self._scope_misses: list[str] = []
+        self._degrade_warned_paths: set[str] = set()
+
+    @property
+    def root_scope(self) -> str:
+        """开流 root_scope（SessionRouter 祖先 walk 唯一来源）。"""
+        return self._root_scope
 
     @property
     def scope_misses(self) -> tuple[str, ...]:
@@ -81,16 +108,13 @@ class WorkflowScopeResolver:
 
         self._record_scope_miss(scope_key)
 
-        if not self._is_internal_path_miss(scope_key):
-            raise self._build_scope_resolution_error(scope_key)
-
-        ancestor = self._nearest_registered_ancestor_entry()
+        ancestor = nearest_degrade_ancestor(
+            scope_key,
+            root_scope=self._root_scope,
+            lookup=self.scope_entry_at,
+        )
         if ancestor is not None:
-            logger.warning(
-                "workflow scope miss degraded to ancestor: path=%r ancestor=%r",
-                scope_key,
-                ancestor.get("scope_key"),
-            )
+            self._warn_degraded_once(scope_key, ancestor)
             return ancestor
 
         raise self._build_scope_resolution_error(scope_key)
@@ -103,22 +127,15 @@ class WorkflowScopeResolver:
             if key not in _SCOPE_METADATA_FIELDS
         }
 
-    def _is_internal_path_miss(self, scope_key: str) -> bool:
-        """miss path 末段为 internal loop 节点 → 视为 internal 误抬，可降级。"""
-        if ">" not in scope_key:
-            return False
-        return _path_tail_segment(scope_key) in LANGGRAPH_INTERNAL_LOOP_NODE_NAMES
-
-    def _nearest_registered_ancestor_entry(self) -> dict[str, Any] | None:
-        """沿 build_path() 的 '>' 分段前缀向上 walk，返回首个 scope_entry_at 命中。"""
-        scope_key = self.current_scope_key()
-        parts = scope_key.split(">")
-        for depth in range(len(parts) - 1, 0, -1):
-            prefix = ">".join(parts[:depth])
-            entry = self.scope_entry_at(prefix)
-            if entry is not None:
-                return entry
-        return None
+    def _warn_degraded_once(self, scope_key: str, ancestor: dict[str, Any]) -> None:
+        if scope_key in self._degrade_warned_paths:
+            return
+        self._degrade_warned_paths.add(scope_key)
+        logger.warning(
+            "workflow scope miss degraded to ancestor: path=%r ancestor=%r",
+            scope_key,
+            ancestor.get("scope_key"),
+        )
 
     def _build_scope_resolution_error(self, scope_key: str) -> WorkflowScopeResolutionError:
         detail_parts = [
@@ -144,4 +161,8 @@ class WorkflowScopeResolver:
         )
 
 
-__all__ = ["WorkflowScopeResolver", "WorkflowScopeResolutionError"]
+__all__ = [
+    "WorkflowScopeResolver",
+    "WorkflowScopeResolutionError",
+    "nearest_degrade_ancestor",
+]

langchain_agentx/workflow/event_adapter/session_router.py

@@ -13,6 +13,7 @@ session_router.py — Workflow 结构/agent 事件 session_id 路由
 当前裁剪范围：
     - 结构容器事件仍走 stack/path；agent/loop 事件优先无状态 resolve_loop_session_id_for_event
     - aggregate 使用 aggregate_key 作为 task_key，无 special case
+    - D-SCOPE-A-SESSION：ns path 精确 miss 时与 ScopeResolver 同 walk（排除 root）
 """
 
 from __future__ import annotations
@@ -20,7 +21,7 @@ from __future__ import annotations
 from typing import Any
 
 from .depth_resolver import DepthResolver
-from .scope_resolver import WorkflowScopeResolver
+from .scope_resolver import WorkflowScopeResolver, nearest_degrade_ancestor
 from .stack import WorkflowStack
 from .types import WorkflowEvent, WorkflowEventType
 
@@ -130,6 +131,12 @@ class WorkflowSessionRouter:
         scope_path = self._scope_path_from_raw_event(raw_event)
         if scope_path:
             entry = self._scope_resolver.scope_entry_at(scope_path)
+            if entry is None:
+                entry = nearest_degrade_ancestor(
+                    scope_path,
+                    root_scope=self._scope_resolver.root_scope,
+                    lookup=self._scope_resolver.scope_entry_at,
+                )
             if entry is not None:
                 return self._loop_session_from_scope_entry(
                     entry,

{langchain_agentx_python-2.2.0.dist-info → langchain_agentx_python-2.2.2.dist-info}/METADATA

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

{langchain_agentx_python-2.2.0.dist-info → langchain_agentx_python-2.2.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-langchain_agentx/__init__.py,sha256=_jWRBw5rNM52V1JxowuR91v-mVr2N_1x-Adhgz-4XrU,1614
+langchain_agentx/__init__.py,sha256=CeiwdY0JNT9SJDHhM5_WnrLFW0CaC3PjbVuO98Owi1o,1614
 langchain_agentx/command/__init__.py,sha256=Ej260S5uFQcmEtGZQG_NH7BYjHoStrpBLtGUsBTxyZk,631
 langchain_agentx/command/allowed_tools.py,sha256=TVA0VM8rm98H-QbLK_GRiX5RhEAZFxKawliMi4kk96A,3359
 langchain_agentx/command/context.py,sha256=DIGOGPBw5UGDBm0WNNJlKx1h_9rCRmcdROv4DT61Qug,731
@@ -217,8 +217,9 @@ langchain_agentx/observability/evaluation/checkers/tool_behavior.py,sha256=o1nH8
 langchain_agentx/observability/events/__init__.py,sha256=Zr9Iguf9XsJQLsCJy13YFdBtXHPEnI9aSWXWmA2MisA,1497
 langchain_agentx/observability/events/accumulated_text_scope.py,sha256=M4OvuQTgReF8SFrOmr-M5vyOJpzfvxj_DKD5bVpGb70,3169
 langchain_agentx/observability/events/agent_defaults.py,sha256=gmX0P__lux5xbCb8dtAlVCb3wZ7avaqFleoW4Q5anw4,1187
-langchain_agentx/observability/events/agent_event_projector.py,sha256=eMri832yK_BZbwsB_APwUN9vu66zMpZVxTstChG5l0A,63010
+langchain_agentx/observability/events/agent_event_projector.py,sha256=Rktmy2D3qizCejAChbuOiAa06Tnup2Z6cVNATfrrxkU,63995
 langchain_agentx/observability/events/api_retry_projection.py,sha256=XGb09sNOi6k1ZGW4YqMLBE8GDxNwNMprk62jV9TS9dQ,2433
+langchain_agentx/observability/events/compact_event_gate.py,sha256=50RJemwB1lnQn_NFWOFSgU418ZUR8dbd_v0538PT7zM,4751
 langchain_agentx/observability/events/factory.py,sha256=gqMATIK9tBQzaPWSPhCCSPuCq-WF562ZDTnFUaMm9Qc,1570
 langchain_agentx/observability/events/finish_event_payload_composer.py,sha256=v7MyLNSZ_gR5u5WFxPJu_0MYNDvC9s9gI2iNNt9Vbr4,13189
 langchain_agentx/observability/events/finish_outcome.py,sha256=igoueAwduzuuGDwg6u9AbBB-T2UBiqbUfNoxWCBYc_g,10401
@@ -724,8 +725,8 @@ langchain_agentx/workflow/validation.py,sha256=3I2jrSgOLAufe3kIzftE_Tfq0ZS-74bIx
 langchain_agentx/workflow/event_adapter/__init__.py,sha256=PkG6dP5mAjukYOFEtNFVDn00q_zPmS506dapZxpDgG8,1736
 langchain_agentx/workflow/event_adapter/adapter.py,sha256=eoOgcSos_cu12BRg3a4P0lQvarwr9jCcgt3OrC68A58,25188
 langchain_agentx/workflow/event_adapter/depth_resolver.py,sha256=1xI44dNk9cPotmk1Up14s0QV12WpkRPAQPYnVDY3ZlQ,3991
-langchain_agentx/workflow/event_adapter/scope_resolver.py,sha256=8KzflPIy0Y7PgX8xjgvEQD6_zzYEDL0oqxquhuA3wHA,5510
-langchain_agentx/workflow/event_adapter/session_router.py,sha256=0ih5_VxVb1_CWeUvz_qQIT14Mo0Oq7KZ22x1W__8hys,8915
+langchain_agentx/workflow/event_adapter/scope_resolver.py,sha256=J4duUIdMfNB87zq_0q2sGBgokg0t0UIaxlBGRYJEv7w,5813
+langchain_agentx/workflow/event_adapter/session_router.py,sha256=v2MZieOXDpcioeskSFswnXGKtT_Aw0M0sY9W3oCFmUY,9292
 langchain_agentx/workflow/event_adapter/stack.py,sha256=VCpJekxlGOg0CU2Unxcq7-TeyAHUajPyakKoGnUlT7g,4396
 langchain_agentx/workflow/event_adapter/structure_lifecycle_guard.py,sha256=0inUI-fw-xgWQHuGVVoWRM3a_gpys9JgvOxG5P4bTdw,6658
 langchain_agentx/workflow/event_adapter/structure_utils.py,sha256=y2gS-Tj9FajAqP8kgygaxrosVIRYNjhEtpnp-OIccB8,2820
@@ -759,8 +760,8 @@ langchain_agentx/workspace/root_grant_manager.py,sha256=W3gy8HTevbERbXqIgRcjzOXO
 langchain_agentx/workspace/tool_boundary.py,sha256=UDwX6swpSLsx9HNkYuuRRiV5o7ZZG_Bru2Yn0c5kNX8,5724
 langchain_agentx/workspace/validators.py,sha256=tQt-6TOcL8Fw7Ig5ebA9S7vGWh1rby920eFW6x8Tk9E,1439
 langchain_agentx/workspace/view.py,sha256=PGasqTaqhlD03SXXazHuw4RHfV681AIdlsYqL70pEjc,4774
-langchain_agentx_python-2.2.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-langchain_agentx_python-2.2.0.dist-info/METADATA,sha256=nn2x47UdjwxReSgREvpk012hKVMAXtw303b9JRhUdAM,24250
-langchain_agentx_python-2.2.0.dist-info/WHEEL,sha256=51RkbunBAw4BWsgaQWTpPhg4Diwp3c9P5iaLk67Hdtg,92
-langchain_agentx_python-2.2.0.dist-info/top_level.txt,sha256=Ge284pniNt8xea0OLk2o9o32GqVpDhOYk20fwE-0xxA,17
-langchain_agentx_python-2.2.0.dist-info/RECORD,,
+langchain_agentx_python-2.2.2.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+langchain_agentx_python-2.2.2.dist-info/METADATA,sha256=YHgIChmc4fVyfDcUNs9faXXrRAdOrZ8CF3db6Wnw-JY,24250
+langchain_agentx_python-2.2.2.dist-info/WHEEL,sha256=51RkbunBAw4BWsgaQWTpPhg4Diwp3c9P5iaLk67Hdtg,92
+langchain_agentx_python-2.2.2.dist-info/top_level.txt,sha256=Ge284pniNt8xea0OLk2o9o32GqVpDhOYk20fwE-0xxA,17
+langchain_agentx_python-2.2.2.dist-info/RECORD,,