feat(usage): expose budget_remaining on agent usage endpoint (#9)

#9 的最后一项 DoD「预算剩余」:GET /api/heicode/agents/:id/usage 新增
budget_remaining = 用户钱包剩余额度(int64;-1 表示读取失败,不阻断用量展示)。
Agent 模型调用经隐藏 token 计费到 user.Quota(#30),故"本任务预算剩余"= 用户剩余额度。
与既有 quota/quota_per_unit 同口径。

#9 的①审计脱敏(PR #11)+②deployment 维度用量(SumAgentUsage/usage 端点)此前已闭环,
本 PR 补齐 budget_remaining。文档 §5.1 随 PR #38 更新(usage 章节在该 PR)。

Affects: Manager only(usage 响应新增只读字段)。无计费/审计 schema 改动。

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

heicode/controller/agent_template_handlers.go

@@ -490,11 +490,18 @@ func HeicodeGetAgentUsage(c *gin.Context) {
 	}
 	start, _ := strconv.ParseInt(strings.TrimSpace(c.Query("start")), 10, 64)
 	end, _ := strconv.ParseInt(strings.TrimSpace(c.Query("end")), 10, 64)
-	usage, err := model.SumAgentUsage(c.GetInt("id"), "agent:"+row.DeploymentID, start, end)
+	userID := c.GetInt("id")
+	usage, err := model.SumAgentUsage(userID, "agent:"+row.DeploymentID, start, end)
 	if err != nil {
 		agentError(c, "DEPLOYMENT_CONFLICT", "failed to aggregate agent usage")
 		return
 	}
+	// #9: budget_remaining — 用户钱包剩余额度。Agent 模型调用经隐藏 token 计费到
+	// user.Quota(见 #30),故"预算剩余"= 用户剩余额度。-1 表示读取失败(不阻断用量展示)。
+	budgetRemaining := int64(-1)
+	if u, uErr := model.GetUserById(userID, false); uErr == nil && u != nil {
+		budgetRemaining = int64(u.Quota)
+	}
 	common.ApiSuccess(c, gin.H{
 		"agent_id":          row.DeploymentID,
 		"quota":             usage.Quota,
@@ -502,6 +509,7 @@ func HeicodeGetAgentUsage(c *gin.Context) {
 		"completion_tokens": usage.CompletionTokens,
 		"call_count":        usage.CallCount,
 		"quota_per_unit":    common.QuotaPerUnit,
+		"budget_remaining":  budgetRemaining,
 	})
 }