langchain-agentx-python 0.9.0__py3-none-any.whl → 0.9.2__py3-none-any.whl

langchain_agentx/__init__.py

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

langchain_agentx/loop/exit/exit_logic.py

@@ -42,77 +42,28 @@ _logger = logging.getLogger(__name__)
 # 需要继续执行的 finish_reason 集合（与 OpenCode 一致）
 CONTINUE_FINISH_REASONS = frozenset({"tool-calls", "unknown"})
 
-# extract_finish_reason 输出的框架归一化值（含内部写入 metadata 的哨兵，如 corrector 写 "tool-calls"）。
-# 维护规则：新增 extract_finish_reason 分支输出时同步补入；与 _PROVIDER_FINISH_REASONS 分离。
-_FRAMEWORK_NORMALIZED_FINISH_REASONS: frozenset[str] = frozenset(
-    {
-        "tool-calls",
-        "unknown",
-        "stop",
-        "length",
-        "content-filter",
-        "error",
-        "sensitive",
-    }
-)
-
-# merge_dicts 拼接还原白名单：provider 原始 finish_reason 枚举（非框架归一化输出）。
-# 维护规则：新增 provider 协议枚举时补入；框架哨兵见 _FRAMEWORK_NORMALIZED_FINISH_REASONS。
-_PROVIDER_FINISH_REASONS: frozenset[str] = frozenset(
-    {
-        # OpenAI 协议
-        "tool_calls",
-        "function_call",
-        "tool_use",
-        "stop",
-        "stop_sequence",
-        "length",
-        "max_tokens",
-        "content_filter",
-        "content-filter",
-        "refusal",
-        "error",
-        # Anthropic 协议
-        "end_turn",
-        # GLM / 国产模型特有
-        "sensitive",
-        # 部分 adapter 可能写入的继续哨兵（与 CONTINUE_FINISH_REASONS 对齐）
-        "unknown",
-    }
-)
 
+def extract_finish_reason(response: AIMessage | None) -> str | None:
+    """
+    从 LangChain `AIMessage` 中提取并标准化 `finish_reason`。
 
-def _normalize_concat_finish_reason(raw: str) -> str:
-    """将 merge_dicts 拼接的畸形 finish_reason 还原为已知枚举值。
+    委托 ProviderSemantics family normalizer 处理 provider 差异，
+    再经框架级别名收口；metadata_override 仍由独立函数负责。
+    """
+    from langchain_agentx.provider.semantics.finish_reason_normalizer import (
+        get_default_finish_reason_dispatcher,
+    )
 
-    算法原理：
-        langchain_core.utils._merge.merge_dicts 合并流式 chunk 的 response_metadata 时，
-        对字符串值使用 ``+=`` 拼接。当每个 chunk 都携带相同 finish_reason（如 GLM），
-        N 个 ``"tool_calls"`` 会被拼成 ``"tool_callstool_calls...tool_calls"``。
-        本函数检测输入是否为白名单枚举的整数次重复，若是则还原为单次枚举。
+    return get_default_finish_reason_dispatcher().extract(response)
 
-    与 merge_dicts 的关系：
-        对未拼接的正常枚举值是 no-op；仅修复拼接畸形。merge_dicts 行为变更不影响安全性。
 
-    白名单维护：
-        仅覆盖 provider 原始枚举（``_PROVIDER_FINISH_REASONS``）；框架归一化值见
-        ``_FRAMEWORK_NORMALIZED_FINISH_REASONS``，不在此做拼接还原。
+def interpret_finish_reason(response: AIMessage | None):
+    """返回 finish_reason 完整解释结果（含 overflow_kind / provider_family）。"""
+    from langchain_agentx.provider.semantics.finish_reason_normalizer import (
+        get_default_finish_reason_dispatcher,
+    )
 
-    未命中行为：
-        无法还原时原样透传；告警在 ``extract_finish_reason`` 分类完成后、对仍未识别的
-        provider 枚举打出（不含框架已归一化值）。
-    """
-    if raw in _FRAMEWORK_NORMALIZED_FINISH_REASONS:
-        return raw
-    if raw in _PROVIDER_FINISH_REASONS:
-        return raw
-    for base in _PROVIDER_FINISH_REASONS:
-        unit_len = len(base)
-        if len(raw) > unit_len and len(raw) % unit_len == 0:
-            repeat_count = len(raw) // unit_len
-            if raw == base * repeat_count:
-                return base
-    return raw
+    return get_default_finish_reason_dispatcher().interpret(response)
 
 
 # 可恢复终态集合（terminal_reason 枚举，先 withhold，由 loop_controller 走恢复链）
@@ -137,53 +88,6 @@ def resolve_escalated_max_output_tokens(max_output_tokens_cap: int | None) -> in
     return min(ESCALATED_MAX_OUTPUT_TOKENS, int(max_output_tokens_cap))
 
 
-def extract_finish_reason(response: AIMessage | None) -> str | None:
-    """
-    从 LangChain `AIMessage` 中提取并标准化 `finish_reason`。
-
-    该实现与原始 LangChain AgentX 逻辑保持一致。
-    """
-    if response is None:
-        return None
-
-    meta = getattr(response, "response_metadata", None) or {}
-    if not isinstance(meta, dict):
-        meta = {}
-
-    raw_reason = (
-        meta.get("finish_reason")
-        or meta.get("stop_reason")
-        or meta.get("done_reason")
-    )
-
-    if raw_reason is None:
-        return None
-
-    finish_reason = _normalize_concat_finish_reason(str(raw_reason))
-
-    if finish_reason in _FRAMEWORK_NORMALIZED_FINISH_REASONS:
-        return finish_reason
-
-    if finish_reason in {"tool_calls", "function_call", "tool_use"}:
-        return "tool-calls"
-    if finish_reason in {"content_filter", "content-filter"}:
-        return "content-filter"
-    if finish_reason in {"length", "max_tokens"}:
-        return "length"
-    if finish_reason in {"stop", "end_turn", "stop_sequence"}:
-        return "stop"
-    if finish_reason == "refusal":
-        return "content-filter"
-    if finish_reason == "error":
-        return "error"
-
-    if finish_reason:
-        _logger.warning(
-            "unrecognized finish_reason from provider metadata: %r", finish_reason
-        )
-    return finish_reason
-
-
 def metadata_override_terminal_reason(response: AIMessage | None) -> str | None:
     """Infer terminal_reason from response_metadata / provider error shape (PTL / media / blocking).
 
@@ -415,6 +319,7 @@ __all__ = [
     "MAX_OUTPUT_TOKENS_RECOVERY_LIMIT",
     "resolve_escalated_max_output_tokens",
     "extract_finish_reason",
+    "interpret_finish_reason",
     "determine_should_end",
     "create_initial_state",
     "AgentLoopState",

langchain_agentx/loop/exit/reason_codes.py

@@ -30,6 +30,7 @@ TRANSITION_REACTIVE_COMPACT_RETRY = "reactive_compact_retry"
 TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE = "max_output_tokens_escalate"
 TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY = "max_output_tokens_recovery"
 TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED = "max_output_tokens_recovery_exhausted"
+TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED = "context_window_recovery_exhausted"
 TRANSITION_TASK_NOTIFICATION_ARRIVED = "task_notification_arrived"
 TRANSITION_STOP_HOOK_PREVENTED = "stop_hook_prevented"
 TRANSITION_STOP_HOOK_BLOCKING = "stop_hook_blocking"
@@ -37,3 +38,42 @@ TRANSITION_TOKEN_BUDGET_CONTINUATION = "token_budget_continuation"
 
 # token_budget continuation 默认上限（与 CC token budget nudge 次数护栏同向）
 DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS = 3
+
+# 错误结束 terminal_reason 集合（finish payload is_error 判据）
+ERROR_TERMINAL_REASONS = frozenset(
+    {
+        TERMINAL_REASON_ERROR,
+        TERMINAL_REASON_MAX_TOKENS,
+        TERMINAL_REASON_BLOCKING_LIMIT,
+    }
+)
+
+__all__ = [
+    "TERMINAL_REASON_COMPLETED",
+    "TERMINAL_REASON_MAX_STEPS",
+    "TERMINAL_REASON_MAX_TURNS",
+    "TERMINAL_REASON_MAX_TOKENS",
+    "TERMINAL_REASON_CONTENT_FILTER",
+    "TERMINAL_REASON_BLOCKING_LIMIT",
+    "TERMINAL_REASON_STOP_HOOK_PREVENTED",
+    "TERMINAL_REASON_ERROR",
+    "TERMINAL_REASON_ABORTED_STREAMING",
+    "TERMINAL_REASON_ABORTED_TOOLS",
+    "TERMINAL_REASON_HOOK_STOPPED",
+    "ERROR_TERMINAL_REASONS",
+    "TRANSITION_NEXT_TURN",
+    "TRANSITION_API_ERROR_TERMINAL",
+    "TRANSITION_WITHHOLD_RECOVERY_RETRY",
+    "TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED",
+    "TRANSITION_COLLAPSE_DRAIN_RETRY",
+    "TRANSITION_REACTIVE_COMPACT_RETRY",
+    "TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE",
+    "TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY",
+    "TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED",
+    "TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED",
+    "TRANSITION_TASK_NOTIFICATION_ARRIVED",
+    "TRANSITION_STOP_HOOK_PREVENTED",
+    "TRANSITION_STOP_HOOK_BLOCKING",
+    "TRANSITION_TOKEN_BUDGET_CONTINUATION",
+    "DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS",
+]

langchain_agentx/loop/exit/withheld_error.py

@@ -0,0 +1,55 @@
+"""
+withheld_error.py — withhold 恢复错误载荷组装
+
+职责：
+    从 terminal_reason / finish_reason / AIMessage 解释结果组装 withheld_error 结构，
+    供 ModelNode 与 GraphEdges 恢复状态机共享。
+
+链路位置：
+    ModelNode._resolve_withhold_recovery_update → withheld_error → GraphEdges._handle_withheld_error
+
+当前裁剪范围：
+    - 不包含恢复梯子路由（见 graph_edges.py）
+    - 不包含 finish 事件投影（Phase 3）
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from langchain_core.messages import AIMessage
+
+
+def build_withheld_error(
+    *,
+    terminal_reason: str,
+    finish_reason: str | None,
+    last_ai_message: "AIMessage | None" = None,
+) -> dict[str, Any]:
+    """组装 withheld_error 载荷（含 overflow 子语义字段）。"""
+    from langchain_agentx.loop.exit.exit_logic import interpret_finish_reason
+
+    interpretation = (
+        interpret_finish_reason(last_ai_message) if last_ai_message is not None else None
+    )
+    return {
+        "reason": terminal_reason,
+        "finish_reason": finish_reason,
+        "overflow_kind": interpretation.overflow_kind if interpretation else None,
+        "raw_finish_reason": interpretation.raw_reason if interpretation else None,
+        "provider_family": interpretation.provider_family if interpretation else None,
+    }
+
+
+def resolve_overflow_kind(withheld_error: dict[str, Any] | None) -> str:
+    """解析 withheld_error 的 overflow 子语义；缺失时保守为 unknown。"""
+    if not isinstance(withheld_error, dict):
+        return "unknown"
+    kind = withheld_error.get("overflow_kind")
+    if kind in ("context_window", "output_limit"):
+        return str(kind)
+    return "unknown"
+
+
+__all__ = ["build_withheld_error", "resolve_overflow_kind"]

langchain_agentx/loop/graph/graph_edges.py

@@ -47,6 +47,7 @@ from ..exit.exit_logic import (
     TOKEN_BUDGET_NUDGE_USER_MESSAGE,
     resolve_escalated_max_output_tokens,
 )
+from ..exit.withheld_error import resolve_overflow_kind
 from ..exit.reason_codes import (
     DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS,
     TERMINAL_REASON_ABORTED_STREAMING,
@@ -58,6 +59,7 @@ from ..exit.reason_codes import (
     TERMINAL_REASON_STOP_HOOK_PREVENTED,
     TRANSITION_API_ERROR_TERMINAL,
     TRANSITION_COLLAPSE_DRAIN_RETRY,
+    TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED,
     TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE,
     TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY,
     TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED,
@@ -327,9 +329,57 @@ class LoopControllerEdge:
         if not withheld_error:
             return None
         if withheld_error.get("reason") == TERMINAL_REASON_MAX_TOKENS:
+            overflow_kind = resolve_overflow_kind(withheld_error)
+            if overflow_kind == "context_window":
+                return self._handle_context_window_recovery(state, withheld_error)
             return self._handle_max_tokens_recovery(state, withheld_error)
         return self._handle_generic_withheld(state, withheld_error)
 
+    def _handle_context_window_recovery(
+        self,
+        state: dict[str, Any],
+        withheld_error: dict[str, Any],
+    ) -> str:
+        if not state.get("has_attempted_reactive_compact", False):
+            state["has_attempted_reactive_compact"] = True
+            state["transition"] = {
+                "reason": TRANSITION_REACTIVE_COMPACT_RETRY,
+                "error_reason": TERMINAL_REASON_MAX_TOKENS,
+                "overflow_kind": "context_window",
+            }
+            emit_loop_decision_event(
+                state=state,
+                decision="continue",
+                selected_edge=self._model_destination,
+                reason_code="reactive_compact_retry",
+                evidence={
+                    "withheld_error": withheld_error,
+                    "overflow_kind": "context_window",
+                    "step": state.get("step", 0),
+                },
+            )
+            return self._model_destination
+        state["withheld_error"] = None
+        state["should_end"] = True
+        state["terminal_reason"] = TERMINAL_REASON_MAX_TOKENS
+        state["transition"] = {
+            "reason": TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED,
+            "error_reason": TERMINAL_REASON_MAX_TOKENS,
+            "overflow_kind": "context_window",
+        }
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=self._end_destination,
+            reason_code="context_window_recovery_exhausted",
+            evidence={
+                "withheld_error": withheld_error,
+                "overflow_kind": "context_window",
+                "step": state.get("step", 0),
+            },
+        )
+        return self._end_destination
+
     def _handle_max_tokens_recovery(
         self,
         state: dict[str, Any],

langchain_agentx/loop/hook/__init__.py

@@ -9,10 +9,11 @@ loop.hook — Hook 子系统（P1/P2）。
 
 当前裁剪范围：
     已包含 P1 + P2 基础执行器导出；并行聚合与治理细节见 HookEngine/规划文档。
+    Phase 1：新增 HookProgressPayloadBuilder 用于 progress 展示元数据构建。
 """
 
-from .config import HookCandidate, HookCandidateDecision, HookSpec, HooksConfigSnapshot
 from .async_hook_runner import AsyncHookRunner
+from .config import HookCandidate, HookCandidateDecision, HookSpec, HooksConfigSnapshot
 from .engine import HookEngine
 from .executors import AgentExecutor, CommandExecutor, HttpExecutor, PromptExecutor
 from .graph_wiring import HookGraphWiring, derive_hook_outcome
@@ -25,6 +26,7 @@ from .hook_projection import (
     derive_attachment_type,
     hook_result_to_event_dict,
 )
+from .progress_payload import HookProgressPayloadBuilder
 from .registry import HookRegistry
 from .trust import WorkspaceTrustChecker
 from .types import (
@@ -36,13 +38,14 @@ from .types import (
 )
 
 __all__ = [
+    "AggregatedHookResult",
+    "AsyncHookRunner",
     "ATTACHMENT_HOOK_BLOCKING_ERROR",
     "ATTACHMENT_HOOK_CANCELLED",
     "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
     "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
     "ATTACHMENT_HOOK_SUCCESS",
-    "AggregatedHookResult",
-    "AsyncHookRunner",
+    "CommandExecutor",
     "HookCandidate",
     "HookCandidateDecision",
     "HookContext",
@@ -50,11 +53,11 @@ __all__ = [
     "HookEvent",
     "HookExecutionRecord",
     "HookGraphWiring",
+    "HookProgressPayloadBuilder",
     "HookRegistry",
     "HookResult",
     "HookSpec",
     "HooksConfigSnapshot",
-    "CommandExecutor",
     "HttpExecutor",
     "PromptExecutor",
     "AgentExecutor",

langchain_agentx/loop/hook/engine.py

@@ -10,6 +10,7 @@ engine.py — Hook 执行引擎（P1/P2）。
 当前裁剪范围：
     已覆盖 function/callback + command/http/prompt/agent 执行器；
     当前执行策略为 callback/function 顺序、其余执行器并行。
+    Phase 1：使用 HookProgressPayloadBuilder 构建 progress payload。
 """
 
 from __future__ import annotations
@@ -38,6 +39,7 @@ from .types import (
     PermissionBehavior,
 )
 from .hook_projection import build_hook_info
+from .progress_payload import HookProgressPayloadBuilder
 from .trust import WorkspaceTrustChecker
 
 if TYPE_CHECKING:
@@ -86,6 +88,7 @@ class HookEngine:
         *,
         event_emitter: HookEventEmitter | None = None,
         trust_checker: WorkspaceTrustChecker | None = None,
+        progress_payload_builder: HookProgressPayloadBuilder | None = None,
     ) -> None:
         self._snapshot = snapshot
         self._function_executor = FunctionExecutor()
@@ -96,6 +99,8 @@ class HookEngine:
         self._agent_executor = AgentExecutor()
         self._event_emitter = event_emitter
         self._trust_checker = trust_checker
+        # Phase 1：使用专门的 builder 而非手写 payload dict
+        self._progress_builder = progress_payload_builder or HookProgressPayloadBuilder()
 
     async def execute(self, ctx: HookContext) -> AggregatedHookResult:
         batch_started_at = time.perf_counter()
@@ -160,19 +165,10 @@ class HookEngine:
         ctx: HookContext,
         agg: AggregatedHookResult,
     ) -> HookResult:
-        hook_name = str(candidate.spec.config.get("name") or candidate.spec.hook_id)
+        # Phase 1：使用 HookProgressPayloadBuilder 构建完整 payload
         if self._event_emitter is not None:
-            self._event_emitter.emit_progress(
-                {
-                    "hook_id": candidate.spec.hook_id,
-                    "hook_name": hook_name,
-                    "hook_event": ctx.event.value,
-                    "tool_call_id": ctx.tool_call_id,
-                    "session_id": ctx.session_id,
-                    "node_level": False,
-                    "phase": "running",
-                }
-            )
+            progress_payload = self._progress_builder.build(candidate, ctx)
+            self._event_emitter.emit_progress(progress_payload)
         started_at = time.perf_counter()
         one = await self._run_one(candidate, ctx)
         duration_ms = (time.perf_counter() - started_at) * 1000

langchain_agentx/loop/hook/progress_payload.py

@@ -0,0 +1,129 @@
+"""
+progress_payload.py — Hook Progress 展示元数据构建器（Phase 1）。
+
+职责：
+    从 HookSpec + HookContext 生成包含 status_message/command/prompt_text/executor_type
+    的 progress payload，供 CLI spinner 使用。
+
+链路位置：
+    HookEngine._run_with_record() 调用 builder 构建 HOOK_PROGRESS.data，
+    避免在 engine 中手写 payload dict。
+
+当前裁剪范围：
+    仅处理四类 P2 执行器（command/http/prompt/agent）的展示元数据推导；
+    CLI 侧的 spinner suffix 推导与截断逻辑不在本模块。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .config import HookCandidate, HookSpec
+    from .types import HookContext
+
+# 模块常量：展示预览的最大长度（避免污染 TUI）
+# CLI 可根据需要进一步调整策略
+_MAX_PREVIEW_LENGTH = 120
+_TRUNCATION_SUFFIX = "..."
+
+
+def _truncate_preview(text: str) -> str:
+    """截断文本到最大预览长度。"""
+    if len(text) > _MAX_PREVIEW_LENGTH:
+        return text[:_MAX_PREVIEW_LENGTH] + _TRUNCATION_SUFFIX
+    return text
+
+
+def _extract_display_command(spec: HookSpec) -> str | None:
+    """从 command hook 提取展示用的 command（截断、脱敏）。"""
+    cmd = spec.config.get("command")
+    if isinstance(cmd, str) and cmd.strip():
+        return _truncate_preview(cmd.strip())
+    return None
+
+
+def _extract_prompt_text(spec: HookSpec) -> str | None:
+    """从 prompt/agent hook 提取 prompt_text（截断）。"""
+    prompt = spec.config.get("prompt")
+    if isinstance(prompt, str) and prompt.strip():
+        return _truncate_preview(prompt.strip())
+    return None
+
+
+def _get_status_message(spec: HookSpec) -> str | None:
+    """从 HookSpec.config 读取 status_message（snake_case 契约）。"""
+    msg = spec.config.get("status_message")
+    if isinstance(msg, str) and msg.strip():
+        return msg.strip()
+    return None
+
+
+class HookProgressPayloadBuilder:
+    """Hook Progress 展示元数据构建器。
+
+    职责边界：
+    - 输入：HookCandidate + HookContext
+    - 输出：包含 status_message/command/prompt_text/executor_type 的 payload dict
+    - 不做：CLI spinner suffix 拼接、UI 文案生成、HookContext 污染
+
+    设计原则：
+    - SDK 输出稳定元数据字段，CLI 负责展示逻辑
+    - command/prompt_text 提供截断预览，CLI 可进一步处理
+    - executor_type 固定输出，帮助 CLI 分类处理
+    """
+
+    def build(self, candidate: "HookCandidate", ctx: "HookContext") -> dict[str, Any]:
+        """构建 HOOK_PROGRESS.data payload。
+
+        Returns:
+            包含以下字段的 dict：
+            - hook_id: per-script hook ID
+            - hook_name: 展示名（config.name 优先）
+            - hook_event: 事件类型
+            - executor_type: 执行器类型（command/http/prompt/agent 等）
+            - status_message: 自定义状态消息（可选）
+            - command: command hook 的展示命令（仅 executor_type == "command"）
+            - prompt_text: prompt/agent hook 的 prompt 预览（仅相关类型）
+            - tool_call_id: 工具调用 ID
+            - session_id: 会话 ID
+            - node_level: 是否为节点级事件
+            - phase: "running"
+        """
+        spec = candidate.spec
+
+        # 基础字段
+        payload: dict[str, Any] = {
+            "hook_id": spec.hook_id,
+            "hook_name": str(spec.config.get("name") or spec.hook_id),
+            "hook_event": ctx.event.value,
+            "executor_type": spec.executor_type,
+            "tool_call_id": ctx.tool_call_id,
+            "session_id": ctx.session_id,
+            "node_level": False,
+            "phase": "running",
+        }
+
+        # 展示元数据：status_message（所有类型通用）
+        status_msg = _get_status_message(spec)
+        if status_msg:
+            payload["status_message"] = status_msg
+
+        # 展示元数据：command（仅 command hook）
+        if spec.executor_type == "command":
+            display_cmd = _extract_display_command(spec)
+            if display_cmd:
+                payload["command"] = display_cmd
+
+        # 展示元数据：prompt_text（仅 prompt/agent hook）
+        if spec.executor_type in ("prompt", "agent"):
+            prompt_preview = _extract_prompt_text(spec)
+            if prompt_preview:
+                payload["prompt_text"] = prompt_preview
+
+        return payload
+
+
+__all__ = [
+    "HookProgressPayloadBuilder",
+]

langchain_agentx/loop/hook/registry.py

@@ -159,19 +159,23 @@ class HookRegistry:
         once: bool = False,
         async_: bool = False,
         async_rewake: bool = False,
+        status_message: str | None = None,
     ) -> str:
         """注册 command hook。"""
+        config = {
+            "command": command,
+            "shell": shell,
+            "if": condition,
+            "once": once,
+            "async": async_,
+            "asyncRewake": async_rewake,
+        }
+        if status_message:
+            config["status_message"] = status_message
         spec = self._make_spec(
             event=event,
             executor_type="command",
-            config={
-                "command": command,
-                "shell": shell,
-                "if": condition,
-                "once": once,
-                "async": async_,
-                "asyncRewake": async_rewake,
-            },
+            config=config,
             matcher=matcher,
             timeout=timeout,
             source="session",
@@ -191,18 +195,22 @@ class HookRegistry:
         allowed_env_vars: list[str] | None = None,
         condition: str | None = None,
         once: bool = False,
+        status_message: str | None = None,
     ) -> str:
         """注册 http hook。"""
+        config = {
+            "url": url,
+            "headers": headers or {},
+            "allowedEnvVars": allowed_env_vars or [],
+            "if": condition,
+            "once": once,
+        }
+        if status_message:
+            config["status_message"] = status_message
         spec = self._make_spec(
             event=event,
             executor_type="http",
-            config={
-                "url": url,
-                "headers": headers or {},
-                "allowedEnvVars": allowed_env_vars or [],
-                "if": condition,
-                "once": once,
-            },
+            config=config,
             matcher=matcher,
             timeout=timeout,
             source="session",
@@ -222,6 +230,7 @@ class HookRegistry:
         model: str | None = None,
         condition: str | None = None,
         once: bool = False,
+        status_message: str | None = None,
     ) -> str:
         """注册 prompt hook。"""
         config: dict[str, Any] = {
@@ -232,6 +241,8 @@ class HookRegistry:
         }
         if model is not None:
             config["model"] = model
+        if status_message:
+            config["status_message"] = status_message
         spec = self._make_spec(
             event=event,
             executor_type="prompt",
@@ -255,6 +266,7 @@ class HookRegistry:
         model: str | None = None,
         condition: str | None = None,
         once: bool = False,
+        status_message: str | None = None,
     ) -> str:
         """注册 agent hook。"""
         config: dict[str, Any] = {
@@ -265,6 +277,8 @@ class HookRegistry:
         }
         if model is not None:
             config["model"] = model
+        if status_message:
+            config["status_message"] = status_message
         spec = self._make_spec(
             event=event,
             executor_type="agent",