[dsh-llm-pi-ai] opencode Go 需要 x-opencode-session，但 pi-ai SDK 从不生成

[skppao1415]

dsh-llm-pi-ai：opencode Go provider 需要 x-opencode-session，但 pi-ai SDK 从不生成该头

English: dsh-llm-pi-ai passes options.sessionId into @earendil-works/pi-ai, but the SDK only maps sessionId to provider-specific headers for Anthropic/Mistral/Azure. For opencode / opencode-go nothing sets x-opencode-session, so every request to opencode Go is rejected with 400 {"type":"MissingSessionID"}.

归属说明：以下问题涉及 @deepseek-ai/dsh-llm-pi-ai（传参正确但下游不落地）与 @earendil-works/pi-ai（缺 provider 分支）。按仓库归属请维护者判断是否转到 pi-ai。

环境

• @deepseek-ai/dsh 0.1.5-rc.2，profile web，provider 配置在 ~/.dsh/settings.yaml 的 llm-pi-ai.providers.opencode-go
• @earendil-works/pi-ai 0.85.1（随 dsh 一起安装于 ~/.dsh/profiles/node_modules/）
• 网关：https://opencode.ai/zen/go/v1/*，模型 deepseek-v4-flash

现象

HTTP 400
{"type":"MissingSessionID","message":"Error from provider (Console Go): Request is missing
 x-opencode-session and cannot be routed efficiently. Please see https://opencode.ai/docs/go/…"}

dsh 侧表现为每一轮运行都失败：本轮运行失败 + INVALID_REQUEST（该错误码映射见 dsh-client-connection / dsh-llm-pi-ai / dsh-llm-deepseek）。

分析

1. dsh-llm-pi-ai/lib/index.js:1873 附近已经把 sessionId 传给 SDK：

   ...(options.sessionId === void 0 ? {} : { sessionId: String(options.sessionId) }),
   headers: requestHeaders(profile.headers)

2. 但 @earendil-works/pi-ai@0.85.1 只在下列分支使用 sessionId：anthropic-messages（x-session-affinity，见 sendSessionAffinityHeaders）、mistral-conversations（x-affinity）、azure/codex（prompt_cache_key）。没有 opencode/opencode-go 分支，因此该头永远不会生成。

3. pi 本体是在应用层补的（二进制内可见 return { "x-opencode-session": sessionId, "x-opencode-client": "pi" }，仅当 provider 为 opencode/opencode-go 或 baseUrl 命中 OPENCODE_HOST），SDK 消费者无法自动获得。

实测对照（同一 key、同一模型）

请求	结果
不带 x-opencode-session	HTTP 400 MissingSessionID
带 x-opencode-session: <uuid> + x-opencode-client: dsh	HTTP 200，正常返回 completion

建议

1. dsh-llm-pi-ai 在 requestHeaders() 里为 opencode-go 合并 x-opencode-session（用会话级 id 更佳；目前 sessionId 已传入，只是没被用上）；
2. 或 @earendil-works/pi-ai 对 opencode 系 provider 支持 sessionId → x-opencode-session；
3. 相关：assertValidHeaders 会剥离大小写冲突的 attribution 头，合并时注意别把该头剥掉。

临时规避

在 provider 配置里写静态头（headers: { x-opencode-session: <uuid>, x-opencode-client: dsh }）即可恢复；代价是全进程共用同一路由 id，若遇到会话级限流需要轮换。

[argszero]

Thanks for the detailed report — the root cause is confirmed, and your three observations each hold up against the sources. A few precision points that change which fix is worth taking, from checking @earendil-works/pi-ai@0.85.1 (the resolved pin of dsh-llm-pi-ai@0.1.5-rc.2) and the harness sources at c291e7961a.

1. The gap is sharper than "no opencode branch": affinity is a switch plus a format

In dist/api/openai-completions.js, header emission is gated twice:

if (sessionId && compat.sendSessionAffinityHeaders) {   // switch, default false
  if (compat.sessionAffinityFormat === "openrouter") headers["x-session-id"] = sessionId;
  else {
    if (compat.sessionAffinityFormat === "openai") headers.session_id = sessionId;
    headers["x-client-request-id"] = sessionId;          // always, in the else branch
    headers["x-session-affinity"] = sessionId;
  }
}

and the vocabulary is fixed: SessionAffinityFormat = "openai" | "openai-nosession" | "openrouter" (dist/types.d.ts). Two things follow that are easy to miss:

• sendSessionAffinityHeaders is off by default and almost nowhere turned on. Across all of pi-ai's shipped catalogs, exactly three providers set it: fireworks, cloudflare-workers-ai, cloudflare-ai-gateway. So the SDK will not send affinity headers to opencode even if sessionId is passed — this is a missing feature, not a misrouted value.
• sessionAffinityFormat alone is inert, and that is exactly the state opencode-go is in. Its catalog does set "sessionAffinityFormat": "openai-nosession" — but only the format, never the switch. And it still would not be enough: "openai-nosession" lands in the else branch and emits x-client-request-id + x-session-affinity, never x-opencode-session. The wire name opencode Go wants is not expressible in the current vocabulary at all.

One more consequence: "openai-nosession" is why the session_id line is conditional. So a fix cannot be "add an opencode value and hope the else branch covers it" — the branch has to name the header.

2. Most of the affinity machinery is already inherited; it is inherited dead

packages/llm/llm-pi-ai/src/provider.ts reuseCatalogProvider() reuses pi-ai's own opencode-go provider whenever a configured route does not override the wire protocol, and resolveModelCompat() (catalog.ts:767) spreads base.compat through when the resolved api still matches. So sessionAffinityFormat: "openai-nosession" does already reach the request path for opencode-go — the model just never passes the switch gate above. Worth knowing before anyone hunts for "where dsh drops the catalog compat": nothing is dropped, the catalog's own value is inert by construction.

3. On your three suggestions

Suggestion 1 (dsh-llm-pi-ai merges the header) is the cheapest and is correct in shape, with two adjustments:

• Key the mapping on the pi-ai provider id, not the route key. The routes are user-chosen dict keys, so a route named opencode-go is also the pi provider id only by coincidence. reuseCatalogProvider preserves pi-ai's own id for catalog routes — which makes the mapping work — but a route that sets api: is rebuilt by createProvider() and loses that identity. model.provider is the field to read, and it is already populated correctly.
• If you inject, prefer pi-ai's model.headers over requestHeaders(profile.headers). requestHeaders() (adapter.ts:205) merges against attribution and is read once per route profile; model.headers is per-model and reaches createClient()'s map directly, so a repointed or hand-declared route can still carry it. Whichever you pick, note the precedence differs: pi-ai merges model.headers first and optionsHeaders last, so the adapter's map wins collisions.

Suggestion 2 is right that pi-ai owns the proper fix, but it needs two changes, not one: a new vocabulary member and flipping the switch on the opencode catalogs — plus adding those models' format entries. Landing only the format (as opencode-go has today) reproduces the present inert state.

Suggestion 3 checks out, and your instinct to call it out was right. requestHeaders() strips any profile header whose lowercased name collides with attributionHeaders(), and attributionHeaders() is derived from a curated AppIdentity (llm/src/attribution.ts) rather than a fixed reserved set — today it emits only user-agent, so x-opencode-session is not at risk. But this is the same guard that stops a deployment from overriding attribution, so any fix that routes the header through profile.headers inherits it. Routing through model.headers sidesteps the question entirely.

4. Why this cannot be a plugin today (the part that decides where the fix lands)

I checked for a mountable seam and there is none, for four independent reasons:

• ctx.llm.registerAdapter() is all-or-nothing per route: prepareRoutes() throws DUPLICATE_ADAPTER on any already-held provider (llm/src/index.ts:429), so a plugin cannot shadow opencode-go's adapter.
• GenerateOptions (llm/src/types.ts:419) has no headers field — sessionId is the only transport-metadata channel, and only adapters read it.
• 'llm/stream' is a chunk waterfall (llm/src/index.ts:72): a listener can wrap the returned iterable, but its parameters are the request and its return is the stream. It cannot reach HTTP headers.
• pi-ai does honor a per-request fetch (ProviderRequestOptions.fetch), which would be a clean interception point — but llm-pi-ai/src/adapter.ts never threads one (no fetch occurrence in the file). That is the smallest genuinely first-party change: make the adapter pass a fetch that decorates the request.

So opencode-go + pi-ai is core-bound, and the notification that opens with an INVALID_REQUEST maps the 400 up the stack as designed. Your static-header workaround is the right stopgap; the route-wide single id is the real cost, exactly as you describe.

5. For whoever implements it

The observable is best pinned in two places: a unit test on the adapter's request construction (assert the header is present on an opencode-go route and absent on others), and a pi-ai-side test asserting the full emitted set — x-opencode-session and whatever client-identity header the gateway expects, since a session-routed request without the client header is a different failure than this one.

I'd be glad to ship a small plugin if a request-header field ever lands on GenerateOptions (a per-call headers map is the missing seam); until then this one belongs in dsh-llm-pi-ai or upstream.

[skppao1415]

Thanks — verified both corrections against the installed 0.85.1 build (switch defaults to false; only fireworks +cloudflare-workers-ai + cloudflare-ai-gateway enable it, so opencode-go's sessionAffinityFormat is inert). I'll take the model.provider / model.headers adjustments for suggestion 1. Same issue as #5495 though, so I'll fold the mechanism delta there instead of keeping this as a separate thread.

[HuoGu-Hub]

别蒸了兄弟，这个问题早好多天之前就已经有个120+⬆的讨论 #5495 了，tianyicui都参与了，可以去看看那一条，讨论里有个dsh-opencode-session插件可以暂时缓解（亲测有效），用静态头也不是不行，就是不知道缓存命中会不会受到影响

[skppao1415]

谢谢指路，是我漏了 #5495，我会去试一下 dsh-opencode-session 插件的。

[PerryLink]

核实结论：报告机制属实，修复归属可以确认 —— 责任在 pi-ai 侧，dsh 侧只有静态头 workaround。

1. dsh 确实把 sessionId 传给 SDK：packages/llm/llm-pi-ai/src/adapter.ts:384（构建产物 lib/index.js:1871-1873，与你引用的位置精确命中）。
2. pi-ai 0.85.1（本机 node_modules 实测版本一致）整个 dist 里 x-opencode-session / x-opencode-client 零出现；sessionId 只在 sendSessionAffinityHeaders 开关下映射为 x-session-affinity 等头，而该开关默认 false（仅 fireworks / cloudflare 系三个 provider 打开）。
3. dsh 的 compat 配置面把 sendSessionAffinityHeaders / sessionAffinityFormat 列为 withhold（catalog.ts:255/257）⇒ 无法经配置修复。
4. 所以唯一可用 workaround 确实是 profile.headers 静态头：config.ts:150-151 的 headers 字段经 adapter.ts:204-212 的 requestHeaders() 合并、SDK 侧「options headers 最后合并可覆盖默认」—— 任何合法头都能透传。

两点细节修正：opencode-go catalog 只有 openai-responses 条目带 openai-nosession 格式（openai-completions 条目没有）；剥离大小写冲突 attribution 头的函数是 requestHeaders() 而不是 assertValidHeaders（后者只做合法性校验）。修复需改代码：dsh-llm-pi-ai 在 adapter 层按 model.provider === 'opencode-go' 注入，或上游 pi-ai 为 opencode 系补分支。