langchain-agentx-python 1.5.6__tar.gz → 1.5.8__tar.gz

{langchain-agentx-python-1.5.6/langchain_agentx_python.egg-info → langchain-agentx-python-1.5.8}/PKG-INFO

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

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/loop/subagent/progress.py

@@ -1,11 +1,14 @@
 """Subagent Progress Event 数据结构
 
-职责：进度事件载荷（Channel B）
-在整体链路中的位置：runner.py 构造 → AgentRuntimeTool.invoke() 的 on_progress 回调消费
+职责：进度事件载荷（teaser lane + transcript lane）
+在整体链路中的位置：runner.py 构造 → progress_dispatcher → adapter 映射
 CC 对照：src/agent/subagent/progress.ts onProgress 回调参数类型
-当前裁剪范围：v1 基础事件类型，无 async 路径
+当前裁剪范围：teaser（tool_use/tool_result）+ transcript_message lane；model_step 仅 trace
 """
 
+# transcript lane 在 tool_progress custom event 上的 phase 值（与 adapter mapper 冻结一致）
+SUBAGENT_TRANSCRIPT_PHASE = "transcript_message"
+
 from dataclasses import dataclass, field
 from typing import Any, Literal
 
@@ -126,21 +129,38 @@ class SubagentExecutionTrace:
         ]
 
 
+@dataclass
+class SubagentTranscriptMessage:
+    """transcript lane 负载：完整规范化 message（非裸 token 流）。"""
+
+    message_kind: Literal["assistant", "user"]
+    message: dict[str, Any]
+
+
 @dataclass
 class SubagentProgressEvent:
     """子 Agent 进度事件（runner 内部 + trace 记录）。
 
     type 枚举：
-    - tool_use / tool_result: 对外 SSE 冒泡（经 _emit_progress → tool_progress）
+    - tool_use / tool_result: teaser lane → subagent-tool-call/result
+    - transcript_message: transcript lane → subagent-transcript-message
     - model_step: internal/trace-only，不 emit 到父 SSE（CC：Thinking 不折叠）
     - hint: 后台化提示（v2）
     - completed / error: internal/trace-only；边界由 adapter SUBAGENT_END 表达
 
     与 CC 对齐：
     - CC AgentTool.tsx 仅 forward tool_use/tool_result（L1106-1108）
-    - 本 SDK 通过 tool_call_detail 携带工具调用的详细信息（present_for_display / trace）
+    - transcript lane 承载规范化 assistant/user message（Capability C）
     """
-    type: Literal["tool_use", "tool_result", "model_step", "hint", "completed", "error"]
+    type: Literal[
+        "tool_use",
+        "tool_result",
+        "transcript_message",
+        "model_step",
+        "hint",
+        "completed",
+        "error",
+    ]
     subagent_type: str = ""
     agent_id: str = ""
     step: int = 0
@@ -148,4 +168,5 @@ class SubagentProgressEvent:
     summary: str = ""
     meta: dict[str, Any] = field(default_factory=dict)
     tool_call_detail: SubagentToolCall | None = None
+    transcript_message: SubagentTranscriptMessage | None = None
     trace: SubagentExecutionTrace | None = None

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/loop/subagent/progress_dispatcher.py

@@ -1,10 +1,10 @@
 """
 loop/subagent/progress_dispatcher.py — 子 Agent tool_progress 冒泡
 
-职责：将 runner 侧 tool_use/tool_result 同步派发到父 graph 回调链。
-链路位置：runner._emit_progress → SubagentProgressDispatcher
+职责：将 runner 侧 teaser / transcript lane 同步派发到父 graph 回调链。
+链路位置：runner._emit_progress / _emit_transcript_progress → SubagentProgressDispatcher
 当前裁剪范围：并行线程池 / _run_coroutine_sync 子线程内同步 dispatch 优先；
-              不新增 SSE 类型；仅 phase ∈ {tool_use, tool_result}。
+              phase ∈ {tool_use, tool_result, transcript_message}；同桶不同 lane。
 """
 
 from __future__ import annotations
@@ -13,7 +13,10 @@ import logging
 from typing import Any
 
 from langchain_agentx.loop.subagent.context import SubagentContext
-from langchain_agentx.loop.subagent.progress import SubagentProgressEvent
+from langchain_agentx.loop.subagent.progress import (
+    SUBAGENT_TRANSCRIPT_PHASE,
+    SubagentProgressEvent,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -24,7 +27,7 @@ class SubagentProgressDispatcher:
     """子 Agent progress → 父 graph custom event 派发器。"""
 
     @staticmethod
-    def build_payload(
+    def build_teaser_payload(
         ctx: SubagentContext,
         event: SubagentProgressEvent,
     ) -> dict[str, Any]:
@@ -43,6 +46,27 @@ class SubagentProgressDispatcher:
             event_data["tool_input"] = dict(event.tool_call_detail.tool_input)
         return event_data
 
+    @staticmethod
+    def build_transcript_payload(
+        ctx: SubagentContext,
+        event: SubagentProgressEvent,
+    ) -> dict[str, Any]:
+        transcript = event.transcript_message
+        if transcript is None:
+            raise ValueError("transcript_message required for transcript lane dispatch")
+        return {
+            "tool_call_id": ctx.parent_tool_call_id,
+            "agent_id": event.agent_id,
+            "phase": SUBAGENT_TRANSCRIPT_PHASE,
+            "step": event.step,
+            "tool_name": event.tool_name,
+            "message_kind": transcript.message_kind,
+            "message": dict(transcript.message),
+            "data": {
+                "subagent_type": event.subagent_type,
+            },
+        }
+
     @classmethod
     def dispatch_sync(cls, parent_config: Any, payload: dict[str, Any]) -> bool:
         """同步派发；在线程池 worker 内可达父 astream_events（须带 runnable_config）。"""
@@ -53,7 +77,11 @@ class SubagentProgressDispatcher:
         try:
             dispatch_custom_event(_EVENT_NAME, payload, config=parent_config)
             return True
-        except RuntimeError:
+        except RuntimeError as exc:
+            logger.debug(
+                "dispatch_custom_event sync path unavailable (will try async): %s",
+                exc,
+            )
             return False
         except Exception:
             logger.debug("dispatch_custom_event failed in subagent progress", exc_info=True)

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/loop/subagent/runner.py

@@ -63,8 +63,12 @@ from langchain_agentx.observability.events.tool_outcome_resolver import (
 from langchain_agentx.loop.subagent.progress import (
     SubagentExecutionTrace,
     SubagentProgressEvent,
+    SubagentTranscriptMessage,
 )
 from langchain_agentx.loop.subagent.progress_dispatcher import SubagentProgressDispatcher
+from langchain_agentx.loop.subagent.transcript_message_builder import (
+    SubagentTranscriptMessageBuilder,
+)
 from langchain_agentx.loop.subagent.subagent_termination_classifier import (
     SubagentTerminationClassifier,
 )
@@ -210,7 +214,7 @@ async def _emit_progress(
     ctx: SubagentContext,
     event: SubagentProgressEvent,
 ) -> None:
-    """发射子 Agent 工具进度到父 graph（CC 对齐：仅 tool_use / tool_result）。
+    """发射子 Agent teaser lane 到父 graph（CC 对齐：仅 tool_use / tool_result）。
 
     同步 dispatch 优先：并行线程池 / _run_coroutine_sync 子线程内 adispatch 无法触达父回调链。
     父 graph 的 config 通过 ctx.runnable_config 传递（在 _collect_subagent_events 中合并）。
@@ -229,7 +233,27 @@ async def _emit_progress(
     if parent_config is None:
         return
 
-    payload = SubagentProgressDispatcher.build_payload(ctx, event)
+    payload = SubagentProgressDispatcher.build_teaser_payload(ctx, event)
+    if SubagentProgressDispatcher.dispatch_sync(parent_config, payload):
+        return
+    await SubagentProgressDispatcher.dispatch_async(parent_config, payload)
+
+
+async def _emit_transcript_progress(
+    ctx: SubagentContext,
+    event: SubagentProgressEvent,
+) -> None:
+    """发射子 Agent transcript lane（Capability C：规范化 assistant/user message）。"""
+    if event.type != "transcript_message" or event.transcript_message is None:
+        return
+    if not event.tool_name:
+        return
+
+    parent_config = getattr(ctx, "runnable_config", None)
+    if parent_config is None:
+        return
+
+    payload = SubagentProgressDispatcher.build_transcript_payload(ctx, event)
     if SubagentProgressDispatcher.dispatch_sync(parent_config, payload):
         return
     await SubagentProgressDispatcher.dispatch_async(parent_config, payload)
@@ -268,6 +292,10 @@ async def _handle_tool_start_event(
     if trace:
         trace.add_tool_call(tool_call)
 
+    tool_call_id = ToolCallIdResolver.resolve_from_langgraph_tool_event(event)
+    if not tool_call_id:
+        tool_call_id = f"{SYNTHETIC_TRANSCRIPT_TOOL_ID_PREFIX}{ctx.agent_id}:{next_step}"
+
     await _emit_progress(
         ctx,
         SubagentProgressEvent(
@@ -281,6 +309,26 @@ async def _handle_tool_start_event(
             trace=trace,
         ),
     )
+
+    message_kind, normalized = SubagentTranscriptMessageBuilder.build_tool_use(
+        tool_name=tool_name,
+        tool_input=tool_input if isinstance(tool_input, dict) else None,
+        tool_call_id=tool_call_id,
+    )
+    await _emit_transcript_progress(
+        ctx,
+        SubagentProgressEvent(
+            type="transcript_message",
+            subagent_type=ctx.subagent_type,
+            agent_id=ctx.agent_id,
+            step=next_step,
+            tool_name=tool_name,
+            transcript_message=SubagentTranscriptMessage(
+                message_kind=message_kind,
+                message=normalized,
+            ),
+        ),
+    )
     return next_step, tool_name
 
 
@@ -357,6 +405,27 @@ async def _handle_tool_end_event(
         ),
     )
 
+    message_kind, normalized = SubagentTranscriptMessageBuilder.build_tool_result(
+        tool_name=tool_name,
+        content=transcript_text,
+        tool_call_id=tool_call_id,
+        synthetic=synthetic,
+    )
+    await _emit_transcript_progress(
+        ctx,
+        SubagentProgressEvent(
+            type="transcript_message",
+            subagent_type=ctx.subagent_type,
+            agent_id=ctx.agent_id,
+            step=step,
+            tool_name=tool_name,
+            transcript_message=SubagentTranscriptMessage(
+                message_kind=message_kind,
+                message=normalized,
+            ),
+        ),
+    )
+
 
 async def _handle_chat_model_end_event(
     *,

langchain-agentx-python-1.5.8/langchain_agentx/loop/subagent/transcript_message_builder.py

@@ -0,0 +1,62 @@
+"""
+loop/subagent/transcript_message_builder.py — 子 Agent transcript lane 规范化 message 构造
+
+职责：在工具开始/结束点构造 CC 对齐的 assistant / user 规范化 message。
+链路位置：runner._handle_tool_* → SubagentTranscriptMessageBuilder → progress_dispatcher
+当前裁剪范围：仅 tool_use / tool_result；不承载纯 text / thinking 流。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from langchain_agentx.loop.message_contract import get_message_contract
+
+MessageKind = Literal["assistant", "user"]
+
+
+class SubagentTranscriptMessageBuilder:
+    """构造 transcript lane 用的规范化 message（对齐 CC agent_progress.data.message）。"""
+
+    @staticmethod
+    def build_tool_use(
+        *,
+        tool_name: str,
+        tool_input: dict[str, Any] | None,
+        tool_call_id: str,
+    ) -> tuple[MessageKind, dict[str, Any]]:
+        """工具开始：assistant message，content 含 tool_use（LangChain tool_calls）。"""
+        args = dict(tool_input) if isinstance(tool_input, dict) else {}
+        record: dict[str, Any] = {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": tool_call_id,
+                    "name": tool_name,
+                    "args": args,
+                }
+            ],
+        }
+        normalized = get_message_contract().to_transcript_row(record)
+        return "assistant", normalized
+
+    @staticmethod
+    def build_tool_result(
+        *,
+        tool_name: str,
+        content: str,
+        tool_call_id: str,
+        synthetic: bool = False,
+    ) -> tuple[MessageKind, dict[str, Any]]:
+        """工具结束：user 侧 tool result message（经 transcript codec 规范化）。"""
+        row = get_message_contract().to_transcript_tool_row(
+            content=content,
+            tool_call_id=tool_call_id,
+            name=tool_name,
+            synthetic=synthetic,
+        )
+        return "user", row
+
+
+__all__ = ["MessageKind", "SubagentTranscriptMessageBuilder"]

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/observability/events/agent_event_projector.py

@@ -38,6 +38,9 @@ from langchain_agentx.observability.events.subagent_event_mapper import (
     SubagentBoundaryPayloadBuilder,
     SubagentProgressEventMapper,
 )
+from langchain_agentx.observability.events.subagent_window_text_guard import (
+    SubagentWindowTextGuard,
+)
 from langchain_agentx.observability.events.tool_call_id_resolver import (
     ToolCallIdResolver,
 )
@@ -115,6 +118,7 @@ class LangchainAgentEventType(Enum):
     SUBAGENT_END = "subagent-end"
     SUBAGENT_TOOL_CALL = "subagent-tool-call"
     SUBAGENT_TOOL_RESULT = "subagent-tool-result"
+    SUBAGENT_TRANSCRIPT_MESSAGE = "subagent-transcript-message"
     SUBAGENT_MODEL_STEP = "subagent-model-step"
     ERROR = "error"
     TOOL_ARTIFACT = "tool-artifact"
@@ -150,6 +154,9 @@ class EventAdapterState:
     current_tool: Optional[str] = None
     tool_input_chunks: list[str] = field(default_factory=list)
     subagent_boundary_by_tool_call_id: Dict[str, Dict[str, str]] = field(default_factory=dict)
+    subagent_window_text_guard: SubagentWindowTextGuard = field(
+        default_factory=SubagentWindowTextGuard
+    )
     accumulated_answer: str = ""
     accumulated_reasoning: str = ""
     last_chain_end_name: str = ""
@@ -267,58 +274,6 @@ class AgentEventProjector:
     def reset_state(self) -> None:
         self.state = EventAdapterState()
 
-    def emit_subagent_event(self, progress_event: Any) -> LangchainAgentEvent | None:
-        from langchain_agentx.loop.subagent.progress import SubagentProgressEvent
-
-        if not isinstance(progress_event, SubagentProgressEvent):
-            return None
-
-        event_type = getattr(progress_event, "type", "")
-        if not event_type:
-            return None
-
-        type_mapping = {
-            "tool_use": LangchainAgentEventType.TOOL_CALL,
-            "tool_result": LangchainAgentEventType.TOOL_RESULT,
-            "model_step": LangchainAgentEventType.TEXT_DELTA,
-            "completed": None,
-            "hint": None,
-        }
-
-        target_type = type_mapping.get(event_type)
-        if target_type is None:
-            return None
-
-        data: Dict[str, Any] = {}
-        if event_type == "tool_use":
-            data = {
-                "tool_name": getattr(progress_event, "tool_name", ""),
-                "status": "running",
-            }
-            detail = getattr(progress_event, "tool_call_detail", None)
-            if detail is not None:
-                data["input"] = getattr(detail, "tool_input", None)
-                data["step"] = getattr(detail, "step", None)
-        elif event_type == "tool_result":
-            data = {
-                "tool_name": getattr(progress_event, "tool_name", ""),
-                "summary": getattr(progress_event, "summary", "")[:200],
-            }
-        elif event_type == "model_step":
-            data = {"text": getattr(progress_event, "summary", "")}
-
-        parent_id = getattr(progress_event, "parent_tool_use_id", None)
-        if parent_id:
-            data["parent_tool_use_id"] = parent_id
-
-        return self._event(
-            event_type=target_type,
-            data=data,
-            step_index=self.state.step_index or None,
-            tool_name=getattr(progress_event, "tool_name", None),
-            session_id=self.state.session_id,
-        )
-
     async def _handle_chain_start(
         self, name: str, data: Dict[str, Any]
     ) -> AsyncGenerator[LangchainAgentEvent, None]:
@@ -469,6 +424,16 @@ class AgentEventProjector:
         snapshot = self.state.subagent_boundary_by_tool_call_id.pop(tool_call_id, {})
         return snapshot.get("agent_id", ""), snapshot.get("subagent_type", "")
 
+    def _should_suppress_main_tier_text_stream(self) -> bool:
+        """D28 SDK-1：子 Agent 窗口内不 emit 父 main-tier TEXT_* / REASONING_*。"""
+        return self.state.subagent_window_text_guard.should_suppress_main_tier_stream
+
+    def _on_subagent_start_boundary(self) -> None:
+        self.state.subagent_window_text_guard.on_subagent_start()
+
+    def _on_subagent_end_boundary(self) -> None:
+        self.state.subagent_window_text_guard.on_subagent_end()
+
     def _hook_event_from_name(self, name: str) -> str:
         mapping = {
             "hook_loop_start": "loop_start",
@@ -842,6 +807,9 @@ class AgentEventProjector:
         if not chunk:
             return
 
+        if self._should_suppress_main_tier_text_stream():
+            return
+
         reasoning_segments: list[str] = []
         text_segments: list[str] = []
 
@@ -948,6 +916,11 @@ class AgentEventProjector:
     async def _handle_model_end(
         self, name: str, data: Dict[str, Any]
     ) -> AsyncGenerator[Optional[LangchainAgentEvent], None]:
+        if self._should_suppress_main_tier_text_stream():
+            self.state.subagent_window_text_guard.reset_active_stream_flags(self.state)
+            self.state.is_model_started = False
+            return
+
         if self.enable_reasoning_events and self.state.is_reasoning_active:
             yield self._event(
                 event_type=LangchainAgentEventType.REASONING_END,
@@ -1073,6 +1046,7 @@ class AgentEventProjector:
                 step_index=self.state.step_index,
                 tool_name=name,
             )
+            self._on_subagent_start_boundary()
 
         if self.synthesize_tool_call:
             yield self._event(
@@ -1124,6 +1098,7 @@ class AgentEventProjector:
                 tool_name=name,
                 session_id=str(child_session_id) if child_session_id else None,
             )
+            self._on_subagent_end_boundary()
 
         self.state.current_tool = None
 
@@ -1373,11 +1348,8 @@ class AgentEventProjector:
                         tool_name=mapped.tool_name,
                     )
                     return
-                agent_id = data.get("agent_id")
-                if isinstance(agent_id, str) and agent_id.strip():
-                    phase = data.get("phase")
-                    if phase == "model_step":
-                        return
+                if SubagentProgressEventMapper.should_suppress_tool_progress_fallback(data):
+                    return
 
             yield self._event(
                 event_type=LangchainAgentEventType.TOOL_PROGRESS,

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -76,9 +76,6 @@ class LangGraphToLangchainAgentEventAdapter:
     def _reset_state(self) -> None:
         self._projector.reset_state()
 
-    def emit_subagent_event(self, progress_event: Any) -> LangchainAgentEvent | None:
-        return self._projector.emit_subagent_event(progress_event)
-
     async def _handle_chain_start(
         self, name: str, data: Dict[str, Any]
     ) -> AsyncGenerator[LangchainAgentEvent, None]:

{langchain-agentx-python-1.5.6 → langchain-agentx-python-1.5.8}/langchain_agentx/observability/events/subagent_event_mapper.py

@@ -1,10 +1,10 @@
 """
 observability/events/subagent_event_mapper.py — 子 Agent SSE 事件映射
 
-职责：tool_progress → subagent-tool-* 分流；
+职责：tool_progress → subagent-tool-* / subagent-transcript-message 分流；
       subagent-start/end 边界 payload 构建。
 链路位置：LangGraphToLangchainAgentEventAdapter._handle_custom_event / _handle_tool_*。
-当前裁剪范围：仅 phase ∈ {tool_use, tool_result}；忽略 model_step / 未知 phase。
+当前裁剪范围：mapper 优先级 — transcript → teaser → drop（model_step 等不落 TOOL_PROGRESS）。
 """
 
 from __future__ import annotations
@@ -17,7 +17,11 @@ if TYPE_CHECKING:
         LangchainAgentEventType,
     )
 
-_SUBAGENT_TOOL_PHASES = frozenset({"tool_use", "tool_result"})
+_SUBAGENT_TRANSCRIPT_PHASE = "transcript_message"
+
+_SUBAGENT_TEASER_PHASES = frozenset({"tool_use", "tool_result"})
+_SUBAGENT_DROP_PHASES = frozenset({"model_step"})
+_SUBAGENT_KNOWN_PHASES = _SUBAGENT_TEASER_PHASES | _SUBAGENT_DROP_PHASES | {_SUBAGENT_TRANSCRIPT_PHASE}
 
 
 @dataclass(frozen=True)
@@ -66,7 +70,25 @@ class SubagentBoundaryPayloadBuilder:
 
 
 class SubagentProgressEventMapper:
-    """将 custom tool_progress 映射为 subagent-tool-call/result。"""
+    """将 custom tool_progress 映射为 subagent-tool-call/result 或 subagent-transcript-message。"""
+
+    @classmethod
+    def is_subagent_progress_with_agent_id(cls, data: dict[str, Any]) -> bool:
+        agent_id = data.get("agent_id")
+        return isinstance(agent_id, str) and bool(agent_id.strip())
+
+    @classmethod
+    def should_suppress_tool_progress_fallback(cls, data: dict[str, Any]) -> bool:
+        """未命中 mapper 的 subagent progress 不得落 TOOL_PROGRESS；主工具 progress（如 Bash running）除外。"""
+        if not cls.is_subagent_progress_with_agent_id(data):
+            return False
+        phase = data.get("phase")
+        if isinstance(phase, str) and phase in _SUBAGENT_KNOWN_PHASES:
+            return True
+        nested = data.get("data")
+        if isinstance(nested, dict) and nested.get("subagent_type"):
+            return True
+        return False
 
     @classmethod
     def map_custom_tool_progress(
@@ -80,14 +102,71 @@ class SubagentProgressEventMapper:
         if not isinstance(data, dict):
             return None
 
-        agent_id = data.get("agent_id")
-        if not isinstance(agent_id, str) or not agent_id.strip():
+        if not cls.is_subagent_progress_with_agent_id(data):
             return None
 
         phase = data.get("phase")
-        if not isinstance(phase, str) or phase not in _SUBAGENT_TOOL_PHASES:
+        if not isinstance(phase, str):
+            return None
+
+        if phase == _SUBAGENT_TRANSCRIPT_PHASE:
+            return cls._map_transcript(data, LangchainAgentEventType)
+
+        if phase in _SUBAGENT_DROP_PHASES:
+            return None
+
+        if phase not in _SUBAGENT_TEASER_PHASES:
             return None
 
+        return cls._map_teaser(data, phase, LangchainAgentEventType)
+
+    @classmethod
+    def _map_transcript(
+        cls,
+        data: dict[str, Any],
+        event_type_cls: type,
+    ) -> MappedSubagentProgress | None:
+        message = data.get("message")
+        if not isinstance(message, dict):
+            return None
+
+        message_kind = data.get("message_kind")
+        if message_kind not in ("assistant", "user"):
+            return None
+
+        agent_id = str(data.get("agent_id") or "")
+        nested = data.get("data")
+        nested_dict = nested if isinstance(nested, dict) else {}
+
+        step_raw = data.get("step", nested_dict.get("step", 0))
+        step = int(step_raw) if isinstance(step_raw, (int, float)) else 0
+
+        event_data: dict[str, Any] = {
+            "tool_call_id": str(data.get("tool_call_id") or ""),
+            "agent_id": agent_id,
+            "subagent_type": str(nested_dict.get("subagent_type") or ""),
+            "message_kind": message_kind,
+            "message": dict(message),
+            "step": step,
+        }
+        tool_name = str(data.get("tool_name") or "")
+        if tool_name:
+            event_data["tool_name"] = tool_name
+
+        return MappedSubagentProgress(
+            event_type=event_type_cls.SUBAGENT_TRANSCRIPT_MESSAGE,
+            data=event_data,
+            tool_name=tool_name or None,
+        )
+
+    @classmethod
+    def _map_teaser(
+        cls,
+        data: dict[str, Any],
+        phase: str,
+        event_type_cls: type,
+    ) -> MappedSubagentProgress:
+        agent_id = str(data.get("agent_id") or "")
         nested = data.get("data")
         nested_dict = nested if isinstance(nested, dict) else {}
 
@@ -108,16 +187,15 @@ class SubagentProgressEventMapper:
             "summary": summary,
         }
 
-        # 透传 tool_input（从 SDK runner 的 tool_progress 事件）
         tool_input = data.get("tool_input")
         if isinstance(tool_input, dict):
             event_data["tool_input"] = dict(tool_input)
 
         if phase == "tool_use":
-            target = LangchainAgentEventType.SUBAGENT_TOOL_CALL
+            target = event_type_cls.SUBAGENT_TOOL_CALL
             event_data["status"] = "running"
         else:
-            target = LangchainAgentEventType.SUBAGENT_TOOL_RESULT
+            target = event_type_cls.SUBAGENT_TOOL_RESULT
 
         return MappedSubagentProgress(
             event_type=target,