capability-runtime 0.1.1__tar.gz → 0.1.3__tar.gz

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capability-runtime
-Version: 0.1.1
+Version: 0.1.3
 Summary: Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events).
 License-Expression: MIT
 Requires-Python: >=3.10

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "capability-runtime"
-version = "0.1.1"
+version = "0.1.3"
 description = "Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events)."
 readme = "README.md"
 requires-python = ">=3.10"

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/__init__.py

@@ -1,7 +1,7 @@
 """capability-runtime：统一 Runtime 入口（能力协议 + 执行 + 报告）。"""
 from __future__ import annotations
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 
 # === 统一入口 ===
 from .config import CustomTool, RuntimeConfig

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/adapters/agent_adapter.py

@@ -80,6 +80,7 @@ class AgentAdapter:
         spec: AgentSpec,
         input: Dict[str, Any],
         context: ExecutionContext,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[Union[AgentEvent, CapabilityResult]]:
         """
         流式执行 AgentSpec：先 yield AgentEvent（若为真实执行），最后 yield CapabilityResult。
@@ -93,6 +94,7 @@ class AgentAdapter:
 
         备注：
         - 每条 `AgentEvent` 也会通过 Runtime 的内部 tap 旁路分发（用于 UI events 投影；不改变对外 `AgentEvent` 转发语义）。
+        - `prompt_control` 为显式 prompt 控制面，优先于兼容入口 `input["_runtime_prompt"]`。
         """
 
         mode = str(getattr(self._services.config, "mode", "mock"))
@@ -100,7 +102,12 @@ class AgentAdapter:
             yield await self._mock_execute(spec=spec, input=input, context=context)
             return
 
-        async for item in self._bridge_execute_stream(spec=spec, input=input, context=context):
+        async for item in self._bridge_execute_stream(
+            spec=spec,
+            input=input,
+            context=context,
+            prompt_control=prompt_control,
+        ):
             yield item
 
     async def _mock_execute(self, *, spec: AgentSpec, input: Dict[str, Any], context: ExecutionContext) -> CapabilityResult:
@@ -193,14 +200,26 @@ class AgentAdapter:
             )
 
     async def _bridge_execute_stream(
-        self, *, spec: AgentSpec, input: Dict[str, Any], context: ExecutionContext
+        self,
+        *,
+        spec: AgentSpec,
+        input: Dict[str, Any],
+        context: ExecutionContext,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[Union[AgentEvent, CapabilityResult]]:
         """
         真实执行（bridge/sdk_native）：驱动 SDK Agent.run_stream_async 并聚合 NodeReport。
+
+        参数：
+        - prompt_control：显式 prompt 控制面；为空时回退读取 `input["_runtime_prompt"]`。
         """
 
         try:
-            prompt_plan = self._resolve_prompt_render_plan(spec=spec, input=input)
+            prompt_plan = self._resolve_prompt_render_plan(
+                spec=spec,
+                input=input,
+                prompt_control=prompt_control,
+            )
         except _InvalidPromptMessages as exc:
             report = self._services.build_fail_closed_report(
                 run_id=context.run_id,
@@ -283,6 +302,19 @@ class AgentAdapter:
         events: List[AgentEvent] = []
         host_meta = self._services.get_host_meta(context=context)
         initial_history = host_meta.get("initial_history") if isinstance(host_meta.get("initial_history"), list) else None
+        on_event_error_count = 0
+        on_event_last_error_type: Optional[str] = None
+
+        def _apply_on_event_error_evidence(report: Any) -> None:
+            """把 on_event fail-open 错误摘要写入 NodeReport.meta。"""
+
+            if on_event_error_count <= 0:
+                return
+            meta = getattr(report, "meta", None)
+            if isinstance(meta, dict):
+                meta["on_event_error_count"] = on_event_error_count
+                if on_event_last_error_type:
+                    meta["on_event_last_error_type"] = on_event_last_error_type
 
         try:
             async for ev in agent.run_stream_async(task, run_id=context.run_id, initial_history=initial_history):
@@ -306,6 +338,8 @@ class AgentAdapter:
                             {"run_id": context.run_id, "capability_id": spec.base.id},
                         )
                     except Exception as cb_exc:
+                        on_event_error_count += 1
+                        on_event_last_error_type = type(cb_exc).__name__
                         log_suppressed_exception(
                             context="on_event_callback",
                             exc=cb_exc,
@@ -323,6 +357,7 @@ class AgentAdapter:
                 meta={"capability_id": spec.base.id, "source": "sdk_agent"},
             )
             self._apply_prompt_evidence(report=report, evidence=prompt_plan.evidence)
+            _apply_on_event_error_evidence(report)
             yield CapabilityResult(
                 status=CapabilityStatus.CANCELLED,
                 error="execution cancelled",
@@ -339,6 +374,7 @@ class AgentAdapter:
                 completion_reason="engine_exception",
                 meta={"engine_exception": type(exc).__name__, **prompt_plan.evidence},
             )
+            _apply_on_event_error_evidence(report)
             yield CapabilityResult(
                 status=CapabilityStatus.FAILED,
                 error=str(exc),
@@ -350,6 +386,7 @@ class AgentAdapter:
 
         report = NodeReportBuilder().build(events=events)
         self._apply_prompt_evidence(report=report, evidence=prompt_plan.evidence)
+        _apply_on_event_error_evidence(report)
         if issues and getattr(self._services.config, "preflight_mode", "error") == "warn":
             report.meta["preflight_mode"] = "warn"
             report.meta["preflight_issues"] = [self._services.redact_issue(i) for i in issues]
@@ -389,13 +426,20 @@ class AgentAdapter:
             artifacts=list(report.artifacts),
         )
 
-    def _resolve_prompt_render_plan(self, *, spec: AgentSpec, input: Dict[str, Any]) -> _PromptRenderPlan:
+    def _resolve_prompt_render_plan(
+        self,
+        *,
+        spec: AgentSpec,
+        input: Dict[str, Any],
+        prompt_control: Optional[Dict[str, Any]] = None,
+    ) -> _PromptRenderPlan:
         """
         解析 AgentSpec + run-level `_runtime_prompt`，生成 prompt 渲染计划。
 
         参数：
         - spec：Agent 声明
         - input：run 输入，其中 `_runtime_prompt` 为保留控制面
+        - prompt_control：显式控制面；若提供则优先于 input 内兼容保留键
 
         返回：
         - `_PromptRenderPlan`
@@ -404,13 +448,14 @@ class AgentAdapter:
         - `_InvalidPromptMessages`：控制面非法，调用方应 fail-fast。
         """
 
-        envelope_raw = input.get(_RUNTIME_PROMPT_KEY)
+        envelope_raw = prompt_control if prompt_control is not None else input.get(_RUNTIME_PROMPT_KEY)
+        envelope_name = "prompt_control" if prompt_control is not None else "_runtime_prompt"
         if envelope_raw is None:
             envelope: Dict[str, Any] = {}
         elif isinstance(envelope_raw, dict):
             envelope = dict(envelope_raw)
         else:
-            raise _InvalidPromptMessages("_runtime_prompt must be a dict")
+            raise _InvalidPromptMessages(f"{envelope_name} must be a dict")
 
         raw_mode = envelope.get("mode") if "mode" in envelope else getattr(spec, "prompt_render_mode", "structured_task")
         if raw_mode is None:
@@ -570,10 +615,9 @@ class AgentAdapter:
         if business_input:
             lines: List[str] = []
             for k, v in business_input.items():
-                if isinstance(v, str):
-                    lines.append(f"- {k}: {v}")
-                else:
-                    lines.append(f"- {k}: {json.dumps(v, ensure_ascii=False)}")
+                key_text = json.dumps(str(k), ensure_ascii=False)
+                value_text = json.dumps(v, ensure_ascii=False)
+                lines.append(f"- {key_text}: {value_text}")
             parts.append(f"{_SECTION_INPUT}\n" + "\n".join(lines))
 
         if spec.output_schema and spec.output_schema.fields:

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/adapters/agently_backend.py

@@ -66,13 +66,19 @@ class AgentlyBackendConfig:
 
     requester_factory: AgentlyRequesterFactory
 
-def _normalize_usage_payload(*, usage: Any, model: Any = None) -> Optional[Dict[str, Any]]:
+def _normalize_usage_payload(
+    *,
+    usage: Any,
+    model: Any = None,
+    request_id: Any = None,
+    provider: Any = None,
+) -> Optional[Dict[str, Any]]:
     """
     把 provider usage 归一为 capability-runtime 的 `llm_usage` payload 形状。
 
     返回：
     - `None`：无法提取任何有效 usage 字段
-    - `dict`：`model/input_tokens/output_tokens/total_tokens`
+    - `dict`：`model/input_tokens/output_tokens/total_tokens/request_id/provider`
     """
 
     if not isinstance(usage, dict):
@@ -93,6 +99,8 @@ def _normalize_usage_payload(*, usage: Any, model: Any = None) -> Optional[Dict[
         "input_tokens": input_tokens,
         "output_tokens": output_tokens,
         "total_tokens": total_tokens,
+        "request_id": request_id.strip() if isinstance(request_id, str) and request_id.strip() else None,
+        "provider": provider.strip() if isinstance(provider, str) and provider.strip() else None,
     }
     return payload if any(value is not None for value in payload.values()) else None
 
@@ -120,7 +128,15 @@ def _extract_usage_payload_from_sse_data(data: str) -> Optional[Dict[str, Any]]:
         return None
     if not isinstance(obj, dict):
         return None
-    return _normalize_usage_payload(usage=obj.get("usage"), model=obj.get("model"))
+    request_id = obj.get("request_id")
+    if not (isinstance(request_id, str) and request_id.strip()):
+        request_id = obj.get("id")
+    return _normalize_usage_payload(
+        usage=obj.get("usage"),
+        model=obj.get("model"),
+        request_id=request_id,
+        provider=obj.get("provider"),
+    )
 
 
 def _merge_stream_options_for_usage(value: Any) -> Dict[str, Any]:

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/adapters/triggerflow_workflow_engine.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import asyncio
 import uuid
 from contextlib import suppress
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from types import MappingProxyType
 from typing import Any, AsyncIterator, Dict, List, Optional, cast
 
@@ -598,8 +598,7 @@ class TriggerFlowWorkflowEngine:
                 completion_reason="loop_iteration_failed",
                 meta={"step_id": step.id, "capability_id": step.capability.id},
             )
-            result.report = report
-            result.node_report = report
+            result = replace(result, report=report, node_report=report)
 
         context.step_outputs[step.id] = result.output
         context.step_results[step.id] = _to_step_result_dict(result)

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/host_protocol.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 """HITL / wait-resume / approval 的宿主协议收敛层。"""
 
+import html
+import re
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Optional
@@ -397,4 +399,10 @@ def _build_message_preview(value: Any) -> str | None:
     normalized = " ".join(value.split())
     if not normalized:
         return None
-    return normalized[:120]
+    secret_pattern = re.compile(
+        r"(?i)\b(password|passwd|api_key|apikey|token|access_token|secret)\s*=\s*"
+        r"(\"[^\"]*\"|'[^']*'|[^\s&]+)"
+    )
+    redacted = secret_pattern.sub(lambda m: f"{m.group(1)}=[REDACTED]", normalized)
+    redacted = re.sub(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+", "Bearer [REDACTED]", redacted)
+    return html.escape(redacted, quote=True)[:120]

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/reporting/node_report.py

@@ -161,6 +161,8 @@ class NodeReportBuilder:
         usage_input_seen = False
         usage_output_seen = False
         usage_total_seen = False
+        usage_request_id: Optional[str] = None
+        usage_provider: Optional[str] = None
 
         def _ensure_tool(call_id: str, *, name: str) -> Dict[str, Any]:
             """获取/初始化工具调用聚合槽位（以 call_id 为主键）。"""
@@ -217,6 +219,14 @@ class NodeReportBuilder:
                 if isinstance(model_name, str) and model_name.strip():
                     usage_model = model_name.strip()
 
+                request_id = usage_summary.get("request_id")
+                if isinstance(request_id, str) and request_id.strip():
+                    usage_request_id = request_id.strip()
+
+                provider = usage_summary.get("provider")
+                if isinstance(provider, str) and provider.strip():
+                    usage_provider = provider.strip()
+
                 input_tokens = usage_summary.get("input_tokens")
                 if isinstance(input_tokens, int):
                     usage_input_total += input_tokens
@@ -378,12 +388,21 @@ class NodeReportBuilder:
             NodeToolCallReport.model_validate(item) for item in tool_calls.values() if isinstance(item, dict)
         ]
         usage_report: Optional[NodeUsageReport] = None
-        if usage_model is not None or usage_input_seen or usage_output_seen or usage_total_seen:
+        if (
+            usage_model is not None
+            or usage_input_seen
+            or usage_output_seen
+            or usage_total_seen
+            or usage_request_id is not None
+            or usage_provider is not None
+        ):
             usage_report = NodeUsageReport(
                 model=usage_model,
                 input_tokens=usage_input_total if usage_input_seen else None,
                 output_tokens=usage_output_total if usage_output_seen else None,
                 total_tokens=usage_total_total if usage_total_seen else None,
+                request_id=usage_request_id,
+                provider=usage_provider,
             )
 
         report = NodeReport(

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/runtime.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 """
 
 import asyncio
+import copy
 import time
 import uuid
 from dataclasses import replace
@@ -344,6 +345,7 @@ class Runtime(RuntimeUIEventsMixin):
         *,
         input: Optional[Dict[str, Any]] = None,
         context: Optional[ExecutionContext] = None,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> CapabilityResult:
         """
         非流式执行（等待完成后返回）。
@@ -352,10 +354,14 @@ class Runtime(RuntimeUIEventsMixin):
         - capability_id：能力 ID
         - input：输入参数 dict
         - context：可选执行上下文（宿主控制；若不传则由 Runtime 创建）
+        - prompt_control：可选 prompt 控制面；优先于兼容入口 `input["_runtime_prompt"]`
         """
 
         result: Optional[CapabilityResult] = None
-        async for item in self.run_stream(capability_id, input=input, context=context):
+        stream_kwargs: Dict[str, Any] = {"input": input, "context": context}
+        if prompt_control is not None:
+            stream_kwargs["prompt_control"] = prompt_control
+        async for item in self.run_stream(capability_id, **stream_kwargs):
             if isinstance(item, CapabilityResult):
                 result = item
         if result is None:
@@ -373,6 +379,7 @@ class Runtime(RuntimeUIEventsMixin):
         *,
         input: Optional[Dict[str, Any]] = None,
         context: Optional[ExecutionContext] = None,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> CapabilityResult:
         """
         强结构输出入口：成功时返回 `dict` 输出。
@@ -380,11 +387,12 @@ class Runtime(RuntimeUIEventsMixin):
         约束：
         - 仅支持带 `output_schema` 的 Agent capability；
         - 不改变 `run()` 的既有语义，而是在其之上做强结构收口。
+        - `prompt_control` 透传给底层 `run()`，用于显式控制 prompt rendering。
         """
 
         spec = self._registry.get(capability_id)
         if spec is None:
-            return await self.run(capability_id, input=input, context=context)
+            return await self.run(capability_id, input=input, context=context, prompt_control=prompt_control)
         if not isinstance(spec, AgentSpec):
             run_id = context.run_id if context is not None else uuid.uuid4().hex
             return self._build_fail_closed_result(
@@ -408,7 +416,7 @@ class Runtime(RuntimeUIEventsMixin):
                 completion_reason="structured_output_schema_missing",
             )
 
-        result = await self.run(capability_id, input=input, context=context)
+        result = await self.run(capability_id, input=input, context=context, prompt_control=prompt_control)
         if result.status != CapabilityStatus.SUCCESS:
             return result
 
@@ -426,6 +434,7 @@ class Runtime(RuntimeUIEventsMixin):
         *,
         input: Optional[Dict[str, Any]] = None,
         context: Optional[ExecutionContext] = None,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[StructuredStreamEvent]:
         """
         结构化输出流式消费入口。
@@ -433,6 +442,7 @@ class Runtime(RuntimeUIEventsMixin):
         说明：
         - 面向业务代码，不透传 mixed stream / UI events 的全部细节；
         - 仅在观察到 `llm_response_delta(text)` 时产出中途快照与字段更新。
+        - `prompt_control` 透传给底层 `run_stream()`，优先于 `input["_runtime_prompt"]`。
         """
 
         spec = self._registry.get(capability_id)
@@ -474,7 +484,10 @@ class Runtime(RuntimeUIEventsMixin):
         previous_snapshot: Optional[Dict[str, Any]] = None
         terminal: Optional[CapabilityResult] = None
 
-        async for item in self.run_stream(capability_id, input=input, context=ctx):
+        stream_kwargs: Dict[str, Any] = {"input": input, "context": ctx}
+        if prompt_control is not None:
+            stream_kwargs["prompt_control"] = prompt_control
+        async for item in self.run_stream(capability_id, **stream_kwargs):
             if isinstance(item, CapabilityResult):
                 terminal = item
                 continue
@@ -564,6 +577,7 @@ class Runtime(RuntimeUIEventsMixin):
         *,
         input: Optional[Dict[str, Any]] = None,
         context: Optional[ExecutionContext] = None,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[Union[AgentEvent, WorkflowStreamEvent, CapabilityResult]]:
         """
         流式执行（执行层混合流）：过程中可能产出事件，最后产出终态 CapabilityResult。
@@ -610,15 +624,30 @@ class Runtime(RuntimeUIEventsMixin):
 
         started = time.monotonic()
         if _get_base(spec).kind == CapabilityKind.AGENT:
-            async for x in self._execute_agent_stream(spec=spec, input=input or {}, context=ctx):
+            async for x in self._execute_agent_stream(
+                spec=spec,
+                input=input or {},
+                context=ctx,
+                prompt_control=prompt_control,
+            ):
                 if isinstance(x, CapabilityResult):
-                    x.duration_ms = (time.monotonic() - started) * 1000
+                    x = replace(
+                        x,
+                        duration_ms=(time.monotonic() - started) * 1000,
+                        artifacts=list(x.artifacts or []),
+                        metadata=copy.deepcopy(x.metadata or {}),
+                    )
                 yield x
             return
 
         async for x in self._execute_workflow_stream(spec=spec, input=input or {}, context=ctx):
             if isinstance(x, CapabilityResult):
-                x.duration_ms = (time.monotonic() - started) * 1000
+                x = replace(
+                    x,
+                    duration_ms=(time.monotonic() - started) * 1000,
+                    artifacts=list(x.artifacts or []),
+                    metadata=copy.deepcopy(x.metadata or {}),
+                )
             yield x
         return
 
@@ -826,7 +855,12 @@ class Runtime(RuntimeUIEventsMixin):
             yield item
 
     async def _execute_agent_stream(
-        self, *, spec: AnySpec, input: Dict[str, Any], context: ExecutionContext
+        self,
+        *,
+        spec: AnySpec,
+        input: Dict[str, Any],
+        context: ExecutionContext,
+        prompt_control: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[Union[AgentEvent, CapabilityResult]]:
         """
         执行 AgentSpec（流式）。
@@ -849,7 +883,10 @@ class Runtime(RuntimeUIEventsMixin):
             )
             return
 
-        async for item in self._agent_adapter.execute_stream(spec=spec, input=input, context=context):
+        execute_kwargs: Dict[str, Any] = {"spec": spec, "input": input, "context": context}
+        if prompt_control is not None:
+            execute_kwargs["prompt_control"] = prompt_control
+        async for item in self._agent_adapter.execute_stream(**execute_kwargs):
             yield item
 
     def build_fail_closed_report(

{capability_runtime-0.1.1 → capability_runtime-0.1.3}/src/capability_runtime/sdk_lifecycle.py

@@ -19,6 +19,7 @@ from skills_runtime.skills.manager import SkillsManager
 from .config import CustomTool, RuntimeConfig, RuntimeMode, normalize_workspace_root
 from .logging_utils import log_suppressed_exception
 from .protocol.chat_backend import ChatBackendProtocol
+from .utils.usage import extract_usage_metrics
 
 
 @dataclass(frozen=True)
@@ -668,7 +669,7 @@ class _UsageTapBackend:
 
 class _AgentUsageEventBridge:
     """
-    Agent 薄代理：在底层未主动发出 `llm_usage` 时，补发 bridge 收集到的 usage AgentEvent。
+    Agent 薄代理：补齐 bridge usage metadata，或在底层未主动发出 `llm_usage` 时补发 usage 事件。
     """
 
     def __init__(self, *, agent: Any, usage_bridge_backend: _UsageTapBackend) -> None:
@@ -683,16 +684,32 @@ class _AgentUsageEventBridge:
         initial_history: Optional[List[Dict[str, Any]]] = None,
     ) -> AsyncIterator[AgentEvent]:
         """
-        转发 SDK Agent 事件流；若未见上游 `llm_usage`，在流结束后补发 bridge usage 事件。
+        转发 SDK Agent 事件流，并按 token usage bridge 规格处理 supplemental usage。
+
+        参数：
+        - task：传给上游 Agent 的任务文本
+        - run_id：可选 run 标识
+        - initial_history：可选初始历史
+
+        返回：
+        - AgentEvent 异步流；上游 `llm_usage` 存在时只补齐缺失 metadata，不重复补 token
         """
 
         saw_llm_usage = False
+        pending_supplemental_usage: List[Dict[str, Any]] = []
         last_run_id = run_id or ""
         last_turn_id: Optional[str] = None
 
         async for ev in self._agent.run_stream_async(task, run_id=run_id, initial_history=initial_history):
             if ev.type == "llm_usage":
                 saw_llm_usage = True
+                pending_supplemental_usage.extend(self._usage_bridge_backend.drain_usage_payloads())
+                if pending_supplemental_usage:
+                    ev = _merge_supplemental_usage_metadata_event(
+                        ev=ev,
+                        supplemental_payloads=pending_supplemental_usage,
+                    )
+                    pending_supplemental_usage.clear()
             if isinstance(ev.run_id, str) and ev.run_id:
                 last_run_id = ev.run_id
             if isinstance(ev.turn_id, str) and ev.turn_id:
@@ -700,10 +717,12 @@ class _AgentUsageEventBridge:
             yield ev
 
         if saw_llm_usage:
+            # 上游 usage 已是 token 权威来源；清空未配对 payload，避免作为新 usage 事件造成双计。
             self._usage_bridge_backend.drain_usage_payloads()
             return
 
-        for payload in self._usage_bridge_backend.drain_usage_payloads():
+        pending_supplemental_usage.extend(self._usage_bridge_backend.drain_usage_payloads())
+        for payload in pending_supplemental_usage:
             yield AgentEvent(
                 type="llm_usage",
                 timestamp=_now_rfc3339(),
@@ -719,6 +738,50 @@ def _now_rfc3339() -> str:
     return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
 
+def _merge_supplemental_usage_metadata_event(*, ev: AgentEvent, supplemental_payloads: List[Dict[str, Any]]) -> AgentEvent:
+    """
+    把 sink payload 作为 supplemental metadata patch 合并到上游 `llm_usage` 事件。
+
+    参数：
+    - ev：上游 SDK / agent loop 已发出的 `llm_usage` AgentEvent
+    - supplemental_payloads：`_caprt_usage_sink` 收集到的 provider/gateway usage payload 列表
+
+    返回：
+    - 新 AgentEvent；仅在上游 metadata 缺失时补 `model/request_id/provider`，不写入 token 字段
+    """
+
+    upstream_payload = dict(ev.payload) if isinstance(ev.payload, dict) else {}
+    merged_payload = dict(upstream_payload)
+
+    for supplemental_payload in supplemental_payloads:
+        supplemental_summary = extract_usage_metrics(supplemental_payload)
+        for field in ("model", "request_id", "provider"):
+            current_value = extract_usage_metrics(merged_payload).get(field)
+            if isinstance(current_value, str) and current_value.strip():
+                continue
+            supplemental_value = supplemental_summary.get(field)
+            if isinstance(supplemental_value, str) and supplemental_value.strip():
+                merged_payload[field] = supplemental_value.strip()
+
+    if merged_payload == upstream_payload:
+        return ev
+    try:
+        return ev.model_copy(update={"payload": merged_payload})
+    except Exception as exc:  # pragma: no cover - 当前 AgentEvent 为 Pydantic v2，保留兼容兜底。
+        log_suppressed_exception(
+            context="supplemental_usage_event_model_copy",
+            exc=exc,
+        )
+        return AgentEvent(
+            type=ev.type,
+            timestamp=ev.timestamp,
+            run_id=ev.run_id,
+            turn_id=ev.turn_id,
+            step_id=ev.step_id,
+            payload=merged_payload,
+        )
+
+
 def _merge_usage_sink(*, extra: Dict[str, Any], sink: Any) -> Dict[str, Any]:
     """
     合并 `_caprt_usage_sink` 回调，保留已有 sink 并保证两者都被调用。