langchain-agentx-python 1.0.4__tar.gz → 1.0.5__tar.gz

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/PKG-INFO

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

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/context/__init__.py

@@ -3,6 +3,12 @@
 from __future__ import annotations
 
 from .blocking_guard import CompactionBlockingGuard, default_compaction_blocking_guard
+from .query_source import (
+    LoopCompilationContext,
+    QuerySource,
+    QuerySourcePolicy,
+    default_query_source_policy,
+)
 from .compaction_service import LoopContextCompaction, default_loop_context_compaction
 from .pipeline import ContextPipeline, DefaultCompactionStages
 from .settings import (
@@ -59,8 +65,12 @@ __all__ = [
     "get_compact_prompt",
     "get_compact_user_summary_message",
     "get_partial_compact_prompt",
+    "LoopCompilationContext",
     "LoopContextCompaction",
     "MicrocompactStage",
+    "QuerySource",
+    "QuerySourcePolicy",
+    "default_query_source_policy",
     "set_active_compaction_settings",
     "SnipCompactStage",
     "StageResult",

langchain-agentx-python-1.0.5/langchain_agentx/loop/context/query_source.py

@@ -0,0 +1,185 @@
+"""
+query_source.py — Query Source 单一来源与 Loop 守卫策略
+
+职责：
+    定义所有 query_source 官方常量，并提供 autocompact / microcompact /
+    token_blocking / persist_replacements 的统一跳过判定。
+
+链路位置：
+    ForkedAgentRunner / Loop 编译 → QuerySourcePolicy.compile_loop_context()
+    → ContextCompactionContext / CompactionSettings / model_node 守卫。
+
+当前裁剪范围：
+    不实现 fork 执行与 Coordinator 触发；仅提供常量与策略判定基座。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, FrozenSet, Literal
+
+CompactionGuardStage = Literal[
+    "autocompact",
+    "microcompact",
+    "token_blocking",
+    "persist_replacements",
+]
+
+EmitterRoute = Literal["main", "sidechain", "drop"]
+
+
+class QuerySource:
+    """官方 query_source 常量（禁止在业务代码散落字面量）。"""
+
+    MAIN_THREAD: Final[str] = "main_thread"
+    EXTRACT_MEMORIES: Final[str] = "extract_memories"
+    SESSION_MEMORY: Final[str] = "session_memory"
+    COMPACT: Final[str] = "compact"
+    AGENT_SUMMARY: Final[str] = "agent_summary"
+    AGENT_PREFIX: Final[str] = "agent:"
+
+    @classmethod
+    def all_official(cls) -> FrozenSet[str]:
+        return frozenset(
+            {
+                cls.MAIN_THREAD,
+                cls.EXTRACT_MEMORIES,
+                cls.SESSION_MEMORY,
+                cls.COMPACT,
+                cls.AGENT_SUMMARY,
+            }
+        )
+
+    @classmethod
+    def is_agent_subagent(cls, query_source: str | None) -> bool:
+        return isinstance(query_source, str) and query_source.startswith(cls.AGENT_PREFIX)
+
+    @classmethod
+    def normalize(cls, query_source: str | None) -> str:
+        if isinstance(query_source, str) and query_source.strip():
+            return query_source.strip()
+        return cls.MAIN_THREAD
+
+
+# 后台 fork 任务：跳过 autocompact / microcompact
+_BACKGROUND_COMPACTION_SKIP: Final[FrozenSet[str]] = frozenset(
+    {
+        QuerySource.EXTRACT_MEMORIES,
+        QuerySource.SESSION_MEMORY,
+        QuerySource.COMPACT,
+        QuerySource.AGENT_SUMMARY,
+    }
+)
+
+# token_blocking 跳过（agent_summary 仍启用）
+_TOKEN_BLOCKING_SKIP: Final[FrozenSet[str]] = frozenset(
+    {
+        QuerySource.EXTRACT_MEMORIES,
+        QuerySource.SESSION_MEMORY,
+        QuerySource.COMPACT,
+    }
+)
+
+
+@dataclass(frozen=True)
+class LoopCompilationContext:
+    """子 Loop 编译时的 query_source 守卫快照。"""
+
+    query_source: str
+    skip_autocompact: bool
+    skip_microcompact: bool
+    skip_token_blocking: bool
+    persist_replacements: bool
+
+    @property
+    def skip_compaction_stages(self) -> bool:
+        return self.skip_autocompact or self.skip_microcompact
+
+
+class QuerySourcePolicy:
+    """query_source 守卫策略（单一来源）。"""
+
+    @staticmethod
+    def microcompact_skip_sources() -> FrozenSet[str]:
+        return _BACKGROUND_COMPACTION_SKIP
+
+    @staticmethod
+    def autocompact_skip_sources() -> FrozenSet[str]:
+        return _BACKGROUND_COMPACTION_SKIP
+
+    @staticmethod
+    def token_blocking_skip_sources() -> FrozenSet[str]:
+        return _TOKEN_BLOCKING_SKIP
+
+    @staticmethod
+    def should_persist_replacements(query_source: str | None) -> bool:
+        normalized = QuerySource.normalize(query_source)
+        if QuerySource.is_agent_subagent(normalized):
+            return True
+        return normalized == QuerySource.MAIN_THREAD
+
+    @classmethod
+    def should_skip(cls, stage: CompactionGuardStage, query_source: str | None) -> bool:
+        normalized = QuerySource.normalize(query_source)
+        if stage == "autocompact":
+            return normalized in cls.autocompact_skip_sources()
+        if stage == "microcompact":
+            return normalized in cls.microcompact_skip_sources()
+        if stage == "token_blocking":
+            return normalized in cls.token_blocking_skip_sources()
+        if stage == "persist_replacements":
+            return not cls.should_persist_replacements(normalized)
+        raise ValueError(f"unknown compaction guard stage: {stage}")
+
+    @classmethod
+    def compile_loop_context(cls, query_source: str | None) -> LoopCompilationContext:
+        normalized = QuerySource.normalize(query_source)
+        return LoopCompilationContext(
+            query_source=normalized,
+            skip_autocompact=cls.should_skip("autocompact", normalized),
+            skip_microcompact=cls.should_skip("microcompact", normalized),
+            skip_token_blocking=cls.should_skip("token_blocking", normalized),
+            persist_replacements=cls.should_persist_replacements(normalized),
+        )
+
+    @classmethod
+    def default_ui_visible(cls, query_source: str | None) -> bool:
+        normalized = QuerySource.normalize(query_source)
+        if normalized == QuerySource.MAIN_THREAD:
+            return True
+        if QuerySource.is_agent_subagent(normalized):
+            return True
+        return False
+
+    @classmethod
+    def resolve_emitter_route(
+        cls,
+        *,
+        query_source: str | None,
+        skip_transcript: bool,
+    ) -> EmitterRoute:
+        if skip_transcript:
+            return "drop"
+        if cls.default_ui_visible(query_source):
+            return "main"
+        return "sidechain"
+
+
+_default_policy: QuerySourcePolicy | None = None
+
+
+def default_query_source_policy() -> QuerySourcePolicy:
+    global _default_policy
+    if _default_policy is None:
+        _default_policy = QuerySourcePolicy()
+    return _default_policy
+
+
+__all__ = [
+    "CompactionGuardStage",
+    "EmitterRoute",
+    "LoopCompilationContext",
+    "QuerySource",
+    "QuerySourcePolicy",
+    "default_query_source_policy",
+]

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/context/settings.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
 from typing import FrozenSet
 
 from ..prompt.compact import AutocompactLlmPromptKind
+from .query_source import QuerySourcePolicy
 
 
 @dataclass(frozen=True)
@@ -52,13 +53,13 @@ class CompactionSettings:
     snip_suffix: str = field(default="\n\n[... snipped by snip_compact ...]")
     # --- microcompact（轻量规范化；递归压缩时跳过）---
     microcompact_skip_query_sources: FrozenSet[str] = field(
-        default_factory=lambda: frozenset({"compact"})
+        default_factory=QuerySourcePolicy.microcompact_skip_sources
     )
     # --- context_collapse（重复 tool 结果治理）---
     collapse_dedupe_consecutive_same_tool_call_id: bool = True
     # --- autocompact（阈值触发；产品与 CC 对齐默认走 LLM 摘要，无 model 时回退 prune）---
     autocompact_skip_query_sources: FrozenSet[str] = field(
-        default_factory=lambda: frozenset({"compact"})
+        default_factory=QuerySourcePolicy.autocompact_skip_sources
     )
     autocompact_use_llm_when_available: bool = True
     autocompact_llm_excerpt_chars_per_message: int = 20_000

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/graph/factory.py

@@ -95,6 +95,8 @@ from ...memory.memdir.agent_memory import (
 )
 from ...memory.memdir.runtime import MemoryPromptBootstrap
 from ...memory.memdir.extractor import MemoryExtractionCoordinator
+from ...memory.memdir.paths import is_memory_enabled
+from ..hook.post_sample_hook import PostSampleHook
 # Session memory imports use lazy imports to avoid circular dependency
 # SessionMemoryCompactBridge uses lazy import to avoid circular dependency with memory.session.session_memory
 from ..prompt import SystemPromptSection, build_effective_system_prompt
@@ -547,16 +549,22 @@ class LoopGraphBuilder:
             trust_checker=trust_checker,
         )
         container_type = self._config.container_type or "agent_session"
+        memory_extractor = self._build_memory_extraction_coordinator(
+            model=model,
+            session_store=session_store,
+            session_id=session_id or "",
+        )
         self._hook_graph_wiring = HookGraphWiring(
             hook_engine,
             trace_lifecycle_collector=trace_lifecycle_collector,
             session_memory=self._session_memory_manager,
-            memory_extractor=MemoryExtractionCoordinator(),
+            memory_extractor=memory_extractor,
             agent_memory_extractor=get_default_agent_memory_extraction_coordinator(),
             workspace_cfg=self._workspace_cfg,
             session_id=session_id or "",
             container_type=container_type,
             subagent_type=self._config.subagent.subagent_type,
+            post_sample_hook=PostSampleHook(memory_extractor=memory_extractor),
         )
         if self._config.trace.enabled:
             self._trace_callback_handler = TraceCallbackHandler(
@@ -650,6 +658,48 @@ class LoopGraphBuilder:
                 if self._skill_runtime_tool is None and rt.__class__.__name__ == "SkillRuntimeTool":
                     self._skill_runtime_tool = rt
 
+    def _build_memory_extraction_coordinator(
+        self,
+        *,
+        model: Any,
+        session_store: Any,
+        session_id: str,
+    ) -> MemoryExtractionCoordinator:
+        from ..subagent.context import ForkedParentRuntime
+        from ..subagent.forked_runner import ForkedAgentRunner
+
+        if (
+            self._is_subagent
+            or not is_memory_enabled(self._workspace_cfg)
+            or self._services.loader is None
+            or self._loop_loader is None
+        ):
+            return MemoryExtractionCoordinator()
+        runtime_cwd = str(self._config.workspace.runtime_cwd or self._workspace_root)
+        parent_runtime = ForkedParentRuntime(
+            session_store=session_store,
+            tool_registry=self._loop_loader.registry,
+            tool_loader=self._services.loader,
+            model=model,
+            workspace_root=str(self._workspace_root),
+            agent_home_segment=self._workspace_cfg.agent_home_segment,
+            parent_run_id=session_id or None,
+            parent_conversation_session_id=session_id or None,
+            system_prompt=self._base_prompt,
+            capabilities=self._services.capabilities,
+            cwd=runtime_cwd,
+        )
+        from ...memory.memdir.metrics import default_memory_fork_metrics
+
+        metrics = default_memory_fork_metrics()
+        return MemoryExtractionCoordinator(
+            forked_runner=ForkedAgentRunner(
+                parent_runtime=parent_runtime,
+                metrics=metrics,
+            ),
+            metrics=metrics,
+        )
+
     def _resolve_workspace_config(self) -> None:
         raw_workspace_root = self._config.workspace.workspace_root
         if raw_workspace_root is None:

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/hook/graph_wiring.py

@@ -1,5 +1,5 @@
 """
-graph_wiring.py — Hook 与 Loop 图装配协作者（Phase 2）。
+graph_wiring.py — Hook 与 Loop 图装配协作者。
 
 职责：
     封装 Hook 节点工厂与最小接线路径，避免 factory.py 继续膨胀。
@@ -8,7 +8,7 @@ graph_wiring.py — Hook 与 Loop 图装配协作者（Phase 2）。
     由 loop/graph/factory.py 在构图阶段调用，产出 loop_start / stop_hooks 节点。
 
 当前裁剪范围：
-    Phase 2 仅接入 `loop_start` 与 `stop_hooks` 主路径；before/after/loop_end 节点先提供工厂占位。
+    Phase 4：after_model 注入 PostSampleHook；stop_hooks 兜底触发 + drain。
 """
 
 from __future__ import annotations
@@ -20,6 +20,7 @@ from uuid import uuid4
 from .async_hook_runner import AsyncHookRunner
 from .engine import HookEngine
 from .hook_projection import derive_hook_outcome, hook_result_to_event_dict
+from .post_sample_hook import PostSampleHook
 from .types import AggregatedHookResult, HookContext, HookEvent
 
 
@@ -46,6 +47,7 @@ class HookGraphWiring:
     container_type: str = "interactive"
     subagent_type: str | None = None
     hook_runner: AsyncHookRunner = field(default_factory=AsyncHookRunner)
+    post_sample_hook: PostSampleHook | None = None
 
     def loop_start_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
         run_id = state.get("_run_id")
@@ -87,6 +89,13 @@ class HookGraphWiring:
                 patch.update(dict(result.state_patch))
         if self.session_memory is not None:
             self.session_memory.maybe_trigger(state)
+        if self.post_sample_hook is not None:
+            self.post_sample_hook.fire_and_forget(
+                state=state,
+                workspace_cfg=self.workspace_cfg,
+                session_id=self.session_id or str(state.get("_session_id") or ""),
+                container_type=self.container_type,
+            )
         if self.trace_lifecycle_collector is not None:
             patch.update(self.trace_lifecycle_collector.after_model_node(state))
         return patch
@@ -106,7 +115,11 @@ class HookGraphWiring:
                 workspace_cfg=self.workspace_cfg,
                 session_id=self.session_id or str(state.get("_session_id") or ""),
                 container_type=self.container_type,
+                force=True,
             )
+            drain = getattr(self.memory_extractor, "drain_on_stop", None)
+            if callable(drain):
+                drain()
         if self.agent_memory_extractor is not None and self.workspace_cfg is not None:
             self.agent_memory_extractor.trigger_from_state(
                 state=state,

langchain-agentx-python-1.0.5/langchain_agentx/loop/hook/post_sample_hook.py

@@ -0,0 +1,52 @@
+"""
+post_sample_hook.py — after_model 非阻塞 post-sampling 挂钩。
+
+职责：
+    对齐 CC executePostSamplingHooks：fire-and-forget 委托 Coordinator.trigger_after_sample()。
+
+链路位置：
+    HookGraphWiring.after_model_node() → PostSampleHook.fire_and_forget()。
+
+当前裁剪范围：
+    仅接入 memdir 记忆抽取；session_memory 仍由 SessionMemoryManager.maybe_trigger 处理。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class PostSampleHook:
+    """after_model 后台任务触发器（非阻塞）。"""
+
+    def __init__(self, memory_extractor: Any | None = None) -> None:
+        self._memory_extractor = memory_extractor
+
+    def fire_and_forget(
+        self,
+        *,
+        state: dict[str, Any],
+        workspace_cfg: Any,
+        session_id: str,
+        container_type: str,
+    ) -> None:
+        if self._memory_extractor is None or workspace_cfg is None:
+            return
+        trigger = getattr(self._memory_extractor, "trigger_after_sample", None)
+        if not callable(trigger):
+            return
+        try:
+            trigger(
+                state=state,
+                workspace_cfg=workspace_cfg,
+                session_id=session_id,
+                container_type=container_type,
+            )
+        except Exception as exc:
+            logger.warning("post_sample memory hook failed: %s", exc)
+
+
+__all__ = ["PostSampleHook"]

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/model/model_node.py

@@ -167,15 +167,19 @@ def _model_response_if_context_token_blocked(
     initial_response_format: ResponseFormat[Any] | None,
     structured_output_tools: Dict[str, Any],
     compaction_settings: CompactionSettings | None,
+    query_source: str | None = None,
 ) -> Any | None:
     """若主上下文启发式已超过 CompactionSettings 顶线，返回合成 ModelResponse，否则 None。"""
     from langchain_agentx.loop.context.blocking_guard import CompactionBlockingGuard
+    from langchain_agentx.loop.context.query_source import QuerySourcePolicy
     from langchain_agentx.loop.context.types import ContextCompactionContext
     from langchain.agents.middleware.types import ModelResponse as _ModelResponse
 
     s = compaction_settings or get_active_compaction_settings()
     if not s.enable_main_model_context_token_block:
         return None
+    if QuerySourcePolicy.should_skip("token_blocking", query_source):
+        return None
     guard = CompactionBlockingGuard(settings=s)
     est = guard.estimate_messages_tokens(state_messages)
     if not guard.should_block(ContextCompactionContext(), estimated_tokens=est):
@@ -318,6 +322,9 @@ class ModelNode(Runnable):
             initial_response_format=self._initial_response_format,
             structured_output_tools=self._structured_output_tools,
             compaction_settings=self._compaction_settings,
+            query_source=state.get("query_source")
+            if isinstance(state.get("query_source"), str)
+            else None,
         )
         if synth is not None:
             model_response = synth
@@ -341,6 +348,9 @@ class ModelNode(Runnable):
             initial_response_format=self._initial_response_format,
             structured_output_tools=self._structured_output_tools,
             compaction_settings=self._compaction_settings,
+            query_source=state.get("query_source")
+            if isinstance(state.get("query_source"), str)
+            else None,
         )
         if synth is not None:
             model_response = synth

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/model/model_nodes.py

@@ -108,15 +108,19 @@ def _model_response_if_context_token_blocked(
     initial_response_format: ResponseFormat[Any] | None,
     structured_output_tools: Dict[str, Any],
     compaction_settings: CompactionSettings | None,
+    query_source: str | None = None,
 ) -> Any | None:
     """若主上下文启发式已超过 `CompactionSettings` 顶线，返回合成 `ModelResponse`，否则 None。"""
     from langchain_agentx.loop.context.blocking_guard import CompactionBlockingGuard
+    from langchain_agentx.loop.context.query_source import QuerySourcePolicy
     from langchain_agentx.loop.context.types import ContextCompactionContext
     from langchain.agents.middleware.types import ModelResponse as _ModelResponse
 
     s = compaction_settings or get_active_compaction_settings()
     if not s.enable_main_model_context_token_block:
         return None
+    if QuerySourcePolicy.should_skip("token_blocking", query_source):
+        return None
     guard = CompactionBlockingGuard(settings=s)
     est = guard.estimate_messages_tokens(state_messages)
     if not guard.should_block(ContextCompactionContext(), estimated_tokens=est):
@@ -371,6 +375,9 @@ class _ModelNodeBuilder:
             initial_response_format=self._initial_response_format,
             structured_output_tools=self._structured_output_tools,
             compaction_settings=self._compaction_settings,
+            query_source=state.get("query_source")
+            if isinstance(state.get("query_source"), str)
+            else None,
         )
         if synth is not None:
             return synth, []
@@ -420,6 +427,9 @@ class _ModelNodeBuilder:
             initial_response_format=self._initial_response_format,
             structured_output_tools=self._structured_output_tools,
             compaction_settings=self._compaction_settings,
+            query_source=state.get("query_source")
+            if isinstance(state.get("query_source"), str)
+            else None,
         )
         if synth is not None:
             return synth, []

{langchain-agentx-python-1.0.4 → langchain-agentx-python-1.0.5}/langchain_agentx/loop/runtime/subagent_execution_paths.py

@@ -24,6 +24,30 @@ from langchain_agentx.loop.runtime.context import SubagentContextOverrides
 from langchain_agentx.workspace import resolve_agent_state_config
 
 
+def resolve_subagent_workspace_root(parent_ctx: Any, *, context: str = "subagent") -> str:
+    """解析父上下文 workspace_root；禁止回退进程 cwd。"""
+    workspace_root = str(getattr(parent_ctx, "workspace_root", None) or "").strip()
+    if not workspace_root:
+        raise ValueError(
+            f"parent workspace_root is required for {context} path resolution; "
+            "supply AgentWorkspaceConfig.workspace_root, not os.getcwd()"
+        )
+    return workspace_root
+
+
+def resolve_subagent_effective_cwd(
+    *,
+    override_cwd: str | None,
+    parent_cwd: str | None,
+    workspace_root: str,
+) -> str:
+    """解析子代理 effective_cwd；最终回退 workspace_root，不回退进程 cwd。"""
+    for candidate in (override_cwd, parent_cwd):
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return workspace_root
+
+
 @dataclass(frozen=True)
 class PreparedSubagentPaths:
     """``SubagentExecutionPaths.prepare`` 的输出：最终 cwd 与可选 worktree 目录。"""
@@ -46,7 +70,7 @@ class SubagentExecutionPaths:
         顺序对齐 CC：**显式 ``overrides.cwd`` 优先于 worktree 目录**（``cwd ?? worktreePath``）。
         """
         parent_cwd = getattr(parent_ctx, "cwd", None)
-        parent_workspace_root = getattr(parent_ctx, "workspace_root", None) or os.getcwd()
+        parent_workspace_root = resolve_subagent_workspace_root(parent_ctx)
         # P0-1 修复：从 agent_home 改为 agent_home_segment（对齐 ToolExecutionContext / SubagentContext 正式字段名）
         parent_agent_home = getattr(parent_ctx, "agent_home_segment", ".langchain_agentx")
         raw = overrides.cwd
@@ -65,5 +89,9 @@ class SubagentExecutionPaths:
             effective = override_cwd or worktree_dir
             return PreparedSubagentPaths(effective_cwd=effective, worktree_dir=worktree_dir)
 
-        base = override_cwd or parent_cwd or os.getcwd()
+        base = resolve_subagent_effective_cwd(
+            override_cwd=override_cwd,
+            parent_cwd=parent_cwd if isinstance(parent_cwd, str) else None,
+            workspace_root=parent_workspace_root,
+        )
         return PreparedSubagentPaths(effective_cwd=base, worktree_dir=None)