langchain-agentx-python 2.3.3__py3-none-any.whl → 2.3.5__py3-none-any.whl

langchain_agentx/__init__.py

@@ -1,64 +1,75 @@
-"""
-LangChain-based agent utilities for CodeBaseX.
-
-This package provides:
-- LangChain-AgentX LangGraph agent factory (`loop`)
-
-Typical usage:
-
-```python
-from langchain_agentx import create_loop_agent
-```
-"""
-
-__version__ = "2.3.3"
-
-from .loop import (  # noqa: F401
-    create_loop_agent,
-)
-
-from .loop.hook import (  # noqa: F401
-    ATTACHMENT_HOOK_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_CANCELLED,
-    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
-    ATTACHMENT_HOOK_SUCCESS,
-)
-from .observability import (  # noqa: F401
-    EventAdapterState,
-    LangchainAgentEvent,
-    LangchainAgentEventType,
-    LangGraphToLangchainAgentEventAdapter,
-    TraceCollector,
-    TraceSession,
-    TraceSpan,
-)
-from .provider import CompatibleChatOpenAI  # noqa: F401
-from .session import AgentSession, create_agent_session  # noqa: F401
-from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
-from .workflow import BaseWorkflow  # noqa: F401
-
-__all__ = [
-    "ATTACHMENT_HOOK_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_CANCELLED",
-    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
-    "ATTACHMENT_HOOK_SUCCESS",
-    "create_loop_agent",
-    "create_agent_session",
-    "AgentSession",
-    "BaseWorkflow",
-    "EventAdapterState",
-    "LangchainAgentEvent",
-    "LangchainAgentEventType",
-    "LangGraphToLangchainAgentEventAdapter",
-    "TraceCollector",
-    "TraceSession",
-    "TraceSpan",
-    "CompatibleChatOpenAI",
-    "HealthCheck",
-    "HealthReport",
-    "PreflightResult",
-    "preflight",
-    "sdk_health",
-]
+"""
+LangChain-based agent utilities for CodeBaseX.
+
+This package provides:
+- LangChain-AgentX LangGraph agent factory (`loop`)
+
+Typical usage:
+
+```python
+from langchain_agentx import create_loop_agent
+```
+"""
+
+__version__ = "2.3.5"
+
+from .mcp.call import McpToolCaller
+from .mcp.client_manager import McpClientManager, McpConnectedClient
+from .mcp.controller import McpRuntimeController
+from .mcp.config.resolver import McpConfigResolver
+from .mcp.events import CollectingEventSink
+from .loop import (  # noqa: F401
+    create_loop_agent,
+)
+
+from .loop.hook import (  # noqa: F401
+    ATTACHMENT_HOOK_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_CANCELLED,
+    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
+    ATTACHMENT_HOOK_SUCCESS,
+)
+from .observability import (  # noqa: F401
+    EventAdapterState,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+    LangGraphToLangchainAgentEventAdapter,
+    TraceCollector,
+    TraceSession,
+    TraceSpan,
+)
+from .provider import CompatibleChatOpenAI  # noqa: F401
+from .session import AgentSession, create_agent_session  # noqa: F401
+from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
+from .workflow import BaseWorkflow  # noqa: F401
+
+__all__ = [
+    "ATTACHMENT_HOOK_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_CANCELLED",
+    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
+    "ATTACHMENT_HOOK_SUCCESS",
+    "create_loop_agent",
+    "create_agent_session",
+    "AgentSession",
+    "CollectingEventSink",
+    "McpClientManager",
+    "McpConfigResolver",
+    "McpConnectedClient",
+    "McpRuntimeController",
+    "McpToolCaller",
+    "BaseWorkflow",
+    "EventAdapterState",
+    "LangchainAgentEvent",
+    "LangchainAgentEventType",
+    "LangGraphToLangchainAgentEventAdapter",
+    "TraceCollector",
+    "TraceSession",
+    "TraceSpan",
+    "CompatibleChatOpenAI",
+    "HealthCheck",
+    "HealthReport",
+    "PreflightResult",
+    "preflight",
+    "sdk_health",
+]

langchain_agentx/command/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""command/mcp — MCP prompts → CommandDefinition 适配。"""
+
+from langchain_agentx.command.mcp.adapter import McpPromptCommandAdapter
+
+__all__ = ["McpPromptCommandAdapter"]

langchain_agentx/command/mcp/adapter.py

@@ -0,0 +1,60 @@
+"""MCP prompts/list → CommandDefinition。
+
+职责：
+    对标 CC ``fetchCommandsForClient``：已连接 session 上 prompts/list，
+    映射 ``command_type=prompt``、``source=mcp``、名 ``mcp__{server}__{prompt}``。
+
+链路位置：
+    McpClientManager.list_prompts(connect=False) → 本适配器 → CommandRegistry.register_many。
+
+当前裁剪：
+    不 connect / 不 ensure；slash UX 由宿主投影；不扩展 CommandType。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from langchain_agentx.command.result import CommandResult
+from langchain_agentx.command.types import CommandDefinition
+from langchain_agentx.protocol.mcp.naming import build_mcp_tool_name
+from langchain_agentx.protocol.mcp.types import McpPromptRef
+
+if TYPE_CHECKING:
+    from langchain_agentx.command.context import CommandContext
+    from langchain_agentx.mcp.client_manager import McpClientManager
+
+
+class McpPromptCommandAdapter:
+    """已连接 Manager 上的 prompts 适配；禁止在此拉起 session。"""
+
+    def __init__(self, manager: McpClientManager) -> None:
+        self._manager = manager
+
+    async def list_definitions(self) -> list[CommandDefinition]:
+        definitions: list[CommandDefinition] = []
+        for spec in self._manager.connected_specs():
+            refs = await self._manager.list_prompts(spec.name, connect=False)
+            for ref in refs:
+                definitions.append(self._to_definition(ref))
+        return definitions
+
+    def _to_definition(self, ref: McpPromptRef) -> CommandDefinition:
+        return CommandDefinition(
+            name=build_mcp_tool_name(ref.server_name, ref.name),
+            description=ref.description,
+            command_type="prompt",
+            source="mcp",
+            handler=self._make_handler(ref),
+        )
+
+    def _make_handler(self, ref: McpPromptRef):
+        manager = self._manager
+
+        async def _handler(context: CommandContext) -> CommandResult:
+            _ = context
+            messages = await manager.get_prompt(ref.server_name, ref.name, connect=False)
+            text = "\n\n".join(messages.messages)
+            return CommandResult(should_query=True, injected_prompt=text)
+
+        return _handler

langchain_agentx/command/prompt_shell.py

@@ -1,123 +1,123 @@
-"""
-command/prompt_shell.py — Prompt 内嵌 shell 命令执行（CC executeShellCommandsInPrompt 对齐）。
-
-职责：
-    解析并执行 prompt 中的 !`command` 占位，将输出内联替换；执行前走路由权限检查。
-
-链路位置：
-    由 command/builtin/commit* 在展开 prompt 前调用。
-"""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Callable, Sequence
-from pathlib import Path
-from typing import Protocol
-
-from langchain_agentx.tool_runtime.models import ToolExecutionContext
-from langchain_agentx.tool_runtime.permission_context import set_command_bash_allow_rules
-from langchain_agentx.tool_runtime.session_store import AgentSessionStore
-from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
-
-_INLINE_PATTERN = re.compile(r"!`([^`]+)`")
-
-
-class PromptShellPermissionError(RuntimeError):
-    """prompt 内嵌 shell 命令未通过 Bash 权限检查。"""
-
-
-class _ShellRunner(Protocol):
-    def run_text(
-        self,
-        argv: list[str],
-        *,
-        cwd: str | Path | None = None,
-        timeout_sec: float | None = None,
-    ) -> tuple[int, str, str]: ...
-
-
-def _default_runner_call(
-    runner: TextSubprocessRunner,
-    command: str,
-    *,
-    cwd: str | Path | None,
-) -> tuple[int, str, str]:
-    completed = runner.run(
-        ["bash", "-lc", command],
-        cwd=cwd,
-        timeout=30.0,
-        capture_output=True,
-    )
-    stdout = completed.stdout or ""
-    stderr = completed.stderr or ""
-    if completed.returncode != 0 and not stdout.strip():
-        return completed.returncode, "", stderr.strip() or f"exit {completed.returncode}"
-    return completed.returncode, stdout, stderr
-
-
-def _assert_prompt_shell_permission(
-    command: str,
-    *,
-    bash_allow_rules: Sequence[str] | None,
-    cwd: str | Path | None,
-) -> None:
-    from langchain_agentx.tools.bash.tool import BashRuntimeTool
-
-    store = AgentSessionStore("prompt-shell")
-    if bash_allow_rules:
-        set_command_bash_allow_rules(store, bash_allow_rules)
-    workspace_root = str(cwd) if cwd is not None else None
-    ctx = ToolExecutionContext(
-        tool_name="Bash",
-        tool_call_id="prompt-shell",
-        input_args={"command": command},
-        state={},
-        session_store=store,
-        workspace_root=workspace_root,
-        cwd=workspace_root,
-    )
-    l1 = BashRuntimeTool().run_l1_permission_check({"command": command}, ctx)
-    if l1.outcome == "deny":
-        message = (l1.decision.message if l1.decision else None) or "Permission denied"
-        raise PromptShellPermissionError(
-            f'Shell command permission check failed for "!`{command}`": {message}',
-        )
-
-
-async def execute_shell_commands_in_prompt(
-    text: str,
-    *,
-    cwd: str | Path | None = None,
-    runner: TextSubprocessRunner | None = None,
-    shell_runner: Callable[[str], tuple[int, str, str]] | None = None,
-    bash_allow_rules: Sequence[str] | None = None,
-    check_permissions: bool = True,
-) -> str:
-    """将 text 中所有 !`command` 替换为命令 stdout（失败时内联 stderr/exit）。"""
-    if "!`" not in text:
-        return text
-
-    text_runner = runner or default_text_subprocess_runner()
-    result = text
-
-    for match in list(_INLINE_PATTERN.finditer(text)):
-        command = match.group(1).strip()
-        if not command:
-            continue
-        if check_permissions and shell_runner is None:
-            _assert_prompt_shell_permission(
-                command,
-                bash_allow_rules=bash_allow_rules,
-                cwd=cwd,
-            )
-        if shell_runner is not None:
-            _code, stdout, stderr = shell_runner(command)
-        else:
-            _code, stdout, stderr = _default_runner_call(text_runner, command, cwd=cwd)
-        replacement = stdout.strip() if stdout.strip() else stderr.strip()
-        if not replacement:
-            replacement = "(no output)"
-        result = result.replace(match.group(0), replacement, 1)
-
-    return result
+"""
+command/prompt_shell.py — Prompt 内嵌 shell 命令执行（CC executeShellCommandsInPrompt 对齐）。
+
+职责：
+    解析并执行 prompt 中的 !`command` 占位，将输出内联替换；执行前走路由权限检查。
+
+链路位置：
+    由 command/builtin/commit* 在展开 prompt 前调用。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Protocol
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext
+from langchain_agentx.tool_runtime.permission_context import set_command_bash_allow_rules
+from langchain_agentx.tool_runtime.session_store import AgentSessionStore
+from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
+
+_INLINE_PATTERN = re.compile(r"!`([^`]+)`")
+
+
+class PromptShellPermissionError(RuntimeError):
+    """prompt 内嵌 shell 命令未通过 Bash 权限检查。"""
+
+
+class _ShellRunner(Protocol):
+    def run_text(
+        self,
+        argv: list[str],
+        *,
+        cwd: str | Path | None = None,
+        timeout_sec: float | None = None,
+    ) -> tuple[int, str, str]: ...
+
+
+def _default_runner_call(
+    runner: TextSubprocessRunner,
+    command: str,
+    *,
+    cwd: str | Path | None,
+) -> tuple[int, str, str]:
+    completed = runner.run(
+        ["bash", "-lc", command],
+        cwd=cwd,
+        timeout=30.0,
+        capture_output=True,
+    )
+    stdout = completed.stdout or ""
+    stderr = completed.stderr or ""
+    if completed.returncode != 0 and not stdout.strip():
+        return completed.returncode, "", stderr.strip() or f"exit {completed.returncode}"
+    return completed.returncode, stdout, stderr
+
+
+def _assert_prompt_shell_permission(
+    command: str,
+    *,
+    bash_allow_rules: Sequence[str] | None,
+    cwd: str | Path | None,
+) -> None:
+    from langchain_agentx.tools.bash.tool import BashRuntimeTool
+
+    store = AgentSessionStore("prompt-shell")
+    if bash_allow_rules:
+        set_command_bash_allow_rules(store, bash_allow_rules)
+    workspace_root = str(cwd) if cwd is not None else None
+    ctx = ToolExecutionContext(
+        tool_name="Bash",
+        tool_call_id="prompt-shell",
+        input_args={"command": command},
+        state={},
+        session_store=store,
+        workspace_root=workspace_root,
+        cwd=workspace_root,
+    )
+    l1 = BashRuntimeTool().run_l1_permission_check({"command": command}, ctx)
+    if l1.outcome == "deny":
+        message = (l1.decision.message if l1.decision else None) or "Permission denied"
+        raise PromptShellPermissionError(
+            f'Shell command permission check failed for "!`{command}`": {message}',
+        )
+
+
+async def execute_shell_commands_in_prompt(
+    text: str,
+    *,
+    cwd: str | Path | None = None,
+    runner: TextSubprocessRunner | None = None,
+    shell_runner: Callable[[str], tuple[int, str, str]] | None = None,
+    bash_allow_rules: Sequence[str] | None = None,
+    check_permissions: bool = True,
+) -> str:
+    """将 text 中所有 !`command` 替换为命令 stdout（失败时内联 stderr/exit）。"""
+    if "!`" not in text:
+        return text
+
+    text_runner = runner or default_text_subprocess_runner()
+    result = text
+
+    for match in list(_INLINE_PATTERN.finditer(text)):
+        command = match.group(1).strip()
+        if not command:
+            continue
+        if check_permissions and shell_runner is None:
+            _assert_prompt_shell_permission(
+                command,
+                bash_allow_rules=bash_allow_rules,
+                cwd=cwd,
+            )
+        if shell_runner is not None:
+            _code, stdout, stderr = shell_runner(command)
+        else:
+            _code, stdout, stderr = _default_runner_call(text_runner, command, cwd=cwd)
+        replacement = stdout.strip() if stdout.strip() else stderr.strip()
+        if not replacement:
+            replacement = "(no output)"
+        result = result.replace(match.group(0), replacement, 1)
+
+    return result

langchain_agentx/command/registry.py

@@ -36,6 +36,22 @@ class CommandRegistry:
         for alias in command.aliases:
             self._alias_to_name[self._normalize(alias)] = normalized_name
 
+    def register_many(
+        self,
+        commands: Iterable[CommandDefinition],
+        *,
+        skip_existing: bool = True,
+    ) -> list[str]:
+        """批量注册。默认跳过已有名（内置优先于 MCP）。"""
+        registered: list[str] = []
+        for command in commands:
+            normalized_name = self._normalize(command.name)
+            if skip_existing and normalized_name in self._commands:
+                continue
+            self.register(command)
+            registered.append(normalized_name)
+        return registered
+
     def register_plugin(
         self,
         commands: Iterable[CommandDefinition],

langchain_agentx/loop/config/compaction_config.py

@@ -0,0 +1,38 @@
+"""Compaction 控制面 env 解析（对齐 CC DISABLE_COMPACT / DISABLE_AUTO_COMPACT）。"""
+
+from __future__ import annotations
+
+import os
+
+
+def _parse_bool_env(name: str) -> bool | None:
+    raw = os.environ.get(name, "").strip().lower()
+    if not raw:
+        return None
+    return raw in ("1", "true", "yes", "on")
+
+
+def resolve_is_auto_compact_enabled(*, config_is_auto_compact: bool = True) -> bool:
+    """CC：DISABLE_COMPACT 关全部；DISABLE_AUTO_COMPACT 仅关 proactive autocompact。"""
+    if _parse_bool_env("DISABLE_COMPACT") is True:
+        return False
+    if _parse_bool_env("DISABLE_AUTO_COMPACT") is True:
+        return False
+    return config_is_auto_compact
+
+
+def compute_autocompact_trigger_token_threshold(
+    *,
+    context_window_tokens: int,
+    max_output_tokens_reserved: int,
+    compact_buffer_tokens: int,
+) -> int:
+    """对齐 CC：effectiveWindow - AUTOCOMPACT_BUFFER_TOKENS。"""
+    effective = max(0, int(context_window_tokens) - int(max_output_tokens_reserved))
+    return max(0, effective - int(compact_buffer_tokens))
+
+
+__all__ = [
+    "compute_autocompact_trigger_token_threshold",
+    "resolve_is_auto_compact_enabled",
+]

langchain_agentx/loop/config/loop_config.py

@@ -253,6 +253,7 @@ class AgentLoopConfig:
     token_budget_max_continuations: int = 3
     compact_buffer_tokens: int = 13_000
     max_output_tokens_reserved: int = 20_000
+    is_auto_compact: bool = True
 
     # -----------------------------------------------------------------------
     # 运行模式
@@ -312,6 +313,12 @@ class AgentLoopConfig:
     )
     model_retry: ModelRetrySettings = field(default_factory=ModelRetrySettings)
 
+    # MCP：默认空，不 connect / 不扫盘。仅显式 specs / controller / plugin 片段时 Loop 接线（S2）。
+    mcp_servers: tuple[Any, ...] = ()
+    mcp_plugins: tuple[Any, ...] = ()
+    mcp_skills_enabled: bool = True
+    mcp_elicitation_auto_accept: bool = False
+
     # -----------------------------------------------------------------------
     # 便捷构造器
     # -----------------------------------------------------------------------
@@ -393,6 +400,9 @@ class LoopServices:
     queued_command_providers: Sequence[Any] = field(default_factory=tuple)
     active_files_getter: Callable[[], list[str]] | None = None
 
+    mcp_controller: Any = None  # McpRuntimeController；默认 None 零成本
+    command_registry: Any = None  # CommandRegistry；MCP prompts register_many
+
 
 __all__ = [
     "PromptConfig",

langchain_agentx/loop/context/pipeline.py

@@ -33,17 +33,33 @@ from .stages.base import CompactionStage
 from .types import CompactProgress, ContextCompactionContext
 
 
+def _apply_autocompact_failure_patch(
+    state: dict[str, Any],
+    stages_meta: list[dict[str, Any]],
+    patch: dict[str, Any],
+) -> None:
+    ac = next((m for m in stages_meta if m.get("name") == "autocompact"), None)
+    if ac is None:
+        return
+    extra = ac.get("extra") or {}
+    prev = int(state.get("consecutive_autocompact_failures") or 0)
+    if extra.get("autocompact_llm_failed"):
+        patch["consecutive_autocompact_failures"] = prev + 1
+    elif extra.get("autocompact_mode") == "llm":
+        patch["consecutive_autocompact_failures"] = 0
+
+
 class DefaultCompactionStages:
     """CC 五段默认装配（顺序即契约）。"""
 
     @staticmethod
-    def build() -> tuple[CompactionStage, ...]:
+    def build(settings: CompactionSettings | None = None) -> tuple[CompactionStage, ...]:
         return (
-            ToolResultBudgetStage(),
-            SnipCompactStage(),
-            MicrocompactStage(),
-            ContextCollapseStage(),
-            AutocompactStage(),
+            ToolResultBudgetStage(settings),
+            SnipCompactStage(settings),
+            MicrocompactStage(settings),
+            ContextCollapseStage(settings),
+            AutocompactStage(settings),
         )
 
 
@@ -65,7 +81,7 @@ class ContextPipeline:
         settings: CompactionSettings | None = None,
     ) -> ContextPipeline:
         """使用 `DefaultCompactionStages` 构建管道。"""
-        return cls(DefaultCompactionStages.build(), settings=settings)
+        return cls(DefaultCompactionStages.build(settings), settings=settings)
 
     @property
     def stages(self) -> tuple[CompactionStage, ...]:
@@ -117,6 +133,7 @@ class ContextPipeline:
                 "mode": ctx.mode,
             }
 
+        _apply_autocompact_failure_patch(state, stages_meta, patch)
         if not patch:
             return {}
         return patch
@@ -198,6 +215,7 @@ class ContextPipeline:
                 "mode": ctx.mode,
             }
 
+        _apply_autocompact_failure_patch(state, stages_meta, patch)
         if not patch:
             return {}
         return patch

langchain_agentx/loop/context/settings.py

@@ -32,6 +32,8 @@ class CompactionSettings:
     prune_protected_tools: FrozenSet[str] = field(default_factory=lambda: frozenset({"Skill"}))
     default_max_context_tokens: int = 120_000
     default_compress_trigger_fraction: float = 0.8
+    # 非 None 时 AutocompactStage 用绝对触发线（由 AgentLoopConfig compact_buffer 派生）。
+    autocompact_trigger_token_threshold: int | None = None
     default_compress_keep_recent_messages: int = 8
     # --- autocompact LLM 提示词（对齐 `compact.ts` + `prompt.ts`）---
     # 摘要插在保留 tail 之前 → 默认 `partial_up_to`；全量折叠无尾窗时用 `full`；与 CC partial pivot「from」一致时用 `partial_from`。
@@ -62,6 +64,8 @@ class CompactionSettings:
         default_factory=QuerySourcePolicy.autocompact_skip_sources
     )
     autocompact_use_llm_when_available: bool = True
+    is_auto_compact_enabled: bool = True
+    max_consecutive_autocompact_failures: int = 3
     autocompact_llm_excerpt_chars_per_message: int = 20_000
     # --- snip carry → autocompact 阈值放宽（对齐 CC snipTokensFreed 计入阈值）---
     # True：将本流水线已累计的 `snip_tokens_freed_carry` 加到触发阈值上，避免 snip 已释放后仍立刻 autocompact。
@@ -89,6 +93,12 @@ class CompactionSettings:
 active_compaction_settings: CompactionSettings = CompactionSettings()
 
 
+def autocompact_trigger_threshold_tokens(settings: CompactionSettings) -> int:
+    if settings.autocompact_trigger_token_threshold is not None:
+        return settings.autocompact_trigger_token_threshold
+    return int(settings.default_max_context_tokens * settings.default_compress_trigger_fraction)
+
+
 def get_active_compaction_settings() -> CompactionSettings:
     """返回当前生效的策略（默认即模块级 `active_compaction_settings`）。"""
     return active_compaction_settings
@@ -104,6 +114,7 @@ __all__ = [
     "AutocompactLlmPromptKind",
     "CompactionSettings",
     "active_compaction_settings",
+    "autocompact_trigger_threshold_tokens",
     "get_active_compaction_settings",
     "set_active_compaction_settings",
 ]