chore(version): 1.5.9

回答「opencodego 的用量与费用透传呢」时逐字段核对上游产出，发现 usage 漏了
一项、费用整项丢失。

## 上游实际发什么（实测 opencode.ai/zen/go/v1）

  {
    "choices": [...],
    "usage": { "prompt_tokens": 37, "completion_tokens": 40, "total_tokens": 77,
               "prompt_cache_hit_tokens": 0, "prompt_cache_miss_tokens": 37,
               "prompt_tokens_details": {"cached_tokens": 0},
               "completion_tokens_details": {"reasoning_tokens": 40} },
    "cost": "0"
  }

cost 在**顶层**且是**字符串**。流式时还会单独发一帧：
{"choices":[],"cost":"0"}

## 此前丢了两样

1. completion_tokens_details.reasoning_tokens —— 输出里有多少是思考 token。
   没有它，客户端无法判断 completion_tokens 里多少是可见回答、多少是思考，
   而两者都按输出计费。
2. cost —— 唯一的费用信号，网关整个丢弃。Go 订阅是包月制恒为 "0"，
   但 Zen 按量付费模型（以及未来的其它源）有信息量。

顺带修掉一处流式/非流式不一致：命中缓存时上游同时给
prompt_tokens_details.cached_tokens 和独立的 hit/miss，流式路径写成了 elseif，
只留 details，与非流式产出不同（只认独立字段的老客户端会看不到缓存）。

## 实现

- types.TokenUsage += CompletionTokensDetails；UnifiedResponse / UnifiedChunk += Cost
- opencodego/opencodezen 适配器映射两个字段；空 choices 帧改成 usage 与 cost
  都可带（早退只带 usage 会把同帧的 cost 丢干净 —— 新测试先抓到的就是这个）
- Gateway ChatCompletion / ChatChunk += cost，随终帧发（对齐上游的
  {"choices":[],"cost":"0"} 形态）
- Go 兜底 standardSSEChunk 同步支持（openai 系适配器不再漏 reasoning_tokens；
  纯 cost 帧不再被整体丢弃），新增 rawCostString 兼容字符串/数字两种形态

费用只做**搬运**：不解析、不换算、不汇总 —— 它是上游事实，且只有部分上游提供。

## 验证

经网关实测 gozen:deepseek-v4.1-flash，流式与非流式产出逐字段一致：
  prompt_tokens_details.cached_tokens=6784
  prompt_cache_hit_tokens=6784 / miss=148
  completion_tokens_details.reasoning_tokens=16
  cost="0"

测试：TestOpenCodeCostAndReasoningPassthrough（含「无数据不得凭空造字段」反例）、
TestOpenCodeStreamCacheFieldsMatchNonStream、TestTokenUsageMarshalsCompletionTokensDetails。

cmd/gui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "modelrouter-gui",
-  "version": "1.4.2",
+  "version": "1.5.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "modelrouter-gui",
-      "version": "1.4.2",
+      "version": "1.5.9",
       "license": "Proprietary",
       "devDependencies": {
         "electron": "^33.0.0",

cmd/gui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelrouter-gui",
-  "version": "1.4.2",
+  "version": "1.5.9",
   "description": "ModelRouter Desktop — embedded ModelRouter core with tray",
   "author": "ModelRouter",
   "main": "main.js",

internal/gateway/chat.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"log"
 	"net/http"
+	"regexp"
 	"strings"
 	"sync/atomic"
 	"time"
@@ -28,6 +29,9 @@ type chatRequest struct {
 	ToolChoice      interface{}            `json:"tool_choice,omitempty"`
 	DisableThinking bool                   `json:"disable_thinking"`
 	ExtraBody       map[string]interface{} `json:"extra_body,omitempty"`
+
+	// PromptCacheKey 是 OpenAI 原生的缓存键；部分客户端用它携带会话标识。
+	PromptCacheKey string `json:"prompt_cache_key,omitempty"`
 }
 
 // ChatCompletion is the non-streaming OpenAI response object.
@@ -38,6 +42,10 @@ type ChatCompletion struct {
 	Model   string            `json:"model"`
 	Choices []ChatChoice      `json:"choices"`
 	Usage   *types.TokenUsage `json:"usage,omitempty"`
+	// Cost is the upstream-reported charge for this request, passed through
+	// verbatim (OpenCode reports it as a decimal string, always "0" on the
+	// flat-rate Go subscription). Absent when the upstream reports nothing.
+	Cost string `json:"cost,omitempty"`
 }
 
 type ChatChoice struct {
@@ -62,6 +70,10 @@ type ChatChunk struct {
 	// Usage is sent in the final chunk of a stream (empty choices) so
 	// OpenAI-compatible clients can read token usage.
 	Usage *types.TokenUsage `json:"usage,omitempty"`
+	// Cost is the upstream-reported charge for this request, passed through
+	// verbatim (OpenCode reports it as a decimal string). Emitted on the
+	// terminal chunk, mirroring OpenCode's own {"choices":[],"cost":"0"}.
+	Cost string `json:"cost,omitempty"`
 }
 
 type ChunkChoice struct {
@@ -115,13 +127,15 @@ func (g *Gateway) resolveCands(ctx context.Context, req *chatRequest) ([]*provid
 }
 
 // filterCandsByModels keeps only providers exposing at least one model of the
-// scope (used for user keys with a restricted model scope). An "AUTO" scope
-// entry means the key is allowed to use any model. Scope entries with a
-// Source pinned to a specific upstream narrow the candidates to that source
+// scope (used for user keys with a restricted model scope). Scope entries with
+// a Source pinned to a specific upstream narrow the candidates to that source
 // for the matching model.
+//
+// An "AUTO" scope entry only allows the AUTO routing mode; it does NOT grant
+// access to specific models.
 func filterCandsByModels(cands []*provider.Provider, allow []config.ModelScope) []*provider.Provider {
 	for _, m := range allow {
-		if m.Model == "" || strings.EqualFold(m.Model, "AUTO") {
+		if m.Model == "" {
 			return cands
 		}
 	}
@@ -152,20 +166,18 @@ func filterCandsByModels(cands []*provider.Provider, allow []config.ModelScope)
 	return out
 }
 
-// intersectModels restricts a model list to the scope (preserving order). An
-// "AUTO" scope entry grants every model.
+// intersectModels restricts a model list to the scope (preserving order).
+// An "AUTO" scope entry only allows the AUTO routing mode; it does NOT grant
+// every model.
 func intersectModels(models []string, allow []config.ModelScope) []string {
 	allowed := make(map[string]bool, len(allow))
-	any := false
 	for _, m := range allow {
-		if m.Model == "" || strings.EqualFold(m.Model, "AUTO") {
-			any = true
-			break
+		if m.Model == "" {
+			return models
+		}
+		if !strings.EqualFold(m.Model, "AUTO") {
+			allowed[m.Model] = true
 		}
-		allowed[m.Model] = true
-	}
-	if any {
-		return models
 	}
 	out := make([]string, 0, len(models))
 	seen := map[string]bool{}
@@ -179,24 +191,16 @@ func intersectModels(models []string, allow []config.ModelScope) []string {
 }
 
 // checkModelScope validates the effective model against the key's model scope
-// and token quota. Returns an error message when rejected. A scope entry with
-// model "AUTO" grants all models; its quota caps the key's total tokens.
+// and token quota. Returns an error message when rejected.
+//
+// A scope entry with model "AUTO" only allows requests where the effective
+// model is AUTO (the routing mode). It does NOT grant access to specific model
+// ids — that requires an explicit scope entry for the model.
 func (g *Gateway) checkModelScope(ctx context.Context, model string) string {
 	allow := g.allowedModels(ctx)
 	if allow == nil {
 		return ""
 	}
-	for _, sc := range allow {
-		if sc.Model != "" && strings.EqualFold(sc.Model, "AUTO") {
-			if sc.TokenQuota > 0 {
-				used := g.scopeTokens(ctx, sc)
-				if used >= sc.TokenQuota {
-					return fmt.Sprintf("token quota exceeded (%d/%d)", used, sc.TokenQuota)
-				}
-			}
-			return ""
-		}
-	}
 	for _, sc := range allow {
 		if sc.Model != model {
 			continue
@@ -229,12 +233,15 @@ func (g *Gateway) scopeTokens(ctx context.Context, sc config.ModelScope) int64 {
 // source that actually serves the bare model (via Registry.EffectiveModel), so
 // model ids that themselves contain separators (e.g. "deepseek-v4-flash-free")
 // are never corrupted (P10-2).
+//
+// A scope entry with model "AUTO" only matches the literal AUTO routing mode;
+// it does NOT grant access to specific model ids.
 func (g *Gateway) hasScopeModel(list []config.ModelScope, s string) bool {
 	if r := g.core.Registry(); r != nil {
 		s = r.EffectiveModel(s)
 	}
 	for _, x := range list {
-		if x.Model == s || (x.Model != "" && strings.EqualFold(x.Model, "AUTO")) {
+		if x.Model == s {
 			return true
 		}
 	}
@@ -287,6 +294,8 @@ func (g *Gateway) handleChat(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "invalid_request", "invalid json: "+err.Error())
 		return
 	}
+	// 客户端自带的会话标识（若有）比推导出来的更准，见 clientSessionFromRequest。
+	clientSession := clientSessionFromRequest(r, req.PromptCacheKey)
 	if len(req.Messages) == 0 {
 		writeError(w, http.StatusBadRequest, "invalid_request", "messages is required")
 		return
@@ -317,6 +326,7 @@ func (g *Gateway) handleChat(w http.ResponseWriter, r *http.Request) {
 			ToolChoice:      req.ToolChoice,
 			DisableThinking: req.DisableThinking,
 			ExtraBody:       req.ExtraBody,
+			ClientSession:   clientSession,
 		}
 		rec := &Req{
 			Key:  keyID(reqKey(ctx)),
@@ -372,6 +382,7 @@ func (g *Gateway) handleChat(w http.ResponseWriter, r *http.Request) {
 		ToolChoice:      req.ToolChoice,
 		DisableThinking: req.DisableThinking,
 		ExtraBody:       req.ExtraBody,
+		ClientSession:   clientSession,
 	}
 	rec := &Req{
 		Key:    keyID(reqKey(ctx)),
@@ -517,21 +528,115 @@ func upstreamErrStatus(err error) int {
 	return http.StatusBadGateway
 }
 
+// overflowMarkers 匹配上游「上下文超窗」类措辞。
+//
+// 上游写法五花八门，且**不在 pi 客户端的识别列表里**。pi 靠
+// @earendil-works/pi-ai 的 OVERFLOW_PATTERNS 判断超窗并据此触发压缩重试，
+// 而 justworker 返回的是「请精简对话历史…(Context window is full…)」——
+// 与那 25 条正则一条都不匹配，于是 pi 既不压缩也不重试，只把它当成一条
+// 普通上游错误。这里把可识别的超窗措辞归一化成 pi 一定认得的标记。
+var overflowMarkers = []*regexp.Regexp{
+	regexp.MustCompile(`(?i)context[ _-]?window is full`),
+	regexp.MustCompile(`(?i)context[_ ]length[_ ]exceeded`),
+	regexp.MustCompile(`(?i)exceeds? the context window`),
+	regexp.MustCompile(`(?i)maximum context length`),
+	regexp.MustCompile(`(?i)reduce the length of the messages`),
+	regexp.MustCompile(`(?i)too many tokens`),
+	regexp.MustCompile(`(?i)token limit exceeded`),
+	regexp.MustCompile(`请精简对话历史`),
+	regexp.MustCompile(`上下文(长度)?超(出|限)`),
+	regexp.MustCompile(`对话历史过长`),
+}
+
+// overflowCanonical 命中 pi 的 /context[_ ]length[_ ]exceeded/i。
+//
+// 注意：这个前缀只是必要条件，不是充分条件——pi 还会先用
+// NON_OVERFLOW_PATTERNS 排除整条消息，见 overflowClientMessage。
+const overflowCanonical = "context_length_exceeded"
+
+// looksLikeOverflow 判断错误文本是否属于上下文超窗。
+func looksLikeOverflow(s string) bool {
+	for _, re := range overflowMarkers {
+		if re.MatchString(s) {
+			return true
+		}
+	}
+	return false
+}
+
 // clientUpstreamErr collapses upstream failure details into a short message
 // for the client: per-tier bodies (WAF HTML pages, quota payloads, ...) stay
 // in rec.Err / the stats API and the server log instead of the response.
 // Per-tier one-line reasons are kept (quota/cooling skips carry no error body
 // and are the actionable part); each is capped so HTML dumps can't leak.
+//
+// 超窗会被归一化成「干净」的 overflowCanonical 消息，见 overflowClientMessage。
 func clientUpstreamErr(err error) string {
 	log.Printf("[gateway] upstream failure surfaced to client: %v", err)
+	if looksLikeOverflow(err.Error()) {
+		return overflowClientMessage(err)
+	}
+	return upstreamErrSummary(err)
+}
+
+// overflowHint 是给客户端的超窗说明，刻意只用 pi 认得的措辞。
+const overflowHint = "context window is full; reduce the length of the messages"
+
+// clientSessionFromRequest 取客户端自带的会话标识，拿不到时返回 ""。
+//
+// 通用 OpenAI 客户端默认不带会话 id，但 pi 支持：只要 provider 的 compat 里打开
+// sendSessionAffinityHeaders，pi 就会把**平台真实的会话 id**（uuidv7，整个会话
+// 恒定）放到 x-session-affinity / x-client-request-id 上（sessionAffinityFormat
+// 为 openrouter 时是 x-session-id，为 openai 时是 session_id）。
+// 有了它就不必再从首条 user 消息推导会话指纹（那只在客户端不发会话 id 时才作为
+// 退路，且历史压缩后会漂移）。prompt_cache_key 是 OpenAI 原生的缓存键，
+// 客户端若带也一并当会话用。
+//
+// 刻意不采纳 x-client-request-id：名字含 request，部分客户端每请求都换，
+// 拿它当会话会让上游缓存永不命中。pi 总会同时发 x-session-affinity，够用。
+func clientSessionFromRequest(r *http.Request, bodyKey string) string {
+	for _, h := range []string{"X-Session-Affinity", "X-Session-Id", "Session-Id"} {
+		if v := strings.TrimSpace(r.Header.Get(h)); v != "" {
+			return v
+		}
+	}
+	return strings.TrimSpace(bodyKey)
+}
+
+// overflowClientMessage 为超窗失败生成「干净」的客户端消息。
+//
+// 为什么不能沿用 upstreamErrSummary：pi 的 isContextOverflow 先查
+// NON_OVERFLOW_PATTERNS（/rate limit/、/too many requests/、Bedrock 前缀），
+// 一旦命中就直接判为「非超窗」——**哪怕消息里已经有 context_length_exceeded**，
+// pi 也不会压缩重试。而 AUTO 链的失败消息天生是多 tier 原因的拼接：
+// 超窗 tier（gozen 400 maximum context length）常与配额/限流 tier
+// （429 token plan exhausted、cooling、no free slot）同时出现。
+// 把明细原样带出去，等于让一条限流 tier 的措辞反过来封杀超窗识别。
+// 所以这里只保留「超窗」措辞 + 是哪个源超的窗，其余一律不带。
+func overflowClientMessage(err error) string {
+	var ce *scheduler.ChainErr
+	if errors.As(err, &ce) {
+		for _, t := range ce.Tiers {
+			if looksLikeOverflow(t.Err.Error()) {
+				return fmt.Sprintf("%s: %s (%s/%s)", overflowCanonical, overflowHint, t.Source, t.Model)
+			}
+		}
+	}
+	return fmt.Sprintf("%s: %s", overflowCanonical, overflowHint)
+}
+
+// upstreamErrSummary 把上游失败压成一行短消息。
+func upstreamErrSummary(err error) string {
 	var ce *scheduler.ChainErr
 	if errors.As(err, &ce) {
 		parts := make([]string, 0, len(ce.Tiers)+len(ce.Skipped))
 		for _, t := range ce.Tiers {
-			parts = append(parts, types.OneLine(fmt.Sprintf("%s/%s: %v", t.Source, t.Model, t.Err), 80))
+			// 160 而不是 80：短诊断词（"Context window is full"）常落在尾部，
+			// 80 字节按字节截断正好会把它切掉，超窗就再也认不出来。
+			parts = append(parts, types.OneLine(fmt.Sprintf("%s/%s: %v", t.Source, t.Model, t.Err), 160))
 		}
 		for _, sk := range ce.Skipped {
-			parts = append(parts, types.OneLine(sk, 80))
+			parts = append(parts, types.OneLine(sk, 160))
 		}
 		msg := strings.Join(parts, "; ")
 		if len(msg) > 300 {
@@ -606,6 +711,7 @@ func writeChatCompletion(w http.ResponseWriter, resp *types.UnifiedResponse, mod
 		Created: time.Now().Unix(),
 		Model:   modelName,
 		Choices: []ChatChoice{{Index: 0, Message: msg, FinishReason: resp.FinishReason}},
+		Cost:    resp.Cost,
 	}
 	if resp.TokenUsage.Total > 0 || resp.TokenUsage.Prompt > 0 || resp.TokenUsage.Completion > 0 {
 		out.Usage = &resp.TokenUsage
@@ -725,11 +831,15 @@ func (g *Gateway) pumpStream(w http.ResponseWriter, rec *Req, chunks <-chan type
 	// source's status-page latency average.
 	rec.FirstByteMs = time.Since(t0).Milliseconds()
 	var lastUsage *types.TokenUsage
+	var lastCost string
 	lastFinish := ""
 	for ck := range chunks {
 		if ck.Usage != nil {
 			lastUsage = mergeUsage(lastUsage, ck.Usage)
 		}
+		if ck.Cost != "" {
+			lastCost = ck.Cost
+		}
 		chunk := ChatChunk{
 			ID: id, Object: "chat.completion.chunk", Created: created, Model: modelName,
 		}
@@ -796,6 +906,14 @@ func (g *Gateway) pumpStream(w http.ResponseWriter, rec *Req, chunks <-chan type
 			ID: id, Object: "chat.completion.chunk", Created: created, Model: modelName,
 			Choices: []ChunkChoice{},
 			Usage:   tut,
+			Cost:    lastCost,
+		})
+	} else if lastCost != "" {
+		// Cost arrived without any usage (OpenCode sends it on its own frame).
+		send(ChatChunk{
+			ID: id, Object: "chat.completion.chunk", Created: created, Model: modelName,
+			Choices: []ChunkChoice{},
+			Cost:    lastCost,
 		})
 	}
 	fmt.Fprintf(w, "data: [DONE]\n\n")

internal/gateway/client_session_test.go

@@ -0,0 +1,47 @@
+package gateway
+
+import (
+	"net/http"
+	"testing"
+)
+
+// 客户端自带的会话标识必须被采纳：它比「首条 user 消息指纹」更准
+// （历史压缩后指纹会漂移），也是唯一能天然按会话隔离的来源。
+func TestClientSessionFromRequestHeaders(t *testing.T) {
+	cases := []struct {
+		name    string
+		headers map[string]string
+		bodyKey string
+		want    string
+	}{
+		{"pi 默认格式 x-session-affinity", map[string]string{"X-Session-Affinity": "ses-1"}, "", "ses-1"},
+		{"openrouter 格式 x-session-id", map[string]string{"X-Session-Id": "ses-2"}, "", "ses-2"},
+		{"openai 格式 session_id", map[string]string{"Session-Id": "ses-3"}, "", "ses-3"},
+		{"body prompt_cache_key 兜底", nil, "cache-4", "cache-4"},
+		{"头优先于 body", map[string]string{"X-Session-Affinity": "ses-5"}, "cache-x", "ses-5"},
+		{"空白不算", map[string]string{"X-Session-Affinity": "   "}, "", ""},
+		{"都没有则为空（适配器自行推导）", nil, "", ""},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			r, _ := http.NewRequest(http.MethodPost, "/v1/chat/completions", nil)
+			for k, v := range tc.headers {
+				r.Header.Set(k, v)
+			}
+			if got := clientSessionFromRequest(r, tc.bodyKey); got != tc.want {
+				t.Errorf("clientSessionFromRequest = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// 刻意不采纳 x-client-request-id：名字含 request，部分客户端每请求都换，
+// 拿它当会话会让上游前缀缓存永不命中。
+func TestClientRequestIDIsNotUsedAsSession(t *testing.T) {
+	r, _ := http.NewRequest(http.MethodPost, "/v1/chat/completions", nil)
+	r.Header.Set("X-Client-Request-Id", "per-request-uuid")
+	if got := clientSessionFromRequest(r, ""); got != "" {
+		t.Errorf("x-client-request-id 不应被当作会话（否则缓存永不命中），got %q", got)
+	}
+}

internal/gateway/gateway_test.go

@@ -670,8 +670,11 @@ func TestHasScopeModelWithSourcePrefix(t *testing.T) {
 	if g.hasScopeModel(scope, "deepseek-v4-flash-free-extra") {
 		t.Error("hasScopeModel returned true for unrelated model")
 	}
-	if !g.hasScopeModel([]config.ModelScope{{Model: "AUTO"}}, "zen:anything") {
-		t.Error("AUTO scope should allow any prefixed model")
+	if g.hasScopeModel([]config.ModelScope{{Model: "AUTO"}}, "zen:deepseek-v4-flash-free") {
+		t.Error("AUTO scope must NOT grant specific model ids even with prefix")
+	}
+	if g.hasScopeModel([]config.ModelScope{{Model: "AUTO"}}, "deepseek-v4-pro") {
+		t.Error("AUTO scope must NOT grant specific model ids")
 	}
 }
 

internal/gateway/overflow_err_test.go

@@ -0,0 +1,167 @@
+package gateway
+
+import (
+	"errors"
+	"regexp"
+	"strings"
+	"testing"
+
+	"llmsproxy/internal/scheduler"
+	"llmsproxy/internal/types"
+)
+
+// piOverflowRe 是 @earendil-works/pi-ai 的 OVERFLOW_PATTERNS 中对应的一条。
+// 归一化标记必须命中它，否则改了等于没改：客户端仍不会压缩重试。
+var piOverflowRe = regexp.MustCompile(`context[_ ]length[_ ]exceeded`)
+
+func TestOverflowCanonicalMatchesPiPattern(t *testing.T) {
+	if !piOverflowRe.MatchString(overflowCanonical) {
+		t.Fatalf("归一化标记 %q 不匹配 pi 的超窗正则，客户端仍不会压缩重试", overflowCanonical)
+	}
+}
+
+// justworker 的真实措辞：与 pi 现有 25 条正则一条都不匹配，
+// 所以必须在网关侧归一化，否则超窗对客户端完全不可见。
+func TestJustworkerOverflowIsNormalized(t *testing.T) {
+	raw := "请精简对话历史…(Context window is full, please reduce the conversation history)…"
+
+	// 前提校验：原始措辞确实不被 pi 认出（否则本用例失去意义）。
+	if piOverflowRe.MatchString(raw) {
+		t.Fatalf("前提不成立：原始措辞本就匹配 pi 正则: %q", raw)
+	}
+	if !looksLikeOverflow(raw) {
+		t.Fatalf("网关应识别出这是超窗: %q", raw)
+	}
+
+	err := &scheduler.ChainErr{Tiers: []scheduler.TierError{{
+		Tier: 1, Source: "justworker", Model: "claude-opus-5", Err: errors.New(raw),
+	}}}
+
+	got := clientUpstreamErr(err)
+	if !piOverflowRe.MatchString(got) {
+		t.Fatalf("归一化后仍不匹配 pi 正则，客户端不会压缩重试: %q", got)
+	}
+}
+
+// 直连路径（非 AUTO 链）也要归一化——它走的是同一个入口。
+func TestDirectPathOverflowIsNormalized(t *testing.T) {
+	got := clientUpstreamErr(errors.New("upstream 400: Context window is full"))
+	if !piOverflowRe.MatchString(got) {
+		t.Fatalf("直连超窗未被归一化: %q", got)
+	}
+}
+
+// 非超窗错误不能被加上超窗标记，否则会把普通失败误报成需要压缩。
+func TestNonOverflowNotNormalized(t *testing.T) {
+	err := &scheduler.ChainErr{Tiers: []scheduler.TierError{{
+		Tier: 1, Source: "x", Model: "y", Err: errors.New("502 Bad Gateway: upstream connect error"),
+	}}}
+	got := clientUpstreamErr(err)
+	if strings.Contains(got, overflowCanonical) {
+		t.Fatalf("普通上游失败被误标为超窗: %q", got)
+	}
+	if !strings.Contains(got, "502 Bad Gateway") {
+		t.Fatalf("普通失败的诊断信息应保留: %q", got)
+	}
+}
+
+// 回归：短诊断词常落在错误尾部，80 字节截断会正好把它切掉，
+// 超窗就永远认不出来。宽度放宽后必须保住。
+func TestOverflowPhraseSurvivesTruncationWidth(t *testing.T) {
+	prefix := strings.Repeat("x", 100)
+	// OneLine 的长度限制作用于整条 "source/model: err"，不是只算 err 本身。
+	full := "justworker/claude-opus-5: " + prefix + " Context window is full"
+
+	// 前提：80 字节下短语确实会被切掉（这正是修复前的行为）。
+	if got := types.OneLine(full, 80); strings.Contains(got, "Context window is full") {
+		t.Fatalf("前提不成立：80 字节下短语居然还在: %q", got)
+	}
+	// 160 字节下必须保住，否则超窗识别会被截断悄悄破坏。
+	if got := types.OneLine(full, 160); !strings.Contains(got, "Context window is full") {
+		t.Fatalf("160 字节应保住尾部短诊断词: %q", got)
+	}
+
+	err := &scheduler.ChainErr{Tiers: []scheduler.TierError{{
+		Tier: 1, Source: "justworker", Model: "claude-opus-5",
+		Err: errors.New(prefix + " Context window is full"),
+	}}}
+
+	got := clientUpstreamErr(err)
+	if !strings.Contains(strings.ToLower(got), "context window is full") {
+		t.Fatalf("宽度 160 应保住尾部短诊断词，实际: %q", got)
+	}
+	if !piOverflowRe.MatchString(got) {
+		t.Fatalf("归一化标记丢失: %q", got)
+	}
+}
+
+// piNonOverflowRe 是 @earendil-works/pi-ai 的 NON_OVERFLOW_PATTERNS。
+// pi 的 isContextOverflow 先查这一组，命中则直接判为「非超窗」——
+// 即使 OVERFLOW_PATTERNS 也命中，也不会压缩重试。
+var piNonOverflowRe = []*regexp.Regexp{
+	regexp.MustCompile(`^(Throttling error|Service unavailable):`),
+	regexp.MustCompile(`(?i)rate limit`),
+	regexp.MustCompile(`(?i)too many requests`),
+}
+
+// piWouldCompact 复刻 isContextOverflow 的 Case 1 判定顺序：
+// 先排除 NON_OVERFLOW，再匹配 OVERFLOW。
+func piWouldCompact(errorMessage string) bool {
+	for _, p := range piNonOverflowRe {
+		if p.MatchString(errorMessage) {
+			return false
+		}
+	}
+	return piOverflowRe.MatchString(errorMessage)
+}
+
+// issue 回归：AUTO 链失败消息天然把「超窗 tier」和「配额/限流 tier」拼在一起，
+// 超窗标记后面只要出现 rate limit / too many requests 的字样，
+// pi 就会把整条消息判为「非超窗」而拒绝压缩重试。
+func TestOverflowMessageSurvivesRateLimitedSiblingTier(t *testing.T) {
+	cases := []struct {
+		name    string
+		sibling string
+	}{
+		{"rate limit 措辞", "api error 429: rate limit exceeded"},
+		{"too many requests 措辞", "429 Too Many Requests"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := &scheduler.ChainErr{Tiers: []scheduler.TierError{
+				{Tier: 1, Source: "sensenova", Model: "glm-5.2", Err: errors.New(tc.sibling)},
+				{Tier: 3, Source: "gozen", Model: "deepseek-v4.1-flash",
+					Err: errors.New("api error 400: This model's maximum context length is 1048576 tokens")},
+			}}
+
+			got := clientUpstreamErr(err)
+			if !piWouldCompact(got) {
+				t.Fatalf("同链限流 tier 封杀了超窗识别，pi 不会压缩重试: %q", got)
+			}
+			// 干净：不得把限流 tier 的措辞带出去。
+			for _, p := range piNonOverflowRe {
+				if p.MatchString(got) {
+					t.Fatalf("超窗消息仍带限流措辞 %v: %q", p, got)
+				}
+			}
+			// 但仍要能看出是哪个源超的窗。
+			if !strings.Contains(got, "gozen/deepseek-v4.1-flash") {
+				t.Errorf("超窗源信息丢失: %q", got)
+			}
+		})
+	}
+}
+
+// 直连超窗同样要干净可用。
+func TestDirectOverflowMessageIsClean(t *testing.T) {
+	raw := "api error 400: Error from provider (Console Go): This model's maximum context length is 1048576 tokens. " +
+		"However, you requested 1440050 tokens. Please reduce the length of the messages or completion."
+	got := clientUpstreamErr(errors.New(raw))
+	if !piWouldCompact(got) {
+		t.Fatalf("直连超窗未被 pi 识别: %q", got)
+	}
+	if !strings.Contains(got, overflowCanonical) {
+		t.Fatalf("缺少归一化标记: %q", got)
+	}
+}

internal/lua/adapters/agentrouter.lua

@@ -5,10 +5,12 @@ adapter.version = "1.0.0"
 adapter.endpoint = "/chat/completions"
 adapter.headers = {}
 
--- AgentRouter 的 WAF 会按客户端指纹白名单校验，只放行官方客户端。
--- 这里通过 build_headers 注入官方客户端 User-Agent 以通过校验。
--- 默认 QwenCode 指纹（实测可通）；可在 source.meta.user_agent 覆盖成 Claude Code 指纹。
-
+-- AgentRouter 的阿里云 WAF 按三重维度校验：出口 IP（必须海外）、
+-- TLS 指纹（JS/Go HTTP 层与 curl 不同）、浏览器指纹 header 集。
+-- 纯 UA 已不够：WAF 拦 12 种 agent CLI UA 中的 10 种（全 405 HTML），
+-- 只有同时带 Origin: qwen.ai + Referer + X-Requested-With 才放行，
+-- 且同 IP 短时间连续 3+ 次请求会被速率封禁，靠 adapter 侧低频调用 +
+-- llmsproxy 的 prefFailStep 冷却自然限制，来源无法控制速率。
 local default_ua = "QwenCode/0.2.0 (linux; x64)"
 
 -- AgentRouter fronts Claude models (claude-opus-4-8), and Claude upstreams
@@ -65,6 +67,13 @@ function adapter.build_headers(meta)
         ["Content-Type"] = "application/json",
         ["Authorization"] = "Bearer " .. meta.api_key,
         ["User-Agent"] = ua,
+        -- QwenCode client fingerprint: WAF rejects bare UA without these.
+        ["Accept"] = "application/json, text/plain, */*",
+        ["Accept-Language"] = "zh-CN,zh;q=0.9",
+        ["Origin"] = "https://qwen.ai",
+        ["Referer"] = "https://qwen.ai/",
+        ["X-Requested-With"] = "XMLHttpRequest",
+        ["Connection"] = "keep-alive",
     }
 end
 

internal/lua/adapters/gemini.lua

@@ -7,6 +7,10 @@ adapter.headers = {}
 
 -- Gemini API: POST /v1/models/{model}:generateContent
 -- Auth: API key in query param ?key=XXX or Authorization: Bearer XXX
+--
+-- 请求方向必须把 OpenAI 的工具调用翻译成 Gemini 的 functionCall /
+-- functionResponse，否则 agent 回放的历史里助手那一轮的调用会凭空消失，
+-- 紧随其后的工具结果就成了「无来源」的孤立结果，模型只能反复重发同一个调用。
 function adapter.transform_request(raw_body)
     local ok, req = pcall(json.decode, raw_body)
     if not ok then return raw_body end
@@ -14,16 +18,23 @@ function adapter.transform_request(raw_body)
     -- 将 OpenAI 风格 content（字符串或 [{type:*}] 数组）拆成 Gemini parts
     local function to_parts(content)
         if type(content) == "string" then
+            if content == "" then return {} end
             return { { text = content } }
         end
         local parts = {}
         for _, p in ipairs(content or {}) do
-            if p.type == "text" then
-                table.insert(parts, { text = p.text })
-            elseif p.type == "image_url" and type(p.image_url) == "table" and p.image_url.url then
-                local mt, b64 = string.match(p.image_url.url, "^data:([^,]+);base64,(.+)$")
-                if b64 then
-                    table.insert(parts, { inline_data = { mime_type = mt or "image/png", data = b64 } })
+            if type(p) == "string" then
+                if p ~= "" then table.insert(parts, { text = p }) end
+            elseif type(p) == "table" then
+                if p.type == "text" then
+                    if p.text ~= nil and p.text ~= "" then
+                        table.insert(parts, { text = p.text })
+                    end
+                elseif p.type == "image_url" and type(p.image_url) == "table" and p.image_url.url then
+                    local mt, b64 = string.match(p.image_url.url, "^data:([^,]+);base64,(.+)$")
+                    if b64 then
+                        table.insert(parts, { inline_data = { mime_type = mt or "image/png", data = b64 } })
+                    end
                 end
             end
         end
@@ -31,11 +42,59 @@ function adapter.transform_request(raw_body)
     end
 
     local contents = {}
+    local system = ""
+    local call_names = {}   -- tool_call_id -> 函数名（functionResponse 只认名字）
+
     for _, m in ipairs(req.messages or {}) do
-        table.insert(contents, {
-            role = (m.role == "assistant") and "model" or m.role,
-            parts = to_parts(m.content)
-        })
+        local role = m.role or "user"
+
+        if role == "system" then
+            if type(m.content) == "string" then
+                system = system .. m.content .. "\n"
+            end
+
+        elseif role == "assistant" then
+            local parts = to_parts(m.content)
+            if type(m.tool_calls) == "table" then
+                for _, tc in ipairs(m.tool_calls) do
+                    if type(tc) == "table" then
+                        local fn = tc["function"] or {}
+                        local args = fn.arguments
+                        if type(args) == "string" and args ~= "" then
+                            local aok, decoded = pcall(json.decode, args)
+                            args = aok and decoded or {}
+                        elseif type(args) ~= "table" then
+                            args = {}
+                        end
+                        if tc.id ~= nil then call_names[tc.id] = fn.name or "" end
+                        table.insert(parts, {
+                            functionCall = { name = fn.name or "", args = args }
+                        })
+                    end
+                end
+            end
+            -- Gemini 不接受空的 parts 数组；无可发送内容的轮次直接跳过
+            if #parts > 0 then
+                table.insert(contents, { role = "model", parts = parts })
+            end
+
+        elseif role == "tool" then
+            local name = call_names[m.tool_call_id] or m.name or ""
+            local text = type(m.content) == "string" and m.content or ""
+            table.insert(contents, {
+                role = "user",
+                parts = { { functionResponse = {
+                    name = name,
+                    response = { content = text },
+                } } }
+            })
+
+        else
+            local parts = to_parts(m.content)
+            if #parts > 0 then
+                table.insert(contents, { role = "user", parts = parts })
+            end
+        end
     end
 
     local gemini_req = {
@@ -46,6 +105,30 @@ function adapter.transform_request(raw_body)
         }
     }
 
+    if system ~= "" then
+        gemini_req.systemInstruction = { parts = { { text = system } } }
+    end
+
+    -- tools -> functionDeclarations
+    if type(req.tools) == "table" then
+        local decls = {}
+        for _, t in ipairs(req.tools) do
+            if type(t) == "table" and type(t["function"]) == "table" then
+                local fn = t["function"]
+                local params = fn.parameters
+                if type(params) ~= "table" then params = { type = "object", properties = {} } end
+                table.insert(decls, {
+                    name = fn.name or "",
+                    description = fn.description or "",
+                    parameters = params,
+                })
+            end
+        end
+        if #decls > 0 then
+            gemini_req.tools = { { functionDeclarations = decls } }
+        end
+    end
+
     if req.stream then
         gemini_req.stream = true
     end

internal/lua/adapters/ollama.lua

@@ -6,6 +6,10 @@ adapter.endpoint = "/api/chat"
 adapter.headers = {}
 
 -- Ollama API 格式：{ model, messages, stream, options:{temperature,num_predict} }
+-- 工具调用必须一并翻译：Ollama 的 assistant 消息用 tool_calls（arguments 是对象
+-- 而非 JSON 字符串），工具结果用 tool 角色 + tool_name。此前这里只复制了
+-- role/content，助手那轮的调用和 tool 消息的归属全部丢失，模型看到无来源的
+-- 工具结果就只能反复重发同一个调用。
 function adapter.transform_request(raw_body)
     local ok, req = pcall(json.decode, raw_body)
     if not ok then return raw_body end
@@ -22,6 +26,7 @@ function adapter.transform_request(raw_body)
     -- 转换 messages 格式（Ollama messages 支持 images base64 数组）
     if req.messages then
         local msgs = {}
+        local call_names = {}   -- tool_call_id -> 函数名
         for _, m in ipairs(req.messages) do
             local text, images
             if type(m.content) == "string" then
@@ -30,22 +35,61 @@ function adapter.transform_request(raw_body)
                 text = ""
                 images = {}
                 for _, p in ipairs(m.content or {}) do
-                    if p.type == "text" then
-                        text = text .. (p.text or "")
-                    elseif p.type == "image_url" and type(p.image_url) == "table" and p.image_url.url then
-                        local b64 = string.match(p.image_url.url, "^data:[^,]+;base64,(.+)$")
-                        if b64 then table.insert(images, b64) end
+                    if type(p) == "table" then
+                        if p.type == "text" then
+                            text = text .. (p.text or "")
+                        elseif p.type == "image_url" and type(p.image_url) == "table" and p.image_url.url then
+                            local b64 = string.match(p.image_url.url, "^data:[^,]+;base64,(.+)$")
+                            if b64 then table.insert(images, b64) end
+                        end
                     end
                 end
                 if #images == 0 then images = nil end
             end
             local msg = { role = m.role, content = text }
             if images then msg.images = images end
+
+            -- 助手轮的工具调用：arguments 转成对象
+            if type(m.tool_calls) == "table" and #m.tool_calls > 0 then
+                local tcs = {}
+                for _, tc in ipairs(m.tool_calls) do
+                    if type(tc) == "table" then
+                        local fn = tc["function"] or {}
+                        local args = fn.arguments
+                        if type(args) == "string" and args ~= "" then
+                            local aok, decoded = pcall(json.decode, args)
+                            args = aok and decoded or {}
+                        elseif type(args) ~= "table" then
+                            args = {}
+                        end
+                        if tc.id ~= nil then call_names[tc.id] = fn.name or "" end
+                        table.insert(tcs, {
+                            ["function"] = { name = fn.name or "", arguments = args }
+                        })
+                    end
+                end
+                if #tcs > 0 then msg.tool_calls = tcs end
+            end
+
+            -- 工具结果：Ollama 用 tool_name 标识归属（不认 tool_call_id）
+            if m.role == "tool" then
+                local name = call_names[m.tool_call_id] or m.name or ""
+                if m.tool_call_id ~= nil then
+                    msg.tool_call_id = m.tool_call_id
+                end
+                if name ~= "" then msg.tool_name = name end
+            end
+
             table.insert(msgs, msg)
         end
         ollama_req.messages = msgs
     end
 
+    -- tools 透传（Ollama 的 shape 与 OpenAI 一致）
+    if type(req.tools) == "table" and #req.tools > 0 then
+        ollama_req.tools = req.tools
+    end
+
     return json.encode(ollama_req)
 end
 

internal/lua/adapters/opencode.lua

@@ -34,8 +34,10 @@ end
 
 -- OpenAI /chat/completions format (pass-through, strip provider-specific fields)
 -- zen 上游 schema 只接受 text content part（无视觉/音频能力）：多模态 part
--- （image_url / input_audio / file 等）一律剥离；因此失去全部 content 的
--- 消息整条丢弃，避免上游 "unknown variant `image_url`, expected `text`"。
+-- （image_url / input_audio / file 等）一律剥离。剥离后 content 变空的消息
+-- 若不再携带 tool_calls / tool_call_id 才整条丢弃（避免上游
+-- "unknown variant `image_url`, expected `text`"）；带工具调用的必须保留，
+-- 否则会把紧随其后的 tool 结果变成孤儿，模型会反复重发同一个调用。
 -- zen 上游角色白名单只有 system / user / assistant / tool / latest_reminder：
 -- OpenAI 的 developer（及 function 等）不在其中，直接透传会触发上游
 -- "unknown variant `developer`, expected one of ..." 错误；统一归一化为 system。
@@ -52,8 +54,14 @@ function adapter.transform_request(raw_body)
     if not ok then return raw_body end
     req.disable_thinking = nil
     req.extra_body = nil
-    if type(req.stream_options) ~= "table" then req.stream_options = {} end
-    req.stream_options.include_usage = true
+    -- stream_options is only valid alongside stream:true. Sending it on a
+    -- non-streaming request is rejected by stricter upstreams (OpenCode Go:
+    -- "stream_options should be set along with stream"), which failed every
+    -- non-stream call. Only attach it when the request actually streams.
+    if req.stream then
+        if type(req.stream_options) ~= "table" then req.stream_options = {} end
+        req.stream_options.include_usage = true
+    end
     if req.messages then
         local kept = {}
         for _, msg in ipairs(req.messages) do
@@ -72,7 +80,24 @@ function adapter.transform_request(raw_body)
                     end
                 end
                 if #parts == 0 then
-                    drop = true
+                    -- Content collapsed to nothing after stripping unsupported
+                    -- parts. A message that still carries a tool call must
+                    -- NEVER be dropped: the very next message is its tool
+                    -- result, and dropping the call orphans that result. The
+                    -- model then sees a result for a call it never made and
+                    -- re-issues the same tool call on every turn (observed as
+                    -- an infinite "repeated tool call" loop).
+                    --
+                    -- This is the common shape for agent clients: an assistant
+                    -- turn whose content is only [thinking, toolCall] serialises
+                    -- to content:[] with tool_calls — exactly the case that used
+                    -- to vanish here. Emit "" instead, which zen accepts.
+                    if (type(msg.tool_calls) == "table" and #msg.tool_calls > 0)
+                        or msg.tool_call_id ~= nil then
+                        msg.content = ""
+                    else
+                        drop = true
+                    end
                 else
                     msg.content = parts
                 end

internal/lua/adapters/opencodego.lua

@@ -0,0 +1,354 @@
+local adapter = {}
+
+adapter.name = "opencodego"
+adapter.version = "1.0.0"
+adapter.endpoint = "/chat/completions"
+
+-- OpenCode Go（包月订阅端点，https://opencode.ai/zen/go/v1）
+--
+-- 与 OpenCode Zen（opencodezen.lua，https://opencode.ai/zen/v1）是两个不同的
+-- 服务，行为要求并不相同，因此各有专用适配器：
+--
+--   * 本适配器（Go）服务包月订阅池。上游**强制要求**
+--     `x-opencode-session` 头，缺失直接 400 "MissingSessionID"。
+--   * Go 的 thinking 模型（deepseek-v4.1-flash 等）**必须回传** assistant 轮的
+--     `reasoning_content`，否则 400：
+--       The `reasoning_content` in the thinking mode must be passed back to the API.
+--     这是本适配器与 Zen 适配器最关键的差异 —— Zen 会剥掉它，Go 必须原样保留。
+--   * Go 上游对协议更严格：非流式请求带 `stream_options` 会被拒
+--     （"stream_options should be set along with stream"）。
+--
+-- 同样需要 opencode 客户端指纹（UA + x-opencode-*）才能被正确识别与路由。
+adapter.headers = {
+    ["User-Agent"] = "opencode/1.18.21 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14",
+}
+
+-- 每请求生成身份头。沙箱无 os/math，用 meta.timestamp + 请求体哈希派生：
+-- 同秒内重复请求 id 相同可接受（zen 只校验存在性，不校验格式）。
+local function rand_id(prefix, seed)
+    return prefix .. string.sub(sha256_hex(seed), 1, 24)
+end
+
+-- 会话指纹：取历史里**第一条 user 消息**。
+--
+-- 为什么不直接用客户端的会话 id：实测抓包（tcpdump 抓 127.0.0.1:8081 的真实
+-- agent 请求）确认通用 OpenAI 客户端**根本不发**任何会话标识 —— body 里没有
+-- user / session_id / conversation_id / metadata，请求头也只有 X-Stainless-*
+-- （OpenAI JS SDK）与 User-Agent。opencode 原生客户端那套 x-opencode-session
+-- 是它自己的概念，通用客户端无从转发。
+--
+-- 退而求其次但要够用：历史被逐轮重放，**第一条 user 消息在整个会话里恒定**，
+-- 用它做指纹即可得到"每会话一个 session"，而不是"每源一个 session"。
+-- 拿不到时（无 user 消息）返回空串，调用方回退到按源稳定。
+local function conversation_fingerprint(body)
+    if type(body) ~= "string" or body == "" then return "" end
+    local ok, req = pcall(json.decode, body)
+    if not ok or type(req) ~= "table" then return "" end
+    for _, m in ipairs(req.messages or {}) do
+        if type(m) == "table" and m.role == "user" then
+            local c = m.content
+            if type(c) == "string" then
+                if c ~= "" then return c end
+            elseif type(c) == "table" then
+                for _, part in ipairs(c) do
+                    if type(part) == "table" and part.type == "text" and part.text then
+                        return part.text
+                    end
+                end
+            end
+            return ""
+        end
+    end
+    return ""
+end
+
+-- session_seed 决定上游会话号（x-opencode-session 的种子）。
+--
+-- 优先级：
+--   1) 客户端自带的会话标识（meta.client_session）——pi 等在开启
+--      compat.sendSessionAffinityHeaders 后会发 x-session-affinity，
+--      这是平台真实的会话 id，整个会话恒定且天然按会话隔离。
+--   2) 退路：历史里**第一条 user 消息**做会话指纹。
+--   3) 再退：只按源固定（连 user 消息都没有时）。
+--
+-- 为什么需要 2/3：通用 OpenAI 客户端默认**根本不发**会话标识 —— 实测抓包
+-- （tcpdump 抓 127.0.0.1:8081 真实 agent 请求）确认 body 里没有
+-- user / session_id / conversation_id / metadata，请求头也只有
+-- X-Stainless-*（OpenAI JS SDK）与 User-Agent。opencode 原生客户端那套
+-- x-opencode-session 是它自己的概念，通用客户端无从转发。
+--
+-- 为什么必须稳定：上游前缀缓存是**会话级**的。会话号每请求一变，
+-- 缓存永不命中（实测：固定会号第 2 次命中 5888，每请求换会号则恒为 0）。
+local function session_seed(meta)
+    local src = (meta.source and meta.source.name) or ""
+    local base = "session|llmsproxy|" .. src
+    local cs = meta.client_session
+    if type(cs) == "string" and cs ~= "" then
+        return base .. "|client|" .. cs
+    end
+    return base .. "|" .. conversation_fingerprint(meta.body)
+end
+
+function adapter.build_headers(meta)
+    local ts = tostring(meta.timestamp or "")
+    local src = (meta.source and meta.source.name) or ""
+    return {
+        ["User-Agent"] = adapter.headers["User-Agent"],
+        ["x-opencode-client"] = "cli",
+        -- project 固定：同网关实例共享一个工作区身份
+        ["x-opencode-project"] = string.sub(sha256_hex("llmsproxy|" .. src), 1, 32),
+        -- session 必须**按源稳定**，不能每请求换：上游的前缀缓存在同一 session
+        -- 内才复用。实测（同一段 6032 token 提示词）：
+        --   固定 session  -> 第 2 次命中 5888/6032，cached_tokens=5888
+        --   每请求换 session -> 永远 0 命中
+        -- 原先用 meta.timestamp 派生，等于每请求都是新会话，缓存永远无效，
+        -- 上游也无法做会话亲和路由。
+        ["x-opencode-session"] = rand_id("ses_", session_seed(meta)),
+        -- request id 仍每请求唯一（它只是请求标识，不参与缓存键）
+        ["x-opencode-request"] = rand_id("msg_", "request|" .. ts .. "|" .. tostring(meta.body or "")),
+    }
+end
+
+-- OpenAI /chat/completions format (pass-through, strip provider-specific fields)
+-- zen 上游 schema 只接受 text content part（无视觉/音频能力）：多模态 part
+-- （image_url / input_audio / file 等）一律剥离。剥离后 content 变空的消息
+-- 若不再携带 tool_calls / tool_call_id 才整条丢弃（避免上游
+-- "unknown variant `image_url`, expected `text`"）；带工具调用的必须保留，
+-- 否则会把紧随其后的 tool 结果变成孤儿，模型会反复重发同一个调用。
+-- zen 上游角色白名单只有 system / user / assistant / tool / latest_reminder：
+-- OpenAI 的 developer（及 function 等）不在其中，直接透传会触发上游
+-- "unknown variant `developer`, expected one of ..." 错误；统一归一化为 system。
+local ROLE_WHITELIST = {
+    system = true,
+    user = true,
+    assistant = true,
+    tool = true,
+    latest_reminder = true,
+}
+
+function adapter.transform_request(raw_body)
+    local ok, req = pcall(json.decode, raw_body)
+    if not ok then return raw_body end
+    req.disable_thinking = nil
+    req.extra_body = nil
+    -- stream_options is only valid alongside stream:true; sending it on a
+    -- non-streaming request is rejected by strict upstreams.
+    if req.stream then
+        if type(req.stream_options) ~= "table" then req.stream_options = {} end
+        req.stream_options.include_usage = true
+    end
+    if req.messages then
+        local kept = {}
+        for _, msg in ipairs(req.messages) do
+            if type(msg.role) == "string" and not ROLE_WHITELIST[msg.role] then
+                msg.role = "system"
+            end
+            -- Go 的 thinking 模式**必须**回传 reasoning_content：剥掉它会让
+            -- 上游直接 400（"The `reasoning_content` in the thinking mode must
+            -- be passed back to the API"），agent 的每一轮都会失败。
+            -- 注意：与 opencodezen.lua 的行为**相反**，不要在这里剥。
+            --
+            -- 但绝大多数客户端（pi 等）根本不保存也不回传 reasoning，只保留
+            -- 工具调用本身。上游只在“带 tool_calls 的助手轮”上校验这个字段，
+            -- 实测**空串即可通过校验**，所以缺省时补空串：既满足上游的
+            -- 一致性要求，又不伪造任何推理内容（用户看到的 reasoning 仍然是
+            -- 上游本轮真实返回的）。
+            if msg.role == "assistant"
+                and type(msg.tool_calls) == "table" and #msg.tool_calls > 0
+                and msg.reasoning_content == nil then
+                msg.reasoning_content = ""
+            end
+            local drop = false
+            if type(msg.content) == "table" then
+                local parts = {}
+                for _, part in ipairs(msg.content) do
+                    if type(part) == "table" and part.type ~= nil and part.type ~= "text" then
+                        -- multimodal part not supported by zen
+                    else
+                        table.insert(parts, part)
+                    end
+                end
+                if #parts == 0 then
+                    -- Content collapsed to nothing after stripping unsupported
+                    -- parts. A message that still carries a tool call must
+                    -- NEVER be dropped: the very next message is its tool
+                    -- result, and dropping the call orphans that result. The
+                    -- model then sees a result for a call it never made and
+                    -- re-issues the same tool call on every turn (observed as
+                    -- an infinite "repeated tool call" loop).
+                    if (type(msg.tool_calls) == "table" and #msg.tool_calls > 0)
+                        or msg.tool_call_id ~= nil then
+                        msg.content = ""
+                    else
+                        drop = true
+                    end
+                else
+                    msg.content = parts
+                end
+            end
+            if not drop then
+                table.insert(kept, msg)
+            end
+        end
+        req.messages = kept
+    end
+    return json.encode(req)
+end
+
+function adapter.transform_response(raw_body)
+    local ok, resp = pcall(json.decode, raw_body)
+    if not ok or resp == nil then return raw_body end
+
+    local unified = {
+        content = "",
+        finish_reason = "",
+        token_usage = { prompt = 0, completion = 0, total = 0 }
+    }
+
+    if type(resp.usage) == "table" then
+        unified.token_usage.prompt = resp.usage.prompt_tokens or 0
+        unified.token_usage.completion = resp.usage.completion_tokens or 0
+        unified.token_usage.total = resp.usage.total_tokens or 0
+        local hit = 0
+        if type(resp.usage.prompt_tokens_details) == "table" and resp.usage.prompt_tokens_details.cached_tokens ~= nil then
+            hit = resp.usage.prompt_tokens_details.cached_tokens
+            unified.token_usage.prompt_tokens_details = { cached_tokens = hit }
+        end
+        if (resp.usage.prompt_cache_hit_tokens or 0) > 0 then
+            unified.token_usage.prompt_cache_hit_tokens = resp.usage.prompt_cache_hit_tokens
+            unified.token_usage.prompt_cache_miss_tokens = resp.usage.prompt_cache_miss_tokens or 0
+            if hit == 0 then
+                unified.token_usage.prompt_tokens_details = { cached_tokens = resp.usage.prompt_cache_hit_tokens }
+            end
+        end
+        -- 上游报告输出里有多少是思考 token。不给客户端的话，无法判断
+        -- completion_tokens 里多少是「可见回答」、多少是「思考」（都按输出计费）。
+        local ctd = resp.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            unified.token_usage.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
+        end
+    end
+
+    -- 本次调用的费用，上游放在**顶层**且是**字符串**（如 "0"、"0.0012"）。
+    -- Go 订阅是包月制，恒为 "0"；只有 Zen 按量付费模型才有信息量。
+    -- 原样透传：网关不解析、不换算、不汇总 —— 它只是上游事实的搬运者。
+    if resp.cost ~= nil then
+        unified.cost = tostring(resp.cost)
+    end
+
+    if type(resp.choices) == "table" and #resp.choices > 0 then
+        local ch = resp.choices[1]
+        if type(ch.message) == "table" then
+            unified.content = ch.message.content or ""
+            local reasoning = ch.message.reasoning_content or ch.message.reasoning
+            if reasoning then
+                unified.reasoning_content = reasoning
+            end
+            if type(ch.message.tool_calls) == "table" then
+                local tcs = {}
+                for _, tc in ipairs(ch.message.tool_calls) do
+                    local args_ok, args = pcall(json.decode, tc["function"].arguments)
+                    if not args_ok then args = {} end
+                    table.insert(tcs, {
+                        id = tc.id,
+                        type = tc.type or "function",
+                        name = tc["function"].name,
+                        arguments = args
+                    })
+                end
+                unified.tool_calls = tcs
+            end
+        end
+        unified.finish_reason = ch.finish_reason or ""
+    end
+
+    return json.encode(unified)
+end
+
+function adapter.transform_stream_chunk(raw_chunk)
+    local ok, chunk = pcall(json.decode, raw_chunk)
+    if not ok then return "" end
+
+    -- OpenAI-style streams may attach usage to a chunk with empty choices
+    -- (the final usage chunk). Preserve it; the gateway emits it as the
+    -- terminal usage chunk. Note: keys must match Go's TokenUsage json tags
+    -- (prompt/completion/total); the gateway re-emits standard *_tokens.
+    local uses = nil
+    if type(chunk.usage) == "table" then
+        uses = {
+            prompt = chunk.usage.prompt_tokens or chunk.usage.prompt or 0,
+            completion = chunk.usage.completion_tokens or chunk.usage.completion or 0,
+            total = chunk.usage.total_tokens or chunk.usage.total or 0,
+        }
+        -- 独立字段与 prompt_tokens_details **并存**透传，不要写成 elseif：
+        -- 上游命中缓存时两者都发，非流式路径也是两个都带。写成 elseif 会让
+        -- 流式丢掉 prompt_cache_hit_tokens/miss，与同一源的**非流式**产出不一致
+        -- （dsh 优先读 details，但只认独立字段的老客户端会看不到缓存）。
+        if type(chunk.usage.prompt_tokens_details) == "table" and chunk.usage.prompt_tokens_details.cached_tokens ~= nil then
+            uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_tokens_details.cached_tokens }
+        end
+        if (chunk.usage.prompt_cache_hit_tokens or 0) > 0 then
+            uses.prompt_cache_hit_tokens = chunk.usage.prompt_cache_hit_tokens
+            uses.prompt_cache_miss_tokens = chunk.usage.prompt_cache_miss_tokens or 0
+            if uses.prompt_tokens_details == nil then
+                uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_cache_hit_tokens }
+            end
+        end
+        local ctd = chunk.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            uses.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
+        end
+    end
+
+    if not chunk.choices or #chunk.choices == 0 then
+        -- 空 choices 的帧既不是内容也不是结束信号。上游发两种：
+        --   {"choices":[],"usage":{...}}   —— 终帧用量
+        --   {"choices":[],"cost":"0"}      —— 单独的费用帧
+        -- 两者可能落在同一帧上，必须都转出去；早退只带 usage 会把费用丢干净。
+        local out = { done = false }
+        if uses ~= nil then out.usage = uses end
+        if chunk.cost ~= nil then out.cost = tostring(chunk.cost) end
+        if uses == nil and chunk.cost == nil then return "" end
+        return json.encode(out)
+    end
+    local delta = chunk.choices[1].delta or {}
+    local fr = chunk.choices[1].finish_reason
+
+    local finish = (type(fr) == "string" and fr ~= "") and fr or nil
+
+    local unified = {
+        content = delta.content or "",
+        done = (finish ~= nil)
+    }
+    if finish then
+        unified.finish_reason = finish
+    end
+    if uses ~= nil then
+        unified.usage = uses
+    end
+    -- zen 用 reasoning 字段承载推理文本（OpenAI 惯例是 reasoning_content）
+    local reasoning = delta.reasoning_content or delta.reasoning
+    if reasoning then
+        unified.reasoning_content = reasoning
+    end
+    if delta.tool_calls then
+        -- pass raw streaming fragments through; OpenAI clients accumulate index+id+name+arguments
+        unified.tool_calls = delta.tool_calls
+    end
+    return json.encode(unified)
+end
+
+-- 错误收敛（可选钩子）：zen 错误信封固定为 {error={type,message}}；
+-- 免费池限流 FreeUsageLimitError 单独标注。返回 nil 走通用兜底。
+function adapter.transform_error(status, body)
+    local ok, resp = pcall(json.decode, body)
+    if not ok or type(resp) ~= "table" then return nil end
+    local e = resp.error
+    if type(e) ~= "table" then return nil end
+    if e.type == "FreeUsageLimitError" then
+        return "zen free pool quota exhausted"
+    end
+    return e.message
+end
+
+return adapter

internal/lua/adapters/opencodezen.lua

@@ -0,0 +1,342 @@
+local adapter = {}
+
+adapter.name = "opencodezen"
+adapter.version = "1.0.0"
+adapter.endpoint = "/chat/completions"
+
+-- OpenCode Zen（按量付费端点，https://opencode.ai/zen/v1）
+--
+-- 与 OpenCode Go（opencodego.lua，https://opencode.ai/zen/go/v1）是两个不同的
+-- 服务，行为要求并不相同，因此各有专用适配器：
+--
+--   * 本适配器（Zen）服务免费池 / 按量付费池。免费模型必须带 opencode 客户端
+--     指纹（UA + x-opencode-*），否则上游拒绝："free tier can only be used in
+--     OpenCode"。Zen 的免费池以非 thinking 模型为主，历史上回传
+--     reasoning_content 会引出上游报错，故这里剥掉（Go 侧相反，见 opencodego.lua）。
+--   * Go 订阅读者请看 opencodego.lua：那边**必须**回传 reasoning_content，
+--     否则 thinking 模式直接 400。
+--
+-- 缺 x-opencode-client/session/request/project 身份头会被判为匿名客户端，
+-- 部分模型在带 tools 时上游直接失败（流式返回单 chunk
+-- "finish_reason":"network_error" 空 content，非流式 503
+-- "Endpoint is unavailable"，表现为"空回复"）。
+adapter.headers = {
+    ["User-Agent"] = "opencode/1.18.21 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14",
+}
+
+-- 每请求生成身份头。沙箱无 os/math，用 meta.timestamp + 请求体哈希派生：
+-- 同秒内重复请求 id 相同可接受（zen 只校验存在性，不校验格式）。
+local function rand_id(prefix, seed)
+    return prefix .. string.sub(sha256_hex(seed), 1, 24)
+end
+
+-- 会话指纹：取历史里**第一条 user 消息**。
+--
+-- 为什么不直接用客户端的会话 id：实测抓包（tcpdump 抓 127.0.0.1:8081 的真实
+-- agent 请求）确认通用 OpenAI 客户端**根本不发**任何会话标识 —— body 里没有
+-- user / session_id / conversation_id / metadata，请求头也只有 X-Stainless-*
+-- （OpenAI JS SDK）与 User-Agent。opencode 原生客户端那套 x-opencode-session
+-- 是它自己的概念，通用客户端无从转发。
+--
+-- 退而求其次但要够用：历史被逐轮重放，**第一条 user 消息在整个会话里恒定**，
+-- 用它做指纹即可得到"每会话一个 session"，而不是"每源一个 session"。
+-- 拿不到时（无 user 消息）返回空串，调用方回退到按源稳定。
+local function conversation_fingerprint(body)
+    if type(body) ~= "string" or body == "" then return "" end
+    local ok, req = pcall(json.decode, body)
+    if not ok or type(req) ~= "table" then return "" end
+    for _, m in ipairs(req.messages or {}) do
+        if type(m) == "table" and m.role == "user" then
+            local c = m.content
+            if type(c) == "string" then
+                if c ~= "" then return c end
+            elseif type(c) == "table" then
+                for _, part in ipairs(c) do
+                    if type(part) == "table" and part.type == "text" and part.text then
+                        return part.text
+                    end
+                end
+            end
+            return ""
+        end
+    end
+    return ""
+end
+
+-- session_seed 决定上游会话号（x-opencode-session 的种子）。
+--
+-- 优先级：
+--   1) 客户端自带的会话标识（meta.client_session）——pi 等在开启
+--      compat.sendSessionAffinityHeaders 后会发 x-session-affinity，
+--      这是平台真实的会话 id，整个会话恒定且天然按会话隔离。
+--   2) 退路：历史里**第一条 user 消息**做会话指纹。
+--   3) 再退：只按源固定（连 user 消息都没有时）。
+--
+-- 为什么需要 2/3：通用 OpenAI 客户端默认**根本不发**会话标识 —— 实测抓包
+-- （tcpdump 抓 127.0.0.1:8081 真实 agent 请求）确认 body 里没有
+-- user / session_id / conversation_id / metadata，请求头也只有
+-- X-Stainless-*（OpenAI JS SDK）与 User-Agent。opencode 原生客户端那套
+-- x-opencode-session 是它自己的概念，通用客户端无从转发。
+--
+-- 为什么必须稳定：上游前缀缓存是**会话级**的。会话号每请求一变，
+-- 缓存永不命中（实测：固定会号第 2 次命中 5888，每请求换会号则恒为 0）。
+local function session_seed(meta)
+    local src = (meta.source and meta.source.name) or ""
+    local base = "session|llmsproxy|" .. src
+    local cs = meta.client_session
+    if type(cs) == "string" and cs ~= "" then
+        return base .. "|client|" .. cs
+    end
+    return base .. "|" .. conversation_fingerprint(meta.body)
+end
+
+function adapter.build_headers(meta)
+    local ts = tostring(meta.timestamp or "")
+    local src = (meta.source and meta.source.name) or ""
+    return {
+        ["User-Agent"] = adapter.headers["User-Agent"],
+        ["x-opencode-client"] = "cli",
+        -- project 固定：同网关实例共享一个工作区身份
+        ["x-opencode-project"] = string.sub(sha256_hex("llmsproxy|" .. src), 1, 32),
+        -- session 必须**按源稳定**，不能每请求换：上游的前缀缓存在同一 session
+        -- 内才复用。实测（同一段 6032 token 提示词）：
+        --   固定 session  -> 第 2 次命中 5888/6032，cached_tokens=5888
+        --   每请求换 session -> 永远 0 命中
+        -- 原先用 meta.timestamp 派生，等于每请求都是新会话，缓存永远无效，
+        -- 上游也无法做会话亲和路由。
+        ["x-opencode-session"] = rand_id("ses_", session_seed(meta)),
+        -- request id 仍每请求唯一（它只是请求标识，不参与缓存键）
+        ["x-opencode-request"] = rand_id("msg_", "request|" .. ts .. "|" .. tostring(meta.body or "")),
+    }
+end
+
+-- OpenAI /chat/completions format (pass-through, strip provider-specific fields)
+-- zen 上游 schema 只接受 text content part（无视觉/音频能力）：多模态 part
+-- （image_url / input_audio / file 等）一律剥离。剥离后 content 变空的消息
+-- 若不再携带 tool_calls / tool_call_id 才整条丢弃（避免上游
+-- "unknown variant `image_url`, expected `text`"）；带工具调用的必须保留，
+-- 否则会把紧随其后的 tool 结果变成孤儿，模型会反复重发同一个调用。
+-- zen 上游角色白名单只有 system / user / assistant / tool / latest_reminder：
+-- OpenAI 的 developer（及 function 等）不在其中，直接透传会触发上游
+-- "unknown variant `developer`, expected one of ..." 错误；统一归一化为 system。
+local ROLE_WHITELIST = {
+    system = true,
+    user = true,
+    assistant = true,
+    tool = true,
+    latest_reminder = true,
+}
+
+function adapter.transform_request(raw_body)
+    local ok, req = pcall(json.decode, raw_body)
+    if not ok then return raw_body end
+    req.disable_thinking = nil
+    req.extra_body = nil
+    -- stream_options is only valid alongside stream:true; sending it on a
+    -- non-streaming request is rejected by strict upstreams.
+    if req.stream then
+        if type(req.stream_options) ~= "table" then req.stream_options = {} end
+        req.stream_options.include_usage = true
+    end
+    if req.messages then
+        local kept = {}
+        for _, msg in ipairs(req.messages) do
+            if type(msg.role) == "string" and not ROLE_WHITELIST[msg.role] then
+                msg.role = "system"
+            end
+            -- Zen 免费池不接受回传 reasoning_content（Go 侧相反）
+            msg.reasoning_content = nil
+            local drop = false
+            if type(msg.content) == "table" then
+                local parts = {}
+                for _, part in ipairs(msg.content) do
+                    if type(part) == "table" and part.type ~= nil and part.type ~= "text" then
+                        -- multimodal part not supported by zen
+                    else
+                        table.insert(parts, part)
+                    end
+                end
+                if #parts == 0 then
+                    -- Content collapsed to nothing after stripping unsupported
+                    -- parts. A message that still carries a tool call must
+                    -- NEVER be dropped: the very next message is its tool
+                    -- result, and dropping the call orphans that result. The
+                    -- model then sees a result for a call it never made and
+                    -- re-issues the same tool call on every turn (observed as
+                    -- an infinite "repeated tool call" loop).
+                    if (type(msg.tool_calls) == "table" and #msg.tool_calls > 0)
+                        or msg.tool_call_id ~= nil then
+                        msg.content = ""
+                    else
+                        drop = true
+                    end
+                else
+                    msg.content = parts
+                end
+            end
+            if not drop then
+                table.insert(kept, msg)
+            end
+        end
+        req.messages = kept
+    end
+    return json.encode(req)
+end
+
+function adapter.transform_response(raw_body)
+    local ok, resp = pcall(json.decode, raw_body)
+    if not ok or resp == nil then return raw_body end
+
+    local unified = {
+        content = "",
+        finish_reason = "",
+        token_usage = { prompt = 0, completion = 0, total = 0 }
+    }
+
+    if type(resp.usage) == "table" then
+        unified.token_usage.prompt = resp.usage.prompt_tokens or 0
+        unified.token_usage.completion = resp.usage.completion_tokens or 0
+        unified.token_usage.total = resp.usage.total_tokens or 0
+        local hit = 0
+        if type(resp.usage.prompt_tokens_details) == "table" and resp.usage.prompt_tokens_details.cached_tokens ~= nil then
+            hit = resp.usage.prompt_tokens_details.cached_tokens
+            unified.token_usage.prompt_tokens_details = { cached_tokens = hit }
+        end
+        if (resp.usage.prompt_cache_hit_tokens or 0) > 0 then
+            unified.token_usage.prompt_cache_hit_tokens = resp.usage.prompt_cache_hit_tokens
+            unified.token_usage.prompt_cache_miss_tokens = resp.usage.prompt_cache_miss_tokens or 0
+            if hit == 0 then
+                unified.token_usage.prompt_tokens_details = { cached_tokens = resp.usage.prompt_cache_hit_tokens }
+            end
+        end
+        -- 上游报告输出里有多少是思考 token。不给客户端的话，无法判断
+        -- completion_tokens 里多少是「可见回答」、多少是「思考」（都按输出计费）。
+        local ctd = resp.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            unified.token_usage.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
+        end
+    end
+
+    -- 本次调用的费用，上游放在**顶层**且是**字符串**（如 "0"、"0.0012"）。
+    -- Go 订阅是包月制，恒为 "0"；只有 Zen 按量付费模型才有信息量。
+    -- 原样透传：网关不解析、不换算、不汇总 —— 它只是上游事实的搬运者。
+    if resp.cost ~= nil then
+        unified.cost = tostring(resp.cost)
+    end
+
+    if type(resp.choices) == "table" and #resp.choices > 0 then
+        local ch = resp.choices[1]
+        if type(ch.message) == "table" then
+            unified.content = ch.message.content or ""
+            local reasoning = ch.message.reasoning_content or ch.message.reasoning
+            if reasoning then
+                unified.reasoning_content = reasoning
+            end
+            if type(ch.message.tool_calls) == "table" then
+                local tcs = {}
+                for _, tc in ipairs(ch.message.tool_calls) do
+                    local args_ok, args = pcall(json.decode, tc["function"].arguments)
+                    if not args_ok then args = {} end
+                    table.insert(tcs, {
+                        id = tc.id,
+                        type = tc.type or "function",
+                        name = tc["function"].name,
+                        arguments = args
+                    })
+                end
+                unified.tool_calls = tcs
+            end
+        end
+        unified.finish_reason = ch.finish_reason or ""
+    end
+
+    return json.encode(unified)
+end
+
+function adapter.transform_stream_chunk(raw_chunk)
+    local ok, chunk = pcall(json.decode, raw_chunk)
+    if not ok then return "" end
+
+    -- OpenAI-style streams may attach usage to a chunk with empty choices
+    -- (the final usage chunk). Preserve it; the gateway emits it as the
+    -- terminal usage chunk. Note: keys must match Go's TokenUsage json tags
+    -- (prompt/completion/total); the gateway re-emits standard *_tokens.
+    local uses = nil
+    if type(chunk.usage) == "table" then
+        uses = {
+            prompt = chunk.usage.prompt_tokens or chunk.usage.prompt or 0,
+            completion = chunk.usage.completion_tokens or chunk.usage.completion or 0,
+            total = chunk.usage.total_tokens or chunk.usage.total or 0,
+        }
+        -- 独立字段与 prompt_tokens_details **并存**透传，不要写成 elseif：
+        -- 上游命中缓存时两者都发，非流式路径也是两个都带。写成 elseif 会让
+        -- 流式丢掉 prompt_cache_hit_tokens/miss，与同一源的**非流式**产出不一致
+        -- （dsh 优先读 details，但只认独立字段的老客户端会看不到缓存）。
+        if type(chunk.usage.prompt_tokens_details) == "table" and chunk.usage.prompt_tokens_details.cached_tokens ~= nil then
+            uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_tokens_details.cached_tokens }
+        end
+        if (chunk.usage.prompt_cache_hit_tokens or 0) > 0 then
+            uses.prompt_cache_hit_tokens = chunk.usage.prompt_cache_hit_tokens
+            uses.prompt_cache_miss_tokens = chunk.usage.prompt_cache_miss_tokens or 0
+            if uses.prompt_tokens_details == nil then
+                uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_cache_hit_tokens }
+            end
+        end
+        local ctd = chunk.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            uses.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
+        end
+    end
+
+    if not chunk.choices or #chunk.choices == 0 then
+        -- 空 choices 的帧既不是内容也不是结束信号。上游发两种：
+        --   {"choices":[],"usage":{...}}   —— 终帧用量
+        --   {"choices":[],"cost":"0"}      —— 单独的费用帧
+        -- 两者可能落在同一帧上，必须都转出去；早退只带 usage 会把费用丢干净。
+        local out = { done = false }
+        if uses ~= nil then out.usage = uses end
+        if chunk.cost ~= nil then out.cost = tostring(chunk.cost) end
+        if uses == nil and chunk.cost == nil then return "" end
+        return json.encode(out)
+    end
+    local delta = chunk.choices[1].delta or {}
+    local fr = chunk.choices[1].finish_reason
+
+    local finish = (type(fr) == "string" and fr ~= "") and fr or nil
+
+    local unified = {
+        content = delta.content or "",
+        done = (finish ~= nil)
+    }
+    if finish then
+        unified.finish_reason = finish
+    end
+    if uses ~= nil then
+        unified.usage = uses
+    end
+    -- zen 用 reasoning 字段承载推理文本（OpenAI 惯例是 reasoning_content）
+    local reasoning = delta.reasoning_content or delta.reasoning
+    if reasoning then
+        unified.reasoning_content = reasoning
+    end
+    if delta.tool_calls then
+        -- pass raw streaming fragments through; OpenAI clients accumulate index+id+name+arguments
+        unified.tool_calls = delta.tool_calls
+    end
+    return json.encode(unified)
+end
+
+-- 错误收敛（可选钩子）：zen 错误信封固定为 {error={type,message}}；
+-- 免费池限流 FreeUsageLimitError 单独标注。返回 nil 走通用兜底。
+function adapter.transform_error(status, body)
+    local ok, resp = pcall(json.decode, body)
+    if not ok or type(resp) ~= "table" then return nil end
+    local e = resp.error
+    if type(e) ~= "table" then return nil end
+    if e.type == "FreeUsageLimitError" then
+        return "zen free pool quota exhausted"
+    end
+    return e.message
+end
+
+return adapter

internal/lua/toolcall_preservation_test.go

@@ -0,0 +1,353 @@
+package lua
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// TestAdaptersPreserveToolCalls is the fleet-wide guard for the
+// "orphaned tool result" class of bug: when an agent client replays a turn
+// whose assistant message carries tool_calls, EVERY adapter must forward both
+// the call and the attribution of its result. Dropping the call (or the
+// tool_call_id / tool_name that ties the result to it) makes the model see a
+// result for a call it never made and re-issue the same call forever.
+//
+// The input deliberately uses content:[] — the shape most agent clients emit
+// for a tool-calling assistant turn with no text.
+func TestAdaptersPreserveToolCalls(t *testing.T) {
+	vm := NewVM(freshAdapterDir(t))
+	if err := vm.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer vm.Stop()
+
+	body := `{"model":"m","messages":[
+		{"role":"user","content":"read /tmp/x"},
+		{"role":"assistant","content":[],"tool_calls":[{"id":"call_abc","type":"function","function":{"name":"read","arguments":"{\"path\":\"/tmp/x\"}"}}]},
+		{"role":"tool","tool_call_id":"call_abc","content":"hello world"},
+		{"role":"user","content":"summarize"}
+	]}`
+	const (
+		callID   = "call_abc"
+		fnName   = "read"
+		toolOut  = "hello world"
+		lastUser = "summarize"
+	)
+
+	// Adapters that identify a tool result by the call id.
+	byID := []string{"openai", "deepseek", "github", "groq", "kimicode", "mistral",
+		"sensenova", "trae", "agentrouter", "opencode", "anthropic"}
+
+	for _, a := range byID {
+		out, err := vm.Transform(a, "transform_request", body)
+		if err != nil {
+			t.Errorf("%s: transform_request: %v", a, err)
+			continue
+		}
+		if !strings.Contains(out, callID) {
+			t.Errorf("%s dropped the tool call id %q: %s", a, callID, out)
+		}
+		if !strings.Contains(out, fnName) {
+			t.Errorf("%s dropped the function name %q: %s", a, fnName, out)
+		}
+		if !strings.Contains(out, toolOut) {
+			t.Errorf("%s dropped the tool result: %s", a, out)
+		}
+		if !strings.Contains(out, lastUser) {
+			t.Errorf("%s dropped the final user turn: %s", a, out)
+		}
+	}
+
+	// Ollama identifies the result with tool_name (its API has no tool_call_id
+	// on assistant turns) and takes arguments as an object, not a JSON string.
+	out, err := vm.Transform("ollama", "transform_request", body)
+	if err != nil {
+		t.Fatalf("ollama: %v", err)
+	}
+	for _, want := range []string{`"tool_calls"`, fnName, `"tool_name"`, toolOut} {
+		if !strings.Contains(out, want) {
+			t.Errorf("ollama missing %s: %s", want, out)
+		}
+	}
+
+	// Gemini identifies the result by function NAME and has no call id in its
+	// wire format; both directions must be present as functionCall /
+	// functionResponse parts, and the system role must move to
+	// systemInstruction rather than sitting in contents.
+	gBody := `{"model":"m","messages":[
+		{"role":"system","content":"be brief"},
+		{"role":"user","content":"read /tmp/x"},
+		{"role":"assistant","content":[],"tool_calls":[{"id":"call_abc","type":"function","function":{"name":"read","arguments":"{\"path\":\"/tmp/x\"}"}}]},
+		{"role":"tool","tool_call_id":"call_abc","content":"hello world"}
+	]}`
+	gout, err := vm.Transform("gemini", "transform_request", gBody)
+	if err != nil {
+		t.Fatalf("gemini: %v", err)
+	}
+	for _, want := range []string{`"functionCall"`, `"functionResponse"`, fnName, toolOut, `"systemInstruction"`} {
+		if !strings.Contains(gout, want) {
+			t.Errorf("gemini missing %s: %s", want, gout)
+		}
+	}
+	// No message may keep the OpenAI-only roles inside contents.
+	var greq struct {
+		Contents []struct {
+			Role string `json:"role"`
+		} `json:"contents"`
+	}
+	if err := json.Unmarshal([]byte(gout), &greq); err != nil {
+		t.Fatalf("gemini unmarshal: %v (%s)", err, gout)
+	}
+	for _, c := range greq.Contents {
+		if c.Role != "user" && c.Role != "model" {
+			t.Errorf("gemini contents carry an invalid role %q: %s", c.Role, gout)
+		}
+	}
+
+	// Negative control: a text-only turn must still be forwarded verbatim.
+	plain := `{"model":"m","messages":[{"role":"user","content":"just text"}]}`
+	for _, a := range append(byID, "ollama", "gemini") {
+		pout, err := vm.Transform(a, "transform_request", plain)
+		if err != nil {
+			t.Errorf("%s plain: %v", a, err)
+			continue
+		}
+		if !strings.Contains(pout, "just text") {
+			t.Errorf("%s dropped plain text: %s", a, pout)
+		}
+	}
+}
+
+// TestOpenCodeStreamOptionsOnlyWhenStreaming pins the fix for
+// "stream_options should be set along with stream": OpenCode Go (and other
+// strict OpenAI-compatible upstreams) reject a non-streaming request that
+// carries stream_options, which broke every non-stream call through the
+// opencode adapter.
+func TestOpenCodeStreamOptionsOnlyWhenStreaming(t *testing.T) {
+	vm := NewVM(freshAdapterDir(t))
+	if err := vm.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer vm.Stop()
+
+	// non-streaming: stream_options must be absent entirely
+	out, err := vm.Transform("opencode", "transform_request",
+		`{"model":"m","messages":[{"role":"user","content":"hi"}]}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(out, "stream_options") {
+		t.Fatalf("non-streaming request must not carry stream_options: %s", out)
+	}
+
+	// streaming: stream_options.include_usage must be set
+	sout, err := vm.Transform("opencode", "transform_request",
+		`{"model":"m","stream":true,"messages":[{"role":"user","content":"hi"}]}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(sout, "stream_options") || !strings.Contains(sout, "include_usage") {
+		t.Fatalf("streaming request must carry stream_options.include_usage: %s", sout)
+	}
+}
+
+// TestOpenCodeGoVsZenReasoning pins the one behavioural difference that made a
+// shared adapter wrong: OpenCode Go's thinking mode REQUIRES the assistant
+// turn's reasoning_content to be echoed back ("The `reasoning_content` in the
+// thinking mode must be passed back to the API"), while the Zen free pool must
+// not receive it. Hence two purpose-built adapters.
+func TestOpenCodeGoVsZenReasoning(t *testing.T) {
+	vm := NewVM(freshAdapterDir(t))
+	if err := vm.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer vm.Stop()
+
+	body := `{"model":"m","messages":[
+		{"role":"user","content":"hi"},
+		{"role":"assistant","content":"","reasoning_content":"I should read the file.","tool_calls":[{"id":"call_1","type":"function","function":{"name":"read","arguments":"{\"path\":\"/x\"}"}}]},
+		{"role":"tool","tool_call_id":"call_1","content":"r"}
+	]}`
+
+	// Go: reasoning_content must survive, and the tool call must stay paired.
+	gout, err := vm.Transform("opencodego", "transform_request", body)
+	if err != nil {
+		t.Fatalf("opencodego: %v", err)
+	}
+	if !strings.Contains(gout, "I should read the file.") {
+		t.Errorf("opencodego must pass reasoning_content back (thinking mode requires it): %s", gout)
+	}
+	if !strings.Contains(gout, "call_1") || !strings.Contains(gout, "tool_call_id") {
+		t.Errorf("opencodego must keep the tool call paired with its result: %s", gout)
+	}
+
+	// Zen: reasoning_content is stripped.
+	zout, err := vm.Transform("opencodezen", "transform_request", body)
+	if err != nil {
+		t.Fatalf("opencodezen: %v", err)
+	}
+	if strings.Contains(zout, "I should read the file.") {
+		t.Errorf("opencodezen must strip reasoning_content: %s", zout)
+	}
+	if !strings.Contains(zout, "call_1") {
+		t.Errorf("opencodezen must still keep the tool call: %s", zout)
+	}
+
+	// An assistant turn that carries tool_calls but no reasoning_content must
+	// get an empty one injected: Go validates that field on tool-calling turns
+	// and 400s when it is absent, while most clients never send it.
+	// Verified against the live endpoint that an empty string passes.
+	bare := `{"model":"m","messages":[
+		{"role":"user","content":"go"},
+		{"role":"assistant","content":"","tool_calls":[{"id":"c1","type":"function","function":{"name":"read","arguments":"{}"}}]},
+		{"role":"tool","tool_call_id":"c1","content":"r"}
+	]}`
+	bout, err := vm.Transform("opencodego", "transform_request", bare)
+	if err != nil {
+		t.Fatalf("opencodego bare: %v", err)
+	}
+	if !strings.Contains(bout, `"reasoning_content":""`) {
+		t.Errorf("opencodego must inject an empty reasoning_content on a tool-calling turn: %s", bout)
+	}
+	// A plain assistant turn (no tool calls) must NOT gain the field.
+	plainAsst := `{"model":"m","messages":[{"role":"user","content":"hi"},{"role":"assistant","content":"hello"}]}`
+	pout, err := vm.Transform("opencodego", "transform_request", plainAsst)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(pout, "reasoning_content") {
+		t.Errorf("opencodego must not inject reasoning_content on a plain assistant turn: %s", pout)
+	}
+
+	// Both must still omit stream_options on non-streaming requests.
+	for _, a := range []string{"opencodego", "opencodezen"} {
+		out, err := vm.Transform(a, "transform_request", `{"model":"m","messages":[{"role":"user","content":"hi"}]}`)
+		if err != nil {
+			t.Fatalf("%s: %v", a, err)
+		}
+		if strings.Contains(out, "stream_options") {
+			t.Errorf("%s must not send stream_options when not streaming: %s", a, out)
+		}
+	}
+}
+
+// TestOpenCodeSessionIsStableForCache pins the session-derivation contract that
+// makes the upstream prefix cache usable.
+//
+// Measured against the live OpenCode Go endpoint: the prefix cache is
+// SESSION-scoped. Replaying the same 6032-token prompt hits 5888 cached tokens
+// when the session id is fixed, and 0 when it changes per request. Deriving the
+// session from meta.timestamp (the previous behaviour) meant every request was a
+// new session, so the cache could never hit.
+//
+// The session must be stable WITHIN one conversation and differ BETWEEN
+// conversations. Since generic OpenAI clients send no session id at all
+// (verified by capturing real agent traffic: no user / session_id /
+// conversation_id / metadata in the body, no session header), the conversation
+// is fingerprinted by its FIRST user message — history is replayed every turn,
+// so that message is invariant for the life of the conversation.
+func TestOpenCodeSessionIsStableForCache(t *testing.T) {
+	for _, name := range []string{"opencodego", "opencodezen"} {
+		vm := NewVM(freshAdapterDir(t))
+		if err := vm.Start(); err != nil {
+			t.Fatal(err)
+		}
+		meta := func(ts int, body string) map[string]interface{} {
+			return map[string]interface{}{
+				"timestamp": ts,
+				"body":      body,
+				"source":    map[string]interface{}{"name": "somesource", "meta": nil},
+			}
+		}
+
+		// Same conversation, later turn: history grew, first user msg unchanged.
+		h1, err := vm.BuildHeaders(name, meta(1000,
+			`{"messages":[{"role":"user","content":"fix the bug"},{"role":"assistant","content":"looking"}]}`))
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		h2, err := vm.BuildHeaders(name, meta(2000,
+			`{"messages":[{"role":"user","content":"fix the bug"},{"role":"assistant","content":"looking"},{"role":"user","content":"and tests"}]}`))
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		// Different conversation.
+		h3, err := vm.BuildHeaders(name, meta(3000,
+			`{"messages":[{"role":"user","content":"an unrelated task"}]}`))
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+
+		if h1["x-opencode-session"] == "" {
+			t.Fatalf("%s: session header must be set", name)
+		}
+		if h1["x-opencode-session"] != h2["x-opencode-session"] {
+			t.Errorf("%s: x-opencode-session must be STABLE across turns of one conversation "+
+				"(%q vs %q) — the prefix cache is session-scoped", name, h1["x-opencode-session"], h2["x-opencode-session"])
+		}
+		if h1["x-opencode-session"] == h3["x-opencode-session"] {
+			t.Errorf("%s: a different conversation must get a different session", name)
+		}
+		if h1["x-opencode-request"] == h2["x-opencode-request"] {
+			t.Errorf("%s: x-opencode-request must differ per request", name)
+		}
+		// No user message at all falls back to per-source stability.
+		h4, _ := vm.BuildHeaders(name, meta(4000, `{"messages":[{"role":"system","content":"s"}]}`))
+		h5, _ := vm.BuildHeaders(name, meta(5000, `{"messages":[{"role":"system","content":"s"}]}`))
+		if h4["x-opencode-session"] != h5["x-opencode-session"] {
+			t.Errorf("%s: sessionless requests must still be stable per source", name)
+		}
+		vm.Stop()
+	}
+}
+
+// 客户端自带的会话标识（pi 的 x-session-affinity）必须优先于会话指纹：
+// 它是平台真实会话 id，历史压缩后也不会漂移，且天然按会话隔离。
+func TestOpenCodePrefersClientSessionID(t *testing.T) {
+	for _, name := range []string{"opencodego", "opencodezen"} {
+		vm := NewVM(freshAdapterDir(t))
+		if err := vm.Start(); err != nil {
+			t.Fatal(err)
+		}
+		meta := func(body, cs string) map[string]interface{} {
+			return map[string]interface{}{
+				"timestamp":      1000,
+				"body":           body,
+				"client_session": cs,
+				"source":         map[string]interface{}{"name": "somesource", "meta": nil},
+			}
+		}
+
+		// 同一条会话：历史在长，但客户端会话 id 不变。
+		a, err := vm.BuildHeaders(name, meta(`{"messages":[{"role":"user","content":"fix the bug"}]}`, "cs-aaa"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		b, err := vm.BuildHeaders(name, meta(`{"messages":[{"role":"user","content":"a totally different opener"}]}`, "cs-aaa"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if a["x-opencode-session"] != b["x-opencode-session"] {
+			t.Errorf("%s: 客户端会话 id 相同就必须同会话（内容无关）: %q vs %q",
+				name, a["x-opencode-session"], b["x-opencode-session"])
+		}
+
+		// 不同会话。
+		c, _ := vm.BuildHeaders(name, meta(`{"messages":[{"role":"user","content":"fix the bug"}]}`, "cs-bbb"))
+		if a["x-opencode-session"] == c["x-opencode-session"] {
+			t.Errorf("%s: 不同客户端会话必须不同会号", name)
+		}
+
+		// 客户端没给会话 id 时，回落到指纹（同内容 -> 同会号）。
+		d, _ := vm.BuildHeaders(name, meta(`{"messages":[{"role":"user","content":"fix the bug"}]}`, ""))
+		e, _ := vm.BuildHeaders(name, meta(`{"messages":[{"role":"user","content":"fix the bug"}]}`, ""))
+		if d["x-opencode-session"] != e["x-opencode-session"] {
+			t.Errorf("%s: 无客户端会号时应回落到稳定指纹", name)
+		}
+		if d["x-opencode-session"] == a["x-opencode-session"] {
+			t.Errorf("%s: 客户端会号与指纹两条路必须产出不同会号", name)
+		}
+		vm.Stop()
+	}
+}

internal/lua/usage_cost_test.go

@@ -0,0 +1,177 @@
+package lua
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// OpenCode Zen/Go 在 usage 里报告输出有多少是思考 token，并在**顶层**用一个
+// **字符串**给出本次费用。前者决定「completion_tokens 里多少是可见回答」，
+// 后者是唯一的费用信号。两者都曾被适配器丢掉。
+func TestOpenCodeCostAndReasoningPassthrough(t *testing.T) {
+	for _, name := range []string{"opencodego", "opencodezen"} {
+		vm := NewVM(freshAdapterDir(t))
+		if err := vm.Start(); err != nil {
+			t.Fatal(err)
+		}
+
+		// ---- 非流式 ----
+		resp := `{"id":"x","object":"chat.completion","model":"deepseek-v4.1-flash",
+			"choices":[{"index":0,"message":{"role":"assistant","content":"hi","reasoning_content":"think"},
+			"finish_reason":"stop"}],
+			"usage":{"prompt_tokens":37,"completion_tokens":40,"total_tokens":77,
+			"prompt_cache_hit_tokens":0,"prompt_cache_miss_tokens":37,
+			"prompt_tokens_details":{"cached_tokens":0},
+			"completion_tokens_details":{"reasoning_tokens":40}},
+			"cost":"0"}`
+		out, err := vm.Transform(name, "transform_response", resp)
+		if err != nil {
+			t.Fatalf("%s transform_response: %v", name, err)
+		}
+		var r struct {
+			TokenUsage struct {
+				Completion int `json:"completion"`
+				Details    *struct {
+					ReasoningTokens int `json:"reasoning_tokens"`
+				} `json:"completion_tokens_details"`
+			} `json:"token_usage"`
+			Cost string `json:"cost"`
+		}
+		if err := json.Unmarshal([]byte(out), &r); err != nil {
+			t.Fatalf("%s unmarshal: %v (%s)", name, err, out)
+		}
+		if r.Cost != "0" {
+			t.Errorf("%s: cost 未透传（上游给的是字符串 \"0\"）: %q", name, r.Cost)
+		}
+		if r.TokenUsage.Details == nil || r.TokenUsage.Details.ReasoningTokens != 40 {
+			t.Errorf("%s: completion_tokens_details.reasoning_tokens 未透传: %s", name, out)
+		}
+		// 前提校验：reasoning_tokens 确实 ≤ completion_tokens（全为思考）。
+		if r.TokenUsage.Details != nil && r.TokenUsage.Details.ReasoningTokens > r.TokenUsage.Completion {
+			t.Errorf("%s: reasoning 不应超过 completion", name)
+		}
+
+		// ---- 流式：非零费用也要透传 ----
+		chunk := `{"id":"x","object":"chat.completion.chunk","choices":[],
+			"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15,
+			"completion_tokens_details":{"reasoning_tokens":4}},"cost":"0.0012"}`
+		co, err := vm.Transform(name, "transform_stream_chunk", chunk)
+		if err != nil {
+			t.Fatalf("%s transform_stream_chunk: %v", name, err)
+		}
+		var c struct {
+			Cost  string `json:"cost"`
+			Usage *struct {
+				Details *struct {
+					ReasoningTokens int `json:"reasoning_tokens"`
+				} `json:"completion_tokens_details"`
+			} `json:"usage"`
+		}
+		if err := json.Unmarshal([]byte(co), &c); err != nil {
+			t.Fatalf("%s unmarshal chunk: %v (%s)", name, err, co)
+		}
+		if c.Usage == nil || c.Usage.Details == nil || c.Usage.Details.ReasoningTokens != 4 {
+			t.Errorf("%s: 流式 reasoning_tokens 未透传: %s", name, co)
+		}
+		if c.Cost != "0.0012" {
+			t.Errorf("%s: 流式 cost 未透传: %s", name, co)
+		}
+
+		// ---- 独立的 cost 帧（上游就这么发：choices 为空、只有 cost）----
+		only := `{"choices":[],"cost":"0"}`
+		oo, err := vm.Transform(name, "transform_stream_chunk", only)
+		if err != nil {
+			t.Fatalf("%s cost-only chunk: %v", name, err)
+		}
+		if oo == "" {
+			t.Fatalf("%s: 纯 cost 帧被整个丢弃（客户端将看不到费用）", name)
+		}
+		var oc struct {
+			Cost string `json:"cost"`
+		}
+		if err := json.Unmarshal([]byte(oo), &oc); err != nil {
+			t.Fatalf("%s unmarshal cost chunk: %v (%s)", name, err, oo)
+		}
+		if oc.Cost != "0" {
+			t.Errorf("%s: 纯 cost 帧内容丢失: %s", name, oo)
+		}
+
+		// ---- 回归：没有 cost / 没有 details 时不得凭空造字段 ----
+		bare := `{"choices":[{"index":0,"delta":{"content":"hi"},"finish_reason":"stop"}],
+			"usage":{"prompt_tokens":3,"completion_tokens":1,"total_tokens":4}}`
+		bo, _ := vm.Transform(name, "transform_response", bare)
+		if got := bo; len(got) > 0 && containsAll(got, `"cost"`) {
+			t.Errorf("%s: 上游没给 cost 却透传了该字段: %s", name, got)
+		}
+
+		vm.Stop()
+	}
+}
+
+func containsAll(s string, subs ...string) bool {
+	for _, sub := range subs {
+		found := false
+		for i := 0; i+len(sub) <= len(s); i++ {
+			if s[i:i+len(sub)] == sub {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return false
+		}
+	}
+	return true
+}
+
+// 流式与非流式对同一上游切片的产出必须一致：命中缓存时上游同时给
+// prompt_tokens_details.cached_tokens 和独立的 hit/miss 字段，两边都要透传。
+func TestOpenCodeStreamCacheFieldsMatchNonStream(t *testing.T) {
+	for _, name := range []string{"opencodego", "opencodezen"} {
+		vm := NewVM(freshAdapterDir(t))
+		if err := vm.Start(); err != nil {
+			t.Fatal(err)
+		}
+		type cache struct {
+			Details *struct {
+				CachedTokens int `json:"cached_tokens"`
+			} `json:"prompt_tokens_details"`
+			Hit  int `json:"prompt_cache_hit_tokens"`
+			Miss int `json:"prompt_cache_miss_tokens"`
+		}
+		usage := `"usage":{"prompt_tokens":5732,"completion_tokens":20,"total_tokens":5752,
+			"prompt_cache_hit_tokens":5504,"prompt_cache_miss_tokens":228,
+			"prompt_tokens_details":{"cached_tokens":5504}}`
+
+		// 非流式
+		nout, _ := vm.Transform(name, "transform_response",
+			`{"choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],`+usage+`}`)
+		var nr struct {
+			U cache `json:"token_usage"`
+		}
+		if err := json.Unmarshal([]byte(nout), &nr); err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		// 流式
+		sout, _ := vm.Transform(name, "transform_stream_chunk",
+			`{"choices":[],`+usage+`}`)
+		var sr struct {
+			U cache `json:"usage"`
+		}
+		if err := json.Unmarshal([]byte(sout), &sr); err != nil {
+			t.Fatalf("%s chunk: %v (%s)", name, err, sout)
+		}
+
+		if nr.U.Hit != 5504 || nr.U.Miss != 228 {
+			t.Errorf("%s: 非流式 hit/miss 异常: %+v", name, nr.U)
+		}
+		if sr.U.Hit != nr.U.Hit || sr.U.Miss != nr.U.Miss {
+			t.Errorf("%s: 流式 hit/miss 与非流式不一致 (stream %d/%d vs non-stream %d/%d): %s",
+				name, sr.U.Hit, sr.U.Miss, nr.U.Hit, nr.U.Miss, sout)
+		}
+		if sr.U.Details == nil || sr.U.Details.CachedTokens != 5504 {
+			t.Errorf("%s: 流式 cached_tokens 丢失: %s", name, sout)
+		}
+		vm.Stop()
+	}
+}

internal/lua/vm_test.go

@@ -221,6 +221,70 @@ func TestOpenCodeStripsMultiModalParts(t *testing.T) {
 	}
 }
 
+// TestOpenCodeKeepsToolCallWithEmptyContent pins the fix for an infinite
+// "repeated tool call" loop: an assistant turn whose content serialises to an
+// empty ARRAY while carrying tool_calls must survive the multimodal strip.
+// Dropping it orphans the following tool result, so the model never sees the
+// call it already made and re-issues it on every turn.
+func TestOpenCodeKeepsToolCallWithEmptyContent(t *testing.T) {
+	vm := NewVM(freshAdapterDir(t))
+	if err := vm.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer vm.Stop()
+
+	body := `{"model":"x","messages":[
+		{"role":"user","content":"read /tmp/x"},
+		{"role":"assistant","content":[],"tool_calls":[{"id":"call_abc","type":"function","function":{"name":"read","arguments":"{\"path\":\"/tmp/x\"}"}}]},
+		{"role":"tool","tool_call_id":"call_abc","content":"hello"},
+		{"role":"user","content":"now summarize"}
+	]}`
+	out, err := vm.Transform("opencode", "transform_request", body)
+	if err != nil {
+		t.Fatalf("transform_request: %v", err)
+	}
+
+	var req struct {
+		Messages []struct {
+			Role      string          `json:"role"`
+			Content   json.RawMessage `json:"content"`
+			ToolCalls []struct {
+				ID string `json:"id"`
+			} `json:"tool_calls"`
+			ToolCallID string `json:"tool_call_id"`
+		} `json:"messages"`
+	}
+	if err := json.Unmarshal([]byte(out), &req); err != nil {
+		t.Fatalf("unmarshal: %v (%s)", err, out)
+	}
+	if len(req.Messages) != 4 {
+		t.Fatalf("expected 4 messages (tool call must not be dropped), got %d: %s", len(req.Messages), out)
+	}
+	asst := req.Messages[1]
+	if asst.Role != "assistant" || len(asst.ToolCalls) != 1 || asst.ToolCalls[0].ID != "call_abc" {
+		t.Fatalf("assistant tool_calls lost: %s", out)
+	}
+	if string(asst.Content) != `""` {
+		t.Fatalf("empty content must be rewritten to \"\", got %s", asst.Content)
+	}
+	if req.Messages[2].Role != "tool" || req.Messages[2].ToolCallID != "call_abc" {
+		t.Fatalf("tool result must stay paired with its call: %s", out)
+	}
+
+	// Negative control: a message with neither text nor tool calls is still dropped.
+	only := `{"model":"x","messages":[
+		{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://ex.com/a.png"}}]},
+		{"role":"user","content":"keep me"}
+	]}`
+	out2, err := vm.Transform("opencode", "transform_request", only)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.Count(out2, `"role"`); got != 1 {
+		t.Fatalf("image-only message without tool calls must still be dropped, got %d: %s", got, out2)
+	}
+}
+
 func TestBuildHeadersCustomHook(t *testing.T) {
 	vm := NewVM(freshAdapterDir(t))
 	if err := vm.Start(); err != nil {

internal/provider/provider.go

@@ -707,7 +707,7 @@ func (p *Provider) probeModels(ctx context.Context) (bool, string) {
 	if err != nil {
 		return false, ""
 	}
-	if hdrs, herr := p.buildHeaders("{}", u); herr == nil {
+	if hdrs, herr := p.buildHeaders("{}", u, ""); herr == nil {
 		req.Header = hdrs
 	}
 	resp, err := p.client.Do(req)
@@ -750,7 +750,7 @@ func (p *Provider) probeChat(ctx context.Context) (bool, string) {
 		body, err := json.Marshal(probe)
 		if err == nil {
 			var hdr http.Header
-			if hdrs, herr := p.buildHeaders(string(body), p.URL()); herr == nil {
+			if hdrs, herr := p.buildHeaders(string(body), p.URL(), ""); herr == nil {
 				hdr = hdrs
 			}
 			raw, status, derr := p.do(ctx, p.URL(), string(body), hdr)
@@ -1031,13 +1031,15 @@ func (p *Provider) Throttle(ctx context.Context) error {
 
 // ---- request construction ----
 
-func (p *Provider) buildHeaders(body, url string) (http.Header, error) {
+func (p *Provider) buildHeaders(body, url, clientSession string) (http.Header, error) {
 	meta := map[string]interface{}{
 		"url":       url,
 		"method":    http.MethodPost,
 		"body":      body,
 		"api_key":   p.cfg.APIKey,
 		"timestamp": types.Now(),
+		// client_session 是客户端自带的会话标识（请求头），为空时适配器自行推导。
+		"client_session": clientSession,
 		"source": map[string]interface{}{
 			"name": p.cfg.Name,
 			"meta": p.cfg.Meta,
@@ -1082,7 +1084,7 @@ func (p *Provider) Chat(ctx context.Context, req *types.ChatRequest) (*types.Uni
 	if err != nil {
 		return nil, err
 	}
-	hdrs, err := p.buildHeaders(body, p.URL())
+	hdrs, err := p.buildHeaders(body, p.URL(), req.ClientSession)
 	if err != nil {
 		return nil, err
 	}
@@ -1142,7 +1144,7 @@ func (p *Provider) ChatStream(ctx context.Context, req *types.ChatRequest) (<-ch
 		p.Release()
 		return nil, err
 	}
-	hdrs, err := p.buildHeaders(body, p.URL())
+	hdrs, err := p.buildHeaders(body, p.URL(), req.ClientSession)
 	if err != nil {
 		p.Release()
 		return nil, err
@@ -1411,7 +1413,7 @@ func (p *Provider) Image(ctx context.Context, req *types.ImageGenRequest) (*type
 		// fall back to passthrough adapter (openai-style)
 		transformed = string(b)
 	}
-	hdrs, err := p.buildHeaders(transformed, p.ImageURL())
+	hdrs, err := p.buildHeaders(transformed, p.ImageURL(), "")
 	if err != nil {
 		return nil, err
 	}
@@ -1516,12 +1518,24 @@ func standardSSEChunk(data string) string {
 			PromptTokensDetails *struct {
 				CachedTokens int `json:"cached_tokens"`
 			} `json:"prompt_tokens_details"`
+			CompletionTokensDetails *struct {
+				ReasoningTokens int `json:"reasoning_tokens"`
+			} `json:"completion_tokens_details"`
 		} `json:"usage"`
+		// Cost is a top-level decimal string on OpenCode Zen/Go responses.
+		Cost json.RawMessage `json:"cost"`
 	}
 	if err := json.Unmarshal([]byte(data), &raw); err != nil {
 		return ""
 	}
 	if len(raw.Choices) == 0 && raw.UpstreamUsage.Total == 0 && raw.UpstreamUsage.TotalTokens == 0 {
+		// Cost-only chunk: OpenCode sends the charge on its own frame
+		// {"choices":[],"cost":"0"} with no usage at all. Dropping it here
+		// would lose the only cost signal the client can see.
+		if c := rawCostString(raw.Cost); c != "" {
+			out, _ := json.Marshal(types.UnifiedChunk{Cost: c})
+			return string(out)
+		}
 		return ""
 	}
 	var usage *types.TokenUsage
@@ -1539,6 +1553,11 @@ func standardSSEChunk(data string) string {
 				CachedTokens: pu.PromptTokensDetails.CachedTokens,
 			}
 		}
+		if pu.CompletionTokensDetails != nil {
+			usage.CompletionTokensDetails = &types.CompletionTokensDetails{
+				ReasoningTokens: pu.CompletionTokensDetails.ReasoningTokens,
+			}
+		}
 	}
 	finish := ""
 	done := false
@@ -1563,6 +1582,24 @@ func standardSSEChunk(data string) string {
 	return string(out)
 }
 
+// rawCostString normalizes an upstream cost field into a plain string. The
+// value is a decimal **string** on OpenCode Zen/Go ("0", "0.0012"), but other
+// upstreams have been seen to send a bare number, so both are accepted.
+// Returns "" when absent, null, or empty.
+func rawCostString(raw json.RawMessage) string {
+	s := strings.TrimSpace(string(raw))
+	if s == "" || s == "null" {
+		return ""
+	}
+	if s[0] == '"' {
+		var unq string
+		if json.Unmarshal(raw, &unq) == nil {
+			return strings.TrimSpace(unq)
+		}
+	}
+	return s
+}
+
 // pickFirst returns a if non-zero, else b (for usage keys that may appear in
 // either standard *_tokens or legacy short form).
 func pickFirst(a, b int) int {

internal/types/types.go

@@ -3,6 +3,7 @@
 package types
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"strings"
@@ -28,6 +29,10 @@ type ChatRequest struct {
 	ToolChoice      interface{}            `json:"tool_choice,omitempty"`
 	DisableThinking bool                   `json:"disable_thinking"`
 	ExtraBody       map[string]interface{} `json:"-"`
+
+	// ClientSession 是客户端自带的会话标识（请求头 x-session-affinity 等）。
+	// 不参与序列化：它只用于让适配器生成稳定的上游会话，不应泄漏给上游 body。
+	ClientSession string `json:"-"`
 }
 
 func (r *ChatRequest) MarshalJSON() ([]byte, error) {
@@ -61,6 +66,39 @@ type ChatMessage struct {
 
 func StringContent(s string) json.RawMessage { b, _ := json.Marshal(s); return b }
 
+// isEmptyJSONArray reports whether raw is the literal empty JSON array [].
+func isEmptyJSONArray(raw json.RawMessage) bool {
+	t := bytes.TrimSpace(raw)
+	return len(t) == 2 && t[0] == '[' && t[1] == ']'
+}
+
+// UnmarshalJSON decodes a chat message, normalising an empty-array content
+// ("content":[]) to an empty string and dropping an empty tool_calls array.
+//
+// Why this exists: Lua adapters json.decode the request and re-encode it, and
+// an empty Lua table is indistinguishable from an empty JSON array — the
+// encoder emits {} for both. Agent clients serialise an assistant turn that
+// carries tool_calls and no text as content:[], so every pass-through adapter
+// turned it into content:{} — a shape that is not valid OpenAI (content is
+// string | array of parts | null) and that real upstreams reject with
+// "400 invalid arguments". Normalising at the decode boundary fixes every
+// adapter at once, including ones added later.
+func (m *ChatMessage) UnmarshalJSON(b []byte) error {
+	type alias ChatMessage
+	var a alias
+	if err := json.Unmarshal(b, &a); err != nil {
+		return err
+	}
+	*m = ChatMessage(a)
+	if isEmptyJSONArray(m.Content) {
+		m.Content = StringContent("")
+	}
+	if isEmptyJSONArray(m.ToolCalls) {
+		m.ToolCalls = nil
+	}
+	return nil
+}
+
 type ToolCall struct {
 	ID        string                 `json:"id"`
 	Type      string                 `json:"type"`
@@ -79,6 +117,11 @@ type UnifiedResponse struct {
 	ToolCalls        []ToolCall `json:"tool_calls,omitempty"`
 	// ImageData used by image-generation adapters.
 	ImageData []ImageData `json:"image_data,omitempty"`
+	// Cost is the upstream-reported charge for this request, passed through
+	// verbatim (OpenCode Zen/Go put a decimal **string** at the response top
+	// level). Deliberately not parsed or summed by the gateway: it is an
+	// upstream fact, and only some upstreams report it at all.
+	Cost string `json:"cost,omitempty"`
 }
 
 type TokenUsage struct {
@@ -95,6 +138,16 @@ type TokenUsage struct {
 	// prompt_tokens_details.cached_tokens is absent.
 	PromptCacheHit  int `json:"prompt_cache_hit_tokens,omitempty"`
 	PromptCacheMiss int `json:"prompt_cache_miss_tokens,omitempty"`
+	// CompletionTokensDetails mirrors the OpenAI v2 usage.completion_tokens_details
+	// object. OpenCode Zen/Go report how much of the completion was thinking
+	// tokens here; without it clients cannot tell how much of the billed output
+	// was reasoning rather than visible answer.
+	CompletionTokensDetails *CompletionTokensDetails `json:"completion_tokens_details,omitempty"`
+}
+
+// CompletionTokensDetails is the OpenAI v2 completion_tokens_details object.
+type CompletionTokensDetails struct {
+	ReasoningTokens int `json:"reasoning_tokens"`
 }
 
 // PromptTokensDetails is the OpenAI v2 prompt_tokens_details object. Only
@@ -119,15 +172,16 @@ func (t TokenUsage) MarshalJSON() ([]byte, error) {
 		pdetails = &PromptTokensDetails{CachedTokens: t.PromptCacheHit}
 	}
 	return json.Marshal(struct {
-		PromptTokens          int                  `json:"prompt_tokens"`
-		CompletionTokens      int                  `json:"completion_tokens"`
-		TotalTokens           int                  `json:"total_tokens"`
-		Prompt                int                  `json:"prompt"`
-		Completion            int                  `json:"completion"`
-		Total                 int                  `json:"total"`
-		PromptTokensDetails   *PromptTokensDetails `json:"prompt_tokens_details,omitempty"`
-		PromptCacheHitTokens  int                  `json:"prompt_cache_hit_tokens,omitempty"`
-		PromptCacheMissTokens int                  `json:"prompt_cache_miss_tokens,omitempty"`
+		PromptTokens          int                      `json:"prompt_tokens"`
+		CompletionTokens      int                      `json:"completion_tokens"`
+		TotalTokens           int                      `json:"total_tokens"`
+		Prompt                int                      `json:"prompt"`
+		Completion            int                      `json:"completion"`
+		Total                 int                      `json:"total"`
+		PromptTokensDetails   *PromptTokensDetails     `json:"prompt_tokens_details,omitempty"`
+		PromptCacheHitTokens  int                      `json:"prompt_cache_hit_tokens,omitempty"`
+		PromptCacheMissTokens int                      `json:"prompt_cache_miss_tokens,omitempty"`
+		CompletionDetails     *CompletionTokensDetails `json:"completion_tokens_details,omitempty"`
 	}{
 		PromptTokens:          t.Prompt,
 		CompletionTokens:      t.Completion,
@@ -138,6 +192,7 @@ func (t TokenUsage) MarshalJSON() ([]byte, error) {
 		PromptTokensDetails:   pdetails,
 		PromptCacheHitTokens:  t.PromptCacheHit,
 		PromptCacheMissTokens: t.PromptCacheMiss,
+		CompletionDetails:     t.CompletionTokensDetails,
 	})
 }
 
@@ -181,6 +236,9 @@ type UnifiedChunk struct {
 	// often has empty choices). Gateway uses it to emit exact usage in the
 	// final stream chunk instead of estimates.
 	Usage *TokenUsage `json:"usage,omitempty"`
+	// Cost is upstream-reported charge for this request (decimal string),
+	// passed through verbatim; OpenCode sends it on its own stream chunk.
+	Cost string `json:"cost,omitempty"`
 }
 
 // Meta passed to Lua build_headers hook

internal/types/types_test.go

@@ -2,6 +2,7 @@ package types
 
 import (
 	"encoding/json"
+	"strings"
 	"testing"
 )
 
@@ -68,3 +69,86 @@ func TestTokenUsageMarshalCacheFields(t *testing.T) {
 	t.Logf("DeepSeek JSON: %s", string(b))
 	t.Logf("OpenAI JSON: %s", string(b2))
 }
+
+// TestChatMessageNormalizesEmptyArrayContent pins the fix for the malformed
+// content:{} that pass-through adapters produced for an assistant turn carrying
+// tool_calls with no text. Lua adapters cannot tell an empty JSON array from an
+// empty object, so the decode boundary normalises it for every adapter at once.
+func TestChatMessageNormalizesEmptyArrayContent(t *testing.T) {
+	var msg ChatMessage
+	raw := `{"role":"assistant","content":[],"tool_calls":[{"id":"call_1","type":"function","function":{"name":"read","arguments":"{}"}}]}`
+	if err := json.Unmarshal([]byte(raw), &msg); err != nil {
+		t.Fatal(err)
+	}
+	if string(msg.Content) != `""` {
+		t.Fatalf("empty-array content must normalise to \"\", got %s", msg.Content)
+	}
+	if len(msg.ToolCalls) == 0 {
+		t.Fatal("tool_calls must survive normalisation")
+	}
+
+	// A non-empty content array must be left byte-identical (multimodal path).
+	var mm ChatMessage
+	multi := `{"role":"user","content":[{"type":"text","text":"hi"}]}`
+	if err := json.Unmarshal([]byte(multi), &mm); err != nil {
+		t.Fatal(err)
+	}
+	if string(mm.Content) != `[{"type":"text","text":"hi"}]` {
+		t.Fatalf("multimodal content must pass through untouched, got %s", mm.Content)
+	}
+
+	// A plain string content is untouched.
+	var sm ChatMessage
+	if err := json.Unmarshal([]byte(`{"role":"user","content":"plain"}`), &sm); err != nil {
+		t.Fatal(err)
+	}
+	if string(sm.Content) != `"plain"` {
+		t.Fatalf("string content must pass through untouched, got %s", sm.Content)
+	}
+
+	// An omitted content stays omitted (omitempty semantics preserved).
+	var om ChatMessage
+	if err := json.Unmarshal([]byte(`{"role":"assistant","tool_calls":[]}`), &om); err != nil {
+		t.Fatal(err)
+	}
+	if om.Content != nil {
+		t.Fatalf("absent content must stay absent, got %s", om.Content)
+	}
+	if om.ToolCalls != nil {
+		t.Fatalf("empty tool_calls array must be dropped, got %s", om.ToolCalls)
+	}
+}
+
+// 上游报告输出里有多少是思考 token；缺少这个字段，客户端无法判断
+// completion_tokens 里多少是可见回答、多少是思考（两者都按输出计费）。
+func TestTokenUsageMarshalsCompletionTokensDetails(t *testing.T) {
+	u := TokenUsage{
+		Prompt: 37, Completion: 40, Total: 77,
+		CompletionTokensDetails: &CompletionTokensDetails{ReasoningTokens: 40},
+	}
+	b, err := json.Marshal(u)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]interface{}
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatal(err)
+	}
+	ctd, ok := got["completion_tokens_details"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("completion_tokens_details 未输出: %s", b)
+	}
+	if n, _ := ctd["reasoning_tokens"].(float64); int(n) != 40 {
+		t.Errorf("reasoning_tokens = %v, want 40 (%s)", ctd["reasoning_tokens"], b)
+	}
+	// 标准 OpenAI 字段同时存在，老客户端不受影响。
+	if _, ok := got["completion_tokens"]; !ok {
+		t.Errorf("标准 completion_tokens 丢失: %s", b)
+	}
+
+	// 未设置时不得凭空造字段。
+	b2, _ := json.Marshal(TokenUsage{Prompt: 1, Completion: 2, Total: 3})
+	if strings.Contains(string(b2), "completion_tokens_details") {
+		t.Errorf("无数据时不应输出 completion_tokens_details: %s", b2)
+	}
+}