bug(llm-pi-ai): openai-responses 路由无法关闭 session_id 请求头

[GrainRainAndy]

openai-responses 路由必发 session_id，拒绝下划线 header 名的网关返回 400，导致部分第三方中转/路由不可用。

• 复现步骤：

  1. 配置一条 api: openai-responses 的自定义路由，baseURL 指向拒绝含下划线 header 名的第三方 OpenAI 兼容网关。
  2. 配置一个该网关确认支持 Responses API 的模型。
  3. 经 Harness 发送一条最小消息。

  llm-pi-ai:
    providers:
      third-party-responses:
        apiKeyEnv: THIRD_PARTY_API_KEY
        api: openai-responses
        baseURL: https://gateway.example/v1
        models:
          - id: example-model

• 实际结果：

  请求在到达鉴权与模型之前返回 400 Bad Request。

  对真实第三方 Responses endpoint 做过单变量对照：两次请求的 URL、模型、鉴权、请求正文字段完全一致，仅改变是否携带 session_id header。

  不带 session_id（仍带 x-client-request-id、正文 prompt_cache_key、stream: true）：HTTP 200，text/event-stream，收到 response.created / response.output_text.delta / response.completed，获得 Response ID，模型返回预期文本。

  带 session_id：HTTP 400，text/plain，正文 Bad Request，无 Response ID，无 SSE 事件。

  失败由该 header 触发，与 API key、endpoint、模型 id、请求正文、流式协议无关。endpoint、凭据、provider 名和模型 id 不在此披露。

  成因：packages/llm/llm-pi-ai/src/adapter.ts:317 将 Agent 请求的 sessionId 透传给 pi-ai。pi-ai 0.82.1 dist/api/openai-responses.js:166-175 按 compat.sessionAffinityFormat 分派 header；detectSessionAffinityFormat（同文件 :34-36）仅在 provider 为 openrouter 或 baseURL 含 openrouter.ai 时返回 openrouter，其余一律返回 openai，即发送 session_id。自定义网关必然落入该分支。

  pi-ai 已定义 SessionAffinityFormat = "openai" | "openai-nosession" | "openrouter"（dist/types.d.ts:41），并在 OpenAICompletionsCompat（:463）与 OpenAIResponsesCompat（:472）上都接受 sessionAffinityFormat。Harness 侧的 PiAiCompatProfile（src/catalog.ts）与配置 schema compatProfile（src/config.ts:188）只暴露 thinkingFormat 和 supportsReasoningEffort，该字段无从配置。

  两个协议在此处不对称：Completions 侧的 affinity header 受 sendSessionAffinityHeaders 开关控制且检测默认为 false（dist/api/openai-completions.js:489、:1174）；Responses 侧没有这个开关，只要有 sessionId 就发。

  无可用 workaround：profile 的 headers 只能新增或覆盖 header 的值，无法移除 header 名。把 session_id 置空仍会发出含下划线的 header 名，网关同样拒绝；pi-ai 将 options headers 最后合并（openai-responses.js:178-180），覆盖顺序也不改变这一点。

• 预期结果：

  compat 可在 provider 级和模型级配置 sessionAffinityFormat。

  llm-pi-ai:
    providers:
      third-party-responses:
        apiKeyEnv: THIRD_PARTY_API_KEY
        api: openai-responses
        baseURL: https://gateway.example/v1
        compat:
          sessionAffinityFormat: openai-nosession
        models:
          - id: example-model

  openai-nosession 省略 session_id，保留 x-client-request-id。正文 prompt_cache_key 由 cacheRetention 决定（openai-responses.js:204），不受此字段影响。未配置时维持 pi-ai 的自动检测。

  解析优先级：模型级 compat → provider 级 compat → 已安装 catalog 条目 → pi-ai 自动检测。

• 环境：

  • deepseek-harness master（47f943859b）
  • @deepseek-ai/dsh-llm-pi-ai 0.1.0-rc.5
  • @earendil-works/pi-ai 0.82.1
  • macOS Tahoe 26.5.2，故障位于 HTTP header 处理阶段，与操作系统无关

参考

• pi-ai SessionAffinityFormat / OpenAIResponsesCompat
• pi-ai 同类问题：openai-responses sends non-conforming session_id header, rejected by strict HTTP gateways (Envoy, nginx) earendil-works/pi#3579
• OpenAI Responses API 迁移指南：https://developers.openai.com/api/docs/guides/migrate-to-responses

[Mide69]

已在当前 master 逐条核实，两处关键定位依然准确（行号有小幅漂移，更新如下）：

1. packages/llm/llm-pi-ai/src/adapter.ts:325（原报告 :317，因其他改动略有偏移）：

...options.sessionId === undefined ? {} : { sessionId: String(options.sessionId) },

options.sessionId 原样透传给 streamSimple，没有任何按 provider/route 关闭的开关。

2. packages/llm/llm-pi-ai/src/config.ts:188：

const compatProfile: z<PiAiCompatProfile> = z.object({
  thinkingFormat: z.union(SUPPORTED_THINKING_FORMATS),
  supportsReasoningEffort: z.boolean(),
})

compatProfile schema 确实只暴露 thinkingFormat 和 supportsReasoningEffort，没有 sessionAffinityFormat 字段——你提出的配置面目前确实无从表达。

你提出的 compat.sessionAffinityFormat（provider 级 + 模型级，解析优先级 模型 → provider → catalog → pi-ai 自动检测）与现有 compatProfile 的结构和惯例是一致的，是合理的落地方案。这份报告已经把根因、pi-ai 侧的不对称行为（Completions 有 sendSessionAffinityHeaders 开关，Responses 没有）和上游 pi-ai issue 都定位得很清楚了，我没有更多技术细节可补充——只是确认它在当前 master 上依然成立、没有过时。

[weijiafu14]

这份报告的单变量对照做得很干净。两件：一条你说"无可用 workaround"的 workaround，和一份对你根因判断的独立佐证。

一、有 workaround：在中间放一个只删这一个 header 的透传代理

你的结论是：

无可用 workaround：profile 的 headers 只能新增或覆盖 header 的值，无法移除 header 名。

在 DSH 的配置面里确实无法移除，这一点你说得对。但你可以在 DSH 和网关之间放一个自己的本地转发器，让它在转发前把这个 header 摘掉——DSH 那边只需要把 baseURL 指到 http://127.0.0.1:<port>/v1。

我们仓库里有个现成的透传器可以拿来改（recording-proxy.mjs，一个独立文件，不需要装任何东西，拷走 node 直接跑）。它本来是用来把请求体录下来的：请求真发给上游、真实响应原样流回，中间只多存一份 body。改成"顺手删一个 header"就是转发前多一行：

delete headers['session_id']

（它默认就删掉了逐跳 header 并原样带上 authorization，所以凭据照常走请求自己的头，不读环境变量、不落盘。）

这条路的性质要说清楚：它是绕过，不是修复，而且多一跳本地转发。但对"现在就想让这条路由能用"来说，它是可用的；而且它顺带给你一个额外好处——你可以直接看到 DSH 到底发了哪些 header，用来验证修复落地后 session_id 是不是真的没了。

（如果你不想引第三方文件，任何一个能改写请求头的本地反代都行，nginx 的 proxy_set_header session_id ""; 在多数版本里等于不发这个头——但这条我没试过，上面那个 node 脚本是我确定行为的那条。）

二、你对 PiAiCompatProfile 的判断，我这边有一份独立佐证

@Mide69 已经核过 config.ts:188 的 compatProfile schema 只有两个字段。我可以从另一个角度佐证同一件事——用类型系统证明这个字段不在 PiAiCompatProfile 上。

我们做 DSH 的兼容层，需要把 Pi 侧的 compat 声明翻译成 DSH profile 字段。为了防止上游加字段时我们悄悄漏掉，那张映射表钉了一个编译期门：

const DSH_COMPAT_FIELD_PROTOCOLS = {
  supportsStore, supportsDeveloperRole, supportsReasoningEffort,
  supportsUsageInStreaming, maxTokensField, requiresToolResultName,
  requiresAssistantAfterToolResult, requiresThinkingAsText,
  requiresReasoningContentOnAssistantMessages, thinkingFormat,
  chatTemplateKwargs, supportsStrictMode, cacheControlFormat,
  supportsLongCacheRetention, supportsEagerToolInputStreaming,
  supportsCacheControlOnTools, supportsTemperature, forceAdaptiveThinking,
  allowEmptySignature, supportsStrictTools,
} satisfies Record<keyof PiAiCompatProfile, ReadonlySet<string>>

satisfies Record<keyof PiAiCompatProfile, …> 要求这张表必须穷举 PiAiCompatProfile 的每一个键。这段在我们仓库里编译通过，而表里没有 sessionAffinityFormat——所以它确实不是 PiAiCompatProfile 的键，你要的配置面在类型层就不存在。

（这个门的用途正是你这类情况的反面：上游哪天把 sessionAffinityFormat 加进 PiAiCompatProfile，我们的构建会立刻失败并逼我们处理它。所以如果有人想跟进这个提案的落地状态，这是个很便宜的探针。）

三、你指出的那个不对称，是这份报告最有价值的部分

Completions 侧的 affinity header 受 sendSessionAffinityHeaders 开关控制且检测默认为 false；Responses 侧没有这个开关，只要有 sessionId 就发。

这句话把诉求从"给我加个配置项"变成了"两个协议在同一件事上的策略不一致，而其中一个没有任何出口"。后者好推得多，因为它不需要论证这个开关有多重要——只需要问为什么 Completions 有而 Responses 没有。

而且这个不对称还解释了一件事：为什么这个问题只在 Responses 路由上出现、Completions 路由的用户从没报过。建议把这段提到摘要里。

（顺带一个相关的观察：detectSessionAffinityFormat 只认 openrouter 这一个特例，其余一律当 openai——这和 detectCompat 只枚举一方端点是同一个模式。#780 那边的结论也是同一句话：自动探测只能枚举一方端点，第三方网关的方言封不住，所以配置面才是可持续的表面。 你这条是那个论点的第三个实例，引一下会更有力。）

边界与利益相关

我们不修 DSH 自家组件——llm-pi-ai 的 adapter、compatProfile schema 都在 DSH 里。第一节是绕过不是修复；第二节是佐证，我没有读过 pi-ai 0.82.1 的源码，那部分完全采信你和 @Mide69 的核实。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销：第一节那个脚本是独立单文件，拷走就能跑，不需要装我们任何东西；你要的是官方把这个字段接出来，那是 DSH 的活。