langchain-agentx-python 2.1.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

langchain_agentx/__init__.py

@@ -1,64 +1,64 @@
-"""
-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.1.0"
-
-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.1.2"
+
+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_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/loop/context/settings.py

@@ -1,109 +1,109 @@
-"""
-主循环上下文治理的 **策略与提示词**（单一配置对象，便于替换与单测）。
-
-与 Claude Code 对齐：
-- 数值与 `OPENCODE_*` 环境变量覆盖语义、会话摘要模板与 CC `messagesForQuery` 后续各阶段读取的阈值/提示一致方向；
-- 各 `CompactionStage` 实现应通过 `get_active_compaction_settings()` 读取，避免散落魔法数。
-
-设计要点：
-- `CompactionSettings` 为 `frozen` 值对象；可变绑定为模块级 `active_compaction_settings`，单测可 `set_active_compaction_settings(...)` 整体替换。
-
-注意：
-- 不依赖 LangGraph；与 `tool_runtime` 单条截断分工见设计文档。
-- 紧凑化提示词函数（如 `get_compact_prompt`）在 **`loop/prompt/compact.py`**，不在本模块再导出。
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import FrozenSet
-
-from ..prompt.compact import AutocompactLlmPromptKind
-from .query_source import QuerySourcePolicy
-
-
-@dataclass(frozen=True)
-class CompactionSettings:
-    """CC 对齐上下文治理的默认策略（提示词 + 数值阈值）。"""
-
-    num_chars_per_token: int = 4
-    prune_protect_tokens: int = 40_000
-    prune_minimum_tokens: int = 20_000
-    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
-    default_compress_keep_recent_messages: int = 8
-    # --- autocompact LLM 提示词（对齐 `compact.ts` + `prompt.ts`）---
-    # 摘要插在保留 tail 之前 → 默认 `partial_up_to`；全量折叠无尾窗时用 `full`；与 CC partial pivot「from」一致时用 `partial_from`。
-    autocompact_llm_prompt_kind: AutocompactLlmPromptKind = "partial_up_to"
-    # 追加到 CC 模板末尾的 Additional Instructions（对齐 hook merge 的 customInstructions）。
-    compact_custom_instructions: str | None = None
-    # 非 None 时跳过 builder，整段作为 compact 调用的指令（单测 / 完全自定义）。
-    autocompact_llm_instructions_override: str | None = None
-    # 兼容旧字段：未设置 override 时若此字段非空则优先于 builder（避免破坏只传 compaction_system_prompt 的调用方）。
-    compaction_system_prompt: str | None = None
-    # --- tool_result_budget（对齐 applyToolResultBudget：单条结果软上限）---
-    tool_result_max_chars_per_message: int = 48_000
-    tool_result_budget_suffix: str = field(
-        default="\n\n[... truncated by tool_result_budget ...]"
-    )
-    # --- snip_compact（对齐 snip：尾部保留 + 历史大块截断）---
-    snip_preserve_tail_messages: int = 10
-    snip_max_tool_content_chars: int = 12_288
-    snip_suffix: str = field(default="\n\n[... snipped by snip_compact ...]")
-    # --- microcompact（轻量规范化；递归压缩时跳过）---
-    microcompact_skip_query_sources: FrozenSet[str] = field(
-        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=QuerySourcePolicy.autocompact_skip_sources
-    )
-    autocompact_use_llm_when_available: bool = True
-    autocompact_llm_excerpt_chars_per_message: int = 20_000
-    # --- snip carry → autocompact 阈值放宽（对齐 CC snipTokensFreed 计入阈值）---
-    # True：将本流水线已累计的 `snip_tokens_freed_carry` 加到触发阈值上，避免 snip 已释放后仍立刻 autocompact。
-    autocompact_snip_carry_threshold_slack: bool = True
-    # --- blocking / token 告警（对齐 CC calculateTokenWarningState 分档）---
-    compaction_token_warn_fraction: float = 0.85
-    compaction_block_compact_llm_fraction: float = 0.98
-    # 达到或超过视为「主上下文已顶满」，建议由调用方拦主模型（本守卫 `should_block`）。
-    compaction_block_main_model_fraction: float = 1.0
-    # True：`model` 节点在 `invoke` 前若 `should_block` 命中则不再调主模型，写入合成 AIMessage 并结束。
-    enable_main_model_context_token_block: bool = True
-    # --- tool transcript guard（对齐 CC `ensureToolResultPairing`：发往 LLM 前修复 tool 配对）---
-    # True：在绑定模型 `invoke/ainvoke` 前对 `messages` 做确定性修复（跨 assistant 去重 tool_call_id、
-    # 去重连续 ToolMessage、补 synthetic 等），降低提供商 400 与会话卡死风险；不依赖提示词。
-    enable_tool_transcript_repair_before_llm: bool = True
-    # --- SystemMessage 单一来源兜底（对齐 CC normalizeMessagesForAPI）---
-    # True：在 LLM 调用前剥离 state["messages"] 中所有 SystemMessage，避免 OpenAI 兼容 API 400 错误。
-    enable_system_message_sanitizer: bool = True
-    # True：剥离时输出内容预览（最多 3 条），便于排查违规来源。
-    enable_system_message_content_preview: bool = True
-    # --- 观测：写入 state.compaction_pipeline_meta（需 LoopAgentStateFields 含该键）---
-    emit_compaction_pipeline_meta: bool = True
-
-
-active_compaction_settings: CompactionSettings = CompactionSettings()
-
-
-def get_active_compaction_settings() -> CompactionSettings:
-    """返回当前生效的策略（默认即模块级 `active_compaction_settings`）。"""
-    return active_compaction_settings
-
-
-def set_active_compaction_settings(settings: CompactionSettings) -> None:
-    """替换全局策略（单测或进程级配置用）。"""
-    global active_compaction_settings
-    active_compaction_settings = settings
-
-
-__all__ = [
-    "AutocompactLlmPromptKind",
-    "CompactionSettings",
-    "active_compaction_settings",
-    "get_active_compaction_settings",
-    "set_active_compaction_settings",
-]
+"""
+主循环上下文治理的 **策略与提示词**（单一配置对象，便于替换与单测）。
+
+与 Claude Code 对齐：
+- 数值与 `OPENCODE_*` 环境变量覆盖语义、会话摘要模板与 CC `messagesForQuery` 后续各阶段读取的阈值/提示一致方向；
+- 各 `CompactionStage` 实现应通过 `get_active_compaction_settings()` 读取，避免散落魔法数。
+
+设计要点：
+- `CompactionSettings` 为 `frozen` 值对象；可变绑定为模块级 `active_compaction_settings`，单测可 `set_active_compaction_settings(...)` 整体替换。
+
+注意：
+- 不依赖 LangGraph；与 `tool_runtime` 单条截断分工见设计文档。
+- 紧凑化提示词函数（如 `get_compact_prompt`）在 **`loop/prompt/compact.py`**，不在本模块再导出。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import FrozenSet
+
+from ..prompt.compact import AutocompactLlmPromptKind
+from .query_source import QuerySourcePolicy
+
+
+@dataclass(frozen=True)
+class CompactionSettings:
+    """CC 对齐上下文治理的默认策略（提示词 + 数值阈值）。"""
+
+    num_chars_per_token: int = 4
+    prune_protect_tokens: int = 40_000
+    prune_minimum_tokens: int = 20_000
+    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
+    default_compress_keep_recent_messages: int = 8
+    # --- autocompact LLM 提示词（对齐 `compact.ts` + `prompt.ts`）---
+    # 摘要插在保留 tail 之前 → 默认 `partial_up_to`；全量折叠无尾窗时用 `full`；与 CC partial pivot「from」一致时用 `partial_from`。
+    autocompact_llm_prompt_kind: AutocompactLlmPromptKind = "partial_up_to"
+    # 追加到 CC 模板末尾的 Additional Instructions（对齐 hook merge 的 customInstructions）。
+    compact_custom_instructions: str | None = None
+    # 非 None 时跳过 builder，整段作为 compact 调用的指令（单测 / 完全自定义）。
+    autocompact_llm_instructions_override: str | None = None
+    # 兼容旧字段：未设置 override 时若此字段非空则优先于 builder（避免破坏只传 compaction_system_prompt 的调用方）。
+    compaction_system_prompt: str | None = None
+    # --- tool_result_budget（对齐 applyToolResultBudget：单条结果软上限）---
+    tool_result_max_chars_per_message: int = 48_000
+    tool_result_budget_suffix: str = field(
+        default="\n\n[... truncated by tool_result_budget ...]"
+    )
+    # --- snip_compact（对齐 snip：尾部保留 + 历史大块截断）---
+    snip_preserve_tail_messages: int = 10
+    snip_max_tool_content_chars: int = 12_288
+    snip_suffix: str = field(default="\n\n[... snipped by snip_compact ...]")
+    # --- microcompact（轻量规范化；递归压缩时跳过）---
+    microcompact_skip_query_sources: FrozenSet[str] = field(
+        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=QuerySourcePolicy.autocompact_skip_sources
+    )
+    autocompact_use_llm_when_available: bool = True
+    autocompact_llm_excerpt_chars_per_message: int = 20_000
+    # --- snip carry → autocompact 阈值放宽（对齐 CC snipTokensFreed 计入阈值）---
+    # True：将本流水线已累计的 `snip_tokens_freed_carry` 加到触发阈值上，避免 snip 已释放后仍立刻 autocompact。
+    autocompact_snip_carry_threshold_slack: bool = True
+    # --- blocking / token 告警（对齐 CC calculateTokenWarningState 分档）---
+    compaction_token_warn_fraction: float = 0.85
+    compaction_block_compact_llm_fraction: float = 0.98
+    # 达到或超过视为「主上下文已顶满」，建议由调用方拦主模型（本守卫 `should_block`）。
+    compaction_block_main_model_fraction: float = 1.0
+    # True：`model` 节点在 `invoke` 前若 `should_block` 命中则不再调主模型，写入合成 AIMessage 并结束。
+    enable_main_model_context_token_block: bool = True
+    # --- tool transcript guard（对齐 CC `ensureToolResultPairing`：发往 LLM 前修复 tool 配对）---
+    # True：在绑定模型 `invoke/ainvoke` 前对 `messages` 做确定性修复（跨 assistant 去重 tool_call_id、
+    # 去重连续 ToolMessage、补 synthetic 等），降低提供商 400 与会话卡死风险；不依赖提示词。
+    enable_tool_transcript_repair_before_llm: bool = True
+    # --- SystemMessage 单一来源兜底（对齐 CC normalizeMessagesForAPI）---
+    # True：在 LLM 调用前剥离 state["messages"] 中所有 SystemMessage，避免 OpenAI 兼容 API 400 错误。
+    enable_system_message_sanitizer: bool = True
+    # True：剥离时输出内容预览（最多 3 条），便于排查违规来源。
+    enable_system_message_content_preview: bool = True
+    # --- 观测：写入 state.compaction_pipeline_meta（需 LoopAgentStateFields 含该键）---
+    emit_compaction_pipeline_meta: bool = True
+
+
+active_compaction_settings: CompactionSettings = CompactionSettings()
+
+
+def get_active_compaction_settings() -> CompactionSettings:
+    """返回当前生效的策略（默认即模块级 `active_compaction_settings`）。"""
+    return active_compaction_settings
+
+
+def set_active_compaction_settings(settings: CompactionSettings) -> None:
+    """替换全局策略（单测或进程级配置用）。"""
+    global active_compaction_settings
+    active_compaction_settings = settings
+
+
+__all__ = [
+    "AutocompactLlmPromptKind",
+    "CompactionSettings",
+    "active_compaction_settings",
+    "get_active_compaction_settings",
+    "set_active_compaction_settings",
+]

langchain_agentx/loop/subagent/context.py

@@ -91,7 +91,7 @@ class SubagentContext:
     parent_tool_call_id: str | None = None  # 触发本子 Agent 的 tool_call_id
     parent_conversation_session_id: str | None = None
     enable_trace: bool = True
-    runnable_config: Any = None  # 父 graph 的 runnable_config，用于子 graph 事件自动冒泡到父 graph
+    runnable_config: Any = None  # 父 runnable_config：仅供 tool_progress custom event 回调链；非子 raw 合并
     isolation: str = "none"
     worktree_dir: str | None = None
     workspace_root: str = ""

langchain_agentx/loop/subagent/orchestrator.py

@@ -307,7 +307,8 @@ class SubagentOrchestrator:
     ) -> "AgentToolOutput":
         """异步执行子代理。
 
-        子 graph 事件通过 config 自动冒泡到父 graph，无需手动回调。
+        子 graph 在独立 LoopStreamDriver 消费（Phase-4）；progress 经 custom event 冒泡，
+        裸子 on_tool_* 不并进父 astream。
         """
         from langchain_agentx.tools.agent.models import AgentToolOutput
 
@@ -595,7 +596,7 @@ class SubagentOrchestrator:
     ) -> Any:
         """异步启动子 agent。
 
-        子 graph 事件通过 config 自动冒泡到父 graph。
+        子 graph Phase-4 独立 Driver 消费；progress 经 custom event 冒泡到父流。
         """
         owner_run_ctx = get_run_context()
         handle = self._register_background_agent(

langchain_agentx/loop/subagent/runner.py

@@ -226,7 +226,7 @@ async def _emit_progress(
     """发射子 Agent teaser lane 到父 graph（CC 对齐：仅 tool_use / tool_result）。
 
     同步 dispatch 优先：并行线程池 / _run_coroutine_sync 子线程内 adispatch 无法触达父回调链。
-    父 graph 的 config 通过 ctx.runnable_config 传递（在 _collect_subagent_events 中合并）。
+    父 config 经 ctx.runnable_config 仅服务 custom event 派发（Phase-4 不合并父 callbacks）。
     """
     if event.type not in ("tool_use", "tool_result"):
         return