docs(client-api): add budget_remaining to agent usage §5.1 (#9)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/integration/heicode-desktop-client-api.md

@@ -236,11 +236,13 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
   "prompt_tokens": 8000,
   "completion_tokens": 4000,
   "call_count": 12,
-  "quota_per_unit": 500000   // 额度→货币换算分母(quota/quota_per_unit=美元额度)
+  "quota_per_unit": 500000,   // 额度→货币换算分母(quota/quota_per_unit=美元额度)
+  "budget_remaining": 1234567 // ★ 用户钱包剩余额度(预算剩余;-1=读取失败,不阻断展示)
 }}
 ```
 
 - **空数据语义**:无调用记录时各计数为 `0`(仍返回 `success:true`,不是 404)。
+- **`budget_remaining`(#9)**:用户剩余可用额度(同 `quota_per_unit` 口径换算)。Agent 模型调用经隐藏 token 计费到 `user.Quota`,故"本任务预算剩余"= 用户钱包剩余额度。
 - **与 billing logs 的关系**:用量来自统一计费 logs(`SumAgentUsage`),按 token name `agent:<deployment_id>` 过滤聚合 —— 即 agent 走 HM `/v1/*` 的真实消耗,与用户钱包/订阅扣费同源。
 - **计费归集语义(#30)**:每个部署的 agent,HM 为其 mint 一个**隐藏、不展示在用户 token 列表**的模型 token(`UnlimitedQuota:true`)。`UnlimitedQuota` 的含义是「**不对该 token 自身设单独的剩余额度上限**」——它**不**绕过用户额度:agent 经此 token 调 `/v1/*` 时,HM 仍先校验 `user.Quota`,并在结算时从 `user.Quota`(钱包)或订阅项扣费、写计费 log,完全经过计费表达式。停止/删除 agent 后该 token 被撤销,旧 token 无法再调 `/v1/*`。该 token 对普通用户隐藏,但审计/管理员可追踪。