langchain-agentx-python 1.1.8__tar.gz → 1.1.9__tar.gz

{langchain-agentx-python-1.1.8/langchain_agentx_python.egg-info → langchain-agentx-python-1.1.9}/PKG-INFO

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

{langchain-agentx-python-1.1.8 → langchain-agentx-python-1.1.9}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.1.8 → langchain-agentx-python-1.1.9}/langchain_agentx/command/allowed_tools.py

@@ -2,7 +2,7 @@
 command/allowed_tools.py — CC 风格 allowed_tools 解析与应用。
 
 职责：
-    解析 Bash(git add:*) / read_file 等条目，写入 session 权限上下文。
+    解析 Bash(git add:*) / Read 等条目，写入 session 权限上下文。
 
 链路位置：
     Session run_slash_command → apply_command_tool_scope。
@@ -20,6 +20,7 @@ from ..tool_runtime.permission_context import (
     set_command_bash_allow_rules,
 )
 from ..tool_runtime.session_store import AgentSessionStore
+from ..tool_runtime.tool_name_constants import Bash
 
 _ALLOWED_TOOL_RE = re.compile(r"^([A-Za-z][A-Za-z0-9_-]*)(?:\((.*)\))?$")
 
@@ -38,7 +39,7 @@ def parse_allowed_tool_rule(entry: str) -> ParsedAllowedToolRule | None:
     match = _ALLOWED_TOOL_RE.fullmatch(text)
     if match is None:
         return None
-    tool_name = match.group(1).lower()
+    tool_name = match.group(1)
     raw_content = match.group(2)
     rule_content = None if raw_content is None else raw_content.strip()
     if rule_content == "" or rule_content == "*":
@@ -59,15 +60,15 @@ def partition_allowed_tools(
         parsed = parse_allowed_tool_rule(entry)
         if parsed is None:
             continue
-        if parsed.tool_name == "bash":
+        if parsed.tool_name == Bash:
             if parsed.rule_content is not None:
                 key = parsed.rule_content.lower()
                 if key not in seen_patterns:
                     seen_patterns.add(key)
                     bash_patterns.append(parsed.rule_content)
-            elif "bash" not in seen_tools:
-                seen_tools.add("bash")
-                tool_names.append("bash")
+            elif Bash not in seen_tools:
+                seen_tools.add(Bash)
+                tool_names.append(Bash)
         else:
             if parsed.tool_name not in seen_tools:
                 seen_tools.add(parsed.tool_name)

{langchain-agentx-python-1.1.8 → langchain-agentx-python-1.1.9}/langchain_agentx/command/fork_executor.py

@@ -21,7 +21,7 @@ from langchain_agentx.workspace.config import ResolvedAgentStateConfig
 
 
 def _bash_only_tool_filter(all_tools: list[Any]) -> list[Any]:
-    return [tool for tool in all_tools if getattr(tool, "name", "") == "bash"]
+    return [tool for tool in all_tools if getattr(tool, "name", "") == "Bash"]
 
 
 def _commit_fork_subagent_config() -> SubagentConfig:
@@ -32,7 +32,7 @@ def _commit_fork_subagent_config() -> SubagentConfig:
         description="Isolated slash-command fork worker",
         when_to_use="Internal fork execution for slash commands",
         tool_filter=_bash_only_tool_filter,
-        tools_description="bash",
+        tools_description="Bash",
         default_max_steps=8,
         allow_async=False,
         tags={"fork", "slash-command"},

{langchain-agentx-python-1.1.8 → langchain-agentx-python-1.1.9}/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,
-    )
-    decision = BashRuntimeTool().check_permissions({"command": command}, ctx)
-    if decision.behavior == "deny":
-        message = decision.message 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-python-1.1.8 → langchain-agentx-python-1.1.9}/langchain_agentx/loop/config/interaction_profile.py

@@ -211,6 +211,8 @@ def assemble_services(
     if loader is None:
         return replace(svcs, prompt_handler=handler)
 
+    apply_profile_policy_defaults(cfg, loader)
+
     if _loader_headless(loader) != bool(cfg.headless):
         loader.sync_headless(bool(cfg.headless))
     loader.set_prompt_handler(handler)
@@ -218,6 +220,45 @@ def assemble_services(
     return replace(svcs, loader=loader, prompt_handler=handler)
 
 
+def apply_profile_policy_defaults(
+    config: AgentLoopConfig,
+    loader: Any,
+) -> None:
+    """HITL 剖面（code-interactive / code-plan）默认启用 GAP-7 denial tracking。
+
+    库级 ``ToolPolicyConfig.denial_tracking`` 默认 None/off；interactive REPL 产品剖面
+    在 ``assemble_services`` 注入 ``enabled=True``。显式 ``denial_tracking`` 不覆盖。
+    """
+    profile_id = InteractionProfileResolver().resolve_profile_id(config)
+    if profile_id not in _HITL_PROFILE_IDS:
+        return
+
+    from langchain_agentx.tool_runtime.denial_tracking import DenialTrackingConfig
+    from langchain_agentx.tool_runtime.policy import ToolPolicyConfig
+
+    process = getattr(loader, "process_loader", None) or getattr(loader, "process", None)
+    if process is None:
+        return
+
+    current = process.policy_config
+    if current is not None and current.denial_tracking is not None:
+        return
+
+    base = current or ToolPolicyConfig()
+    updated = replace(base, denial_tracking=DenialTrackingConfig(enabled=True))
+    process.apply_policy_config(updated)
+
+    policy = process.policy
+    if policy is None:
+        return
+    registry = getattr(loader, "registry", None)
+    if registry is None:
+        return
+    for tool in registry.list():
+        if getattr(tool, "_policy", None) is not None:
+            tool._policy = policy
+
+
 def sanity_check_profile(
     config: AgentLoopConfig,
     services: LoopServices,
@@ -239,6 +280,7 @@ def sanity_check_profile(
 
 __all__ = [
     "InteractionProfileResolver",
+    "apply_profile_policy_defaults",
     "assemble_services",
     "normalize_config",
     "sanity_check_profile",

{langchain-agentx-python-1.1.8 → langchain-agentx-python-1.1.9}/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",
+]