框架：提供 Trace 模型用量只读查询

扩展 TraceStore 公共协议和文件实现，按 Trace 返回持久化的 provider 用量；缺少记录时返回稳定空汇总，为 Host 诊断报告统计 Planner、Worker、Validator 奠定接口。

agent/agent/trace/protocols.py

@@ -151,6 +151,10 @@ class TraceStore(Protocol):
         """
         ...
 
+    async def get_model_usage(self, trace_id: str) -> Dict[str, Any]:
+        """Return the durable provider usage summary for one Trace."""
+        ...
+
     async def get_main_path_messages(
         self, trace_id: str, head_sequence: int
     ) -> List[Message]:

agent/agent/trace/store.py

@@ -791,6 +791,28 @@ class FileSystemTraceStore:
 
     # ===== 模型使用追踪 =====
 
+    async def get_model_usage(self, trace_id: str) -> Dict[str, Any]:
+        """Read one Trace's provider usage without exposing storage paths."""
+
+        _validate_path_segment(trace_id, "trace_id")
+        usage_file = self._get_model_usage_file(trace_id)
+        if not usage_file.exists():
+            return {
+                "summary": {
+                    "total_models": 0,
+                    "total_tokens": 0,
+                    "total_cache_read_tokens": 0,
+                    "agent_tokens": 0,
+                    "tool_tokens": 0,
+                },
+                "models": [],
+                "timeline": [],
+            }
+        value = json.loads(usage_file.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise ValueError("model usage root must be an object")
+        return value
+
     async def record_model_usage(
         self,
         trace_id: str,