fix: send x-opencode-session for OpenCode Go requests (#349)

## Requirement or Bug

OpenCode Go models fail in the desktop app and the CLI with `400 Request
is missing x-opencode-session and cannot be routed efficiently`.

## Bug Reproduction Steps

1. Configure an OpenCode Go provider (base URL
`https://opencode.ai/zen/go/v1`) with an API key.
2. Send any message in a session.
3. The model request fails with the 400 above.

## Root Cause

OpenCode Go requires a stable session id in the `x-opencode-session`
header for each conversation
([docs](https://opencode.ai/docs/go/#where-can-i-use-it)). The engine
only built this header in the legacy `kosong/model` requester. Requests
now go through the `llm-adapter` requester, which never sent it. Even
the legacy path read `conversationId`, which no turn sets; turns set
only `cacheKey` (the session id). This is a fundamental fix.

## Code Changes

- `llm-adapter/model/model-requester-impl.ts`: merge
`x-opencode-session: <cacheKey>` into the model default headers when the
base URL is an `https://` `opencode.ai` host.
- `llm-adapter/model/catalog-service.ts`: the connectivity ping sends a
random session id, so the settings "test connection" works against
OpenCode.
- Move `opencodeSession.ts` into
`llm-adapter/model/opencode-session.ts`; the legacy requester imports it
from there and falls back to `cacheKey`.

## Behavior Changes and Affected Users

| Behavior | Before | After | Who relies on the old behavior | Escape
hatch |
| --- | --- | --- | --- | --- |
| Requests to `https://*.opencode.ai` | No session header; Go rejects
them with 400 | `x-opencode-session` is the session id (a header the
user set in provider config wins); the ping probe uses a random id |
Nobody (requests failed) | None needed |
| Requests to every other provider | Unchanged | Unchanged (the helper
returns no header for other hosts) | n/a | n/a |

Tests: `test/llm-adapter/model/modelRequester.test.ts` adds two cases
(header sent to OpenCode; not sent to other hosts or without a session
id). The first case fails without the fix.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] The behavior-change table above is complete, and every removed
behavior or flipped default is named in the changeset and either has an
escape hatch or was explicitly approved by a maintainer in this PR.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
* Fixed OpenCode Go requests that could fail when the required session
header was missing.
* Requests now include a session header when applicable, while
preserving an existing session header.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elkaix

.changeset/opencode-go-session-header.md

@@ -0,0 +1,6 @@
+---
+"@pymodel/pythinker-code": patch
+"@pymodel/pythinker-desktop": patch
+---
+
+Fix OpenCode Go requests failing with "Request is missing x-opencode-session".

packages/agent-core-v2/src/kosong/model/modelRequesterImpl.ts

@@ -12,7 +12,7 @@ import type {
 import { translateProviderError } from '#/kosong/protocol/errors';
 import type { IProtocolAdapterRegistry } from '#/kosong/protocol/protocol';
 
-import { opencodeSessionHeaders } from './opencodeSession';
+import { opencodeSessionHeaders } from '#/llm-adapter/model/opencode-session';
 
 import type { AuthProvider, Model } from './catalog';
 import type {
@@ -92,7 +92,10 @@ export class ModelRequesterImpl implements ModelRequester {
     const options: GenerateOptions = {
       signal,
       cacheKey: params?.cacheKey,
-      extraHeaders: opencodeSessionHeaders(this.model.baseUrl, params?.conversationId),
+      extraHeaders: opencodeSessionHeaders(
+        this.model.baseUrl,
+        params?.conversationId ?? params?.cacheKey,
+      ),
       sampling: params?.sampling,
       thinking:
         params?.thinkingEffort === undefined

packages/agent-core-v2/src/llm-adapter/model/catalog-service.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+
 import { parsePythinkerCodeCustomHeaders } from '@pymodel/pythinker-code-oauth';
 
 import { Disposable } from '#/_base/di/lifecycle';
@@ -171,7 +173,7 @@ export class ModelCatalog extends Disposable implements IModelCatalog {
             messages: [{ role: 'user', content: [{ type: 'text', text: 'ping' }], toolCalls: [] }],
           },
           undefined,
-          { maxCompletionTokens: 512 },
+          { cacheKey: randomUUID(), maxCompletionTokens: 512 },
         )) {
           if (event.type === 'part' && event.part.type === 'text') {
             text += event.part.text;

packages/agent-core-v2/src/llm-adapter/model/model-requester-impl.ts

@@ -17,6 +17,7 @@ import {
   type LlmRequestContent,
   type LlmRequestEvent,
   type LlmRequester,
+  mergeRequestHeaders,
 } from '#human/llm/requester/requester';
 import type { TokenUsage } from '#human/llm/usage';
 
@@ -32,6 +33,7 @@ import { fromLlmAssistantMessage, toLlmMessage, type Tool } from '../contract/me
 import { mergeUsagePatch } from '#human/llm/usage';
 
 import type { Model } from './catalog';
+import { opencodeSessionHeaders } from './opencode-session';
 import type {
   ModelRequestEvent,
   ModelRequestInput,
@@ -159,8 +161,23 @@ export class ModelRequesterImpl implements ModelRequester {
     };
 
     const credential = await this.model.credentialProvider?.resolve();
+    const credentialed = applyCredential(resolved.model, credential);
+    const sessionHeaders = opencodeSessionHeaders(
+      credentialed.baseUrl,
+      params?.cacheKey,
+      credentialed.defaultHeaders,
+    );
     await requester.generate(
-      { ...config, model: applyCredential(resolved.model, credential) },
+      {
+        ...config,
+        model:
+          sessionHeaders === undefined
+            ? credentialed
+            : {
+                ...credentialed,
+                defaultHeaders: mergeRequestHeaders(credentialed.defaultHeaders, sessionHeaders),
+              },
+      },
       content,
       {
         signal: signal ?? new AbortController().signal,

…e-v2/src/kosong/model/opencodeSession.ts …rc/llm-adapter/model/opencode-session.tspackages/agent-core-v2/src/kosong/model/opencodeSession.ts renamed to packages/agent-core-v2/src/llm-adapter/model/opencode-session.ts packages/agent-core-v2/src/kosong/model/opencodeSession.ts renamed to packages/agent-core-v2/src/llm-adapter/model/opencode-session.ts

@@ -18,8 +18,12 @@ export function isOpencodeGatewayBaseUrl(baseUrl: string | undefined): boolean {
 export function opencodeSessionHeaders(
   baseUrl: string | undefined,
   conversationId: string | undefined,
+  existing?: Readonly<Record<string, string>>,
 ): Record<string, string> | undefined {
   const id = conversationId?.trim();
   if (!isOpencodeGatewayBaseUrl(baseUrl) || id === undefined || id.length === 0) return undefined;
+  if (Object.keys(existing ?? {}).some((key) => key.toLowerCase() === OPENCODE_SESSION_HEADER)) {
+    return undefined;
+  }
   return { [OPENCODE_SESSION_HEADER]: id };
 }

packages/agent-core-v2/test/llm-adapter/model/modelRequester.test.ts

@@ -467,3 +467,42 @@ describe('buildStreamTiming', () => {
     });
   });
 });
+
+describe('ModelRequesterImpl OpenCode session header', () => {
+  async function headersFor(
+    baseUrl: string,
+    cacheKey: string | undefined,
+    defaultHeaders?: Record<string, string>,
+  ) {
+    const requester = new FakeLlmRequester();
+    requester.handler = (_i, emit) => textStream(emit);
+    const impl = new ModelRequesterImpl(modelWith(undefined), {
+      resolve: () => ({
+        requester,
+        protocol: 'openai',
+        model: { ...BASE_LLM_MODEL, baseUrl, defaultHeaders },
+      }),
+    });
+    await collect(impl.request(INPUT, undefined, { cacheKey }));
+    return requester.calls[0]!.config.model.defaultHeaders;
+  }
+
+  it('sends the session id as x-opencode-session to the OpenCode gateway', async () => {
+    expect(await headersFor('https://opencode.ai/zen/go/v1', 'session-1')).toEqual({
+      'x-opencode-session': 'session-1',
+    });
+  });
+
+  it('does not send the header to other providers or without a session id', async () => {
+    expect(await headersFor('https://api.example.test/v1', 'session-1')).toBeUndefined();
+    expect(await headersFor('https://opencode.ai/zen/go/v1', undefined)).toBeUndefined();
+  });
+
+  it('keeps a session header the user configured', async () => {
+    expect(
+      await headersFor('https://opencode.ai/zen/go/v1', 'session-1', {
+        'X-OpenCode-Session': 'custom',
+      }),
+    ).toEqual({ 'X-OpenCode-Session': 'custom' });
+  });
+});