managed-agent-sdk 0.0.2__tar.gz → 0.0.3__tar.gz

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.3}/CHANGELOG.md

@@ -6,6 +6,59 @@ managed-agent-sdk（Python）的所有重要更新都会记录在这里。
 
 ## [未发布]
 
+## [0.0.3] - 2026-10-09
+
+### 🔒 安全
+
+- 不再泄漏 SecretId 与请求签名 —— 官方 SDK 会在 `DEBUG` 级别把完整
+  `Authorization` 头打进日志，现已将其 logger（`tencentcloud_sdk_common`）
+  钉在 `WARNING`。确需查看原始请求时，显式对该 logger 设 `DEBUG` 即可
+
+### ⚠️ 不兼容变更
+
+- 日志配置合并为 `LoggerOpts(enable, level, sink, file)`，删除
+  `ClientOpts` 上原有的 `log_level` 字段，`logger` 的类型由 `Logger` 改为 `LoggerOpts`。原写法
+  `ClientOpts(logger=..., log_level="debug")` 改为
+  `ClientOpts(logger=LoggerOpts(level="debug"))`
+- 控制台日志**默认开启**（`warn` 级别），原先默认静默。用
+  `LoggerOpts(enable=False)` 关闭；关闭后即使宿主配置了 root logger 也不输出
+
+### ✨ 新增
+
+- `prompt()` 返回值新增 `refusal`，携带服务端给出的结构化拒绝原因；
+  同时导出 `RefusalReason` 类型
+- `prompt()` 返回值新增 `trace_id`（本轮 W3C trace id）与 `usage`（本轮
+  token 消耗）；入参新增 `trace_id`，不传时自动生成，每轮通过
+  `traceparent` 请求头传给服务端。导出 `UsageInfo` 类型
+- 文件日志：配置 `LoggerOpts(file=LogFileOpts())` 后写入
+  `.wma-log/sdk-debug.log`，与控制台分别设置级别；凭据自动脱敏，按大小
+  轮转、按天清理
+- 接入伽利略上报：记录对话轮次的开始、结束、失败等事件，默认开启，可用
+  `TelemetryOpts(enabled=False)` 关闭。`aclose()` 会等待上报发送完成
+
+### 🐛 修复
+
+- 收到 401 时作废 token 缓存，不再反复用同一张已失效的票重试
+- `invalidate()` 补上世代守卫：换票在途时作废，其结果不再写回缓存
+
+### ✨ 优化
+
+- 补齐运行期日志：ACP 数据面（建连、重连、心跳、SSE）与 OneID 换票层
+  此前均无日志
+- 数据面日志改走 `ClientOpts.logger`，`log_level` 对其生效；传了 `logger`
+  未指定级别时按 `"warn"` 兜底
+- 控制面日志带上 TraceId，贯穿请求 / 响应 / 错误三条日志，并写入
+  `X-TC-TraceId` 请求头
+- 日志降噪：连接 ID 截断显示，不再逐次记录 token 缓存命中
+- 更正 `aclose()` 的文档说明 —— 它当前是空实现，不调用不会漏资源
+
+### 📖 文档
+
+- 快速开始简化为 3 步，去掉多余的 `versions.create()`
+- 新增「回复文本怎么拿」「版本要不要自己建」两节
+
+## [0.0.2] - 2026-09-22
+
 ### ✨ 优化
 
 - 优化部分功能

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: managed-agent-sdk
-Version: 0.0.2
+Version: 0.0.3
 Summary: Managed Agent SDK (Python) — 控制面走腾讯云 API，数据面走 ACP
 Project-URL: Homepage, https://cnb.cool/codebuddy/managed-agent-doc/-/tree/main/python
 Project-URL: Documentation, https://cnb.cool/codebuddy/managed-agent-doc/-/blob/main/python/api.md
@@ -67,15 +67,15 @@ import asyncio
 from managed_agent_sdk import (
     CreateAgentOpts,
     CreateSessionOpts,
-    CreateVersionOpts,
     ManagedAgentClient,
     ManifestBuilder,
+    PromptOpts,
 )
 
 
 async def main() -> None:
     async with ManagedAgentClient() as client:
-        # 创建 Agent
+        # 1. 创建 Agent —— 服务端顺带建好承载 manifest 的 default 版本
         agent = await client.agents.create(
             CreateAgentOpts(
                 agent_name="日志分析助手",
@@ -84,21 +84,17 @@ async def main() -> None:
             )
         )
 
-        # 创建版本（manifest 服务端必填）
-        version = await agent.versions.create(
-            CreateVersionOpts(
-                manifest=ManifestBuilder().system_prompt("你是日志分析专家").build(),
-            )
-        )
+        # 2. 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
+        session = await agent.sessions.create(CreateSessionOpts())
 
-        # 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
-        session = await agent.sessions.create(
-            CreateSessionOpts(version_id=version.version_id)
-        )
+        # 3. 对话。回复文本走 on_chunk，见下方说明
+        def on_chunk(n) -> None:
+            u = n.update
+            if u.sessionUpdate == "agent_message_chunk" and u.content.type == "text":
+                print(u.content.text, end="", flush=True)
 
-        # 对话
-        res = await session.prompt("分析这份日志")
-        print(res.stop_reason)
+        res = await session.prompt("分析这份日志", PromptOpts(on_chunk=on_chunk))
+        print(f"\nstop_reason: {res.stop_reason}")
 
         await session.disconnect()
 
@@ -106,7 +102,23 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-`prompt()` 的返回值只携带 `stop_reason`，回复文本从 `on_chunk` 取 —— 流式内容与终局结果分两条通道，这是 ACP 的协议设计。
+### 回复文本怎么拿
+
+`prompt()` 的返回值只携带 `stop_reason` 与 `refusal`，**不含回复正文** ——
+流式内容与终局结果分两条通道，这是 ACP 的协议设计。两条路都能拿到正文：
+
+- **`on_chunk`**（上面的写法）：实时增量，适合边生成边展示
+- **`session.messages()`**：轮次结束后按 `EventType == "ASSISTANT"` 取 `Message["Content"]`，
+  适合只要最终结果、不关心过程
+
+### 版本要不要自己建
+
+入门不需要。`agents.create()` 传了 `manifest` / `model` 时，服务端会建好一个
+`default` 版本承载它们；`sessions.create()` 不传 `version_id` 时按 Agent 的
+routing 配置分流，也会落到它。
+
+要灰度多个配置（A/B、逐步放量）时才用 `agent.versions.create()` 显式建版本，
+再配合 `agent.update_routing()` 分流。
 
 ## 配置连接器 / 技能 / 专家
 

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.3}/README.md

@@ -29,15 +29,15 @@ import asyncio
 from managed_agent_sdk import (
     CreateAgentOpts,
     CreateSessionOpts,
-    CreateVersionOpts,
     ManagedAgentClient,
     ManifestBuilder,
+    PromptOpts,
 )
 
 
 async def main() -> None:
     async with ManagedAgentClient() as client:
-        # 创建 Agent
+        # 1. 创建 Agent —— 服务端顺带建好承载 manifest 的 default 版本
         agent = await client.agents.create(
             CreateAgentOpts(
                 agent_name="日志分析助手",
@@ -46,21 +46,17 @@ async def main() -> None:
             )
         )
 
-        # 创建版本（manifest 服务端必填）
-        version = await agent.versions.create(
-            CreateVersionOpts(
-                manifest=ManifestBuilder().system_prompt("你是日志分析专家").build(),
-            )
-        )
+        # 2. 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
+        session = await agent.sessions.create(CreateSessionOpts())
 
-        # 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
-        session = await agent.sessions.create(
-            CreateSessionOpts(version_id=version.version_id)
-        )
+        # 3. 对话。回复文本走 on_chunk，见下方说明
+        def on_chunk(n) -> None:
+            u = n.update
+            if u.sessionUpdate == "agent_message_chunk" and u.content.type == "text":
+                print(u.content.text, end="", flush=True)
 
-        # 对话
-        res = await session.prompt("分析这份日志")
-        print(res.stop_reason)
+        res = await session.prompt("分析这份日志", PromptOpts(on_chunk=on_chunk))
+        print(f"\nstop_reason: {res.stop_reason}")
 
         await session.disconnect()
 
@@ -68,7 +64,23 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-`prompt()` 的返回值只携带 `stop_reason`，回复文本从 `on_chunk` 取 —— 流式内容与终局结果分两条通道，这是 ACP 的协议设计。
+### 回复文本怎么拿
+
+`prompt()` 的返回值只携带 `stop_reason` 与 `refusal`，**不含回复正文** ——
+流式内容与终局结果分两条通道，这是 ACP 的协议设计。两条路都能拿到正文：
+
+- **`on_chunk`**（上面的写法）：实时增量，适合边生成边展示
+- **`session.messages()`**：轮次结束后按 `EventType == "ASSISTANT"` 取 `Message["Content"]`，
+  适合只要最终结果、不关心过程
+
+### 版本要不要自己建
+
+入门不需要。`agents.create()` 传了 `manifest` / `model` 时，服务端会建好一个
+`default` 版本承载它们；`sessions.create()` 不传 `version_id` 时按 Agent 的
+routing 配置分流，也会落到它。
+
+要灰度多个配置（A/B、逐步放量）时才用 `agent.versions.create()` 显式建版本，
+再配合 `agent.update_routing()` 分流。
 
 ## 配置连接器 / 技能 / 专家
 

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.3}/src/managed_agent_sdk/__init__.py

@@ -49,9 +49,11 @@ from .acp_types import (
     EmbeddedResource,
     ImageContent,
     PromptResponse,
+    RefusalReason,
     ResourceLink,
     SessionNotification,
     TextContent,
+    UsageInfo,
 )
 from .agent import (
     Agent,
@@ -129,7 +131,9 @@ from .opts import (
     Credentials,
     Filter,
     Language,
+    LogFileOpts,
     Logger,
+    LoggerOpts,
     LogLevel,
     Page,
     PageOpts,
@@ -139,6 +143,7 @@ from .opts import (
     SortDirection,
 )
 from .session import MessageListOpts, PromptOpts, Session
+from .telemetry import TelemetryOpts, TurnTelemetryOpts
 from .types import (
     A2AConfig,
     A2ASkillItem,
@@ -194,6 +199,7 @@ __all__ = [
     "ResourceLink",
     "EmbeddedResource",
     "PromptResponse",
+    "RefusalReason",
     "SessionNotification",
     "AcpConnectionState",
     "NotificationListener",
@@ -226,6 +232,8 @@ __all__ = [
     "UpdateVersionOpts",
     "MessageListOpts",
     "PromptOpts",
+    "TelemetryOpts",
+    "TurnTelemetryOpts",
     "A2ASkill",
     "ListConnectorsOpts",
     "ListSkillsOpts",
@@ -296,8 +304,11 @@ __all__ = [
     "Filter",
     "Credentials",
     "Logger",
+    "LogFileOpts",
+    "LoggerOpts",
     "LogLevel",
     "Language",
+    "UsageInfo",
     # ── 错误 ────────────────────────────────
     "CloudAgentError",
     "ValidationError",

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.3}/src/managed_agent_sdk/_version.py

@@ -8,7 +8,7 @@
 
 import platform
 
-__version__ = "0.0.2"
+__version__ = "0.0.3"
 
 #: 请求头 ``User-Agent`` 的值。
 #:

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.3}/src/managed_agent_sdk/acp/client.py

@@ -21,7 +21,13 @@ import logging
 from collections import defaultdict, deque
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from acp import Client
+from acp.client import ClientSideConnection
+from acp.exceptions import RequestError
+from acp.schema import DeniedOutcome, RequestPermissionResponse, SessionNotification
+from pydantic import ValidationError as PydanticValidationError
 
 from managed_agent_sdk._generated.defaults import (
     ACP_HEARTBEAT_TIMEOUT_MS,
@@ -37,9 +43,17 @@ from managed_agent_sdk.acp.transport import (
     TransportOptions,
 )
 from managed_agent_sdk.errors import AcpAuthError, AcpNetworkError, AcpProtocolError
+from managed_agent_sdk.opts import (
+    FileSinkLike,
+    LeveledLogger,
+    Logger,
+    LogLevel,
+    short_conn_id,
+)
+from managed_agent_sdk.telemetry import AcpPostInfo, AcpSseConnectInfo
 
 if TYPE_CHECKING:
-    from acp.schema import PromptResponse, SessionNotification
+    from acp.schema import PromptResponse
 
     from managed_agent_sdk.opts import ConnectOpts
 
@@ -108,33 +122,35 @@ class _NotificationRouter:
         self,
         dispatch: Callable[[Any], None],
         get_connection_id: Callable[[], str | None] | None = None,
+        log: LeveledLogger | None = None,
     ) -> None:
         self._dispatch = dispatch
         self._get_connection_id = get_connection_id
+        # 未注入时退化为「模块级 logger + 不过滤」，与 LeveledLogger 的回退一致
+        self._log = log if log is not None else LeveledLogger(None, None)
 
     def _conn_tag(self) -> str:
-        """返回当前 connection_id（日志前缀用）；未连接时返回 ``-``。"""
+        """返回当前 connection_id 的短形式（日志前缀用）；未连接时返回 ``-``。
+
+        截断到 12 位：完整 ID 是 141 字符的 base64，会把日志行撑到 180+ 字符。
+        需要完整值时看传输层建连那条 ``connected (full id: …)``。
+        """
         if self._get_connection_id is None:
             return "-"
-        cid = self._get_connection_id()
-        return cid if cid else "-"
+        return short_conn_id(self._get_connection_id())
 
-    async def session_update(
-        self, session_id: str, update: Any, **_kwargs: Any
-    ) -> None:
+    async def session_update(self, session_id: str, update: Any, **_kwargs: Any) -> None:
         """每条 session/update notification 都走这里。
 
         注意：官方 router 已经把 payload 展开为字段，这里重新组装成一个
         ``SessionNotification`` 实例供用户订阅者消费（保留 Pydantic 类型安全）。
         """
-        from acp.schema import SessionNotification
-
         notification = SessionNotification(session_id=session_id, update=update)
         self._dispatch(notification)
 
     async def ext_notification(self, method: str, params: Any) -> None:
         """扩展通知（如 _codebuddy.ai/* ）—— 当前忽略。"""
-        logger.debug(
+        self._log.debug(
             "[acp conn=%s] ignore ext_notification: method=%s",
             self._conn_tag(),
             method,
@@ -151,9 +167,7 @@ class _NotificationRouter:
 
     async def request_permission(self, **_kwargs: Any) -> Any:
         """服务端发 request_permission 时返回 "用户取消"（协议合法拒绝）。"""
-        from acp.schema import DeniedOutcome, RequestPermissionResponse
-
-        logger.debug(
+        self._log.debug(
             "[acp conn=%s] request_permission received but no permission handler configured "
             "— responding with cancelled outcome",
             self._conn_tag(),
@@ -187,8 +201,6 @@ class _NotificationRouter:
 
 def _raise_method_not_found(method: str) -> None:
     """抛 ACP 标准的 ``-32601 method not found``（由协议包翻成 JSON-RPC error）。"""
-    from acp.exceptions import RequestError
-
     raise RequestError.method_not_found(method)
 
 
@@ -212,22 +224,24 @@ class RawSessionNotification:
     """原始 update 负载（dict）。"""
 
 
-def _parse_session_notification(params: dict[str, Any], session_id: str) -> Any:
+def _parse_session_notification(
+    params: dict[str, Any], session_id: str, log: LeveledLogger | None = None
+) -> Any:
     """把 ``session/update`` 的 params 解析成通知对象。
 
     已知 ``sessionUpdate`` 取值产出 :class:`acp.schema.SessionNotification`，
     与协议包自己解析的结果完全一致；未知取值降级为
     :class:`RawSessionNotification`，不丢消息。
     """
-    from acp.schema import SessionNotification
-    from pydantic import ValidationError
-
     try:
         return SessionNotification.model_validate(params)
-    except ValidationError:
-        logger.debug(
-            "[acp] session/update with unrecognized payload, delivering raw: %r",
-            params.get("update"),
+    except PydanticValidationError:
+        # 只记类型名，不记 payload —— update 里有用户对话正文
+        update = params.get("update")
+        kind = update.get("sessionUpdate") if isinstance(update, dict) else None
+        (log or LeveledLogger(None, None)).debug(
+            "[acp] session/update unrecognized (sessionUpdate=%s), delivering raw",
+            kind or "?",
         )
         return RawSessionNotification(session_id=session_id, update=params.get("update"))
 
@@ -241,20 +255,35 @@ class AcpClient:
     def __init__(
         self,
         *,
-        client_logger: Any = None,
+        client_logger: Logger | None = None,
+        log_level: LogLevel | None = None,
+        file_sink: FileSinkLike | None = None,
         transport: Any = None,
+        on_post_complete: Callable[[AcpPostInfo], None] | None = None,
+        on_sse_connect_attempt: Callable[[AcpSseConnectInfo], None] | None = None,
     ) -> None:
         """构造 ACP 客户端。
 
         Args:
             client_logger: 调用方经 ``ClientOpts.logger`` 传入的日志器。
-                为 ``None`` 时用模块级 ``logging.getLogger("managed_agent_sdk")``。
+                为 ``None`` 时回退模块级 ``logging.getLogger("managed_agent_sdk")``。
                 对应 Node 侧把 logger 透传给 ``AcpClient`` 的做法 —— 缺了它，
                 ``ClientOpts.logger`` 对数据面完全无效。
+            log_level: 日志级别，经 ``ClientOpts.log_level`` 传入。仅在显式注入
+                ``client_logger`` 时生效 —— 回退到模块级 logger 时交给宿主的
+                logging 配置，不在这里二次过滤。
+            file_sink: 诊断日志文件出口，经 ``ClientOpts.logger.file`` 开启时由
+                ``ManagedAgentClient`` 注入。与控制台各自判级，互不影响。
             transport: 替换 HTTP 传输层（``httpx.AsyncBaseTransport``），
                 对应 Node 侧的 ``ClientOpts.fetch``。
         """
-        self._logger: Any = client_logger if client_logger is not None else logger
+        self._log_level = log_level
+        self._client_logger = client_logger
+        self._file_sink = file_sink
+        self._logger = LeveledLogger(client_logger, log_level, file_sink)
+        # 埋点路径 span 的数据源，原样交给传输层
+        self._on_post_complete = on_post_complete
+        self._on_sse_connect_attempt = on_sse_connect_attempt
         self._transport_override = transport
         self._state: AcpConnectionState = "INITIAL"
 
@@ -263,6 +292,8 @@ class AcpClient:
         self._initialize_result: Any = None
 
         self._token_provider: Callable[[], Awaitable[str]] | None = None
+        #: 作废 token 缓存 —— 传输层收到 401 时调用，与 ``_token_provider`` 同源。
+        self._token_invalidator: Callable[[], None] | None = None
 
         # session_id -> set[listener]
         self._subscribers: dict[str, set[NotificationListener]] = defaultdict(set)
@@ -295,14 +326,24 @@ class AcpClient:
     def initialized(self) -> bool:
         return self._initialize_result is not None
 
-    def set_token_provider(self, fn: Callable[[], Awaitable[str]]) -> None:
-        """注入取 token 函数。
+    def set_token_provider(
+        self,
+        fn: Callable[[], Awaitable[str]],
+        invalidate: Callable[[], None] | None = None,
+    ) -> None:
+        """注入取 token 与作废回调。
 
-        传输层**每次请求**（建连 / 重连 / POST / DELETE）前调用；实现方负责
-        缓存与临期刷新。必须每次都取：OneID token 有效期 30 天，长连接会
+        传输层**每次请求**（建连 / 重连 / POST / DELETE）前调用 ``fn``；实现方
+        负责缓存与临期刷新。必须每次都取：OneID token 有效期 30 天，长连接会
         跨过它，只在建连时取一次的话过期后所有请求都带着废票发。
+
+        ``invalidate`` 在传输层收到 **401** 时调用，与 ``fn`` 同源：401 说明那张
+        票已被服务端拒，而它在本地可能还没到期 —— 不作废的话 ``fn()`` 会一直
+        命中缓存返回废票，401 反复出现直到本地有效期走完。静态 token 场景没有
+        缓存可作废，可以省略。
         """
         self._token_provider = fn
+        self._token_invalidator = invalidate
 
     def _conn_tag(self) -> str:
         """返回当前 connection_id（日志前缀用）；未连接时返回 ``-``。"""
@@ -318,6 +359,7 @@ class AcpClient:
         opts: ConnectOpts | None = None,
         *,
         http_client: Any = None,
+        ephemeral_headers: dict[str, str] | None = None,
     ) -> None:
         """建立 ACP 连接。
 
@@ -331,16 +373,12 @@ class AcpClient:
         self._state = "CONNECTING"
 
         # 从 ConnectOpts 读重连 / 心跳参数（默认值来自 spec/defaults.yaml）
-        heartbeat_ms = (
-            opts.heartbeat_timeout_ms if opts is not None else ACP_HEARTBEAT_TIMEOUT_MS
-        )
+        heartbeat_ms = opts.heartbeat_timeout_ms if opts is not None else ACP_HEARTBEAT_TIMEOUT_MS
         reconnect_init_ms = (
             opts.reconnect_backoff_ms if opts is not None else ACP_RECONNECT_BACKOFF_MS
         )
         reconnect_max_ms = (
-            opts.reconnect_max_backoff_ms
-            if opts is not None
-            else ACP_RECONNECT_MAX_BACKOFF_MS
+            opts.reconnect_max_backoff_ms if opts is not None else ACP_RECONNECT_MAX_BACKOFF_MS
         )
         reconnect_max = opts.reconnect_max_attempts if opts is not None else float("inf")
 
@@ -351,11 +389,19 @@ class AcpClient:
                 endpoint=acp_url,
                 auth_token=token,
                 get_token=self._token_provider,
+                invalidate_token=self._token_invalidator,
                 # UA 在前：调用方显式传的同名头优先
                 headers={
                     "User-Agent": USER_AGENT,
                     **(dict(opts.headers) if opts is not None and opts.headers else {}),
                 },
+                logger=self._client_logger,
+                log_level=self._log_level,
+                file_sink=self._file_sink,
+                # 建连发生在某一轮 prompt 内时，本轮 trace 从第一个 GET 就带上
+                ephemeral_headers=ephemeral_headers,
+                on_post_complete=self._on_post_complete,
+                on_sse_connect_attempt=self._on_sse_connect_attempt,
                 heartbeat_timeout_ms=heartbeat_ms,
                 reconnect_initial_delay_ms=reconnect_init_ms,
                 reconnect_max_delay_ms=reconnect_max_ms,
@@ -372,6 +418,7 @@ class AcpClient:
             await transport.start()
         except TransportConnectError as e:
             self._state = "CLOSED"
+            await transport.aclose()
             # 状态码与 x-request-id 结构化带出，鉴权类单独成型 ——
             # 调用方据此决定是换票重连还是直接失败
             err_cls = AcpAuthError if e.non_retryable else AcpNetworkError
@@ -383,20 +430,13 @@ class AcpClient:
             ) from e
 
         # 连上 SSE → 构造官方 ClientSideConnection
-        # 运行时 import 避免 circular / 未装 agent-client-protocol 时 crash 太早
-        from typing import cast
-
-        from acp import Client
-        from acp.client import ClientSideConnection
-
         router = _NotificationRouter(
             self._dispatch_notification,
             get_connection_id=lambda: transport.connection_id,
+            log=self._logger,
         )
         try:
-            conn = ClientSideConnection(
-                cast(Client, router), transport.writer, transport.reader
-            )
+            conn = ClientSideConnection(cast(Client, router), transport)
         except Exception as e:
             self._state = "CLOSED"
             await transport.aclose()
@@ -433,9 +473,7 @@ class AcpClient:
             try:
                 await self._conn.close()
             except Exception as e:
-                self._logger.debug(
-                    "[acp conn=%s] conn.close error (ignored): %s", last_conn_id, e
-                )
+                self._logger.debug("[acp conn=%s] conn.close error (ignored): %s", last_conn_id, e)
             self._conn = None
 
         if self._transport is not None:
@@ -464,8 +502,12 @@ class AcpClient:
             raise AcpProtocolError("Not connected")
         if session_id in self._loaded_sessions:
             return
-        await self._conn.load_session(cwd=cwd, session_id=session_id, mcp_servers=[])
-        self._loaded_sessions.add(session_id)
+        try:
+            await self._conn.load_session(cwd=cwd, session_id=session_id, mcp_servers=[])
+            self._loaded_sessions.add(session_id)
+        finally:
+            if self._transport is not None:
+                self._transport.set_ephemeral_headers(None)
 
     async def prompt(
         self,
@@ -473,18 +515,28 @@ class AcpClient:
         blocks: list[Any],
         *,
         cancel_event: asyncio.Event | None = None,
+        traceparent: str | None = None,
     ) -> PromptResponse:
         """发 prompt。
 
         - 本次 prompt 期间的 notifications 由 ``subscribe()`` 订阅器独立接收
         - 同 session_id 的多次 prompt 会排队（ACP 协议要求）
         - ``cancel_event.set()`` 或 ``task.cancel()`` 触发时向服务端发 ``session/cancel``
+        - ``traceparent`` 经传输层随本轮所有 POST 发出（同轮 cancel 也带上）
         """
         if self._conn is None:
             raise AcpProtocolError("Not connected")
 
         lock = self._prompt_locks[session_id]
         async with lock:
+            if cancel_event is not None and cancel_event.is_set():
+                raise asyncio.CancelledError()
+            if self._transport is not None:
+                self._transport.set_ephemeral_headers(
+                    {"traceparent": traceparent, "X-Trace-Id": traceparent.split("-")[1]}
+                    if traceparent
+                    else None
+                )
             self._active_prompts.add(session_id)
             try:
                 # 构造主任务：调官方 prompt RPC
@@ -535,6 +587,8 @@ class AcpClient:
                 return response  # type: ignore[no-any-return]
             finally:
                 self._active_prompts.discard(session_id)
+                if self._transport is not None:
+                    self._transport.set_ephemeral_headers(None)
 
     async def session_cancel(self, session_id: str) -> None:
         """发 session/cancel 通知（幂等，尽力而为）。"""
@@ -596,9 +650,7 @@ class AcpClient:
 
     # ─── Notification 订阅 ────────────────────────────────
 
-    def subscribe(
-        self, session_id: str, listener: NotificationListener
-    ) -> Callable[[], None]:
+    def subscribe(self, session_id: str, listener: NotificationListener) -> Callable[[], None]:
         """订阅指定 session 的 notifications。返回 unsubscribe 函数。
 
         一个 session 可以有多个 listener，按注册顺序同步调用（异常静默吞）。
@@ -665,7 +717,7 @@ class AcpClient:
         if not isinstance(session_id, str):
             return False
 
-        self._dispatch_notification(_parse_session_notification(params, session_id))
+        self._dispatch_notification(_parse_session_notification(params, session_id, self._logger))
         return True
 
     # ─── 连接级事件 ────────────────────────────────