Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Fix OpenCode MissingSessionID errors through FCC (#1700)

Ali Khokharf64e2b31d8e2
diff --git a/e2e/conftest.py b/e2e/conftest.py
index aa3b45ce..53a65a1b 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -5,7 +5,7 @@ import socket
import sys
import threading
import time
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterator, Mapping
from dataclasses import replace
from pathlib import Path
@@ -101,6 +101,7 @@ class _ModelListingProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, response_model
summary = str(request.system).startswith("Summarize")
@@ -221,6 +222,7 @@ class _ModelListingProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/pyproject.toml b/pyproject.toml
index 4880295e..5d4b8363 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.22.9"
+version = "5.22.10"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.py
index 4fe732a3..fc2e836e 100644
--- a/src/free_claude_code/api/handlers/messages.py
+++ b/src/free_claude_code/api/handlers/messages.py
@@ -1,7 +1,7 @@
"""Claude Messages API product flow."""
import asyncio
-from collections.abc import AsyncIterator, Callable
+from collections.abc import AsyncIterator, Callable, Mapping
from dataclasses import dataclass, replace
from fastapi.responses import JSONResponse, Response
@@ -82,6 +82,7 @@ class MessagesHandler:
token_counter: TokenCounter = get_token_count,
provider_executor: ProviderExecutor | None = None,
generation_id: int | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> None:
self._settings = settings
self._model_router = model_router or ModelRouter(settings)
@@ -92,6 +93,7 @@ class MessagesHandler:
token_counter=token_counter,
generation_id=generation_id,
log_raw_payloads=settings.log_raw_api_payloads,
+ request_headers=request_headers,
)
self._message_intercepts: tuple[MessageIntercept, ...] = (
self._intercept_web_server_tool,
diff --git a/src/free_claude_code/api/handlers/responses.py b/src/free_claude_code/api/handlers/responses.py
index f5f279ed..ff0df509 100644
--- a/src/free_claude_code/api/handlers/responses.py
+++ b/src/free_claude_code/api/handlers/responses.py
@@ -1,5 +1,7 @@
"""OpenAI Responses API product flow for Codex clients."""
+from collections.abc import Mapping
+
from fastapi.responses import JSONResponse
from free_claude_code.api.request_errors import (
@@ -40,6 +42,7 @@ class ResponsesHandler:
model_router: ModelRouter | None = None,
provider_executor: ProviderExecutor | None = None,
generation_id: int | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> None:
self._settings = settings
self._model_router = model_router or ModelRouter(settings)
@@ -48,6 +51,7 @@ class ResponsesHandler:
progress_timeout_seconds=settings.provider_progress_timeout,
generation_id=generation_id,
log_raw_payloads=settings.log_raw_api_payloads,
+ request_headers=request_headers,
)
async def create(
diff --git a/src/free_claude_code/api/routes.py b/src/free_claude_code/api/routes.py
index 0a3129d7..4f37a28c 100644
--- a/src/free_claude_code/api/routes.py
+++ b/src/free_claude_code/api/routes.py
@@ -1,5 +1,7 @@
"""FastAPI route handlers."""
+from collections.abc import Mapping
+
from fastapi import APIRouter, Depends, HTTPException, Request, Response
from loguru import logger
@@ -46,6 +48,7 @@ async def _create_messages_response(
request_data: MessagesRequest,
*,
request_id: str,
+ request_headers: Mapping[str, str] | None = None,
) -> object:
lease: RequestRuntimeLease | None = None
try:
@@ -55,6 +58,7 @@ async def _create_messages_response(
provider_resolver=_provider_resolver(lease),
token_counter=get_token_count,
generation_id=lease.generation_id,
+ request_headers=request_headers,
)
response = await handler.create(request_data, request_id=request_id)
except ApplicationError as exc:
@@ -78,6 +82,7 @@ async def _create_responses_response(
request_data: OpenAIResponsesRequest,
*,
request_id: str,
+ request_headers: Mapping[str, str] | None = None,
) -> object:
lease: RequestRuntimeLease | None = None
try:
@@ -86,6 +91,7 @@ async def _create_responses_response(
lease.settings,
provider_resolver=_provider_resolver(lease),
generation_id=lease.generation_id,
+ request_headers=request_headers,
)
response = await handler.create(request_data, request_id=request_id)
except ApplicationError as exc:
@@ -120,6 +126,7 @@ async def create_message(
services,
request_data,
request_id=get_request_id(request),
+ request_headers=request.headers,
)
@@ -140,6 +147,7 @@ async def create_response(
services,
request_data,
request_id=get_request_id(request),
+ request_headers=request.headers,
)
diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.py
index f48314bd..1d1e4dc8 100644
--- a/src/free_claude_code/application/execution.py
+++ b/src/free_claude_code/application/execution.py
@@ -4,7 +4,8 @@ import asyncio
import inspect
import math
import sys
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from types import MappingProxyType
from typing import Literal
from loguru import logger
@@ -59,6 +60,7 @@ class ProviderExecutor:
responses_token_counter: ResponsesTokenCounter = estimate_responses_input_tokens,
generation_id: int | None = None,
log_raw_payloads: bool = False,
+ request_headers: Mapping[str, str] | None = None,
) -> None:
if not math.isfinite(progress_timeout_seconds) or progress_timeout_seconds <= 0:
raise ValueError("progress_timeout_seconds must be finite and positive")
@@ -67,6 +69,7 @@ class ProviderExecutor:
self._responses_token_counter = responses_token_counter
self._generation_id = generation_id
self._log_raw_payloads = log_raw_payloads
+ self._request_headers = MappingProxyType(dict(request_headers or {}))
self._progress_timeout_seconds = float(progress_timeout_seconds)
def _progress_timeout_failure(
@@ -212,6 +215,7 @@ class ProviderExecutor:
request_id=request_id,
response_model=routed.resolved.original_model,
reasoning=routed.reasoning,
+ request_headers=self._request_headers,
)
return self._stream_candidates(
@@ -278,6 +282,7 @@ class ProviderExecutor:
request_id=request_id,
response_model=routed.resolved.original_model,
reasoning=routed.reasoning,
+ request_headers=self._request_headers,
)
raw_input = routed.request.input
diff --git a/src/free_claude_code/application/ports.py b/src/free_claude_code/application/ports.py
index 51066402..91aa5186 100644
--- a/src/free_claude_code/application/ports.py
+++ b/src/free_claude_code/application/ports.py
@@ -1,6 +1,6 @@
"""Typed capabilities consumed by application use cases."""
-from collections.abc import AsyncIterator, Callable
+from collections.abc import AsyncIterator, Callable, Mapping
from dataclasses import dataclass
from typing import Protocol
@@ -30,6 +30,7 @@ class ProviderPort(Protocol):
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]: ...
def preflight_responses(
@@ -47,6 +48,7 @@ class ProviderPort(Protocol):
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]: ...
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index 59c28a94..758cef65 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -1,7 +1,7 @@
"""Base provider interface - extend this to implement your own provider."""
from abc import ABC, abstractmethod
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from dataclasses import dataclass
from loguru import logger
@@ -122,6 +122,7 @@ class BaseProvider(ABC):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
"""Stream response in Anthropic SSE format."""
@@ -134,5 +135,6 @@ class BaseProvider(ABC):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
"""Stream response in OpenAI Responses SSE format."""
diff --git a/src/free_claude_code/providers/github_copilot/provider.py b/src/free_claude_code/providers/github_copilot/provider.py
index d38479c8..c319c652 100644
--- a/src/free_claude_code/providers/github_copilot/provider.py
+++ b/src/free_claude_code/providers/github_copilot/provider.py
@@ -2,7 +2,7 @@
import asyncio
import sys
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from contextlib import suppress
import httpx
@@ -150,6 +150,7 @@ class GitHubCopilotProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.preflight_messages(request, reasoning=reasoning)
return self._dispatch(
@@ -168,6 +169,7 @@ class GitHubCopilotProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.preflight_responses(request, reasoning=reasoning)
return self._dispatch(
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 175d1be5..38d2e56b 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -743,6 +743,12 @@ class OpenAIChatProvider(BaseProvider):
"""Return the body passed to the upstream OpenAI-compatible client."""
return body
+ def _upstream_headers(
+ self, request_headers: Mapping[str, str]
+ ) -> Mapping[str, str]:
+ """Select provider-specific headers from this request's client metadata."""
+ return {}
+
def _record_tool_call_extra_content(
self, tool_call_id: str, extra_content: dict[str, Any]
) -> None:
@@ -784,6 +790,7 @@ class OpenAIChatProvider(BaseProvider):
*,
used_retry_kinds: set[str] | None = None,
endpoint: RequestEndpoint | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> tuple[Any, dict, ProviderAttempt]:
"""Create a streaming chat completion with bounded request fallbacks."""
body = self._apply_learned_output_cap(body)
@@ -801,9 +808,13 @@ class OpenAIChatProvider(BaseProvider):
if endpoint is not None
else self._client
)
- if endpoint is not None:
+ if extra_headers or endpoint is not None:
create_body = create_body.copy()
- create_body["extra_headers"] = endpoint.openai_headers()
+ create_body["extra_headers"] = {
+ **(create_body.get("extra_headers") or {}),
+ **(extra_headers or {}),
+ **(endpoint.openai_headers() if endpoint is not None else {}),
+ }
stream = await client.chat.completions.create(
**create_body,
stream=True,
@@ -919,6 +930,7 @@ class OpenAIChatProvider(BaseProvider):
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
endpoint_context: EndpointContext | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
"""Stream response in Anthropic SSE format."""
body = self._build_request_body(request, reasoning=reasoning)
@@ -943,6 +955,7 @@ class OpenAIChatProvider(BaseProvider):
),
reasoning=reasoning,
endpoint_context=endpoint_context,
+ extra_headers=self._upstream_headers(request_headers or {}),
)
return runner.run()
@@ -955,6 +968,7 @@ class OpenAIChatProvider(BaseProvider):
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
endpoint_context: EndpointContext | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
"""Stream a Chat upstream directly as OpenAI Responses SSE."""
translated = self._build_responses_request_body(request, reasoning=reasoning)
@@ -979,6 +993,7 @@ class OpenAIChatProvider(BaseProvider):
response_model=public_model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ extra_headers=self._upstream_headers(request_headers or {}),
)
return runner.run()
@@ -1000,6 +1015,7 @@ class _OpenAIChatStreamRunner:
response_model: str,
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> None:
self._provider = provider
self._body = body
@@ -1011,6 +1027,7 @@ class _OpenAIChatStreamRunner:
self._request_id = request_id
self._response_model = response_model
self._reasoning = reasoning
+ self._extra_headers = dict(extra_headers or {})
self._terminal_failure: ExecutionFailure | None = None
self._endpoint = (
RequestEndpoint(endpoint_context, provider._endpoint_transport)
@@ -1089,6 +1106,7 @@ class _OpenAIChatStreamRunner:
ProviderOperationKind.GENERATION,
used_retry_kinds=used_retry_kinds,
endpoint=self._endpoint,
+ extra_headers=self._extra_headers,
)
scope = ProviderAttemptScope(
attempt,
diff --git a/src/free_claude_code/providers/openai_codex/provider.py b/src/free_claude_code/providers/openai_codex/provider.py
index 377accc3..f6058335 100644
--- a/src/free_claude_code/providers/openai_codex/provider.py
+++ b/src/free_claude_code/providers/openai_codex/provider.py
@@ -3,7 +3,7 @@
import asyncio
import sys
import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from importlib.metadata import PackageNotFoundError, version
from typing import Any
@@ -173,6 +173,7 @@ class OpenAICodexProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
return self._responses.stream_messages(
request,
@@ -191,6 +192,7 @@ class OpenAICodexProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
return self._responses.stream_responses(
request,
diff --git a/src/free_claude_code/providers/openai_responses/transport.py b/src/free_claude_code/providers/openai_responses/transport.py
index 9b4e000f..3b7a395f 100644
--- a/src/free_claude_code/providers/openai_responses/transport.py
+++ b/src/free_claude_code/providers/openai_responses/transport.py
@@ -3,7 +3,7 @@
import asyncio
import sys
import uuid
-from collections.abc import AsyncIterator, Callable
+from collections.abc import AsyncIterator, Callable, Mapping
from typing import cast
import httpx2
@@ -124,6 +124,7 @@ class OpenAIResponsesTransport:
response_model: str,
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
body = self._build_messages_body(request, reasoning=reasoning)
tool_names = OpenAIToolNameCodec.from_request(request)
@@ -131,6 +132,7 @@ class OpenAIResponsesTransport:
return self._run_stream(
body,
endpoint_context=endpoint_context,
+ extra_headers=dict(extra_headers or {}),
request_id=request_id,
response_model=response_model,
presenter_factory=lambda: MessagesResponsesPresenter(
@@ -161,12 +163,14 @@ class OpenAIResponsesTransport:
response_model: str,
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens
body, tools = self._build_native_body(request, reasoning=reasoning)
return self._run_stream(
body,
endpoint_context=endpoint_context,
+ extra_headers=dict(extra_headers or {}),
request_id=request_id,
response_model=response_model,
presenter_factory=lambda: NativeResponsesPresenter(
@@ -229,6 +233,7 @@ class OpenAIResponsesTransport:
response_model: str,
presenter_factory: ResponsesPresenterFactory,
endpoint_context: EndpointContext | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
execution = self._admission.start_execution(request_id=request_id)
outcome = ResponsesExecutionOutcome()
@@ -245,6 +250,7 @@ class OpenAIResponsesTransport:
execution=execution,
outcome=outcome,
endpoint=endpoint,
+ extra_headers=extra_headers,
)
try:
async for event in provider_stream:
@@ -281,6 +287,7 @@ class OpenAIResponsesTransport:
execution: ProviderExecution,
outcome: ResponsesExecutionOutcome,
endpoint: RequestEndpoint | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
recovery = RecoveryController()
trace_event(
@@ -320,7 +327,7 @@ class OpenAIResponsesTransport:
request_id=request_id,
)
sdk_stream = await self._create_sdk_stream(
- body, client=client, endpoint=endpoint
+ body, client=client, endpoint=endpoint, extra_headers=extra_headers
)
stream = scope.retain(_ClosableResponsesStream(sdk_stream))
stream_opened = True
@@ -471,6 +478,7 @@ class OpenAIResponsesTransport:
*,
client: AsyncOpenAI,
endpoint: RequestEndpoint | None = None,
+ extra_headers: Mapping[str, str] | None = None,
) -> AsyncStream[ResponseStreamEvent]:
model = body.get("model")
if not isinstance(model, str) or not model:
@@ -487,7 +495,11 @@ class OpenAIResponsesTransport:
stream=True,
store=False,
extra_body=extra_body or None,
- extra_headers=endpoint.openai_headers() if endpoint is not None else None,
+ extra_headers={
+ **(extra_headers or {}),
+ **(endpoint.openai_headers() if endpoint is not None else {}),
+ }
+ or None,
)
diff --git a/src/free_claude_code/providers/opencode/provider.py b/src/free_claude_code/providers/opencode/provider.py
index ecdc2818..bb00ce55 100644
--- a/src/free_claude_code/providers/opencode/provider.py
+++ b/src/free_claude_code/providers/opencode/provider.py
@@ -1,7 +1,7 @@
"""OpenCode provider with catalog-driven Chat/Responses dispatch."""
import sys
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from dataclasses import dataclass
import httpx
@@ -129,6 +129,16 @@ class OpenCodeProvider(OpenAIChatProvider):
snapshot = await self._catalog.refresh()
return snapshot.model_infos
+ def _upstream_headers(
+ self, request_headers: Mapping[str, str]
+ ) -> Mapping[str, str]:
+ headers = {name.lower(): value for name, value in request_headers.items()}
+ for name in ("x-opencode-session", "session-id", "x-session-id"):
+ session_id = headers.get(name)
+ if session_id and session_id.strip():
+ return {"x-opencode-session": session_id}
+ return {}
+
def preflight_messages(
self,
request: MessagesRequest,
@@ -172,6 +182,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
endpoint_context: EndpointContext | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
return self._dispatch_stream(
request,
@@ -180,6 +191,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model=response_model or request.model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ request_headers=request_headers,
)
async def _dispatch_stream(
@@ -191,6 +203,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model: str,
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
snapshot = await self._catalog.snapshot(request_id=request_id)
route = self._require_route(snapshot, request.model)
@@ -206,6 +219,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model=response_model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ extra_headers=self._upstream_headers(request_headers or {}),
)
else:
super().preflight_messages(routed, reasoning=reasoning)
@@ -216,6 +230,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model=response_model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ request_headers=request_headers,
)
async for event in selected_stream:
yield event
@@ -237,6 +252,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
endpoint_context: EndpointContext | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
return self._dispatch_responses_stream(
request,
@@ -245,6 +261,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model=response_model or request.model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ request_headers=request_headers,
)
async def _dispatch_responses_stream(
@@ -256,6 +273,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model: str,
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
snapshot = await self._catalog.snapshot(request_id=request_id)
route = self._require_route(snapshot, request.model)
@@ -271,6 +289,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model=response_model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ extra_headers=self._upstream_headers(request_headers or {}),
)
else:
super().preflight_responses(routed, reasoning=reasoning)
@@ -281,6 +300,7 @@ class OpenCodeProvider(OpenAIChatProvider):
response_model=response_model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ request_headers=request_headers,
)
async for event in selected_stream:
yield event
diff --git a/tests/api/model_fallback_support.py b/tests/api/model_fallback_support.py
index 258f4d66..d352a5c1 100644
--- a/tests/api/model_fallback_support.py
+++ b/tests/api/model_fallback_support.py
@@ -1,7 +1,7 @@
"""Controlled provider boundary for model-fallback API and product tests."""
import json
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterator, Mapping
from contextlib import contextmanager
from unittest.mock import patch
@@ -220,6 +220,7 @@ class ControlledFallbackProvider:
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, reasoning
self.stream_models.append(request.model)
@@ -255,6 +256,7 @@ class ControlledFallbackProvider:
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, reasoning
self.stream_models.append(request.model)
diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.py
index 4c3ccebc..c2dc6f50 100644
--- a/tests/api/test_api_handlers.py
+++ b/tests/api/test_api_handlers.py
@@ -1,5 +1,5 @@
import json
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from typing import Any
from unittest.mock import MagicMock, patch
@@ -75,6 +75,7 @@ class FakeProvider:
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.requests.append(request)
self.stream_kwargs.append(
@@ -96,6 +97,7 @@ class FakeProvider:
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.responses_requests.append(request)
self.stream_kwargs.append(
@@ -376,6 +378,7 @@ async def test_messages_handler_stream_false_provider_exception_keeps_status() -
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.requests.append(request)
self.stream_kwargs.append(
diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.py
index 3b9b4d2b..92451fa0 100644
--- a/tests/api/test_execution_failure_contract.py
+++ b/tests/api/test_execution_failure_contract.py
@@ -2,7 +2,7 @@
import asyncio
import json
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from typing import Any, cast
from unittest.mock import MagicMock, patch
@@ -125,6 +125,7 @@ class StalledProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, response_model, reasoning
try:
@@ -141,6 +142,7 @@ class StalledProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, response_model, reasoning
try:
diff --git a/tests/api/test_opencode_session_headers.py b/tests/api/test_opencode_session_headers.py
new file mode 100644
index 00000000..cb7147b4
--- /dev/null
+++ b/tests/api/test_opencode_session_headers.py
@@ -0,0 +1,221 @@
+"""Session identity across real ingress, routing, provider, and SDK boundaries."""
+
+import asyncio
+from contextlib import asynccontextmanager
+from unittest.mock import patch
+
+import httpx
+import httpx2
+import pytest
+from openai import AsyncOpenAI
+
+from free_claude_code.config.settings import Settings
+from free_claude_code.providers.opencode import create_opencode_provider
+from tests.api.support import create_test_app, provider_manager_for_app
+from tests.providers.support import immediate_admission, make_provider_config
+from tests.providers.test_opencode import (
+ _catalog_payload,
+ _chat_event_stream,
+ _responses_event_stream,
+)
+
+pytestmark = pytest.mark.asyncio
+
+
+def successful_response(request):
+ body = (
+ _responses_event_stream("hello")
+ if request.url.path.endswith("/responses")
+ else _chat_event_stream("hello")
+ )
+ return httpx2.Response(
+ 200, headers={"content-type": "text/event-stream"}, text=body
+ )
+
+
+@asynccontextmanager
+async def wire_client(provider_id="opencode_zen", handler=None):
+ requests = []
+ catalog_requests = []
+
+ async def generation(request):
+ requests.append(request)
+ if handler is not None:
+ return await handler(request)
+ if not request.headers.get("x-opencode-session"):
+ return httpx2.Response(
+ 400,
+ json={
+ "type": "MissingSessionID",
+ "message": "Missing x-opencode-session",
+ },
+ )
+ return successful_response(request)
+
+ def catalog(request):
+ catalog_requests.append(request)
+ return httpx.Response(
+ 200,
+ json=_catalog_payload(
+ provider_key="opencode-go"
+ if provider_id == "opencode_go"
+ else "opencode"
+ ),
+ )
+
+ def sdk(**kwargs):
+ kwargs["http_client"] = httpx2.AsyncClient(
+ transport=httpx2.MockTransport(generation)
+ )
+ return AsyncOpenAI(**kwargs)
+
+ with patch(
+ "free_claude_code.providers.openai_chat.provider.AsyncOpenAI", side_effect=sdk
+ ):
+ provider = create_opencode_provider(
+ provider_id,
+ make_provider_config(
+ api_key="test_opencode_key",
+ base_url="https://opencode.ai/zen/v1",
+ ),
+ immediate_admission(provider_name=provider_id),
+ catalog_client=httpx.AsyncClient(transport=httpx.MockTransport(catalog)),
+ )
+ app = create_test_app(
+ Settings(
+ model=f"{provider_id}/responses-selector",
+ opencode_api_key="test_opencode_key",
+ proxy_auth_enabled=True,
+ proxy_auth_token="fcc-private-token",
+ ),
+ providers={provider_id: provider},
+ )
+ try:
+ async with httpx.AsyncClient(
+ transport=httpx.ASGITransport(app=app),
+ base_url="http://fcc.test",
+ headers={"Authorization": "Bearer fcc-private-token"},
+ ) as client:
+ yield client, provider, requests, catalog_requests
+ finally:
+ await provider_manager_for_app(app).close()
+
+
+def payload(ingress, provider_id, selector):
+ request = {"model": f"{provider_id}/{selector}", "stream": True}
+ if ingress == "responses":
+ request["input"] = "hello"
+ else:
+ request.update(messages=[{"role": "user", "content": "hello"}], max_tokens=128)
+ return request
+
+
[email protected]("provider_id", ["opencode_zen", "opencode_go"])
[email protected]("selector", ["responses-selector", "chat-selector"])
[email protected]("ingress", ["responses", "messages"])
+async def test_existing_session_id_reaches_opencode_without_forwarding_other_headers(
+ provider_id, selector, ingress
+):
+ async with wire_client(provider_id) as (client, provider, requests, catalogs):
+ defaults = {
+ name: value
+ for name, value in provider._client.default_headers.items()
+ if isinstance(value, str)
+ }
+ for name in ("Session-Id", "X-OpenCode-Session", "X-Session-Id"):
+ for conversation in ("conversation-a", "conversation-a", "conversation-b"):
+ response = await client.post(
+ f"/v1/{ingress}",
+ json=payload(ingress, provider_id, selector),
+ headers=[
+ (name.encode(), conversation.encode()),
+ (b"Cookie", b"private=cookie"),
+ (b"X-Private", b"caf\xe9"),
+ ],
+ )
+ assert response.status_code == 200, response.text
+ upstream = requests[-1]
+ assert upstream.headers["x-opencode-session"] == conversation
+ assert upstream.headers["authorization"] == "Bearer test_opencode_key"
+ assert "cookie" not in upstream.headers
+ assert "x-private" not in upstream.headers
+ assert {
+ name: value
+ for name, value in provider._client.default_headers.items()
+ if isinstance(value, str)
+ } == defaults
+ assert all("x-opencode-session" not in request.headers for request in catalogs)
+
+
[email protected]("selector", ["responses-selector", "chat-selector"])
+async def test_session_header_precedence_and_absence_do_not_invent_or_reuse_identity(
+ selector,
+):
+ async with wire_client() as (client, _provider, requests, _catalogs):
+ request = payload("responses", "opencode_zen", selector)
+ response = await client.post(
+ "/v1/responses",
+ json=request,
+ headers={
+ "x-opencode-session": "explicit-session",
+ "session-id": "native-session",
+ },
+ )
+ assert response.status_code == 200, response.text
+ assert requests[-1].headers["x-opencode-session"] == "explicit-session"
+ response = await client.post(
+ "/v1/responses",
+ json={**request, "prompt_cache_key": "not-a-conversation"},
+ )
+ assert response.status_code == 400
+ assert "MissingSessionID" in response.text
+ assert "x-opencode-session" not in requests[-1].headers
+
+
[email protected]("selector", ["responses-selector", "chat-selector"])
+async def test_concurrent_conversations_keep_their_session_ids_during_retry(selector):
+ first_arrived = asyncio.Event()
+ second_arrived = asyncio.Event()
+ attempts = []
+
+ async def upstream(request):
+ session = request.headers.get("x-opencode-session")
+ attempts.append(session)
+ if session == "conversation-a" and attempts.count(session) == 1:
+ first_arrived.set()
+ await second_arrived.wait()
+ return httpx2.Response(503, json={"error": {"message": "Try again"}})
+ if session == "conversation-b":
+ second_arrived.set()
+ return successful_response(request)
+
+ async with wire_client(handler=upstream) as (
+ client,
+ _provider,
+ requests,
+ _catalogs,
+ ):
+ request = payload("responses", "opencode_zen", selector)
+ async with asyncio.timeout(5):
+ first = asyncio.create_task(
+ client.post(
+ "/v1/responses",
+ json=request,
+ headers={"session-id": "conversation-a"},
+ )
+ )
+ try:
+ await first_arrived.wait()
+ second = await client.post(
+ "/v1/responses",
+ json=request,
+ headers={"session-id": "conversation-b"},
+ )
+ assert second.status_code == 200, second.text
+ result = await first
+ assert result.status_code == 200, result.text
+ finally:
+ first.cancel()
+ await asyncio.gather(first, return_exceptions=True)
+ assert attempts == ["conversation-a", "conversation-b", "conversation-a"]
+ assert len(requests) == 3
diff --git a/tests/api/test_request_lifetime.py b/tests/api/test_request_lifetime.py
index 514cf8ef..67aaa7fc 100644
--- a/tests/api/test_request_lifetime.py
+++ b/tests/api/test_request_lifetime.py
@@ -2,7 +2,7 @@
import asyncio
import json
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from typing import cast
import pytest
@@ -417,6 +417,7 @@ class _ControlledProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, response_model, reasoning
self.request_ids.append(request_id)
@@ -436,6 +437,7 @@ class _ControlledProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, response_model, reasoning
self.request_ids.append(request_id)
diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.py
index 90641c57..2221325d 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -1,6 +1,6 @@
import asyncio
import json
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from typing import Any
from unittest.mock import AsyncMock, MagicMock, patch
@@ -148,6 +148,7 @@ class ScriptedSelectionProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Web-search selection received a Responses request")
yield ""
@@ -160,6 +161,7 @@ class ScriptedSelectionProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.requests.append(request)
self.stream_kwargs.append(
diff --git a/tests/application/test_chat_service.py b/tests/application/test_chat_service.py
index a69778d9..31b0c593 100644
--- a/tests/application/test_chat_service.py
+++ b/tests/application/test_chat_service.py
@@ -1,7 +1,7 @@
import asyncio
import sqlite3
import threading
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from dataclasses import dataclass
from pathlib import Path
@@ -232,6 +232,7 @@ class FakeChatProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, response_model, reasoning
text = "summary" if str(request.system).startswith("Summarize") else "answer"
@@ -305,6 +306,7 @@ class FakeChatProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
raise AssertionError(
(request, input_tokens, request_id, response_model, reasoning)
@@ -341,6 +343,7 @@ class ContextRecoveryProvider(FakeChatProvider):
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
is_summary = str(request.system).startswith("Summarize")
if is_summary:
@@ -401,6 +404,7 @@ class MixedFallbackFailureProvider(ContextRecoveryProvider):
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if self.fail_candidates and not str(request.system).startswith("Summarize"):
if request.model == "model":
@@ -432,6 +436,7 @@ class BackpressuredCompletionProvider(FakeChatProvider):
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del request, input_tokens, request_id, response_model, reasoning
yield format_sse_event(
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index 7f48af8d..4793bf30 100644
--- a/tests/application/test_execution.py
+++ b/tests/application/test_execution.py
@@ -1,7 +1,7 @@
"""Application-owned provider execution contracts."""
import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from unittest.mock import MagicMock, patch
import pytest
@@ -52,6 +52,7 @@ class FakeProvider:
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self._record_stream_call(
request,
@@ -73,6 +74,7 @@ class FakeProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Messages test provider received a Responses request")
yield ""
@@ -127,6 +129,7 @@ class ResponsesFakeProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Responses test provider received a Messages request")
yield ""
@@ -139,6 +142,7 @@ class ResponsesFakeProvider:
request_id: str,
response_model: str,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self.stream_calls.append(
{
@@ -189,6 +193,7 @@ class ControlledProvider(FakeProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self._record_stream_call(
request,
@@ -263,6 +268,7 @@ class FailingStreamConstructionProvider(FakeProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
raise RuntimeError("stream construction failed")
@@ -280,6 +286,7 @@ class ExecutionFailureStreamConstructionProvider(FakeProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
del request, input_tokens, request_id, response_model, reasoning
raise self._failure
@@ -307,6 +314,7 @@ class CloseControlledProvider(FakeProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
self._record_stream_call(
request,
@@ -915,6 +923,7 @@ async def test_candidate_requests_are_isolated_from_provider_mutation() -> None:
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
request.messages[0].content = "mutated"
async for chunk in super().stream_messages(
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 7a817221..6af00ea5 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -1,5 +1,5 @@
import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from types import SimpleNamespace
from typing import Any
from unittest.mock import AsyncMock, patch
@@ -394,6 +394,7 @@ class FakeProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
@@ -406,6 +407,7 @@ class FakeProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/tests/providers/test_preflight_contract.py b/tests/providers/test_preflight_contract.py
index 636d1ed2..17b12da9 100644
--- a/tests/providers/test_preflight_contract.py
+++ b/tests/providers/test_preflight_contract.py
@@ -1,6 +1,6 @@
"""The shared OpenAI-chat provider owns explicit request preflight."""
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
import pytest
@@ -41,6 +41,7 @@ class ProviderWithoutPreflight(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index 51dea90f..554951c3 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -1,6 +1,6 @@
import asyncio
import logging
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
from dataclasses import replace
from pathlib import Path
from unittest.mock import AsyncMock, MagicMock, patch
@@ -97,6 +97,7 @@ class AdminModelProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
@@ -109,6 +110,7 @@ class AdminModelProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ request_headers: Mapping[str, str] | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/uv.lock b/uv.lock
index 60af40fb..e0b5729e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.22.9"
+version = "5.22.10"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },