docs(agent-runner): document usage accounting

docs/agent-runner-pluginization/PROTOCOL_V1.md

@@ -405,12 +405,31 @@ class AgentRunResult(BaseModel):
     run_id: str
     type: AgentRunResultType | str
     data: dict[str, Any] = {}
+    usage: LLMTokenUsage | None = None
     sequence: int | None = None
     timestamp: int | None = None
 ```
 
 SDK 当前实现是单一 envelope：`type` 枚举 + `data` dict。Payload 由 SDK typed model 构造并 dump，但 wire 不改成 discriminated union；这样新旧版本偏斜时 Host 仍可按 §3 忽略未知 `type`。
 
+`usage` 是 runner 可选上报的 token 使用量，沿用 SDK `LLMTokenUsage`：
+
+```python
+class LLMTokenUsage(BaseModel):
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    # provider-specific detail/cached/reasoning counters are preserved as extra fields
+```
+
+约束：
+
+- 运行时能观测到 provider/runtime usage 时，SHOULD 在 terminal `run.completed.usage` 上报本次 run 的最终聚合 token usage。
+- `run.failed.usage` MAY 上报失败前已经产生的部分 usage。
+- 不能观测 usage 的 runner 合法地省略该字段；缺失表示 unknown，Host 不得按 0 处理。
+- ACP 等外部协议不保证统一 usage；ACP runner 只能在具体 provider/native event 提供 usage 时填充本字段。
+- cost 不作为 runner result 的权威字段。Host 后续应基于 usage、model identity、时间和自身价格表计算账单成本；provider 原始 cost 如需保留，可放在 `usage` extra 字段中作为非权威 telemetry。
+
 Host 边界分级校验：
 
 - `message.delta`、`message.completed`、`artifact.created`、`state.updated`、`action.requested`、`run.completed`、`run.failed` 属于会影响投递或 Host 副作用的严格 payload；校验失败时丢弃该 result 并记录 warning。

docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md

@@ -170,6 +170,8 @@ status_reason
 created_at / started_at / finished_at / updated_at
 deadline_at
 cancel_requested_at
+usage_json
+cost_json
 metadata_json
 ```
 
@@ -202,6 +204,7 @@ run_id
 sequence
 type
 data_json
+usage_json
 created_at
 source
 artifact_refs_json
@@ -214,6 +217,7 @@ metadata_json
 - append 必须幂等，支持远程 daemon / plugin 重试。
 - 未知 result type 可保存但 Host 只对已知类型执行副作用。
 - 大 payload 仍应转 artifact，不直接塞入 result event。
+- `usage_json` 保存 `AgentRunResult.usage` 原样结构；缺失表示 unknown，不等于 0。
 
 ### 4.3 Run Control API
 
@@ -252,9 +256,24 @@ event -> binding -> context -> runner invocation -> result normalization
 - 每个 `AgentRunResult` 进入 `AgentRunEvent`。
 - `run.completed` / 正常 generator 结束时标记 completed。
 - `run.failed` / exception / timeout 标记 failed 或 timeout。
+- terminal result 携带 usage 时，写入 `AgentRunEvent.usage_json` 并汇总到 `AgentRun.usage_json`。
 - `state.updated`、`artifact.created`、transcript 写入继续走现有 journal，但应与 `AgentRunEvent` 有可追踪关系。
 
-### 4.5 Authorization Snapshot
+### 4.5 Usage / Cost Accounting
+
+SDK 侧 `AgentRunResult` 已提供可选 `usage` 字段，用于把不同 runner / external harness / provider-native event 的 token usage 归一到同一个 run result envelope。
+
+语义：
+
+- `run.completed.usage` SHOULD 表示本次 run 的最终聚合 token usage。
+- `run.failed.usage` MAY 表示失败前已知的部分 token usage。
+- 没有 usage 表示 upstream runtime 没有报告或 adapter 暂未接入；Host 不得按 0 计费或按 0 判断上下文消耗。
+- Host 应把 event-level usage 原样写入 `AgentRunEvent.usage_json`，并在 terminal event 或 finalize 阶段汇总到 `AgentRun.usage_json`。
+- cost 应由 Host 根据 usage、runner/model identity、发生时间和价格表计算，写入 `AgentRun.cost_json`；runner/provider 上报的 cost 只能作为非权威 telemetry 保留在 metadata 或 usage extra 中。
+
+这层约束先解决协议位置和持久化位置；具体 ACP、LiteLLM、remote daemon、local subprocess runner 如何从 native event 中抽取 usage，可在各插件后续适配。
+
+### 4.6 Authorization Snapshot
 
 异步或远程执行时，run 创建时必须固化授权快照：