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

Refactor provider routing and smoke coverage

Alishahryar166ef23072cc8
diff --git a/README.md b/README.md
index 2309e617..70b84164 100644
--- a/README.md
+++ b/README.md
@@ -313,14 +313,14 @@ free-claude-code # starts the server
│ Claude Code │───────>│ Free Claude Code │───────>│ LLM Provider │
│ CLI / VSCode │<───────│ Proxy (:8082) │<───────│ NIM / OR / LMS │
└─────────────────┘ └──────────────────────┘ └──────────────────┘
- Anthropic API OpenAI-compatible
- format (SSE) format (SSE)
+ Anthropic API Native Anthropic
+ format (SSE) or OpenAI chat SSE
```
- **Transparent proxy**: Claude Code sends standard Anthropic API requests; the proxy forwards them to your configured provider
- **Per-model routing**: Opus / Sonnet / Haiku requests resolve to their model-specific backend, with `MODEL` as fallback
- **Request optimization**: 5 categories of trivial requests (quota probes, title generation, prefix detection, suggestions, filepath extraction) are intercepted and responded to locally without using API quota
-- **Format translation**: Requests are translated from Anthropic format to the provider's OpenAI-compatible format and streamed back
+- **Format handling**: OpenRouter, LM Studio, and llama.cpp use native Anthropic Messages endpoints; NIM and DeepSeek use shared OpenAI chat translation
- **Thinking tokens**: `<think>` tags and `reasoning_content` fields are converted into native Claude thinking blocks when `ENABLE_THINKING=true`
The proxy also exposes Claude-compatible probe routes: `GET /v1/models`, `POST /v1/messages`, `POST /v1/messages/count_tokens`, plus `HEAD`/`OPTIONS` support for the common probe endpoints.
@@ -509,6 +509,7 @@ Configure via `WHISPER_DEVICE` (`cpu` | `cuda` | `nvidia_nim`) and `WHISPER_MODE
| `NVIDIA_NIM_API_KEY` | NVIDIA API key | required for NIM |
| `ENABLE_THINKING` | Global switch for provider reasoning requests and Claude thinking blocks. Set `false` to hide thinking across all providers. | `true` |
| `OPENROUTER_API_KEY` | OpenRouter API key | required for OpenRouter |
+| `OPENROUTER_TRANSPORT` | Diagnostic rollback only: `anthropic` uses OpenRouter's native Messages API, `openai` uses chat completions | `anthropic` |
| `DEEPSEEK_API_KEY` | DeepSeek API key | required for DeepSeek |
| `LM_STUDIO_BASE_URL` | LM Studio server URL | `http://localhost:1234/v1` |
| `LLAMACPP_BASE_URL` | llama.cpp server URL | `http://localhost:8080/v1` |
@@ -572,10 +573,10 @@ See [`.env.example`](.env.example) for all supported parameters.
```
free-claude-code/
├── server.py # Entry point
-├── api/ # FastAPI routes, request detection, optimization handlers
-├── providers/ # BaseProvider, OpenAICompatibleProvider, NIM, OpenRouter, DeepSeek, LM Studio, llamacpp
+├── api/ # FastAPI routes, API service layer, model routing, request detection, optimizations
+├── providers/ # Provider registry, scoped runtime state, OpenAI chat + Anthropic messages transports
│ └── common/ # Shared utils (SSE builder, message converter, parsers, error mapping)
-├── messaging/ # MessagingPlatform ABC + Discord/Telegram bots, session management
+├── messaging/ # MessagingPlatform ABC + Discord/Telegram bots, commands, voice, session management
├── config/ # Settings, NIM config, logging
├── cli/ # CLI session and process management
└── tests/ # Pytest test suite
@@ -592,19 +593,21 @@ uv run pytest # Run tests
### Extending
-**Adding an OpenAI-compatible provider** (Groq, Together AI, etc.) — extend `OpenAICompatibleProvider`:
+**Adding an OpenAI-compatible provider** (Groq, Together AI, etc.) — extend `OpenAIChatTransport` or its backward-compatible alias `OpenAICompatibleProvider`, then add a descriptor in the provider registry:
```python
-from providers.openai_compat import OpenAICompatibleProvider
+from providers.openai_compat import OpenAIChatTransport
from providers.base import ProviderConfig
-class MyProvider(OpenAICompatibleProvider):
+class MyProvider(OpenAIChatTransport):
def __init__(self, config: ProviderConfig):
super().__init__(config, provider_name="MYPROVIDER",
base_url="https://api.example.com/v1", api_key=config.api_key)
```
-**Adding a fully custom provider** — extend `BaseProvider` directly and implement `stream_response()`.
+**Adding a native Anthropic provider** — extend `AnthropicMessagesTransport`, then add a descriptor in `providers.registry`.
+
+**Adding a fully custom provider** — extend `BaseProvider` directly, implement `stream_response()`, and register its descriptor.
**Adding a messaging platform** — extend `MessagingPlatform` in `messaging/` and implement `start()`, `stop()`, `send_message()`, `edit_message()`, and `on_message()`.
diff --git a/api/dependencies.py b/api/dependencies.py
index dfd30c7b..bf54cd52 100644
--- a/api/dependencies.py
+++ b/api/dependencies.py
@@ -5,14 +5,10 @@ from loguru import logger
from config.settings import Settings
from config.settings import get_settings as _get_settings
-from providers.base import BaseProvider, ProviderConfig
+from providers.base import BaseProvider
from providers.common import get_user_facing_error_message
-from providers.deepseek import DEEPSEEK_BASE_URL, DeepSeekProvider
from providers.exceptions import AuthenticationError
-from providers.llamacpp import LlamaCppProvider
-from providers.lmstudio import LMStudioProvider
-from providers.nvidia_nim import NVIDIA_NIM_BASE_URL, NvidiaNimProvider
-from providers.open_router import OPENROUTER_BASE_URL, OpenRouterProvider
+from providers.registry import PROVIDER_DESCRIPTORS, ProviderRegistry
# Provider registry: keyed by provider type string, lazily populated
_providers: dict[str, BaseProvider] = {}
@@ -23,132 +19,27 @@ def get_settings() -> Settings:
return _get_settings()
-def _get_proxy_value(settings: Settings, attr_name: str) -> str:
- """Return a provider proxy only when configured as a string."""
- value = getattr(settings, attr_name, "")
- return value if isinstance(value, str) else ""
-
-
-def _create_provider_for_type(provider_type: str, settings: Settings) -> BaseProvider:
- """Construct and return a new provider instance for the given provider type."""
- _proxy_map = {
- "nvidia_nim": _get_proxy_value(settings, "nvidia_nim_proxy"),
- "open_router": _get_proxy_value(settings, "open_router_proxy"),
- "lmstudio": _get_proxy_value(settings, "lmstudio_proxy"),
- "llamacpp": _get_proxy_value(settings, "llamacpp_proxy"),
- }
- proxy = _proxy_map.get(provider_type, "")
-
- if provider_type == "nvidia_nim":
- if not settings.nvidia_nim_api_key or not settings.nvidia_nim_api_key.strip():
- raise AuthenticationError(
- "NVIDIA_NIM_API_KEY is not set. Add it to your .env file. "
- "Get a key at https://build.nvidia.com/settings/api-keys"
- )
- config = ProviderConfig(
- api_key=settings.nvidia_nim_api_key,
- base_url=NVIDIA_NIM_BASE_URL,
- rate_limit=settings.provider_rate_limit,
- rate_window=settings.provider_rate_window,
- max_concurrency=settings.provider_max_concurrency,
- http_read_timeout=settings.http_read_timeout,
- http_write_timeout=settings.http_write_timeout,
- http_connect_timeout=settings.http_connect_timeout,
- enable_thinking=settings.enable_thinking,
- proxy=proxy,
- )
- return NvidiaNimProvider(config, nim_settings=settings.nim)
- if provider_type == "open_router":
- if not settings.open_router_api_key or not settings.open_router_api_key.strip():
- raise AuthenticationError(
- "OPENROUTER_API_KEY is not set. Add it to your .env file. "
- "Get a key at https://openrouter.ai/keys"
- )
- config = ProviderConfig(
- api_key=settings.open_router_api_key,
- base_url=OPENROUTER_BASE_URL,
- rate_limit=settings.provider_rate_limit,
- rate_window=settings.provider_rate_window,
- max_concurrency=settings.provider_max_concurrency,
- http_read_timeout=settings.http_read_timeout,
- http_write_timeout=settings.http_write_timeout,
- http_connect_timeout=settings.http_connect_timeout,
- enable_thinking=settings.enable_thinking,
- proxy=proxy,
- )
- return OpenRouterProvider(config)
- if provider_type == "deepseek":
- if not settings.deepseek_api_key or not settings.deepseek_api_key.strip():
- raise AuthenticationError(
- "DEEPSEEK_API_KEY is not set. Add it to your .env file. "
- "Get a key at https://platform.deepseek.com/api_keys"
- )
- config = ProviderConfig(
- api_key=settings.deepseek_api_key,
- base_url=DEEPSEEK_BASE_URL,
- rate_limit=settings.provider_rate_limit,
- rate_window=settings.provider_rate_window,
- max_concurrency=settings.provider_max_concurrency,
- http_read_timeout=settings.http_read_timeout,
- http_write_timeout=settings.http_write_timeout,
- http_connect_timeout=settings.http_connect_timeout,
- enable_thinking=settings.enable_thinking,
- )
- return DeepSeekProvider(config)
- if provider_type == "lmstudio":
- config = ProviderConfig(
- api_key="lm-studio",
- base_url=settings.lm_studio_base_url,
- rate_limit=settings.provider_rate_limit,
- rate_window=settings.provider_rate_window,
- max_concurrency=settings.provider_max_concurrency,
- http_read_timeout=settings.http_read_timeout,
- http_write_timeout=settings.http_write_timeout,
- http_connect_timeout=settings.http_connect_timeout,
- enable_thinking=settings.enable_thinking,
- proxy=proxy,
- )
- return LMStudioProvider(config)
- if provider_type == "llamacpp":
- config = ProviderConfig(
- api_key="llamacpp",
- base_url=settings.llamacpp_base_url,
- rate_limit=settings.provider_rate_limit,
- rate_window=settings.provider_rate_window,
- max_concurrency=settings.provider_max_concurrency,
- http_read_timeout=settings.http_read_timeout,
- http_write_timeout=settings.http_write_timeout,
- http_connect_timeout=settings.http_connect_timeout,
- enable_thinking=settings.enable_thinking,
- proxy=proxy,
- )
- return LlamaCppProvider(config)
- logger.error(
- "Unknown provider_type: '{}'. Supported: 'nvidia_nim', 'open_router', 'deepseek', 'lmstudio', 'llamacpp'",
- provider_type,
- )
- raise ValueError(
- f"Unknown provider_type: '{provider_type}'. "
- f"Supported: 'nvidia_nim', 'open_router', 'deepseek', 'lmstudio', 'llamacpp'"
- )
-
-
def get_provider_for_type(provider_type: str) -> BaseProvider:
"""Get or create a provider for the given provider type.
Providers are cached in the registry and reused across requests.
"""
- if provider_type not in _providers:
- try:
- _providers[provider_type] = _create_provider_for_type(
- provider_type, get_settings()
- )
- except AuthenticationError as e:
- raise HTTPException(
- status_code=503, detail=get_user_facing_error_message(e)
- ) from e
+ try:
+ provider = ProviderRegistry(_providers).get(provider_type, get_settings())
+ except AuthenticationError as e:
+ raise HTTPException(
+ status_code=503, detail=get_user_facing_error_message(e)
+ ) from e
+ except ValueError:
+ logger.error(
+ "Unknown provider_type: '{}'. Supported: {}",
+ provider_type,
+ ", ".join(f"'{key}'" for key in PROVIDER_DESCRIPTORS),
+ )
+ raise
+ if provider_type in _providers:
logger.info("Provider initialized: {}", provider_type)
- return _providers[provider_type]
+ return provider
def require_api_key(
@@ -196,7 +87,6 @@ def get_provider() -> BaseProvider:
async def cleanup_provider():
"""Cleanup all provider resources."""
global _providers
- for provider in _providers.values():
- await provider.cleanup()
+ await ProviderRegistry(_providers).cleanup()
_providers = {}
logger.debug("Provider cleanup completed")
diff --git a/api/model_router.py b/api/model_router.py
new file mode 100644
index 00000000..8e755e1c
--- /dev/null
+++ b/api/model_router.py
@@ -0,0 +1,58 @@
+"""Model routing for Claude-compatible requests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from loguru import logger
+
+from config.settings import Settings
+
+from .models.anthropic import MessagesRequest, TokenCountRequest
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedModel:
+ original_model: str
+ provider_id: str
+ provider_model: str
+ provider_model_ref: str
+
+
+class ModelRouter:
+ """Resolve incoming Claude model names to configured provider/model pairs."""
+
+ def __init__(self, settings: Settings):
+ self._settings = settings
+
+ def resolve(self, claude_model_name: str) -> ResolvedModel:
+ provider_model_ref = self._settings.resolve_model(claude_model_name)
+ provider_id = Settings.parse_provider_type(provider_model_ref)
+ provider_model = Settings.parse_model_name(provider_model_ref)
+ if provider_model != claude_model_name:
+ logger.debug(
+ "MODEL MAPPING: '{}' -> '{}'", claude_model_name, provider_model
+ )
+ return ResolvedModel(
+ original_model=claude_model_name,
+ provider_id=provider_id,
+ provider_model=provider_model,
+ provider_model_ref=provider_model_ref,
+ )
+
+ def resolve_messages_request(self, request: MessagesRequest) -> MessagesRequest:
+ """Return a routed copy of a MessagesRequest."""
+ original_model = request.original_model or request.model
+ resolved = self.resolve(original_model)
+ routed = request.model_copy(deep=True)
+ routed.original_model = resolved.original_model
+ routed.resolved_provider_model = resolved.provider_model_ref
+ routed.model = resolved.provider_model
+ return routed
+
+ def resolve_token_count_request(
+ self, request: TokenCountRequest
+ ) -> TokenCountRequest:
+ """Return a token-count request copy with provider model name applied."""
+ resolved = self.resolve(request.model)
+ return request.model_copy(update={"model": resolved.provider_model}, deep=True)
diff --git a/api/models/__init__.py b/api/models/__init__.py
index e9a90e03..f54a732c 100644
--- a/api/models/__init__.py
+++ b/api/models/__init__.py
@@ -2,6 +2,7 @@
from .anthropic import (
ContentBlockImage,
+ ContentBlockRedactedThinking,
ContentBlockText,
ContentBlockThinking,
ContentBlockToolResult,
@@ -24,6 +25,7 @@ from .responses import (
__all__ = [
"ContentBlockImage",
+ "ContentBlockRedactedThinking",
"ContentBlockText",
"ContentBlockThinking",
"ContentBlockToolResult",
diff --git a/api/models/anthropic.py b/api/models/anthropic.py
index c03cd359..9758295d 100644
--- a/api/models/anthropic.py
+++ b/api/models/anthropic.py
@@ -3,10 +3,7 @@
from enum import StrEnum
from typing import Any, Literal
-from loguru import logger
-from pydantic import BaseModel, field_validator, model_validator
-
-from config.settings import Settings, get_settings
+from pydantic import BaseModel
# =============================================================================
@@ -44,6 +41,12 @@ class ContentBlockToolResult(BaseModel):
class ContentBlockThinking(BaseModel):
type: Literal["thinking"]
thinking: str
+ signature: str | None = None
+
+
+class ContentBlockRedactedThinking(BaseModel):
+ type: Literal["redacted_thinking"]
+ data: str
class SystemContent(BaseModel):
@@ -64,6 +67,7 @@ class Message(BaseModel):
| ContentBlockToolUse
| ContentBlockToolResult
| ContentBlockThinking
+ | ContentBlockRedactedThinking
]
)
reasoning_content: str | None = None
@@ -76,7 +80,9 @@ class Tool(BaseModel):
class ThinkingConfig(BaseModel):
- enabled: bool = True
+ enabled: bool | None = True
+ type: str | None = None
+ budget_tokens: int | None = None
# =============================================================================
@@ -100,22 +106,6 @@ class MessagesRequest(BaseModel):
original_model: str | None = None
resolved_provider_model: str | None = None
- @model_validator(mode="after")
- def map_model(self) -> MessagesRequest:
- """Map any Claude model name to the configured model (model-aware)."""
- settings = get_settings()
- if self.original_model is None:
- self.original_model = self.model
-
- resolved_full = settings.resolve_model(self.original_model)
- self.resolved_provider_model = resolved_full
- self.model = Settings.parse_model_name(resolved_full)
-
- if self.model != self.original_model:
- logger.debug(f"MODEL MAPPING: '{self.original_model}' -> '{self.model}'")
-
- return self
-
class TokenCountRequest(BaseModel):
model: str
@@ -124,11 +114,3 @@ class TokenCountRequest(BaseModel):
tools: list[Tool] | None = None
thinking: ThinkingConfig | None = None
tool_choice: dict[str, Any] | None = None
-
- @field_validator("model")
- @classmethod
- def validate_model_field(cls, v: str, info) -> str:
- """Map any Claude model name to the configured model (model-aware)."""
- settings = get_settings()
- resolved_full = settings.resolve_model(v)
- return Settings.parse_model_name(resolved_full)
diff --git a/api/models/responses.py b/api/models/responses.py
index 8a238aea..8050516d 100644
--- a/api/models/responses.py
+++ b/api/models/responses.py
@@ -4,7 +4,12 @@ from typing import Any, Literal
from pydantic import BaseModel
-from .anthropic import ContentBlockText, ContentBlockThinking, ContentBlockToolUse
+from .anthropic import (
+ ContentBlockRedactedThinking,
+ ContentBlockText,
+ ContentBlockThinking,
+ ContentBlockToolUse,
+)
class TokenCountResponse(BaseModel):
@@ -37,7 +42,11 @@ class MessagesResponse(BaseModel):
model: str
role: Literal["assistant"] = "assistant"
content: list[
- ContentBlockText | ContentBlockToolUse | ContentBlockThinking | dict[str, Any]
+ ContentBlockText
+ | ContentBlockToolUse
+ | ContentBlockThinking
+ | ContentBlockRedactedThinking
+ | dict[str, Any]
]
type: Literal["message"] = "message"
stop_reason: (
diff --git a/api/routes.py b/api/routes.py
index 2efdb944..1a85259a 100644
--- a/api/routes.py
+++ b/api/routes.py
@@ -1,21 +1,15 @@
"""FastAPI route handlers."""
-import traceback
-import uuid
-
from fastapi import APIRouter, Depends, HTTPException, Request, Response
-from fastapi.responses import StreamingResponse
from loguru import logger
from config.settings import Settings
-from providers.common import get_user_facing_error_message
-from providers.exceptions import InvalidRequestError, ProviderError
from .dependencies import get_provider_for_type, get_settings, require_api_key
from .models.anthropic import MessagesRequest, TokenCountRequest
-from .models.responses import ModelResponse, ModelsListResponse, TokenCountResponse
-from .optimization_handlers import try_optimizations
+from .models.responses import ModelResponse, ModelsListResponse
from .request_utils import get_token_count
+from .services import ClaudeProxyService
router = APIRouter()
@@ -59,6 +53,17 @@ SUPPORTED_CLAUDE_MODELS = [
]
+def get_proxy_service(
+ settings: Settings = Depends(get_settings),
+) -> ClaudeProxyService:
+ """Build the request service for route handlers."""
+ return ClaudeProxyService(
+ settings,
+ provider_getter=get_provider_for_type,
+ token_counter=get_token_count,
+ )
+
+
def _probe_response(allow: str) -> Response:
"""Return an empty success response for compatibility probes."""
return Response(status_code=204, headers={"Allow": allow})
@@ -70,61 +75,12 @@ def _probe_response(allow: str) -> Response:
@router.post("/v1/messages")
async def create_message(
request_data: MessagesRequest,
- raw_request: Request,
- settings: Settings = Depends(get_settings),
+ _raw_request: Request,
+ service: ClaudeProxyService = Depends(get_proxy_service),
_auth=Depends(require_api_key),
):
"""Create a message (always streaming)."""
-
- try:
- if not request_data.messages:
- raise InvalidRequestError("messages cannot be empty")
-
- optimized = try_optimizations(request_data, settings)
- if optimized is not None:
- return optimized
- logger.debug("No optimization matched, routing to provider")
-
- # Resolve provider from the model-aware mapping
- provider_type = Settings.parse_provider_type(
- request_data.resolved_provider_model or settings.model
- )
- provider = get_provider_for_type(provider_type)
-
- request_id = f"req_{uuid.uuid4().hex[:12]}"
- logger.info(
- "API_REQUEST: request_id={} model={} messages={}",
- request_id,
- request_data.model,
- len(request_data.messages),
- )
- logger.debug("FULL_PAYLOAD [{}]: {}", request_id, request_data.model_dump())
-
- input_tokens = get_token_count(
- request_data.messages, request_data.system, request_data.tools
- )
- return StreamingResponse(
- provider.stream_response(
- request_data,
- input_tokens=input_tokens,
- request_id=request_id,
- ),
- media_type="text/event-stream",
- headers={
- "X-Accel-Buffering": "no",
- "Cache-Control": "no-cache",
- "Connection": "keep-alive",
- },
- )
-
- except ProviderError:
- raise
- except Exception as e:
- logger.error(f"Error: {e!s}\n{traceback.format_exc()}")
- raise HTTPException(
- status_code=getattr(e, "status_code", 500),
- detail=get_user_facing_error_message(e),
- ) from e
+ return service.create_message(request_data)
@router.api_route("/v1/messages", methods=["HEAD", "OPTIONS"])
@@ -134,32 +90,13 @@ async def probe_messages(_auth=Depends(require_api_key)):
@router.post("/v1/messages/count_tokens")
-async def count_tokens(request_data: TokenCountRequest, _auth=Depends(require_api_key)):
+async def count_tokens(
+ request_data: TokenCountRequest,
+ service: ClaudeProxyService = Depends(get_proxy_service),
+ _auth=Depends(require_api_key),
+):
"""Count tokens for a request."""
- request_id = f"req_{uuid.uuid4().hex[:12]}"
- with logger.contextualize(request_id=request_id):
- try:
- tokens = get_token_count(
- request_data.messages, request_data.system, request_data.tools
- )
- logger.info(
- "COUNT_TOKENS: request_id={} model={} messages={} input_tokens={}",
- request_id,
- getattr(request_data, "model", "unknown"),
- len(request_data.messages),
- tokens,
- )
- return TokenCountResponse(input_tokens=tokens)
- except Exception as e:
- logger.error(
- "COUNT_TOKENS_ERROR: request_id={} error={}\n{}",
- request_id,
- get_user_facing_error_message(e),
- traceback.format_exc(),
- )
- raise HTTPException(
- status_code=500, detail=get_user_facing_error_message(e)
- ) from e
+ return service.count_tokens(request_data)
@router.api_route("/v1/messages/count_tokens", methods=["HEAD", "OPTIONS"])
diff --git a/api/services.py b/api/services.py
new file mode 100644
index 00000000..61385772
--- /dev/null
+++ b/api/services.py
@@ -0,0 +1,128 @@
+"""Application services for the Claude-compatible API."""
+
+from __future__ import annotations
+
+import traceback
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import HTTPException
+from fastapi.responses import StreamingResponse
+from loguru import logger
+
+from config.settings import Settings
+from providers.base import BaseProvider
+from providers.common import get_user_facing_error_message
+from providers.exceptions import InvalidRequestError, ProviderError
+
+from .model_router import ModelRouter
+from .models.anthropic import MessagesRequest, TokenCountRequest
+from .models.responses import TokenCountResponse
+from .optimization_handlers import try_optimizations
+from .request_utils import get_token_count
+
+TokenCounter = Callable[[list[Any], str | list[Any] | None, list[Any] | None], int]
+
+ProviderGetter = Callable[[str], BaseProvider]
+
+
+class ClaudeProxyService:
+ """Coordinate request optimization, model routing, token count, and providers."""
+
+ def __init__(
+ self,
+ settings: Settings,
+ provider_getter: ProviderGetter,
+ model_router: ModelRouter | None = None,
+ token_counter: TokenCounter = get_token_count,
+ ):
+ self._settings = settings
+ self._provider_getter = provider_getter
+ self._model_router = model_router or ModelRouter(settings)
+ self._token_counter = token_counter
+
+ def create_message(self, request_data: MessagesRequest) -> object:
+ """Create a message response or streaming response."""
+ try:
+ if not request_data.messages:
+ raise InvalidRequestError("messages cannot be empty")
+
+ routed_request = self._model_router.resolve_messages_request(request_data)
+
+ optimized = try_optimizations(routed_request, self._settings)
+ if optimized is not None:
+ return optimized
+ logger.debug("No optimization matched, routing to provider")
+
+ provider_type = (
+ routed_request.resolved_provider_model or self._settings.model
+ ).split("/", 1)[0]
+ provider = self._provider_getter(provider_type)
+
+ request_id = f"req_{uuid.uuid4().hex[:12]}"
+ logger.info(
+ "API_REQUEST: request_id={} model={} messages={}",
+ request_id,
+ routed_request.model,
+ len(routed_request.messages),
+ )
+ logger.debug(
+ "FULL_PAYLOAD [{}]: {}", request_id, routed_request.model_dump()
+ )
+
+ input_tokens = self._token_counter(
+ routed_request.messages, routed_request.system, routed_request.tools
+ )
+ return StreamingResponse(
+ provider.stream_response(
+ routed_request,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ ),
+ media_type="text/event-stream",
+ headers={
+ "X-Accel-Buffering": "no",
+ "Cache-Control": "no-cache",
+ "Connection": "keep-alive",
+ },
+ )
+
+ except ProviderError:
+ raise
+ except Exception as e:
+ logger.error(f"Error: {e!s}\n{traceback.format_exc()}")
+ raise HTTPException(
+ status_code=getattr(e, "status_code", 500),
+ detail=get_user_facing_error_message(e),
+ ) from e
+
+ def count_tokens(self, request_data: TokenCountRequest) -> TokenCountResponse:
+ """Count tokens for a request after applying configured model routing."""
+ request_id = f"req_{uuid.uuid4().hex[:12]}"
+ with logger.contextualize(request_id=request_id):
+ try:
+ routed_request = self._model_router.resolve_token_count_request(
+ request_data
+ )
+ tokens = self._token_counter(
+ routed_request.messages, routed_request.system, routed_request.tools
+ )
+ logger.info(
+ "COUNT_TOKENS: request_id={} model={} messages={} input_tokens={}",
+ request_id,
+ routed_request.model,
+ len(routed_request.messages),
+ tokens,
+ )
+ return TokenCountResponse(input_tokens=tokens)
+ except Exception as e:
+ logger.error(
+ "COUNT_TOKENS_ERROR: request_id={} error={}\n{}",
+ request_id,
+ get_user_facing_error_message(e),
+ traceback.format_exc(),
+ )
+ raise HTTPException(
+ status_code=500, detail=get_user_facing_error_message(e)
+ ) from e
diff --git a/config/env.example b/config/env.example
index 6b0faa5c..37d64f5b 100644
--- a/config/env.example
+++ b/config/env.example
@@ -4,6 +4,8 @@ NVIDIA_NIM_API_KEY=""
# OpenRouter Config
OPENROUTER_API_KEY=""
+# Diagnostic rollback only: "anthropic" (native /messages, default) | "openai" (chat completions)
+OPENROUTER_TRANSPORT="anthropic"
# DeepSeek Config
diff --git a/config/settings.py b/config/settings.py
index 59c69b0f..b346f41b 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -91,6 +91,9 @@ class Settings(BaseSettings):
# ==================== OpenRouter Config ====================
open_router_api_key: str = Field(default="", validation_alias="OPENROUTER_API_KEY")
+ openrouter_transport: str = Field(
+ default="anthropic", validation_alias="OPENROUTER_TRANSPORT"
+ )
# ==================== DeepSeek Config ====================
deepseek_api_key: str = Field(default="", validation_alias="DEEPSEEK_API_KEY")
@@ -237,6 +240,15 @@ class Settings(BaseSettings):
)
return v
+ @field_validator("openrouter_transport")
+ @classmethod
+ def validate_openrouter_transport(cls, v: str) -> str:
+ if v not in ("anthropic", "openai"):
+ raise ValueError(
+ f"openrouter_transport must be 'anthropic' or 'openai', got {v!r}"
+ )
+ return v
+
@field_validator("model", "model_opus", "model_sonnet", "model_haiku")
@classmethod
def validate_model_format(cls, v: str | None) -> str | None:
diff --git a/messaging/handler.py b/messaging/handler.py
index 7eae77ee..be617a89 100644
--- a/messaging/handler.py
+++ b/messaging/handler.py
@@ -22,26 +22,7 @@ from .commands import (
from .event_parser import parse_cli_event
from .models import IncomingMessage
from .platforms.base import MessagingPlatform, SessionManagerInterface
-from .rendering.discord_markdown import (
- discord_bold,
- discord_code_inline,
- escape_discord,
- escape_discord_code,
- render_markdown_to_discord,
-)
-from .rendering.discord_markdown import (
- format_status as format_status_discord, # (emoji, label, suffix)
-)
-from .rendering.telegram_markdown import (
- escape_md_v2,
- escape_md_v2_code,
- mdv2_bold,
- mdv2_code_inline,
- render_markdown_to_mdv2,
-)
-from .rendering.telegram_markdown import (
- format_status as format_status_telegram,
-)
+from .rendering.profiles import build_rendering_profile
from .session import SessionStore
from .transcript import RenderCtx, TranscriptBuffer
from .trees.queue_manager import (
@@ -124,33 +105,19 @@ class ClaudeMessageHandler:
queue_update_callback=self.update_queue_positions,
node_started_callback=self.mark_node_processing,
)
- is_discord = platform.name == "discord"
- self._format_status_fn = (
- format_status_discord if is_discord else format_status_telegram
- )
- self._parse_mode_val: str | None = None if is_discord else "MarkdownV2"
- self._render_ctx_val = RenderCtx(
- bold=discord_bold if is_discord else mdv2_bold,
- code_inline=discord_code_inline if is_discord else mdv2_code_inline,
- escape_code=escape_discord_code if is_discord else escape_md_v2_code,
- escape_text=escape_discord if is_discord else escape_md_v2,
- render_markdown=render_markdown_to_discord
- if is_discord
- else render_markdown_to_mdv2,
- )
- self._limit_chars = 1900 if is_discord else 3900
+ self._rendering_profile = build_rendering_profile(platform.name)
def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
- return self._format_status_fn(emoji, label, suffix)
+ return self._rendering_profile.format_status(emoji, label, suffix)
def _parse_mode(self) -> str | None:
- return self._parse_mode_val
+ return self._rendering_profile.parse_mode
def get_render_ctx(self) -> RenderCtx:
- return self._render_ctx_val
+ return self._rendering_profile.render_ctx
def _get_limit_chars(self) -> int:
- return self._limit_chars
+ return self._rendering_profile.limit_chars
@property
def tree_queue(self) -> TreeQueueManager:
diff --git a/messaging/platforms/discord.py b/messaging/platforms/discord.py
index b0bbd1da..97661c93 100644
--- a/messaging/platforms/discord.py
+++ b/messaging/platforms/discord.py
@@ -18,6 +18,7 @@ from providers.common import get_user_facing_error_message
from ..models import IncomingMessage
from ..rendering.discord_markdown import format_status_discord
+from ..voice import PendingVoiceRegistry, VoiceTranscriptionService
from .base import MessagingPlatform
AUDIO_EXTENSIONS = (".ogg", ".mp4", ".mp3", ".wav", ".m4a")
@@ -115,8 +116,8 @@ class DiscordPlatform(MessagingPlatform):
self._connected = False
self._limiter: Any | None = None
self._start_task: asyncio.Task | None = None
- self._pending_voice: dict[tuple[str, str], tuple[str, str]] = {}
- self._pending_voice_lock = asyncio.Lock()
+ self._pending_voice = PendingVoiceRegistry()
+ self._voice_transcription = VoiceTranscriptionService()
async def _handle_client_message(self, message: Any) -> None:
"""Adapter entry point used by the internal discord client."""
@@ -126,30 +127,17 @@ class DiscordPlatform(MessagingPlatform):
self, chat_id: str, voice_msg_id: str, status_msg_id: str
) -> None:
"""Register a voice note as pending transcription."""
- async with self._pending_voice_lock:
- self._pending_voice[(chat_id, voice_msg_id)] = (voice_msg_id, status_msg_id)
- self._pending_voice[(chat_id, status_msg_id)] = (
- voice_msg_id,
- status_msg_id,
- )
+ await self._pending_voice.register(chat_id, voice_msg_id, status_msg_id)
async def cancel_pending_voice(
self, chat_id: str, reply_id: str
) -> tuple[str, str] | None:
"""Cancel a pending voice transcription. Returns (voice_msg_id, status_msg_id) if found."""
- async with self._pending_voice_lock:
- entry = self._pending_voice.pop((chat_id, reply_id), None)
- if entry is None:
- return None
- voice_msg_id, status_msg_id = entry
- self._pending_voice.pop((chat_id, voice_msg_id), None)
- self._pending_voice.pop((chat_id, status_msg_id), None)
- return (voice_msg_id, status_msg_id)
+ return await self._pending_voice.cancel(chat_id, reply_id)
async def _is_voice_still_pending(self, chat_id: str, voice_msg_id: str) -> bool:
"""Check if a voice note is still pending (not cancelled)."""
- async with self._pending_voice_lock:
- return (chat_id, voice_msg_id) in self._pending_voice
+ return await self._pending_voice.is_pending(chat_id, voice_msg_id)
def _get_audio_attachment(self, message: Any) -> Any | None:
"""Return first audio attachment, or None."""
@@ -210,10 +198,7 @@ class DiscordPlatform(MessagingPlatform):
try:
await attachment.save(str(tmp_path))
- from ..transcription import transcribe_audio
-
- transcribed = await asyncio.to_thread(
- transcribe_audio,
+ transcribed = await self._voice_transcription.transcribe(
tmp_path,
ct,
whisper_model=settings.whisper_model,
@@ -224,9 +209,9 @@ class DiscordPlatform(MessagingPlatform):
await self.queue_delete_message(channel_id, str(status_msg_id))
return True
- async with self._pending_voice_lock:
- self._pending_voice.pop((channel_id, message_id), None)
- self._pending_voice.pop((channel_id, str(status_msg_id)), None)
+ await self._pending_voice.complete(
+ channel_id, message_id, str(status_msg_id)
+ )
incoming = IncomingMessage(
text=transcribed,
diff --git a/messaging/platforms/telegram.py b/messaging/platforms/telegram.py
index e38ab1e5..9eadc4ce 100644
--- a/messaging/platforms/telegram.py
+++ b/messaging/platforms/telegram.py
@@ -27,6 +27,7 @@ if TYPE_CHECKING:
from ..models import IncomingMessage
from ..rendering.telegram_markdown import escape_md_v2, format_status
+from ..voice import PendingVoiceRegistry, VoiceTranscriptionService
from .base import MessagingPlatform
# Optional import - python-telegram-bot may not be installed
@@ -82,37 +83,24 @@ class TelegramPlatform(MessagingPlatform):
self._connected = False
self._limiter: Any | None = None # Will be MessagingRateLimiter
# Pending voice transcriptions: (chat_id, msg_id) -> (voice_msg_id, status_msg_id)
- self._pending_voice: dict[tuple[str, str], tuple[str, str]] = {}
- self._pending_voice_lock = asyncio.Lock()
+ self._pending_voice = PendingVoiceRegistry()
+ self._voice_transcription = VoiceTranscriptionService()
async def _register_pending_voice(
self, chat_id: str, voice_msg_id: str, status_msg_id: str
) -> None:
"""Register a voice note as pending transcription (for /clear reply during transcription)."""
- async with self._pending_voice_lock:
- self._pending_voice[(chat_id, voice_msg_id)] = (voice_msg_id, status_msg_id)
- self._pending_voice[(chat_id, status_msg_id)] = (
- voice_msg_id,
- status_msg_id,
- )
+ await self._pending_voice.register(chat_id, voice_msg_id, status_msg_id)
async def cancel_pending_voice(
self, chat_id: str, reply_id: str
) -> tuple[str, str] | None:
"""Cancel a pending voice transcription. Returns (voice_msg_id, status_msg_id) if found."""
- async with self._pending_voice_lock:
- entry = self._pending_voice.pop((chat_id, reply_id), None)
- if entry is None:
- return None
- voice_msg_id, status_msg_id = entry
- self._pending_voice.pop((chat_id, voice_msg_id), None)
- self._pending_voice.pop((chat_id, status_msg_id), None)
- return (voice_msg_id, status_msg_id)
+ return await self._pending_voice.cancel(chat_id, reply_id)
async def _is_voice_still_pending(self, chat_id: str, voice_msg_id: str) -> bool:
"""Check if a voice note is still pending (not cancelled)."""
- async with self._pending_voice_lock:
- return (chat_id, voice_msg_id) in self._pending_voice
+ return await self._pending_voice.is_pending(chat_id, voice_msg_id)
async def start(self) -> None:
"""Initialize and connect to Telegram."""
@@ -609,10 +597,7 @@ class TelegramPlatform(MessagingPlatform):
tg_file = await context.bot.get_file(voice.file_id)
await tg_file.download_to_drive(custom_path=str(tmp_path))
- from ..transcription import transcribe_audio
-
- transcribed = await asyncio.to_thread(
- transcribe_audio,
+ transcribed = await self._voice_transcription.transcribe(
tmp_path,
voice.mime_type or "audio/ogg",
whisper_model=settings.whisper_model,
@@ -623,9 +608,7 @@ class TelegramPlatform(MessagingPlatform):
await self.queue_delete_message(chat_id, str(status_msg_id))
return
- async with self._pending_voice_lock:
- self._pending_voice.pop((chat_id, message_id), None)
- self._pending_voice.pop((chat_id, str(status_msg_id)), None)
+ await self._pending_voice.complete(chat_id, message_id, str(status_msg_id))
incoming = IncomingMessage(
text=transcribed,
diff --git a/messaging/rendering/profiles.py b/messaging/rendering/profiles.py
new file mode 100644
index 00000000..53b9ef10
--- /dev/null
+++ b/messaging/rendering/profiles.py
@@ -0,0 +1,55 @@
+"""Platform rendering profiles for messaging transcripts and status text."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from messaging.rendering.discord_markdown import (
+ discord_bold,
+ discord_code_inline,
+ escape_discord,
+ escape_discord_code,
+ render_markdown_to_discord,
+)
+from messaging.rendering.discord_markdown import (
+ format_status as format_status_discord,
+)
+from messaging.rendering.telegram_markdown import (
+ escape_md_v2,
+ escape_md_v2_code,
+ mdv2_bold,
+ mdv2_code_inline,
+ render_markdown_to_mdv2,
+)
+from messaging.rendering.telegram_markdown import (
+ format_status as format_status_telegram,
+)
+from messaging.transcript import RenderCtx
+
+
+@dataclass(frozen=True, slots=True)
+class RenderingProfile:
+ format_status: Callable[[str, str, str | None], str]
+ parse_mode: str | None
+ render_ctx: RenderCtx
+ limit_chars: int
+
+
+def build_rendering_profile(platform_name: str) -> RenderingProfile:
+ """Return rendering rules for a messaging platform."""
+ is_discord = platform_name == "discord"
+ return RenderingProfile(
+ format_status=format_status_discord if is_discord else format_status_telegram,
+ parse_mode=None if is_discord else "MarkdownV2",
+ render_ctx=RenderCtx(
+ bold=discord_bold if is_discord else mdv2_bold,
+ code_inline=discord_code_inline if is_discord else mdv2_code_inline,
+ escape_code=escape_discord_code if is_discord else escape_md_v2_code,
+ escape_text=escape_discord if is_discord else escape_md_v2,
+ render_markdown=render_markdown_to_discord
+ if is_discord
+ else render_markdown_to_mdv2,
+ ),
+ limit_chars=1900 if is_discord else 3900,
+ )
diff --git a/messaging/voice.py b/messaging/voice.py
new file mode 100644
index 00000000..821176b4
--- /dev/null
+++ b/messaging/voice.py
@@ -0,0 +1,65 @@
+"""Platform-neutral voice note helpers."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+
+class PendingVoiceRegistry:
+ """Track voice notes that are still waiting on transcription."""
+
+ def __init__(self) -> None:
+ self._pending: dict[tuple[str, str], tuple[str, str]] = {}
+ self._lock = asyncio.Lock()
+
+ async def register(
+ self, chat_id: str, voice_msg_id: str, status_msg_id: str
+ ) -> None:
+ async with self._lock:
+ entry = (voice_msg_id, status_msg_id)
+ self._pending[(chat_id, voice_msg_id)] = entry
+ self._pending[(chat_id, status_msg_id)] = entry
+
+ async def cancel(self, chat_id: str, reply_id: str) -> tuple[str, str] | None:
+ async with self._lock:
+ entry = self._pending.pop((chat_id, reply_id), None)
+ if entry is None:
+ return None
+ voice_msg_id, status_msg_id = entry
+ self._pending.pop((chat_id, voice_msg_id), None)
+ self._pending.pop((chat_id, status_msg_id), None)
+ return entry
+
+ async def is_pending(self, chat_id: str, voice_msg_id: str) -> bool:
+ async with self._lock:
+ return (chat_id, voice_msg_id) in self._pending
+
+ async def complete(
+ self, chat_id: str, voice_msg_id: str, status_msg_id: str
+ ) -> None:
+ async with self._lock:
+ self._pending.pop((chat_id, voice_msg_id), None)
+ self._pending.pop((chat_id, status_msg_id), None)
+
+
+class VoiceTranscriptionService:
+ """Run configured transcription backends off the event loop."""
+
+ async def transcribe(
+ self,
+ file_path: Path,
+ mime_type: str,
+ *,
+ whisper_model: str,
+ whisper_device: str,
+ ) -> str:
+ from .transcription import transcribe_audio
+
+ return await asyncio.to_thread(
+ transcribe_audio,
+ file_path,
+ mime_type,
+ whisper_model=whisper_model,
+ whisper_device=whisper_device,
+ )
diff --git a/providers/__init__.py b/providers/__init__.py
index c9206235..bb1c70c6 100644
--- a/providers/__init__.py
+++ b/providers/__init__.py
@@ -1,5 +1,6 @@
"""Providers package - implement your own provider by extending BaseProvider."""
+from .anthropic_messages import AnthropicMessagesTransport
from .base import BaseProvider, ProviderConfig
from .deepseek import DeepSeekProvider
from .exceptions import (
@@ -13,10 +14,12 @@ from .exceptions import (
from .llamacpp import LlamaCppProvider
from .lmstudio import LMStudioProvider
from .nvidia_nim import NvidiaNimProvider
-from .open_router import OpenRouterProvider
+from .open_router import OpenRouterChatProvider, OpenRouterProvider
+from .openai_compat import OpenAIChatTransport, OpenAICompatibleProvider
__all__ = [
"APIError",
+ "AnthropicMessagesTransport",
"AuthenticationError",
"BaseProvider",
"DeepSeekProvider",
@@ -24,6 +27,9 @@ __all__ = [
"LMStudioProvider",
"LlamaCppProvider",
"NvidiaNimProvider",
+ "OpenAIChatTransport",
+ "OpenAICompatibleProvider",
+ "OpenRouterChatProvider",
"OpenRouterProvider",
"OverloadedError",
"ProviderConfig",
diff --git a/providers/anthropic_messages.py b/providers/anthropic_messages.py
new file mode 100644
index 00000000..acb0db59
--- /dev/null
+++ b/providers/anthropic_messages.py
@@ -0,0 +1,282 @@
+"""Shared transport for providers with native Anthropic Messages endpoints."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Literal
+
+import httpx
+from loguru import logger
+
+from providers.base import BaseProvider, ProviderConfig
+from providers.common import get_user_facing_error_message, map_error
+from providers.rate_limit import GlobalRateLimiter
+
+ANTHROPIC_DEFAULT_MAX_TOKENS = 81920
+StreamChunkMode = Literal["line", "event"]
+
+
+class AnthropicMessagesTransport(BaseProvider):
+ """Base class for providers that stream from an Anthropic-compatible endpoint."""
+
+ stream_chunk_mode: StreamChunkMode = "line"
+
+ def __init__(
+ self,
+ config: ProviderConfig,
+ *,
+ provider_name: str,
+ default_base_url: str,
+ ):
+ super().__init__(config)
+ self._provider_name = provider_name
+ self._api_key = config.api_key
+ self._base_url = (config.base_url or default_base_url).rstrip("/")
+ self._global_rate_limiter = GlobalRateLimiter.get_scoped_instance(
+ provider_name.lower(),
+ rate_limit=config.rate_limit,
+ rate_window=config.rate_window,
+ max_concurrency=config.max_concurrency,
+ )
+ self._client = httpx.AsyncClient(
+ base_url=self._base_url,
+ proxy=config.proxy or None,
+ timeout=httpx.Timeout(
+ config.http_read_timeout,
+ connect=config.http_connect_timeout,
+ read=config.http_read_timeout,
+ write=config.http_write_timeout,
+ ),
+ )
+
+ async def cleanup(self) -> None:
+ """Release HTTP client resources."""
+ await self._client.aclose()
+
+ def _request_headers(self) -> dict[str, str]:
+ """Return headers for the native messages request."""
+ return {"Content-Type": "application/json"}
+
+ def _build_request_body(self, request: Any) -> dict:
+ """Build a native Anthropic request body."""
+ thinking_enabled = self._is_thinking_enabled(request)
+ body = request.model_dump(exclude_none=True)
+
+ body.pop("extra_body", None)
+ body.pop("original_model", None)
+ body.pop("resolved_provider_model", None)
+
+ if "thinking" in body:
+ thinking_cfg = body.pop("thinking")
+ if thinking_enabled and isinstance(thinking_cfg, dict):
+ thinking_payload = {"type": "enabled"}
+ budget_tokens = thinking_cfg.get("budget_tokens")
+ if isinstance(budget_tokens, int):
+ thinking_payload["budget_tokens"] = budget_tokens
+ body["thinking"] = thinking_payload
+
+ if "max_tokens" not in body:
+ body["max_tokens"] = ANTHROPIC_DEFAULT_MAX_TOKENS
+
+ return body
+
+ async def _send_stream_request(self, body: dict) -> httpx.Response:
+ """Create a streaming messages response."""
+ request = self._client.build_request(
+ "POST",
+ "/messages",
+ json=body,
+ headers=self._request_headers(),
+ )
+ return await self._client.send(request, stream=True)
+
+ async def _raise_for_status(
+ self, response: httpx.Response, *, req_tag: str
+ ) -> None:
+ """Raise for non-200 responses after logging the upstream body."""
+ try:
+ response.raise_for_status()
+ except httpx.HTTPStatusError as error:
+ response_text = await self._read_error_body(response)
+ if response_text:
+ logger.error(
+ "{}_ERROR:{} HTTP {}: {}",
+ self._provider_name,
+ req_tag,
+ response.status_code,
+ response_text,
+ )
+ raise error
+
+ async def _read_error_body(self, response: httpx.Response) -> str:
+ """Read a response body for diagnostics."""
+ aread = getattr(response, "aread", None)
+ if aread is None:
+ return ""
+ body = await aread()
+ if isinstance(body, bytes):
+ return body.decode("utf-8", errors="replace")
+ return str(body)
+
+ async def _iter_sse_lines(self, response: httpx.Response) -> AsyncIterator[str]:
+ """Yield raw SSE line chunks preserving local provider behavior."""
+ async for line in response.aiter_lines():
+ if line:
+ yield f"{line}\n"
+ else:
+ yield "\n"
+
+ async def _iter_sse_events(self, response: httpx.Response) -> AsyncIterator[str]:
+ """Group line-delimited SSE responses into full SSE events."""
+ event_lines: list[str] = []
+ async for line in response.aiter_lines():
+ if line:
+ event_lines.append(line)
+ continue
+ if event_lines:
+ yield "\n".join(event_lines) + "\n\n"
+ event_lines.clear()
+ if event_lines:
+ yield "\n".join(event_lines) + "\n\n"
+
+ def _new_stream_state(self, request: Any, *, thinking_enabled: bool) -> Any:
+ """Return per-stream provider state for event transformation."""
+ return None
+
+ def _transform_stream_event(
+ self,
+ event: str,
+ state: Any,
+ *,
+ thinking_enabled: bool,
+ ) -> str | None:
+ """Transform or drop a grouped SSE event before yielding it downstream."""
+ return event
+
+ def _format_error_message(self, base_message: str, request_id: str | None) -> str:
+ """Apply provider-specific request-id formatting to an error message."""
+ if request_id:
+ return f"{base_message}\nRequest ID: {request_id}"
+ return base_message
+
+ def _get_error_message(self, error: Exception, request_id: str | None) -> str:
+ """Map an exception into a user-facing provider error message."""
+ mapped_error = map_error(error, rate_limiter=self._global_rate_limiter)
+ if getattr(mapped_error, "status_code", None) == 405:
+ base_message = (
+ f"Upstream provider {self._provider_name} rejected the request method "
+ "or endpoint (HTTP 405)."
+ )
+ else:
+ base_message = get_user_facing_error_message(
+ mapped_error, read_timeout_s=self._config.http_read_timeout
+ )
+ return self._format_error_message(base_message, request_id)
+
+ def _emit_error_events(
+ self,
+ *,
+ request: Any,
+ input_tokens: int,
+ error_message: str,
+ sent_any_event: bool,
+ ) -> Iterator[str]:
+ """Emit a native Anthropic error event."""
+ error_event = {
+ "type": "error",
+ "error": {"type": "api_error", "message": error_message},
+ }
+ yield f"event: error\ndata: {json.dumps(error_event)}\n\n"
+
+ async def _iter_stream_chunks(
+ self,
+ response: httpx.Response,
+ *,
+ state: Any,
+ thinking_enabled: bool,
+ ) -> AsyncIterator[str]:
+ """Yield stream chunks according to the provider's observable chunk shape."""
+ if self.stream_chunk_mode == "line":
+ async for chunk in self._iter_sse_lines(response):
+ yield chunk
+ return
+
+ async for event in self._iter_sse_events(response):
+ output_event = self._transform_stream_event(
+ event,
+ state,
+ thinking_enabled=thinking_enabled,
+ )
+ if output_event is not None:
+ yield output_event
+
+ async def stream_response(
+ self,
+ request: Any,
+ input_tokens: int = 0,
+ *,
+ request_id: str | None = None,
+ ) -> AsyncIterator[str]:
+ """Stream response via a native Anthropic-compatible messages endpoint."""
+ tag = self._provider_name
+ req_tag = f" request_id={request_id}" if request_id else ""
+ thinking_enabled = self._is_thinking_enabled(request)
+ body = self._build_request_body(request)
+
+ logger.info(
+ "{}_STREAM:{} natively passing Anthropic request model={} msgs={} tools={}",
+ tag,
+ req_tag,
+ body.get("model"),
+ len(body.get("messages", [])),
+ len(body.get("tools", [])),
+ )
+
+ response: httpx.Response | None = None
+ sent_any_event = False
+ state = self._new_stream_state(request, thinking_enabled=thinking_enabled)
+
+ async with self._global_rate_limiter.concurrency_slot():
+ try:
+ response = await self._global_rate_limiter.execute_with_retry(
+ self._send_stream_request, body
+ )
+
+ if response.status_code != 200:
+ await self._raise_for_status(response, req_tag=req_tag)
+
+ async for chunk in self._iter_stream_chunks(
+ response,
+ state=state,
+ thinking_enabled=thinking_enabled,
+ ):
+ sent_any_event = True
+ yield chunk
+
+ except Exception as error:
+ logger.error(
+ "{}_ERROR:{} {}: {}", tag, req_tag, type(error).__name__, error
+ )
+ error_message = self._get_error_message(error, request_id)
+
+ if response is not None and not response.is_closed:
+ await response.aclose()
+
+ logger.info(
+ "{}_STREAM: Emitting native SSE error event for {}{}",
+ tag,
+ type(error).__name__,
+ req_tag,
+ )
+ for event in self._emit_error_events(
+ request=request,
+ input_tokens=input_tokens,
+ error_message=error_message,
+ sent_any_event=sent_any_event,
+ ):
+ yield event
+ return
+ finally:
+ if response is not None and not response.is_closed:
+ await response.aclose()
diff --git a/providers/base.py b/providers/base.py
index ecf02e16..6270c8e8 100644
--- a/providers/base.py
+++ b/providers/base.py
@@ -35,11 +35,23 @@ class BaseProvider(ABC):
def _is_thinking_enabled(self, request: Any) -> bool:
"""Return whether thinking should be enabled for this request."""
thinking = getattr(request, "thinking", None)
- request_enabled = (
- thinking.enabled
- if thinking is not None and hasattr(thinking, "enabled")
- else True
- )
+ request_enabled = True
+ if thinking is not None:
+ thinking_type = (
+ thinking.get("type")
+ if isinstance(thinking, dict)
+ else getattr(thinking, "type", None)
+ )
+ if thinking_type == "disabled":
+ request_enabled = False
+
+ enabled = (
+ thinking.get("enabled")
+ if isinstance(thinking, dict)
+ else getattr(thinking, "enabled", None)
+ )
+ if enabled is not None:
+ request_enabled = bool(enabled)
return self._config.enable_thinking and request_enabled
@abstractmethod
diff --git a/providers/common/error_mapping.py b/providers/common/error_mapping.py
index 55f622e5..d0c0d068 100644
--- a/providers/common/error_mapping.py
+++ b/providers/common/error_mapping.py
@@ -61,16 +61,19 @@ def append_request_id(message: str, request_id: str | None) -> str:
return base
-def map_error(e: Exception) -> Exception:
+def map_error(
+ e: Exception, *, rate_limiter: GlobalRateLimiter | None = None
+) -> Exception:
"""Map OpenAI or HTTPX exception to specific ProviderError."""
message = get_user_facing_error_message(e)
+ limiter = rate_limiter or GlobalRateLimiter.get_instance()
# Map OpenAI Specific Errors
if isinstance(e, openai.AuthenticationError):
return AuthenticationError(message, raw_error=str(e))
if isinstance(e, openai.RateLimitError):
# Trigger global rate limit block
- GlobalRateLimiter.get_instance().set_blocked(60) # Default 60s cooldown
+ limiter.set_blocked(60) # Default 60s cooldown
return RateLimitError(message, raw_error=str(e))
if isinstance(e, openai.BadRequestError):
return InvalidRequestError(message, raw_error=str(e))
@@ -90,7 +93,7 @@ def map_error(e: Exception) -> Exception:
if status in (401, 403):
return AuthenticationError(message, raw_error=str(e))
if status == 429:
- GlobalRateLimiter.get_instance().set_blocked(60)
+ limiter.set_blocked(60)
return RateLimitError(message, raw_error=str(e))
if status == 400:
return InvalidRequestError(message, raw_error=str(e))
diff --git a/providers/llamacpp/client.py b/providers/llamacpp/client.py
index 5dfcf5bb..be372977 100644
--- a/providers/llamacpp/client.py
+++ b/providers/llamacpp/client.py
@@ -1,159 +1,18 @@
"""Llama.cpp provider implementation."""
-import json
-from collections.abc import AsyncIterator
-from typing import Any
-
-import httpx
-from loguru import logger
-
-from providers.base import BaseProvider, ProviderConfig
-from providers.common import get_user_facing_error_message, map_error
-from providers.rate_limit import GlobalRateLimiter
+from providers.anthropic_messages import AnthropicMessagesTransport
+from providers.base import ProviderConfig
+from providers.rate_limit import GlobalRateLimiter as GlobalRateLimiter
LLAMACPP_DEFAULT_BASE_URL = "http://localhost:8080/v1"
-class LlamaCppProvider(BaseProvider):
- """Llama.cpp provider using native Anthropic Messages API endpoint."""
+class LlamaCppProvider(AnthropicMessagesTransport):
+ """Llama.cpp provider using native Anthropic Messages endpoint."""
def __init__(self, config: ProviderConfig):
- super().__init__(config)
- self._provider_name = "LLAMACPP"
- self._base_url = (config.base_url or LLAMACPP_DEFAULT_BASE_URL).rstrip("/")
-
- # We need the base URL without /v1 if the user provided it with /v1,
- # so we can append /v1/messages safely.
- # Actually, if they provided http://localhost:8080/v1, we can just use
- # {base_url}/messages which becomes http://localhost:8080/v1/messages
-
- self._global_rate_limiter = GlobalRateLimiter.get_instance(
- rate_limit=config.rate_limit,
- rate_window=config.rate_window,
- max_concurrency=config.max_concurrency,
- )
- self._client = httpx.AsyncClient(
- base_url=self._base_url,
- proxy=config.proxy or None,
- timeout=httpx.Timeout(
- config.http_read_timeout,
- connect=config.http_connect_timeout,
- read=config.http_read_timeout,
- write=config.http_write_timeout,
- ),
+ super().__init__(
+ config,
+ provider_name="LLAMACPP",
+ default_base_url=LLAMACPP_DEFAULT_BASE_URL,
)
-
- async def cleanup(self) -> None:
- """Release HTTP client resources."""
- await self._client.aclose()
-
- async def stream_response(
- self,
- request: Any,
- input_tokens: int = 0,
- *,
- request_id: str | None = None,
- ) -> AsyncIterator[str]:
- """Stream response natively via Llama.cpp's Anthropic-compatible endpoint."""
- tag = self._provider_name
- req_tag = f" request_id={request_id}" if request_id else ""
- thinking_enabled = self._is_thinking_enabled(request)
-
- # Dump the Anthropic Pydantic model directly into a dict
- body = request.model_dump(exclude_none=True)
-
- # Remove extra_body, original_model, resolved_provider_model which are internal
- body.pop("extra_body", None)
- body.pop("original_model", None)
- body.pop("resolved_provider_model", None)
-
- # Translate internal ThinkingConfig to Anthropic API schema
- if "thinking" in body:
- thinking_cfg = body.pop("thinking")
- if (
- thinking_enabled
- and isinstance(thinking_cfg, dict)
- and thinking_cfg.get("enabled")
- ):
- # Anthropic API requires a budget_tokens value when enabled
- body["thinking"] = {"type": "enabled"}
-
- # Ensure max_tokens is present (Claude API requires it)
- if "max_tokens" not in body:
- body["max_tokens"] = 81920
-
- logger.info(
- "{}_STREAM:{} natively passing Anthropic request to llama.cpp model={} msgs={} tools={}",
- tag,
- req_tag,
- body.get("model"),
- len(body.get("messages", [])),
- len(body.get("tools", [])),
- )
-
- async with self._global_rate_limiter.concurrency_slot():
- try:
- # We use execute_with_retry around the streaming request context
- # To do this safely with httpx streaming, we await the chunk stream
-
- async def _make_request():
- request_obj = self._client.build_request(
- "POST",
- "/messages",
- json=body,
- headers={"Content-Type": "application/json"},
- )
- return await self._client.send(request_obj, stream=True)
-
- response = await self._global_rate_limiter.execute_with_retry(
- _make_request
- )
-
- if response.status_code != 200:
- try:
- response.raise_for_status()
- except httpx.HTTPStatusError as e:
- text = await response.aread()
- logger.error(
- "{}_ERROR:{} HTTP {}: {}",
- tag,
- req_tag,
- response.status_code,
- text.decode("utf-8", errors="replace"),
- )
- raise e
-
- async for line in response.aiter_lines():
- if line:
- yield f"{line}\n"
- else:
- yield "\n"
-
- except Exception as e:
- logger.error("{}_ERROR:{} {}: {}", tag, req_tag, type(e).__name__, e)
- mapped_e = map_error(e)
- if getattr(mapped_e, "status_code", None) == 405:
- error_message = (
- f"Upstream provider {tag} rejected the request method "
- "or endpoint (HTTP 405)."
- )
- else:
- error_message = get_user_facing_error_message(
- mapped_e, read_timeout_s=self._config.http_read_timeout
- )
- if request_id:
- error_message += f"\nRequest ID: {request_id}"
-
- logger.info(
- "{}_STREAM: Emitting native SSE error event for {}{}",
- tag,
- type(e).__name__,
- req_tag,
- )
-
- # Emit an Anthropic-compatible error event
- error_event = {
- "type": "error",
- "error": {"type": "api_error", "message": error_message},
- }
- yield f"event: error\ndata: {json.dumps(error_event)}\n\n"
diff --git a/providers/lmstudio/client.py b/providers/lmstudio/client.py
index c6d66f7f..1e9966b6 100644
--- a/providers/lmstudio/client.py
+++ b/providers/lmstudio/client.py
@@ -1,159 +1,18 @@
"""LM Studio provider implementation."""
-import json
-from collections.abc import AsyncIterator
-from typing import Any
-
-import httpx
-from loguru import logger
-
-from providers.base import BaseProvider, ProviderConfig
-from providers.common import get_user_facing_error_message, map_error
-from providers.rate_limit import GlobalRateLimiter
+from providers.anthropic_messages import AnthropicMessagesTransport
+from providers.base import ProviderConfig
+from providers.rate_limit import GlobalRateLimiter as GlobalRateLimiter
LMSTUDIO_DEFAULT_BASE_URL = "http://localhost:1234/v1"
-class LMStudioProvider(BaseProvider):
- """LM Studio provider using native Anthropic Messages API endpoint."""
+class LMStudioProvider(AnthropicMessagesTransport):
+ """LM Studio provider using native Anthropic Messages endpoint."""
def __init__(self, config: ProviderConfig):
- super().__init__(config)
- self._provider_name = "LMSTUDIO"
- self._base_url = (config.base_url or LMSTUDIO_DEFAULT_BASE_URL).rstrip("/")
-
- # We need the base URL without /v1 if the user provided it with /v1,
- # so we can append /v1/messages safely.
- # Actually, if they provided http://localhost:1234/v1, we can just use
- # {base_url}/messages which becomes http://localhost:1234/v1/messages
-
- self._global_rate_limiter = GlobalRateLimiter.get_instance(
- rate_limit=config.rate_limit,
- rate_window=config.rate_window,
- max_concurrency=config.max_concurrency,
- )
- self._client = httpx.AsyncClient(
- base_url=self._base_url,
- proxy=config.proxy or None,
- timeout=httpx.Timeout(
- config.http_read_timeout,
- connect=config.http_connect_timeout,
- read=config.http_read_timeout,
- write=config.http_write_timeout,
- ),
+ super().__init__(
+ config,
+ provider_name="LMSTUDIO",
+ default_base_url=LMSTUDIO_DEFAULT_BASE_URL,
)
-
- async def cleanup(self) -> None:
- """Release HTTP client resources."""
- await self._client.aclose()
-
- async def stream_response(
- self,
- request: Any,
- input_tokens: int = 0,
- *,
- request_id: str | None = None,
- ) -> AsyncIterator[str]:
- """Stream response natively via LM Studio's Anthropic-compatible endpoint."""
- tag = self._provider_name
- req_tag = f" request_id={request_id}" if request_id else ""
- thinking_enabled = self._is_thinking_enabled(request)
-
- # Dump the Anthropic Pydantic model directly into a dict
- body = request.model_dump(exclude_none=True)
-
- # Remove extra_body, original_model, resolved_provider_model which are internal
- body.pop("extra_body", None)
- body.pop("original_model", None)
- body.pop("resolved_provider_model", None)
-
- # Translate internal ThinkingConfig to Anthropic API schema
- if "thinking" in body:
- thinking_cfg = body.pop("thinking")
- if (
- thinking_enabled
- and isinstance(thinking_cfg, dict)
- and thinking_cfg.get("enabled")
- ):
- # Anthropic API requires a budget_tokens value when enabled
- body["thinking"] = {"type": "enabled"}
-
- # Ensure max_tokens is present (Claude API requires it)
- if "max_tokens" not in body:
- body["max_tokens"] = 81920
-
- logger.info(
- "{}_STREAM:{} natively passing Anthropic request to LMStudio model={} msgs={} tools={}",
- tag,
- req_tag,
- body.get("model"),
- len(body.get("messages", [])),
- len(body.get("tools", [])),
- )
-
- async with self._global_rate_limiter.concurrency_slot():
- try:
- # We use execute_with_retry around the streaming request context
- # To do this safely with httpx streaming, we await the chunk stream
-
- async def _make_request():
- request_obj = self._client.build_request(
- "POST",
- "/messages",
- json=body,
- headers={"Content-Type": "application/json"},
- )
- return await self._client.send(request_obj, stream=True)
-
- response = await self._global_rate_limiter.execute_with_retry(
- _make_request
- )
-
- if response.status_code != 200:
- try:
- response.raise_for_status()
- except httpx.HTTPStatusError as e:
- text = await response.aread()
- logger.error(
- "{}_ERROR:{} HTTP {}: {}",
- tag,
- req_tag,
- response.status_code,
- text.decode("utf-8", errors="replace"),
- )
- raise e
-
- async for line in response.aiter_lines():
- if line:
- yield f"{line}\n"
- else:
- yield "\n"
-
- except Exception as e:
- logger.error("{}_ERROR:{} {}: {}", tag, req_tag, type(e).__name__, e)
- mapped_e = map_error(e)
- if getattr(mapped_e, "status_code", None) == 405:
- error_message = (
- f"Upstream provider {tag} rejected the request method "
- "or endpoint (HTTP 405)."
- )
- else:
- error_message = get_user_facing_error_message(
- mapped_e, read_timeout_s=self._config.http_read_timeout
- )
- if request_id:
- error_message += f"\nRequest ID: {request_id}"
-
- logger.info(
- "{}_STREAM: Emitting native SSE error event for {}{}",
- tag,
- type(e).__name__,
- req_tag,
- )
-
- # Emit an Anthropic-compatible error event
- error_event = {
- "type": "error",
- "error": {"type": "api_error", "message": error_message},
- }
- yield f"event: error\ndata: {json.dumps(error_event)}\n\n"
diff --git a/providers/open_router/__init__.py b/providers/open_router/__init__.py
index a72244a9..ae32e0af 100644
--- a/providers/open_router/__init__.py
+++ b/providers/open_router/__init__.py
@@ -1,5 +1,5 @@
-"""OpenRouter provider - OpenAI-compatible API for hundreds of models."""
+"""OpenRouter provider - Anthropic-compatible and rollback transports."""
-from .client import OPENROUTER_BASE_URL, OpenRouterProvider
+from .client import OPENROUTER_BASE_URL, OpenRouterChatProvider, OpenRouterProvider
-__all__ = ["OPENROUTER_BASE_URL", "OpenRouterProvider"]
+__all__ = ["OPENROUTER_BASE_URL", "OpenRouterChatProvider", "OpenRouterProvider"]
diff --git a/providers/open_router/chat_request.py b/providers/open_router/chat_request.py
new file mode 100644
index 00000000..3e9d2ba6
--- /dev/null
+++ b/providers/open_router/chat_request.py
@@ -0,0 +1,43 @@
+"""OpenAI chat-completions request builder for OpenRouter rollback mode."""
+
+from typing import Any
+
+from loguru import logger
+
+from providers.common.message_converter import build_base_request_body
+
+OPENROUTER_DEFAULT_MAX_TOKENS = 81920
+
+
+def build_chat_request_body(request_data: Any, *, thinking_enabled: bool) -> dict:
+ """Build OpenAI-format request body from Anthropic request for OpenRouter."""
+ logger.debug(
+ "OPENROUTER_CHAT_REQUEST: conversion start model={} msgs={}",
+ getattr(request_data, "model", "?"),
+ len(getattr(request_data, "messages", [])),
+ )
+ body = build_base_request_body(
+ request_data,
+ include_thinking=thinking_enabled,
+ default_max_tokens=OPENROUTER_DEFAULT_MAX_TOKENS,
+ include_reasoning_for_openrouter=thinking_enabled,
+ )
+
+ extra_body: dict[str, Any] = {}
+ request_extra = getattr(request_data, "extra_body", None)
+ if request_extra:
+ extra_body.update(request_extra)
+
+ if thinking_enabled:
+ extra_body.setdefault("reasoning", {"enabled": True})
+
+ if extra_body:
+ body["extra_body"] = extra_body
+
+ logger.debug(
+ "OPENROUTER_CHAT_REQUEST: conversion done model={} msgs={} tools={}",
+ body.get("model"),
+ len(body.get("messages", [])),
+ len(body.get("tools", [])),
+ )
+ return body
diff --git a/providers/open_router/client.py b/providers/open_router/client.py
index af04f222..d6e46a71 100644
--- a/providers/open_router/client.py
+++ b/providers/open_router/client.py
@@ -1,19 +1,39 @@
"""OpenRouter provider implementation."""
+from __future__ import annotations
+
+import json
+import uuid
from collections.abc import Iterator
+from dataclasses import dataclass, field
from typing import Any
+from providers.anthropic_messages import AnthropicMessagesTransport, StreamChunkMode
from providers.base import ProviderConfig
-from providers.common import SSEBuilder
-from providers.openai_compat import OpenAICompatibleProvider
+from providers.common import SSEBuilder, append_request_id
+from providers.openai_compat import OpenAIChatTransport
+from .chat_request import build_chat_request_body
from .request import build_request_body
OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+_ANTHROPIC_VERSION = "2023-06-01"
+
+
+@dataclass
+class _SSEFilterState:
+ """Track Anthropic content block index remapping while filtering thinking."""
+
+ next_index: int = 0
+ index_map: dict[int, int] = field(default_factory=dict)
+ dropped_indexes: set[int] = field(default_factory=set)
+ open_block_types: dict[int, str] = field(default_factory=dict)
+ closed_indexes: set[int] = field(default_factory=set)
+ message_stopped: bool = False
-class OpenRouterProvider(OpenAICompatibleProvider):
- """OpenRouter provider using OpenAI-compatible API."""
+class OpenRouterChatProvider(OpenAIChatTransport):
+ """OpenRouter provider using OpenAI-compatible chat completions."""
def __init__(self, config: ProviderConfig):
super().__init__(
@@ -24,8 +44,8 @@ class OpenRouterProvider(OpenAICompatibleProvider):
)
def _build_request_body(self, request: Any) -> dict:
- """Internal helper for tests and shared building."""
- return build_request_body(
+ """Build OpenAI chat-completions request body."""
+ return build_chat_request_body(
request,
thinking_enabled=self._is_thinking_enabled(request),
)
@@ -33,7 +53,7 @@ class OpenRouterProvider(OpenAICompatibleProvider):
def _handle_extra_reasoning(
self, delta: Any, sse: SSEBuilder, *, thinking_enabled: bool
) -> Iterator[str]:
- """Handle reasoning_details for StepFun models."""
+ """Handle reasoning_details for StepFun models in rollback mode."""
if not thinking_enabled:
return
reasoning_details = getattr(delta, "reasoning_details", None)
@@ -43,3 +63,274 @@ class OpenRouterProvider(OpenAICompatibleProvider):
if text:
yield from sse.ensure_thinking_block()
yield sse.emit_thinking_delta(text)
+
+
+class OpenRouterProvider(AnthropicMessagesTransport):
+ """OpenRouter provider using the native Anthropic-compatible messages API."""
+
+ stream_chunk_mode: StreamChunkMode = "event"
+
+ def __init__(self, config: ProviderConfig):
+ super().__init__(
+ config,
+ provider_name="OPENROUTER",
+ default_base_url=OPENROUTER_BASE_URL,
+ )
+
+ def _build_request_body(self, request: Any) -> dict:
+ """Internal helper for tests and direct request dispatch."""
+ return build_request_body(
+ request,
+ thinking_enabled=self._is_thinking_enabled(request),
+ )
+
+ def _request_headers(self) -> dict[str, str]:
+ """Return OpenRouter's Anthropic-compatible messages headers."""
+ return {
+ "Accept": "text/event-stream",
+ "Authorization": f"Bearer {self._api_key}",
+ "Content-Type": "application/json",
+ "anthropic-version": _ANTHROPIC_VERSION,
+ }
+
+ @staticmethod
+ def _format_sse_event(event_name: str | None, data_text: str) -> str:
+ """Format an SSE event from its event name and data payload."""
+ lines: list[str] = []
+ if event_name:
+ lines.append(f"event: {event_name}")
+ lines.extend(f"data: {line}" for line in data_text.splitlines())
+ return "\n".join(lines) + "\n\n"
+
+ @staticmethod
+ def _parse_sse_event(event: str) -> tuple[str | None, str]:
+ """Extract the event name and raw data payload from an SSE event."""
+ event_name = None
+ data_lines: list[str] = []
+ for line in event.strip().splitlines():
+ if line.startswith("event:"):
+ event_name = line[6:].strip()
+ elif line.startswith("data:"):
+ data_lines.append(line[5:].lstrip())
+ return event_name, "\n".join(data_lines)
+
+ @staticmethod
+ def _is_terminal_done_event(event_name: str | None, data_text: str) -> bool:
+ """Return whether an event is OpenAI-style terminal noise."""
+ return (event_name is None or event_name in {"data", "done"}) and (
+ data_text.strip().upper() == "[DONE]"
+ )
+
+ @staticmethod
+ def _remap_index(
+ payload: dict[str, Any], state: _SSEFilterState, *, create: bool
+ ) -> int | None:
+ """Return the downstream index for a content block event."""
+ upstream_index = payload.get("index")
+ if not isinstance(upstream_index, int):
+ return None
+ if upstream_index in state.dropped_indexes:
+ return None
+ mapped_index = state.index_map.get(upstream_index)
+ if mapped_index is None and create:
+ mapped_index = state.next_index
+ state.index_map[upstream_index] = mapped_index
+ state.next_index += 1
+ return mapped_index
+
+ def _close_open_blocks_before(
+ self, state: _SSEFilterState, upstream_index: int
+ ) -> str:
+ """Close overlapping upstream blocks before starting a new block."""
+ events: list[str] = []
+ for open_upstream_index in list(state.open_block_types):
+ if open_upstream_index == upstream_index:
+ continue
+ mapped_index = state.index_map.get(open_upstream_index)
+ if mapped_index is None:
+ continue
+ payload = {"type": "content_block_stop", "index": mapped_index}
+ events.append(
+ self._format_sse_event("content_block_stop", json.dumps(payload))
+ )
+ state.closed_indexes.add(open_upstream_index)
+ state.open_block_types.pop(open_upstream_index, None)
+ return "".join(events)
+
+ def _filter_sse_event(self, event: str, state: _SSEFilterState) -> str | None:
+ """Drop upstream thinking blocks and remap remaining block indexes."""
+ event_name, data_text = self._parse_sse_event(event)
+ if not event_name or not data_text:
+ return event
+
+ try:
+ payload = json.loads(data_text)
+ except json.JSONDecodeError:
+ return event
+
+ if event_name == "content_block_start":
+ block = payload.get("content_block")
+ block_type = block.get("type") if isinstance(block, dict) else None
+ upstream_index = payload.get("index")
+ if isinstance(block_type, str) and "thinking" in block_type:
+ if isinstance(upstream_index, int):
+ state.dropped_indexes.add(upstream_index)
+ return None
+
+ mapped_index = self._remap_index(payload, state, create=True)
+ if mapped_index is not None:
+ payload["index"] = mapped_index
+ if isinstance(upstream_index, int) and isinstance(block_type, str):
+ prefix = self._close_open_blocks_before(state, upstream_index)
+ state.open_block_types[upstream_index] = block_type
+ return prefix + self._format_sse_event(
+ event_name, json.dumps(payload)
+ )
+ return self._format_sse_event(event_name, json.dumps(payload))
+
+ if event_name == "content_block_delta":
+ delta = payload.get("delta")
+ delta_type = delta.get("type") if isinstance(delta, dict) else None
+ if isinstance(delta_type, str) and "thinking" in delta_type:
+ return None
+
+ mapped_index = self._remap_index(payload, state, create=False)
+ if mapped_index is None:
+ return None
+ payload["index"] = mapped_index
+ return self._format_sse_event(event_name, json.dumps(payload))
+
+ if event_name == "content_block_stop":
+ upstream_index = payload.get("index")
+ if (
+ isinstance(upstream_index, int)
+ and upstream_index in state.closed_indexes
+ ):
+ state.closed_indexes.discard(upstream_index)
+ return None
+ mapped_index = self._remap_index(payload, state, create=False)
+ if mapped_index is None:
+ return None
+ payload["index"] = mapped_index
+ if isinstance(upstream_index, int):
+ state.open_block_types.pop(upstream_index, None)
+ return self._format_sse_event(event_name, json.dumps(payload))
+
+ return event
+
+ def _normalize_sse_event(self, event: str, state: _SSEFilterState) -> str | None:
+ """Normalize OpenRouter-native extras into Anthropic-compatible events."""
+ event_name, data_text = self._parse_sse_event(event)
+ if not event_name or not data_text:
+ return event
+
+ try:
+ payload = json.loads(data_text)
+ except json.JSONDecodeError:
+ return event
+
+ if event_name == "content_block_start":
+ block = payload.get("content_block")
+ if not isinstance(block, dict):
+ return event
+ block_type = block.get("type")
+ upstream_index = payload.get("index")
+ if isinstance(block_type, str) and block_type == "redacted_thinking":
+ if isinstance(upstream_index, int):
+ state.dropped_indexes.add(upstream_index)
+ return None
+
+ mapped_index = self._remap_index(payload, state, create=True)
+ if mapped_index is not None:
+ payload["index"] = mapped_index
+ if isinstance(upstream_index, int) and isinstance(block_type, str):
+ prefix = self._close_open_blocks_before(state, upstream_index)
+ state.open_block_types[upstream_index] = block_type
+ return prefix + self._format_sse_event(
+ event_name, json.dumps(payload)
+ )
+ return self._format_sse_event(event_name, json.dumps(payload))
+ return event
+
+ if event_name == "content_block_delta":
+ delta = payload.get("delta")
+ if not isinstance(delta, dict):
+ return event
+ delta_type = delta.get("type")
+ if isinstance(delta_type, str) and delta_type == "redacted_thinking_delta":
+ return None
+
+ mapped_index = self._remap_index(payload, state, create=False)
+ if mapped_index is not None:
+ payload["index"] = mapped_index
+ return self._format_sse_event(event_name, json.dumps(payload))
+ if payload.get("index") in state.dropped_indexes:
+ return None
+
+ if event_name == "content_block_stop":
+ upstream_index = payload.get("index")
+ if (
+ isinstance(upstream_index, int)
+ and upstream_index in state.closed_indexes
+ ):
+ state.closed_indexes.discard(upstream_index)
+ return None
+ mapped_index = self._remap_index(payload, state, create=False)
+ if mapped_index is not None:
+ payload["index"] = mapped_index
+ if isinstance(upstream_index, int):
+ state.open_block_types.pop(upstream_index, None)
+ return self._format_sse_event(event_name, json.dumps(payload))
+ if payload.get("index") in state.dropped_indexes:
+ return None
+
+ return event
+
+ def _new_stream_state(self, request: Any, *, thinking_enabled: bool) -> Any:
+ """Create per-stream state for thinking block filtering."""
+ return _SSEFilterState()
+
+ def _transform_stream_event(
+ self,
+ event: str,
+ state: Any,
+ *,
+ thinking_enabled: bool,
+ ) -> str | None:
+ """Drop provider-specific terminal noise and hidden thinking events."""
+ if isinstance(state, _SSEFilterState):
+ event_name, data_text = self._parse_sse_event(event)
+ if state.message_stopped or self._is_terminal_done_event(
+ event_name, data_text
+ ):
+ return None
+ if event_name == "message_stop":
+ state.message_stopped = True
+
+ if thinking_enabled:
+ if isinstance(state, _SSEFilterState):
+ return self._normalize_sse_event(event, state)
+ return event
+ if isinstance(state, _SSEFilterState):
+ return self._filter_sse_event(event, state)
+ return event
+
+ def _format_error_message(self, base_message: str, request_id: str | None) -> str:
+ """Keep OpenRouter's existing request-id suffix format."""
+ return append_request_id(base_message, request_id)
+
+ def _emit_error_events(
+ self,
+ *,
+ request: Any,
+ input_tokens: int,
+ error_message: str,
+ sent_any_event: bool,
+ ) -> Iterator[str]:
+ """Emit the Anthropic SSE error shape expected by Claude clients."""
+ sse = SSEBuilder(f"msg_{uuid.uuid4()}", request.model, input_tokens)
+ if not sent_any_event:
+ yield sse.message_start()
+ yield from sse.emit_error(error_message)
+ yield sse.message_delta("end_turn", 1)
+ yield sse.message_stop()
diff --git a/providers/open_router/request.py b/providers/open_router/request.py
index c524a006..89759abf 100644
--- a/providers/open_router/request.py
+++ b/providers/open_router/request.py
@@ -1,39 +1,168 @@
-"""Request builder for OpenRouter provider."""
+"""Native Anthropic Messages request builder for OpenRouter."""
+from __future__ import annotations
+
+from collections.abc import Sequence
from typing import Any
from loguru import logger
-
-from providers.common.message_converter import build_base_request_body
+from pydantic import BaseModel
OPENROUTER_DEFAULT_MAX_TOKENS = 81920
+_REQUEST_FIELDS = (
+ "model",
+ "messages",
+ "system",
+ "max_tokens",
+ "stop_sequences",
+ "stream",
+ "temperature",
+ "top_p",
+ "top_k",
+ "metadata",
+ "tools",
+ "tool_choice",
+ "thinking",
+ "extra_body",
+ "original_model",
+ "resolved_provider_model",
+)
+
+_INTERNAL_FIELDS = {
+ "thinking",
+ "extra_body",
+ "original_model",
+ "resolved_provider_model",
+}
+_THINKING_HISTORY_BLOCK_TYPES = {"thinking", "redacted_thinking"}
+
+
+def _serialize_value(value: Any) -> Any:
+ """Convert Pydantic models and lightweight objects into JSON-ready values."""
+ if isinstance(value, BaseModel):
+ return value.model_dump(exclude_none=True)
+ if isinstance(value, dict):
+ return {
+ key: _serialize_value(item)
+ for key, item in value.items()
+ if item is not None
+ }
+ if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+ return [_serialize_value(item) for item in value]
+ if value is None or isinstance(value, str | int | float | bool):
+ return value
+ if hasattr(value, "__dict__"):
+ return {
+ key: _serialize_value(item)
+ for key, item in vars(value).items()
+ if not key.startswith("_") and item is not None
+ }
+ return value
+
+
+def _dump_request_fields(request_data: Any) -> dict[str, Any]:
+ """Extract the public request fields forwarded to OpenRouter."""
+ if isinstance(request_data, BaseModel):
+ return request_data.model_dump(exclude_none=True)
+
+ dumped: dict[str, Any] = {}
+ for field in _REQUEST_FIELDS:
+ value = getattr(request_data, field, None)
+ if value is not None:
+ dumped[field] = _serialize_value(value)
+ return dumped
+
+
+def _strip_unsigned_thinking_history(messages: Any) -> Any:
+ """Remove assistant thinking history blocks that OpenRouter cannot replay."""
+ if not isinstance(messages, list):
+ return messages
+
+ sanitized_messages: list[Any] = []
+ for message in messages:
+ if not isinstance(message, dict):
+ sanitized_messages.append(message)
+ continue
+
+ content = message.get("content")
+ if not isinstance(content, list):
+ sanitized_messages.append(message)
+ continue
+
+ sanitized_content = [
+ block
+ for block in content
+ if not (
+ isinstance(block, dict)
+ and block.get("type") in _THINKING_HISTORY_BLOCK_TYPES
+ and not isinstance(block.get("signature"), str)
+ )
+ ]
+
+ sanitized_message = dict(message)
+ sanitized_message["content"] = sanitized_content or ""
+ sanitized_messages.append(sanitized_message)
+
+ return sanitized_messages
+
+
+def _normalize_system_prompt(system: Any) -> Any:
+ """Flatten Claude SDK system blocks for OpenRouter's native endpoint."""
+ if not isinstance(system, list):
+ return system
+
+ text_parts: list[str] = []
+ for block in system:
+ if not isinstance(block, dict):
+ continue
+ if block.get("type") == "text" and isinstance(block.get("text"), str):
+ text_parts.append(block["text"])
+ return "\n\n".join(text_parts).strip() if text_parts else system
+
+
+def _apply_reasoning(body: dict[str, Any], thinking_cfg: Any) -> None:
+ """Map Anthropic thinking controls onto OpenRouter reasoning controls."""
+ reasoning = body.setdefault("reasoning", {"enabled": True})
+ if not isinstance(reasoning, dict):
+ return
+ reasoning.setdefault("enabled", True)
+ if not isinstance(thinking_cfg, dict):
+ return
+ budget_tokens = thinking_cfg.get("budget_tokens")
+ if isinstance(budget_tokens, int):
+ reasoning.setdefault("max_tokens", budget_tokens)
+
def build_request_body(request_data: Any, *, thinking_enabled: bool) -> dict:
- """Build OpenAI-format request body from Anthropic request for OpenRouter."""
+ """Build an Anthropic-format request body for OpenRouter's messages API."""
logger.debug(
"OPENROUTER_REQUEST: conversion start model={} msgs={}",
getattr(request_data, "model", "?"),
len(getattr(request_data, "messages", [])),
)
- body = build_base_request_body(
- request_data,
- include_thinking=thinking_enabled,
- default_max_tokens=OPENROUTER_DEFAULT_MAX_TOKENS,
- include_reasoning_for_openrouter=thinking_enabled,
- )
- # OpenRouter reasoning: extra_body={"reasoning": {"enabled": True}}
- extra_body: dict[str, Any] = {}
- request_extra = getattr(request_data, "extra_body", None)
- if request_extra:
- extra_body.update(request_extra)
+ dumped_request = _dump_request_fields(request_data)
+ request_extra = dumped_request.pop("extra_body", None)
+ thinking_cfg = dumped_request.get("thinking")
+ body = {
+ key: value
+ for key, value in dumped_request.items()
+ if key not in _INTERNAL_FIELDS
+ }
- if thinking_enabled:
- extra_body.setdefault("reasoning", {"enabled": True})
+ if isinstance(request_extra, dict):
+ body.update(request_extra)
+
+ body["messages"] = _strip_unsigned_thinking_history(body.get("messages"))
+ if "system" in body:
+ body["system"] = _normalize_system_prompt(body["system"])
+ body["stream"] = True
+ if body.get("max_tokens") is None:
+ body["max_tokens"] = OPENROUTER_DEFAULT_MAX_TOKENS
- if extra_body:
- body["extra_body"] = extra_body
+ if thinking_enabled:
+ _apply_reasoning(body, thinking_cfg)
logger.debug(
"OPENROUTER_REQUEST: conversion done model={} msgs={} tools={}",
diff --git a/providers/openai_compat.py b/providers/openai_compat.py
index 979ec3e8..4125d849 100644
--- a/providers/openai_compat.py
+++ b/providers/openai_compat.py
@@ -24,7 +24,7 @@ from providers.common import (
from providers.rate_limit import GlobalRateLimiter
-class OpenAICompatibleProvider(BaseProvider):
+class OpenAIChatTransport(BaseProvider):
"""Base class for providers using OpenAI-compatible chat completions API."""
def __init__(
@@ -39,7 +39,8 @@ class OpenAICompatibleProvider(BaseProvider):
self._provider_name = provider_name
self._api_key = api_key
self._base_url = base_url.rstrip("/")
- self._global_rate_limiter = GlobalRateLimiter.get_instance(
+ self._global_rate_limiter = GlobalRateLimiter.get_scoped_instance(
+ provider_name.lower(),
rate_limit=config.rate_limit,
rate_window=config.rate_window,
max_concurrency=config.max_concurrency,
@@ -286,7 +287,7 @@ class OpenAICompatibleProvider(BaseProvider):
except Exception as e:
logger.error("{}_ERROR:{} {}: {}", tag, req_tag, type(e).__name__, e)
- mapped_e = map_error(e)
+ mapped_e = map_error(e, rate_limiter=self._global_rate_limiter)
error_occurred = True
if getattr(mapped_e, "status_code", None) == 405:
base_message = (
@@ -377,3 +378,7 @@ class OpenAICompatibleProvider(BaseProvider):
)
yield sse.message_delta(map_stop_reason(finish_reason), output_tokens)
yield sse.message_stop()
+
+
+# Backward-compatible class name used by existing provider implementations.
+OpenAICompatibleProvider = OpenAIChatTransport
diff --git a/providers/rate_limit.py b/providers/rate_limit.py
index 8eae7bfa..7a523f6a 100644
--- a/providers/rate_limit.py
+++ b/providers/rate_limit.py
@@ -29,12 +29,7 @@ class GlobalRateLimiter:
"""
_instance: ClassVar[GlobalRateLimiter | None] = None
-
- def __new__(cls, *args: Any, **kwargs: Any) -> GlobalRateLimiter:
- if cls._instance is not None:
- return cls._instance
- instance = super().__new__(cls)
- return instance
+ _scoped_instances: ClassVar[dict[str, GlobalRateLimiter]] = {}
def __init__(
self,
@@ -88,10 +83,31 @@ class GlobalRateLimiter:
)
return cls._instance
+ @classmethod
+ def get_scoped_instance(
+ cls,
+ scope: str,
+ *,
+ rate_limit: int | None = None,
+ rate_window: float | None = None,
+ max_concurrency: int = 5,
+ ) -> GlobalRateLimiter:
+ """Get or create a provider-scoped limiter instance."""
+ if not scope:
+ raise ValueError("scope must be non-empty")
+ if scope not in cls._scoped_instances:
+ cls._scoped_instances[scope] = cls(
+ rate_limit=rate_limit or 40,
+ rate_window=rate_window or 60.0,
+ max_concurrency=max_concurrency,
+ )
+ return cls._scoped_instances[scope]
+
@classmethod
def reset_instance(cls) -> None:
"""Reset singleton (for testing)."""
cls._instance = None
+ cls._scoped_instances = {}
async def wait_if_blocked(self) -> bool:
"""
diff --git a/providers/registry.py b/providers/registry.py
new file mode 100644
index 00000000..8a63a3fa
--- /dev/null
+++ b/providers/registry.py
@@ -0,0 +1,177 @@
+"""Provider descriptors, factory, and runtime registry."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from dataclasses import dataclass
+from typing import Literal
+
+from config.settings import Settings
+from providers.base import BaseProvider, ProviderConfig
+from providers.deepseek import DEEPSEEK_BASE_URL, DeepSeekProvider
+from providers.exceptions import AuthenticationError
+from providers.llamacpp import LlamaCppProvider
+from providers.lmstudio import LMStudioProvider
+from providers.nvidia_nim import NVIDIA_NIM_BASE_URL, NvidiaNimProvider
+from providers.open_router import (
+ OPENROUTER_BASE_URL,
+ OpenRouterChatProvider,
+ OpenRouterProvider,
+)
+
+TransportType = Literal["openai_chat", "anthropic_messages"]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDescriptor:
+ provider_id: str
+ transport_type: TransportType
+ capabilities: tuple[str, ...]
+ credential_env: str | None = None
+ credential_url: str | None = None
+ default_base_url: str | None = None
+ base_url_attr: str | None = None
+ proxy_attr: str | None = None
+
+
+PROVIDER_DESCRIPTORS: dict[str, ProviderDescriptor] = {
+ "nvidia_nim": ProviderDescriptor(
+ provider_id="nvidia_nim",
+ transport_type="openai_chat",
+ credential_env="NVIDIA_NIM_API_KEY",
+ credential_url="https://build.nvidia.com/settings/api-keys",
+ default_base_url=NVIDIA_NIM_BASE_URL,
+ proxy_attr="nvidia_nim_proxy",
+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
+ ),
+ "open_router": ProviderDescriptor(
+ provider_id="open_router",
+ transport_type="anthropic_messages",
+ credential_env="OPENROUTER_API_KEY",
+ credential_url="https://openrouter.ai/keys",
+ default_base_url=OPENROUTER_BASE_URL,
+ proxy_attr="open_router_proxy",
+ capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),
+ ),
+ "deepseek": ProviderDescriptor(
+ provider_id="deepseek",
+ transport_type="openai_chat",
+ credential_env="DEEPSEEK_API_KEY",
+ credential_url="https://platform.deepseek.com/api_keys",
+ default_base_url=DEEPSEEK_BASE_URL,
+ capabilities=("chat", "streaming", "thinking"),
+ ),
+ "lmstudio": ProviderDescriptor(
+ provider_id="lmstudio",
+ transport_type="anthropic_messages",
+ default_base_url="http://localhost:1234/v1",
+ base_url_attr="lm_studio_base_url",
+ proxy_attr="lmstudio_proxy",
+ capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),
+ ),
+ "llamacpp": ProviderDescriptor(
+ provider_id="llamacpp",
+ transport_type="anthropic_messages",
+ default_base_url="http://localhost:8080/v1",
+ base_url_attr="llamacpp_base_url",
+ proxy_attr="llamacpp_proxy",
+ capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),
+ ),
+}
+
+
+def _string_attr(settings: Settings, attr_name: str | None, default: str = "") -> str:
+ if attr_name is None:
+ return default
+ value = getattr(settings, attr_name, default)
+ return value if isinstance(value, str) else default
+
+
+def _credential_for(provider_id: str, settings: Settings) -> str:
+ if provider_id == "nvidia_nim":
+ return settings.nvidia_nim_api_key
+ if provider_id == "open_router":
+ return settings.open_router_api_key
+ if provider_id == "deepseek":
+ return settings.deepseek_api_key
+ if provider_id == "lmstudio":
+ return "lm-studio"
+ if provider_id == "llamacpp":
+ return "llamacpp"
+ return ""
+
+
+def _require_credential(descriptor: ProviderDescriptor, credential: str) -> None:
+ if descriptor.credential_env is None:
+ return
+ if credential and credential.strip():
+ return
+ message = f"{descriptor.credential_env} is not set. Add it to your .env file."
+ if descriptor.credential_url:
+ message = f"{message} Get a key at {descriptor.credential_url}"
+ raise AuthenticationError(message)
+
+
+def build_provider_config(
+ descriptor: ProviderDescriptor, settings: Settings
+) -> ProviderConfig:
+ credential = _credential_for(descriptor.provider_id, settings)
+ _require_credential(descriptor, credential)
+ base_url = _string_attr(
+ settings, descriptor.base_url_attr, descriptor.default_base_url or ""
+ )
+ proxy = _string_attr(settings, descriptor.proxy_attr)
+ return ProviderConfig(
+ api_key=credential,
+ base_url=base_url or descriptor.default_base_url,
+ rate_limit=settings.provider_rate_limit,
+ rate_window=settings.provider_rate_window,
+ max_concurrency=settings.provider_max_concurrency,
+ http_read_timeout=settings.http_read_timeout,
+ http_write_timeout=settings.http_write_timeout,
+ http_connect_timeout=settings.http_connect_timeout,
+ enable_thinking=settings.enable_thinking,
+ proxy=proxy,
+ )
+
+
+def create_provider(provider_id: str, settings: Settings) -> BaseProvider:
+ descriptor = PROVIDER_DESCRIPTORS.get(provider_id)
+ if descriptor is None:
+ supported = "', '".join(PROVIDER_DESCRIPTORS)
+ raise ValueError(
+ f"Unknown provider_type: '{provider_id}'. Supported: '{supported}'"
+ )
+
+ config = build_provider_config(descriptor, settings)
+ if provider_id == "nvidia_nim":
+ return NvidiaNimProvider(config, nim_settings=settings.nim)
+ if provider_id == "open_router":
+ if settings.openrouter_transport == "openai":
+ return OpenRouterChatProvider(config)
+ return OpenRouterProvider(config)
+ if provider_id == "deepseek":
+ return DeepSeekProvider(config)
+ if provider_id == "lmstudio":
+ return LMStudioProvider(config)
+ if provider_id == "llamacpp":
+ return LlamaCppProvider(config)
+
+ raise AssertionError(f"Unhandled provider descriptor: {provider_id}")
+
+
+class ProviderRegistry:
+ """Cache and clean up provider instances by provider id."""
+
+ def __init__(self, providers: MutableMapping[str, BaseProvider] | None = None):
+ self._providers = providers if providers is not None else {}
+
+ def get(self, provider_id: str, settings: Settings) -> BaseProvider:
+ if provider_id not in self._providers:
+ self._providers[provider_id] = create_provider(provider_id, settings)
+ return self._providers[provider_id]
+
+ async def cleanup(self) -> None:
+ for provider in self._providers.values():
+ await provider.cleanup()
+ self._providers.clear()
diff --git a/smoke/README.md b/smoke/README.md
index fedad56f..8e5dfafc 100644
--- a/smoke/README.md
+++ b/smoke/README.md
@@ -1,91 +1,116 @@
-# Local Live Smoke Tests
+# Product E2E Smoke Tests
-`smoke/` is for live/process/service checks only. Hermetic feature contracts
-belong under `tests/` and run with plain `uv run pytest`.
+`smoke/` is local-only. It can launch subprocesses, call real providers, touch
+local model servers, and optionally send/delete bot messages. Hermetic contracts
+belong under `tests/` and must stay green with plain `uv run pytest`.
-## Safe Default Run
+## Taxonomy
+
+- `smoke/prereq/`: liveness checks that prove the server, routes, auth, CLI
+ scripts, provider pings, local `/models`, and bot permissions are reachable.
+ These are prerequisites only.
+- `smoke/product/`: end-to-end product scenarios. Feature smoke coverage comes
+ from these tests, not from route/header/provider pings.
+- `smoke/features.py`: source-of-truth feature map:
+ feature -> subfeature -> scenario -> env -> expected behavior -> failure class.
+
+## Required Local Commands
+
+```powershell
+uv run pytest smoke --collect-only -q
+uv run pytest smoke -n 0 -m live -s --tb=short
+```
+
+The second command skips everything unless `FCC_LIVE_SMOKE=1` is set, but still
+writes skip entries to `.smoke-results/`.
+
+## Product Smoke Run
```powershell
$env:FCC_LIVE_SMOKE = "1"
uv run pytest smoke -n 0 -m live -s --tb=short
```
-`-n 0` is recommended because the normal project pytest config enables xdist.
-The smoke suite can run with workers, but one process gives clearer logs when a
-real provider, bot, or local model server fails.
+Provider product E2E runs for every configured provider model from `MODEL`,
+`MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU`. If no provider is configured,
+live product smoke fails as `missing_env` unless you explicitly set
+`FCC_ALLOW_NO_PROVIDER_SMOKE=1`.
## Targets
-Default targets do not require bot tokens or voice backends:
+Default targets do not send real bot messages or load voice backends:
-| Target | What it checks | Required environment |
+| Target | Product scenarios | Required environment |
| --- | --- | --- |
-| `api` | live uvicorn routes, probes, token count, optimizations, `/stop` fallback | none |
-| `auth` | Anthropic auth header variants on a live server | none; test sets an isolated token |
-| `cli` | `fcc-init`, `free-claude-code`, optional Claude CLI prompt | `claude` and provider config only for the prompt check |
-| `clients` | VS Code and JetBrains-shaped requests | none |
-| `providers` | configured provider model streams | provider keys or local provider URLs |
-| `tools` | configured model emits live tool use | tool-capable configured provider |
-| `rate_limit` | client disconnect does not crash a provider stream | configured provider |
-| `lmstudio` | LM Studio `/models` endpoint is reachable | running LM Studio server |
-| `llamacpp` | llama.cpp `/models` endpoint is reachable | running `llama-server` |
+| `api` | messages, count_tokens full payload, errors, `/stop`, optimizations | configured provider only for streaming messages |
+| `auth` | x-api-key, bearer, anthropic-auth-token, invalid/missing auth | none; test sets an isolated token |
+| `cli` | `fcc-init`, server entrypoint, Claude CLI adaptive thinking, session cleanup | Claude CLI binary and provider only for real CLI |
+| `clients` | VS Code and JetBrains protocol payloads | configured provider |
+| `config` | env precedence, removed-env migration, proxy/timeouts | none |
+| `extensibility` | provider registry and platform factory construction | none |
+| `messaging` | fake Discord/Telegram full flow, commands, trees, persistence, voice cancel | none |
+| `providers` | multi-turn text, adaptive thinking history, tools, disconnect, errors | configured provider models |
+| `tools` | forced tool_use and tool_result continuation | tool-capable configured provider |
+| `rate_limit` | disconnect cleanup and follow-up request | configured provider |
+| `lmstudio` | local `/models` plus native `/messages` through proxy | running LM Studio server |
+| `llamacpp` | local `/models` plus native `/messages` through proxy | running llama-server |
Side-effectful targets are opt-in:
-| Target | What it checks | Required environment |
+| Target | Product scenarios | Required environment |
| --- | --- | --- |
-| `telegram` | bot API getMe, send, edit, delete | `TELEGRAM_BOT_TOKEN` and chat/user ID |
-| `discord` | channel access, send, edit, delete | `DISCORD_BOT_TOKEN` and channel ID |
-| `voice` | configured transcription backend | `VOICE_NOTE_ENABLED=true` and `FCC_SMOKE_RUN_VOICE=1` |
-
-Use `FCC_SMOKE_TARGETS=all` to include Telegram, Discord, and voice checks.
+| `telegram` | getMe, send, edit, delete, optional manual inbound | token and chat/user ID |
+| `discord` | channel access, send, edit, delete, optional manual inbound | token and channel ID |
+| `voice` | generated WAV through local Whisper or NVIDIA NIM transcription | `VOICE_NOTE_ENABLED=true`, `FCC_SMOKE_RUN_VOICE=1` |
-## Targeted Runs
+## Examples
```powershell
$env:FCC_LIVE_SMOKE = "1"
-$env:FCC_SMOKE_TARGETS = "api,providers,tools"
-uv run pytest smoke -n 0 -m live -s --tb=short
+$env:FCC_SMOKE_PROVIDER_MATRIX = "open_router,nvidia_nim,deepseek,lmstudio,llamacpp"
+uv run pytest smoke/product -n 0 -m live -s --tb=short
```
```powershell
$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "telegram,discord,voice"
$env:FCC_SMOKE_RUN_VOICE = "1"
-uv run pytest smoke -n 0 -m live -s --tb=short
+uv run pytest smoke/product -n 0 -m live -s --tb=short
+```
+
+```powershell
+$env:FCC_LIVE_SMOKE = "1"
+$env:FCC_SMOKE_TARGETS = "messaging,config,extensibility"
+uv run pytest smoke/product -n 0 -m live -s --tb=short
```
## Environment
-- `FCC_ENV_FILE`: optional explicit dotenv path. The app still uses its normal
- env-file precedence.
+- `FCC_ENV_FILE`: explicit dotenv path for startup/config scenarios.
+- `FCC_LIVE_SMOKE=1`: enables live smoke execution.
+- `FCC_ALLOW_NO_PROVIDER_SMOKE=1`: permits no-provider live smoke for harness work.
- `FCC_SMOKE_TARGETS`: comma-separated targets, or `all`.
-- `FCC_SMOKE_PROVIDER_MATRIX`: comma-separated provider prefixes to test.
+- `FCC_SMOKE_PROVIDER_MATRIX`: comma-separated provider prefixes to require.
- `FCC_SMOKE_TIMEOUT_S`: per-request/subprocess timeout, default `45`.
- `FCC_SMOKE_CLAUDE_BIN`: Claude CLI executable name, default `claude`.
- `FCC_SMOKE_TELEGRAM_CHAT_ID`: Telegram chat/user ID for send/edit/delete.
- `FCC_SMOKE_DISCORD_CHANNEL_ID`: Discord channel ID for send/edit/delete.
-- `FCC_SMOKE_INTERACTIVE=1`: enables manual inbound messaging checks.
-- `FCC_SMOKE_RUN_VOICE=1`: allows the voice transcription backend to load/run.
-
-## Feature Inventory
-
-The public feature inventory lives in `smoke/features.py`. Each entry records
-whether the feature is covered by hermetic pytest, live smoke, or both, plus the
-owning tests and skip policy. The manifest intentionally excludes `claude-pick`.
-
-## Results And Failure Classes
+- `FCC_SMOKE_INTERACTIVE=1`: enables manual inbound Telegram/Discord checks.
+- `FCC_SMOKE_RUN_VOICE=1`: allows voice transcription backends to load/run.
-Smoke artifacts are written to `.smoke-results/` and ignored by git. Reports and
-logs redact env values whose names contain `KEY`, `TOKEN`, `SECRET`, `WEBHOOK`,
-or `AUTH`.
+## Failure Classes
-Report classifications:
+Smoke artifacts are written to `.smoke-results/` and redact env values whose
+names contain `KEY`, `TOKEN`, `SECRET`, `WEBHOOK`, or `AUTH`.
-- `missing_env`: a credential, opt-in flag, binary, channel, or model config is absent.
-- `upstream_unavailable`: a real provider, bot API, or local model server is not reachable.
-- `product_failure`: the app returned the wrong shape, crashed, or violated a contract.
-- `harness_bug`: the smoke test made an invalid assumption.
+- `missing_env`: required credentials, binary, provider config, local server, or
+ opt-in flag is absent.
+- `upstream_unavailable`: a real provider, bot API, or local model server is not
+ reachable.
+- `product_failure`: the app accepted the scenario but returned the wrong shape,
+ crashed, leaked state, or violated the product contract.
+- `harness_bug`: the smoke test or driver made an invalid assumption.
-`missing_env` and `upstream_unavailable` should skip. `product_failure` and
-`harness_bug` should be fixed before relying on the smoke baseline.
+`product_failure` and `harness_bug` are failures. `missing_env` and
+`upstream_unavailable` are skips except when the user explicitly selected a
+provider in `FCC_SMOKE_PROVIDER_MATRIX`; selected-but-missing providers fail.
diff --git a/smoke/capabilities.py b/smoke/capabilities.py
new file mode 100644
index 00000000..86e1fd6d
--- /dev/null
+++ b/smoke/capabilities.py
@@ -0,0 +1,413 @@
+"""Hierarchical public capability map.
+
+This module is the architectural companion to ``smoke.features``. The feature
+inventory says which public features must be covered; this map records the
+subfeature contracts, owning module boundary, and coverage owners that protect
+them while the internals are refactored.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityContract:
+ capability: str
+ subfeature: str
+ feature_id: str
+ owner: str
+ inputs: str
+ outputs: str
+ failure: str
+ pytest_tests: tuple[str, ...]
+ smoke_tests: tuple[str, ...] = ()
+
+
+CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
+ CapabilityContract(
+ "api_compatibility",
+ "routes_and_probes",
+ "anthropic_api_routes",
+ "api.services.ClaudeProxyService",
+ "Anthropic-compatible HTTP requests",
+ "JSON or Anthropic SSE responses",
+ "HTTPException or Anthropic error payload",
+ ("tests/api/test_api.py",),
+ ("test_probe_and_models_routes", "test_stop_endpoint_reports_no_messaging"),
+ ),
+ CapabilityContract(
+ "api_compatibility",
+ "head_options_probes",
+ "probe_routes",
+ "api.routes",
+ "HEAD/OPTIONS probe requests",
+ "204 with Allow header",
+ "auth failure when configured",
+ ("tests/api/test_api.py::test_probe_endpoints_return_204_with_allow_headers",),
+ ("test_probe_and_models_routes",),
+ ),
+ CapabilityContract(
+ "api_compatibility",
+ "client_request_shapes",
+ "drop_in_claude_code_replacement",
+ "api.services.ClaudeProxyService",
+ "Claude Code, VS Code, and JetBrains shaped requests",
+ "compatible streaming response",
+ "provider or validation error in Anthropic shape",
+ ("tests/api/test_api.py", "tests/cli/test_cli.py"),
+ ("test_vscode_and_jetbrains_shaped_requests",),
+ ),
+ CapabilityContract(
+ "api_compatibility",
+ "client_extensions",
+ "vscode_extension",
+ "api.services.ClaudeProxyService",
+ "VS Code beta query/header variants",
+ "accepted Anthropic-compatible response",
+ "HTTP error only for auth/provider failures",
+ (),
+ ("test_vscode_and_jetbrains_shaped_requests",),
+ ),
+ CapabilityContract(
+ "api_compatibility",
+ "client_extensions",
+ "intellij_extension",
+ "api.services.ClaudeProxyService",
+ "JetBrains/ACP request variants",
+ "accepted Anthropic-compatible response",
+ "HTTP error only for auth/provider failures",
+ (),
+ ("test_vscode_and_jetbrains_shaped_requests",),
+ ),
+ CapabilityContract(
+ "auth",
+ "anthropic_headers",
+ "optional_authentication",
+ "api.dependencies.require_api_key",
+ "x-api-key, authorization, anthropic-auth-token",
+ "request accepted or 401",
+ "401 missing/invalid API key",
+ ("tests/api/test_auth.py",),
+ ("test_auth_token_is_enforced_for_all_supported_header_shapes",),
+ ),
+ CapabilityContract(
+ "provider_routing",
+ "provider_registry",
+ "provider_matrix",
+ "providers.registry.ProviderRegistry",
+ "provider id and Settings",
+ "configured BaseProvider instance",
+ "503 for missing credentials; ValueError for unknown provider",
+ ("tests/api/test_dependencies.py", "tests/providers/test_registry.py"),
+ ("test_configured_provider_models_stream_successfully",),
+ ),
+ CapabilityContract(
+ "provider_routing",
+ "claude_model_resolution",
+ "per_model_mapping",
+ "api.model_router.ModelRouter",
+ "Claude model name and configured MODEL_* values",
+ "provider id plus provider model name",
+ "settings validation rejects invalid provider prefixes",
+ ("tests/api/test_model_router.py", "tests/config/test_config.py"),
+ ("test_model_mapping_configuration_is_consistent",),
+ ),
+ CapabilityContract(
+ "provider_routing",
+ "mixed_provider_resolution",
+ "mixed_provider_mapping",
+ "api.model_router.ModelRouter",
+ "Opus/Sonnet/Haiku/fallback model config",
+ "distinct provider selections per request",
+ "skip live execution when providers are not configured",
+ ("tests/api/test_model_router.py", "tests/config/test_config.py"),
+ ("test_mixed_provider_model_mapping_when_configured",),
+ ),
+ CapabilityContract(
+ "provider_routing",
+ "provider_runtime_config",
+ "provider_proxy_timeout_config",
+ "providers.registry.ProviderRegistry",
+ "provider proxy, timeout, and rate-limit settings",
+ "provider client and scoped limiter config",
+ "provider construction failure",
+ ("tests/api/test_dependencies.py", "tests/providers/test_registry.py"),
+ ),
+ CapabilityContract(
+ "provider_routing",
+ "zero_cost_backends",
+ "zero_cost_provider_access",
+ "providers.registry.ProviderRegistry",
+ "configured free/local provider",
+ "streaming response from selected backend",
+ "missing env or upstream unavailable skip in smoke",
+ ("tests/api/test_dependencies.py", "tests/providers/"),
+ ("test_configured_provider_models_stream_successfully",),
+ ),
+ CapabilityContract(
+ "streaming_conversion",
+ "anthropic_sse_lifecycle",
+ "streaming_error_mapping",
+ "providers.common.SSEBuilder",
+ "provider stream chunks or native SSE events",
+ "Anthropic message/content/error SSE lifecycle",
+ "Anthropic-compatible error event",
+ (
+ "tests/contracts/test_stream_contracts.py",
+ "tests/providers/test_streaming_errors.py",
+ ),
+ ),
+ CapabilityContract(
+ "streaming_conversion",
+ "thinking_blocks",
+ "thinking_token_support",
+ "providers.common.think_parser",
+ "reasoning_content, reasoning_details, <think> text, native thinking",
+ "Claude thinking blocks or suppression",
+ "thinking hidden when disabled",
+ (
+ "tests/contracts/test_stream_contracts.py",
+ "tests/providers/test_open_router.py",
+ ),
+ ),
+ CapabilityContract(
+ "streaming_conversion",
+ "heuristic_tools",
+ "heuristic_tool_parser",
+ "providers.common.heuristic_tool_parser",
+ "textual tool-call output",
+ "structured Anthropic tool_use blocks",
+ "text fallback when malformed",
+ ("tests/providers/test_parsers.py", "tests/contracts/test_stream_contracts.py"),
+ ("test_live_tool_use_when_configured_model_supports_tools",),
+ ),
+ CapabilityContract(
+ "streaming_conversion",
+ "subagent_task_control",
+ "subagent_control",
+ "providers.common.SSEBuilder",
+ "Task tool call arguments",
+ "run_in_background=false",
+ "invalid JSON flushed as safe object",
+ ("tests/providers/test_subagent_interception.py",),
+ ),
+ CapabilityContract(
+ "request_behavior",
+ "local_optimizations",
+ "request_optimization",
+ "api.optimization_handlers",
+ "Claude Code probe/title/suggestion/filepath requests",
+ "local MessagesResponse without provider call",
+ "falls through to provider when unmatched/disabled",
+ (
+ "tests/api/test_optimization_handlers.py",
+ "tests/api/test_routes_optimizations.py",
+ ),
+ ("test_optimization_fast_paths_do_not_need_provider",),
+ ),
+ CapabilityContract(
+ "request_behavior",
+ "token_counting",
+ "count_tokens_contract",
+ "api.request_utils",
+ "messages, system blocks, tools, images, thinking, tool results",
+ "positive input token estimate",
+ "500 with readable detail on unexpected failure",
+ ("tests/api/test_request_utils.py",),
+ ("test_count_tokens_accepts_thinking_tools_and_results",),
+ ),
+ CapabilityContract(
+ "config",
+ "env_precedence",
+ "config_env_precedence",
+ "config.settings.Settings",
+ "process env, user env file, repo env file, FCC_ENV_FILE",
+ "deterministic settings values",
+ "validation error for invalid settings",
+ ("tests/config/test_config.py",),
+ ),
+ CapabilityContract(
+ "config",
+ "removed_env_migration",
+ "removed_env_migration",
+ "config.settings.Settings",
+ "NIM_ENABLE_THINKING in env or dotenv",
+ "startup validation error with rename guidance",
+ "application fails fast",
+ ("tests/config/test_config.py",),
+ ),
+ CapabilityContract(
+ "provider_runtime",
+ "rate_limit_and_disconnect",
+ "smart_rate_limiting",
+ "providers.rate_limit.GlobalRateLimiter",
+ "concurrent provider requests and 429/disconnect failures",
+ "proactive throttle, retry, cleanup",
+ "mapped provider error or smoke skip for upstream disconnect",
+ ("tests/providers/test_provider_rate_limit.py",),
+ ("test_client_disconnect_mid_stream_does_not_crash_server",),
+ ),
+ CapabilityContract(
+ "local_providers",
+ "lmstudio_native_messages",
+ "lmstudio_endpoint",
+ "providers.anthropic_messages.AnthropicMessagesTransport",
+ "Anthropic request body and local LM Studio URL",
+ "native /messages stream pass-through",
+ "SSE error event for local upstream failure",
+ (
+ "tests/providers/test_lmstudio.py",
+ "tests/providers/test_anthropic_messages.py",
+ ),
+ ("test_lmstudio_models_endpoint_when_available",),
+ ),
+ CapabilityContract(
+ "local_providers",
+ "llamacpp_native_messages",
+ "llamacpp_endpoint",
+ "providers.anthropic_messages.AnthropicMessagesTransport",
+ "Anthropic request body and llama.cpp URL",
+ "native /messages stream pass-through",
+ "SSE error event for local upstream failure",
+ (
+ "tests/providers/test_llamacpp.py",
+ "tests/providers/test_anthropic_messages.py",
+ ),
+ ("test_llamacpp_models_endpoint_when_available",),
+ ),
+ CapabilityContract(
+ "openrouter",
+ "native_anthropic_messages",
+ "provider_matrix",
+ "providers.open_router.OpenRouterProvider",
+ "Anthropic Messages request for OpenRouter",
+ "native OpenRouter Anthropic SSE",
+ "Anthropic SSE error shape",
+ (
+ "tests/providers/test_open_router.py",
+ "tests/providers/test_anthropic_messages.py",
+ ),
+ ("test_configured_provider_models_stream_successfully",),
+ ),
+ CapabilityContract(
+ "messaging",
+ "discord_telegram_platforms",
+ "discord_telegram_bot",
+ "messaging.handler.ClaudeMessageHandler",
+ "Discord/Telegram incoming messages and API callbacks",
+ "live progress edits and final transcript",
+ "platform retry/fallback or user-facing error",
+ (
+ "tests/messaging/test_discord_platform.py",
+ "tests/messaging/test_telegram.py",
+ ),
+ ("test_telegram_bot_api_permissions", "test_discord_bot_api_permissions"),
+ ),
+ CapabilityContract(
+ "messaging",
+ "commands",
+ "messaging_commands",
+ "messaging.commands",
+ "/stop, /clear, /stats command messages",
+ "task cancellation, cleanup, or stats response",
+ "best-effort platform cleanup",
+ (
+ "tests/messaging/test_handler.py",
+ "tests/messaging/test_handler_integration.py",
+ ),
+ ),
+ CapabilityContract(
+ "messaging",
+ "tree_threading",
+ "tree_threading",
+ "messaging.trees.TreeQueueManager",
+ "reply-based message graph",
+ "queued branches and scoped cancellation",
+ "node error propagation",
+ (
+ "tests/messaging/test_tree_queue.py",
+ "tests/messaging/test_tree_concurrency.py",
+ ),
+ ),
+ CapabilityContract(
+ "persistence",
+ "restart_restore",
+ "restart_restore",
+ "messaging.session.SessionStore",
+ "stored tree JSON",
+ "restored node-to-tree mapping",
+ "stale pending work marked lost",
+ ("tests/messaging/test_restart_reply_restore.py",),
+ ),
+ CapabilityContract(
+ "persistence",
+ "session_store",
+ "session_persistence",
+ "messaging.session.SessionStore",
+ "tree data, node mapping, and message log",
+ "JSON persistence compatible with existing files",
+ "best-effort flush error logging",
+ ("tests/messaging/test_session_store_edge_cases.py",),
+ ),
+ CapabilityContract(
+ "voice",
+ "voice_transcription",
+ "voice_notes",
+ "messaging.voice.VoiceTranscriptionService",
+ "Discord/Telegram audio file and voice backend settings",
+ "transcribed prompt routed to handler",
+ "missing optional extra or backend error shown to user",
+ (
+ "tests/messaging/test_voice_handlers.py",
+ "tests/messaging/test_transcription.py",
+ ),
+ ("test_voice_transcription_backend_when_explicitly_enabled",),
+ ),
+ CapabilityContract(
+ "cli",
+ "package_entrypoints",
+ "package_cli_entrypoints",
+ "cli.entrypoints",
+ "installed console scripts",
+ "config scaffold or uvicorn server startup",
+ "process cleanup in finally",
+ ("tests/cli/test_entrypoints.py",),
+ (
+ "test_fcc_init_scaffolds_user_config",
+ "test_free_claude_code_entrypoint_starts_server",
+ ),
+ ),
+ CapabilityContract(
+ "cli",
+ "claude_cli_drop_in",
+ "claude_cli_drop_in",
+ "cli.session.CLISession",
+ "Claude CLI binary and proxy env",
+ "stream-json events and session id mapping",
+ "stderr/error event and process cleanup",
+ ("tests/cli/test_cli.py",),
+ ("test_claude_cli_prompt_when_available",),
+ ),
+ CapabilityContract(
+ "extensibility",
+ "provider_platform_abcs",
+ "extensible_provider_platform_abcs",
+ "providers.registry and messaging.platforms.factory",
+ "new provider/platform implementations",
+ "registered BaseProvider or MessagingPlatform",
+ "unknown platform returns None; unknown provider errors",
+ (
+ "tests/contracts/test_feature_manifest.py",
+ "tests/providers/test_registry.py",
+ ),
+ ),
+)
+
+
+def capability_names() -> set[str]:
+ return {contract.capability for contract in CAPABILITY_CONTRACTS}
+
+
+def contracted_feature_ids() -> set[str]:
+ return {contract.feature_id for contract in CAPABILITY_CONTRACTS}
diff --git a/smoke/features.py b/smoke/features.py
index 7e11552e..1b73b2e4 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -1,8 +1,9 @@
-"""Public feature inventory for pytest contracts and live smoke checks.
+"""Public feature inventory for contract, prerequisite, and product smoke tests.
-The inventory is intentionally explicit. README features and exposed public
-surface area should have either hermetic pytest coverage, live smoke coverage,
-or both. Private helpers are not listed here.
+The inventory is intentionally explicit. README-advertised behavior and exposed
+public surface area must have deterministic pytest contract coverage plus a
+product E2E scenario when that behavior is a user-facing product path. Liveness
+and route probes live in ``smoke/prereq`` and do not count as product coverage.
"""
from __future__ import annotations
@@ -11,7 +12,6 @@ from dataclasses import dataclass
from typing import Literal
FeatureSource = Literal["readme", "public_surface"]
-CoverageKind = Literal["pytest", "live_smoke", "both"]
@dataclass(frozen=True, slots=True)
@@ -19,20 +19,41 @@ class FeatureCoverage:
feature_id: str
title: str
source: FeatureSource
- coverage: CoverageKind
- pytest_tests: tuple[str, ...]
- smoke_tests: tuple[str, ...]
+ pytest_contract_tests: tuple[str, ...]
+ live_prereq_tests: tuple[str, ...]
+ product_e2e_tests: tuple[str, ...]
smoke_targets: tuple[str, ...]
required_env: tuple[str, ...]
skip_policy: str
+ product_e2e_reason: str = ""
@property
def has_pytest_coverage(self) -> bool:
- return self.coverage in {"pytest", "both"}
+ return bool(self.pytest_contract_tests)
+
+ @property
+ def has_live_prereq_coverage(self) -> bool:
+ return bool(self.live_prereq_tests)
+
+ @property
+ def has_product_e2e_coverage(self) -> bool:
+ return bool(self.product_e2e_tests)
@property
def has_smoke_coverage(self) -> bool:
- return self.coverage in {"live_smoke", "both"}
+ return self.has_product_e2e_coverage
+
+ @property
+ def pytest_tests(self) -> tuple[str, ...]:
+ return self.pytest_contract_tests
+
+ @property
+ def smoke_tests(self) -> tuple[str, ...]:
+ return self.product_e2e_tests
+
+ @property
+ def all_smoke_tests(self) -> tuple[str, ...]:
+ return self.live_prereq_tests + self.product_e2e_tests
README_FEATURES: tuple[str, ...] = (
@@ -57,122 +78,124 @@ README_FEATURES: tuple[str, ...] = (
FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"zero_cost_provider_access",
- "Configured provider accepts a real prompt",
+ "Configured provider accepts real conversation turns",
"readme",
- "both",
- ("tests/api/test_dependencies.py", "tests/providers/test_open_router.py"),
+ ("tests/api/test_dependencies.py", "tests/providers/"),
("test_configured_provider_models_stream_successfully",),
+ ("test_provider_text_multiturn_e2e",),
("providers",),
- ("NVIDIA_NIM_API_KEY|OPENROUTER_API_KEY|DEEPSEEK_API_KEY|local provider",),
- "skip when no usable provider credentials or local provider endpoint exists",
+ ("configured provider credentials or local provider endpoint",),
+ "missing providers are missing_env unless FCC_ALLOW_NO_PROVIDER_SMOKE=1",
),
FeatureCoverage(
"drop_in_claude_code_replacement",
- "Claude-compatible routes and CLI environment work",
+ "Claude-compatible API, CLI, and editor protocol flows work",
"readme",
- "both",
("tests/api/test_api.py", "tests/cli/test_cli.py"),
+ ("test_probe_and_models_routes", "test_claude_cli_prompt_when_available"),
(
- "test_probe_and_models_routes",
- "test_claude_cli_prompt_when_available",
- "test_vscode_and_jetbrains_shaped_requests",
+ "test_api_basic_conversation_e2e",
+ "test_claude_cli_adaptive_thinking_e2e",
+ "test_vscode_protocol_e2e",
+ "test_jetbrains_protocol_e2e",
),
("api", "cli", "clients"),
- ("FCC_SMOKE_CLAUDE_BIN", "configured provider for Claude CLI"),
- "skip Claude CLI path when binary or provider config is unavailable",
+ ("configured provider", "FCC_SMOKE_CLAUDE_BIN for real Claude CLI"),
+ "skip real CLI when binary is absent; configured providers must pass",
),
FeatureCoverage(
"provider_matrix",
- "All configured provider prefixes can be exercised",
+ "Every configured provider prefix can satisfy conversation scenarios",
"readme",
- "both",
("tests/api/test_dependencies.py", "tests/providers/"),
("test_configured_provider_models_stream_successfully",),
+ ("test_provider_matrix_presence_e2e", "test_provider_text_multiturn_e2e"),
("providers",),
("MODEL", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"),
- "skip when no configured provider has usable credentials/base URL",
+ "selected providers missing credentials are failing missing_env",
),
FeatureCoverage(
"per_model_mapping",
- "Opus, Sonnet, Haiku, and fallback mappings are visible",
+ "Opus, Sonnet, Haiku, and fallback mappings route explicitly",
"readme",
- "both",
- ("tests/api/test_models_validators.py", "tests/config/test_config.py"),
+ ("tests/api/test_model_router.py", "tests/config/test_config.py"),
("test_model_mapping_configuration_is_consistent",),
+ ("test_model_mapping_matrix_e2e",),
("providers",),
("MODEL", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"),
- "skip live provider execution when no provider config is usable",
+ "skip only when live smoke is intentionally allowed to run with no provider",
),
FeatureCoverage(
"mixed_provider_mapping",
"Model-specific overrides can route to different providers",
"public_surface",
- "both",
- ("tests/config/test_config.py",),
+ ("tests/api/test_model_router.py", "tests/config/test_config.py"),
("test_mixed_provider_model_mapping_when_configured",),
+ ("test_model_mapping_matrix_e2e",),
("providers",),
("MODEL", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"),
- "skip when fewer than two configured provider prefixes are present",
+ "configured mixed-provider mappings must resolve consistently",
),
FeatureCoverage(
"thinking_token_support",
- "Thinking streams and suppression are contract-tested",
+ "Thinking history, adaptive thinking, and redacted blocks are accepted",
"readme",
- "pytest",
(
- "test_interleaved_thinking_text_blocks_are_valid",
- "test_split_think_tags_preserve_text_and_thinking",
- "test_enable_thinking_false_suppresses_reasoning_only",
+ "tests/contracts/test_stream_contracts.py",
+ "tests/providers/test_open_router.py",
),
(),
- (),
- (),
- "hermetic contract coverage",
+ (
+ "test_provider_adaptive_thinking_history_e2e",
+ "test_claude_cli_adaptive_thinking_e2e",
+ ),
+ ("providers", "cli"),
+ ("configured provider",),
+ "configured providers must not reject adaptive thinking payloads",
),
FeatureCoverage(
"heuristic_tool_parser",
- "Text tool calls become structured tool_use blocks",
+ "Tool use and tool result continuation survive provider/client paths",
"readme",
- "both",
+ ("tests/providers/test_parsers.py", "tests/contracts/test_stream_contracts.py"),
+ ("test_live_tool_use_when_configured_model_supports_tools",),
(
- "tests/providers/test_parsers.py",
- "test_thinking_tool_text_and_transcript_order_contract",
+ "test_provider_interleaved_thinking_tool_e2e",
+ "test_provider_tool_result_continuation_e2e",
),
- ("test_live_tool_use_when_configured_model_supports_tools",),
- ("tools",),
+ ("tools", "providers"),
("configured tool-capable provider",),
- "skip live tool-use when no configured provider model is available",
+ "tool-capable configured providers must emit or continue tool results",
),
FeatureCoverage(
"request_optimization",
- "Fast-path local optimizations respond without providers",
+ "Local request optimizations return product responses without providers",
"readme",
- "both",
(
"tests/api/test_optimization_handlers.py",
"tests/api/test_routes_optimizations.py",
),
("test_optimization_fast_paths_do_not_need_provider",),
+ ("test_api_request_optimizations_e2e",),
("api",),
(),
- "always runnable once live server starts",
+ "always runnable once the local smoke server starts",
),
FeatureCoverage(
"smart_rate_limiting",
- "Provider limiter covers proactive throttling, 429 retry, and disconnects",
+ "Disconnect and limiter cleanup preserve follow-up requests",
"readme",
- "both",
("tests/providers/test_provider_rate_limit.py",),
("test_client_disconnect_mid_stream_does_not_crash_server",),
+ ("test_provider_disconnect_e2e",),
("rate_limit", "providers"),
("configured provider",),
- "skip live disconnect path when no configured provider model is available",
+ "upstream disconnects are skips only when classified upstream_unavailable",
),
FeatureCoverage(
"discord_telegram_bot",
- "Messaging credentials, send/edit/delete, and transcript behavior",
+ "Discord and Telegram product flows render progress and transcripts",
"readme",
- "both",
(
"tests/messaging/test_discord_platform.py",
"tests/messaging/test_telegram.py",
@@ -180,265 +203,287 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
(
"test_telegram_bot_api_permissions",
"test_discord_bot_api_permissions",
- "test_interactive_inbound_messaging_requires_explicit_mode",
),
- ("telegram", "discord"),
(
- "TELEGRAM_BOT_TOKEN",
- "ALLOWED_TELEGRAM_USER_ID|FCC_SMOKE_TELEGRAM_CHAT_ID",
- "DISCORD_BOT_TOKEN",
- "ALLOWED_DISCORD_CHANNELS|FCC_SMOKE_DISCORD_CHANNEL_ID",
+ "test_messaging_fake_full_flow_e2e",
+ "test_telegram_live_permissions_e2e",
+ "test_discord_live_permissions_e2e",
),
- "skip when bot tokens/channels are absent; inbound checks require interactive mode",
+ ("messaging", "telegram", "discord"),
+ ("bot tokens/channels only for side-effectful live platform tests",),
+ "fake platform is required; real platforms skip without explicit env",
),
FeatureCoverage(
"subagent_control",
- "Task tool calls do not run in the background",
+ "Task-like tool output is rendered and controlled as foreground work",
"readme",
- "pytest",
- (
- "tests/providers/test_subagent_interception.py",
- "test_thinking_tool_text_and_transcript_order_contract",
- ),
- (),
+ ("tests/providers/test_subagent_interception.py",),
(),
+ ("test_messaging_subagent_control_e2e",),
+ ("messaging",),
(),
- "hermetic contract coverage",
+ "fake platform exercises tool transcript behavior without spawning agents",
),
FeatureCoverage(
"extensible_provider_platform_abcs",
- "Provider/platform registries expose expected built-ins",
+ "Provider and platform factories expose built-in extension points",
"readme",
- "pytest",
- ("test_provider_and_platform_registries_include_advertised_builtins",),
- (),
+ (
+ "tests/contracts/test_feature_manifest.py",
+ "tests/providers/test_registry.py",
+ ),
(),
+ ("test_provider_registry_e2e", "test_platform_factory_e2e"),
+ ("extensibility",),
(),
- "hermetic contract coverage",
+ "always runnable with isolated settings",
),
FeatureCoverage(
"optional_authentication",
- "Anthropic-style auth headers are accepted and enforced",
+ "Anthropic-style auth headers are enforced and accepted",
"readme",
- "both",
("tests/api/test_auth.py",),
("test_auth_token_is_enforced_for_all_supported_header_shapes",),
+ ("test_api_auth_header_variants_e2e",),
("auth",),
("ANTHROPIC_AUTH_TOKEN",),
- "live test starts an isolated server with its own token",
+ "product test starts an isolated token-protected server",
),
FeatureCoverage(
"vscode_extension",
- "VS Code-shaped beta requests work against the proxy",
+ "VS Code protocol-shaped requests work against the proxy",
"readme",
- "live_smoke",
- (),
+ (
+ "tests/api/test_models_validators.py::test_messages_request_accepts_adaptive_thinking_type",
+ ),
("test_vscode_and_jetbrains_shaped_requests",),
+ ("test_vscode_protocol_e2e",),
("clients",),
- (),
- "always runnable once live server starts",
+ ("configured provider",),
+ "extension source is external; protocol payload is covered here",
),
FeatureCoverage(
"intellij_extension",
- "JetBrains/ACP-shaped environment requests work against the proxy",
+ "JetBrains/ACP protocol-shaped requests work against the proxy",
"readme",
- "live_smoke",
- (),
+ (
+ "tests/api/test_models_validators.py::test_messages_request_accepts_adaptive_thinking_type",
+ ),
("test_vscode_and_jetbrains_shaped_requests",),
+ ("test_jetbrains_protocol_e2e",),
("clients",),
- (),
- "always runnable once live server starts",
+ ("configured provider",),
+ "extension source is external; protocol payload is covered here",
),
FeatureCoverage(
"voice_notes",
- "Configured transcription backend can process an audio fixture",
+ "Voice note intake, cancellation, and transcription backends work",
"readme",
- "both",
(
"tests/messaging/test_voice_handlers.py",
"tests/messaging/test_transcription.py",
),
("test_voice_transcription_backend_when_explicitly_enabled",),
- ("voice",),
+ (
+ "test_voice_platform_fake_e2e",
+ "test_voice_local_backend_e2e",
+ "test_voice_nim_backend_e2e",
+ ),
+ ("messaging", "voice"),
("VOICE_NOTE_ENABLED", "FCC_SMOKE_RUN_VOICE", "WHISPER_DEVICE"),
- "skip unless voice is explicitly enabled for local smoke",
+ "fake cancellation is required; backend transcription is opt-in",
),
FeatureCoverage(
"anthropic_api_routes",
- "Root, health, models, messages, count_tokens, and stop routes respond",
+ "Messages, count_tokens, errors, and stop use Anthropic-compatible shapes",
"public_surface",
- "both",
("tests/api/test_api.py",),
("test_probe_and_models_routes", "test_stop_endpoint_reports_no_messaging"),
+ (
+ "test_api_basic_conversation_e2e",
+ "test_api_count_tokens_full_payload_e2e",
+ "test_api_error_shape_e2e",
+ "test_api_stop_e2e",
+ ),
("api",),
- (),
- "always runnable once live server starts",
+ ("configured provider for streaming messages",),
+ "route pings are prereqs; product route behavior is covered by E2E cases",
),
FeatureCoverage(
"probe_routes",
- "HEAD and OPTIONS compatibility probes return 204 and Allow headers",
+ "HEAD and OPTIONS compatibility probes are accepted",
"public_surface",
- "both",
("tests/api/test_api.py::test_probe_endpoints_return_204_with_allow_headers",),
("test_probe_and_models_routes",),
+ (),
("api",),
(),
- "always runnable once live server starts",
+ "always runnable once the local smoke server starts",
+ "probe routes are compatibility prerequisites, not product behavior",
),
FeatureCoverage(
"count_tokens_contract",
- "Token counting accepts text, thinking, tools, tool results, and images",
+ "Token counting accepts full Claude content payloads",
"public_surface",
- "both",
("tests/api/test_request_utils.py",),
("test_count_tokens_accepts_thinking_tools_and_results",),
+ ("test_api_count_tokens_full_payload_e2e",),
("api",),
(),
- "always runnable once live server starts",
+ "always runnable once the local smoke server starts",
),
FeatureCoverage(
"provider_proxy_timeout_config",
- "Provider proxies and HTTP timeouts are passed into clients",
+ "Provider proxies and HTTP timeout settings reach provider config",
"public_surface",
- "pytest",
- ("tests/api/test_dependencies.py",),
+ ("tests/api/test_dependencies.py", "tests/providers/test_registry.py"),
(),
+ ("test_proxy_timeout_config_e2e",),
+ ("config",),
(),
- (),
- "hermetic config coverage",
+ "always runnable with isolated env files",
),
FeatureCoverage(
"lmstudio_endpoint",
- "Configured LM Studio endpoint exposes an OpenAI-compatible models route",
+ "LM Studio native messages and local no-key operation work when running",
"public_surface",
- "both",
- ("tests/providers/test_lmstudio.py",),
+ (
+ "tests/providers/test_lmstudio.py",
+ "tests/providers/test_anthropic_messages.py",
+ ),
("test_lmstudio_models_endpoint_when_available",),
+ ("test_lmstudio_native_messages_e2e",),
("lmstudio",),
- ("LM_STUDIO_BASE_URL",),
- "skip when the local LM Studio server is not reachable",
+ ("LM_STUDIO_BASE_URL with running LM Studio server",),
+ "skip when local upstream is unavailable",
),
FeatureCoverage(
"llamacpp_endpoint",
- "Configured llama.cpp endpoint exposes an OpenAI-compatible models route",
+ "llama.cpp native messages and local no-key operation work when running",
"public_surface",
- "both",
- ("tests/providers/test_llamacpp.py",),
+ (
+ "tests/providers/test_llamacpp.py",
+ "tests/providers/test_anthropic_messages.py",
+ ),
("test_llamacpp_models_endpoint_when_available",),
+ ("test_llamacpp_native_messages_e2e",),
("llamacpp",),
- ("LLAMACPP_BASE_URL",),
- "skip when the local llama.cpp server is not reachable",
+ ("LLAMACPP_BASE_URL with running llama-server",),
+ "skip when local upstream is unavailable",
),
FeatureCoverage(
"package_cli_entrypoints",
"Installed package scripts scaffold config and start the server",
"public_surface",
- "both",
("tests/cli/test_entrypoints.py",),
(
"test_fcc_init_scaffolds_user_config",
"test_free_claude_code_entrypoint_starts_server",
),
+ ("test_entrypoint_init_e2e", "test_entrypoint_server_e2e"),
("cli",),
(),
"always runnable once uv project dependencies are available",
),
FeatureCoverage(
"claude_cli_drop_in",
- "Claude CLI can send a prompt through the proxy when installed",
+ "Claude CLI can send adaptive thinking and tool-shaped history",
"public_surface",
- "live_smoke",
- (),
+ ("tests/cli/test_cli.py",),
("test_claude_cli_prompt_when_available",),
+ (
+ "test_claude_cli_adaptive_thinking_e2e",
+ "test_claude_cli_multiturn_tool_protocol_e2e",
+ ),
("cli",),
("FCC_SMOKE_CLAUDE_BIN", "configured provider"),
- "skip when Claude CLI or provider config is unavailable",
+ "skip only when Claude CLI binary is absent",
),
FeatureCoverage(
"messaging_commands",
- "Messaging /stop, /clear, and /stats commands use platform queues safely",
+ "Messaging /stop, /clear, and /stats operate on product state",
"public_surface",
- "pytest",
(
"tests/messaging/test_handler.py",
"tests/messaging/test_handler_integration.py",
),
(),
+ ("test_messaging_commands_stop_clear_stats_e2e",),
+ ("messaging",),
(),
- (),
- "hermetic messaging handler coverage",
+ "required fake-platform product flow",
),
FeatureCoverage(
"tree_threading",
- "Reply-based message trees support queueing, branching, and cancellation",
+ "Reply-based branches fork sessions and stay scoped",
"public_surface",
- "pytest",
(
"tests/messaging/test_tree_queue.py",
"tests/messaging/test_tree_concurrency.py",
),
(),
+ ("test_tree_threading_e2e",),
+ ("messaging",),
(),
- (),
- "hermetic tree queue coverage",
+ "required fake-platform product flow",
),
FeatureCoverage(
"restart_restore",
- "Persisted tree state is restored after restart for reply routing",
+ "Persisted tree state restores reply routing after restart",
"public_surface",
- "pytest",
("tests/messaging/test_restart_reply_restore.py",),
(),
+ ("test_restart_restore_and_session_persistence_e2e",),
+ ("messaging",),
(),
- (),
- "hermetic persistence coverage",
+ "required fake-platform persistence flow",
),
FeatureCoverage(
"session_persistence",
- "SessionStore persists trees, node mappings, and message logs",
+ "Session JSON preserves trees, node mapping, and message logs",
"public_surface",
- "pytest",
("tests/messaging/test_session_store_edge_cases.py",),
(),
+ ("test_restart_restore_and_session_persistence_e2e",),
+ ("messaging",),
(),
- (),
- "hermetic persistence coverage",
+ "required fake-platform persistence flow",
),
FeatureCoverage(
"config_env_precedence",
- "Environment and dotenv precedence are deterministic",
+ "FCC_ENV_FILE, dotenv, and process env precedence are deterministic",
"public_surface",
- "pytest",
("tests/config/test_config.py",),
(),
+ ("test_env_precedence_e2e",),
+ ("config",),
(),
- (),
- "hermetic config coverage",
+ "always runnable with isolated env files",
),
FeatureCoverage(
"removed_env_migration",
- "Removed NIM_ENABLE_THINKING env var fails fast with migration guidance",
+ "Removed env vars fail fast with migration guidance",
"public_surface",
- "pytest",
("tests/config/test_config.py",),
(),
+ ("test_removed_env_migration_e2e",),
+ ("config",),
(),
- (),
- "hermetic config coverage",
+ "always runnable with isolated env files",
),
FeatureCoverage(
"streaming_error_mapping",
- "Provider and streaming errors map to Anthropic-compatible error shapes",
+ "Provider and validation errors map to Anthropic-compatible payloads",
"public_surface",
- "pytest",
(
"tests/providers/test_streaming_errors.py",
"tests/providers/test_error_mapping.py",
),
(),
- (),
- (),
- "hermetic provider coverage",
+ ("test_api_error_shape_e2e", "test_provider_error_e2e"),
+ ("api", "providers"),
+ ("configured provider for provider error scenario",),
+ "invalid request path is required; provider error path requires provider",
),
)
@@ -452,10 +497,24 @@ def feature_ids(*, source: FeatureSource | None = None) -> set[str]:
}
-def smoke_feature_ids() -> set[str]:
- """Return feature IDs with at least one live smoke owner."""
+def product_smoke_feature_ids() -> set[str]:
+ """Return feature IDs with at least one product E2E owner."""
+ return {
+ feature.feature_id
+ for feature in FEATURE_INVENTORY
+ if feature.has_product_e2e_coverage
+ }
+
+
+def live_prereq_feature_ids() -> set[str]:
+ """Return feature IDs with prerequisite/live probe owners."""
return {
feature.feature_id
for feature in FEATURE_INVENTORY
- if feature.has_smoke_coverage
+ if feature.has_live_prereq_coverage
}
+
+
+def smoke_feature_ids() -> set[str]:
+ """Backward-compatible alias for product smoke feature IDs."""
+ return product_smoke_feature_ids()
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 3862b651..5e7386b3 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -15,8 +15,11 @@ DEFAULT_TARGETS = frozenset(
"auth",
"cli",
"clients",
+ "config",
+ "extensibility",
"llamacpp",
"lmstudio",
+ "messaging",
"providers",
"rate_limit",
"tools",
@@ -38,6 +41,9 @@ TARGET_REQUIRED_ENV: dict[str, tuple[str, ...]] = {
"auth": (),
"cli": ("FCC_SMOKE_CLAUDE_BIN", "configured provider for Claude CLI prompt"),
"clients": (),
+ "config": (),
+ "extensibility": (),
+ "messaging": (),
"providers": ("MODEL or MODEL_* with usable provider configuration",),
"rate_limit": ("configured provider model",),
"tools": ("configured tool-capable provider model",),
diff --git a/smoke/lib/e2e.py b/smoke/lib/e2e.py
new file mode 100644
index 00000000..d5e05928
--- /dev/null
+++ b/smoke/lib/e2e.py
@@ -0,0 +1,675 @@
+"""Reusable product E2E smoke drivers."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+import time
+import uuid
+import wave
+from collections.abc import AsyncGenerator, Awaitable, Callable, Iterator, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+
+from messaging.handler import ClaudeMessageHandler
+from messaging.models import IncomingMessage
+from messaging.platforms.base import MessagingPlatform
+from messaging.session import SessionStore
+from smoke.lib.config import ProviderModel, SmokeConfig, auth_headers
+from smoke.lib.server import RunningServer, start_server
+from smoke.lib.skips import fail_missing_env
+from smoke.lib.sse import (
+ SSEEvent,
+ assert_anthropic_stream_contract,
+ has_tool_use,
+ parse_sse_lines,
+ text_content,
+)
+
+
+@dataclass(slots=True)
+class ConversationTurn:
+ request: dict[str, Any]
+ events: list[SSEEvent]
+
+ @property
+ def assistant_content(self) -> list[dict[str, Any]]:
+ return assistant_content_from_events(self.events)
+
+ @property
+ def text(self) -> str:
+ return text_content(self.events)
+
+
+class SmokeServerDriver:
+ """Start a local proxy server for a product scenario."""
+
+ def __init__(
+ self,
+ config: SmokeConfig,
+ *,
+ name: str,
+ env_overrides: dict[str, str] | None = None,
+ command: list[str] | None = None,
+ ) -> None:
+ self.config = config
+ self.name = name
+ self.env_overrides = env_overrides
+ self.command = command
+
+ @contextmanager
+ def run(self) -> Iterator[RunningServer]:
+ with start_server(
+ self.config,
+ env_overrides=self.env_overrides,
+ command=self.command,
+ name=self.name,
+ ) as server:
+ yield server
+
+
+class ConversationDriver:
+ """Drive multi-turn Anthropic-compatible conversations through the server."""
+
+ def __init__(self, server: RunningServer, config: SmokeConfig) -> None:
+ self.server = server
+ self.config = config
+ self.messages: list[dict[str, Any]] = []
+ self.turns: list[ConversationTurn] = []
+
+ def ask(
+ self,
+ text: str,
+ *,
+ model: str = "fcc-smoke-default",
+ max_tokens: int = 256,
+ extra: dict[str, Any] | None = None,
+ headers: dict[str, str] | None = None,
+ append_assistant: bool = True,
+ ) -> ConversationTurn:
+ self.messages.append({"role": "user", "content": text})
+ payload = {
+ "model": model,
+ "max_tokens": max_tokens,
+ "messages": list(self.messages),
+ }
+ if extra:
+ payload.update(extra)
+ turn = self.stream(payload, headers=headers)
+ if append_assistant:
+ self.messages.append(
+ {"role": "assistant", "content": turn.assistant_content or turn.text}
+ )
+ return turn
+
+ def stream(
+ self,
+ payload: dict[str, Any],
+ *,
+ headers: dict[str, str] | None = None,
+ ) -> ConversationTurn:
+ request_headers = headers or auth_headers()
+ with httpx.stream(
+ "POST",
+ f"{self.server.base_url}/v1/messages",
+ headers=request_headers,
+ json=payload,
+ timeout=self.config.timeout_s,
+ ) as response:
+ if response.status_code != 200:
+ body = response.read().decode("utf-8", errors="replace")
+ raise AssertionError(
+ f"stream request failed: HTTP {response.status_code} {body[:1000]}"
+ )
+ events = parse_sse_lines(response.iter_lines())
+ assert_anthropic_stream_contract(events)
+ turn = ConversationTurn(payload, events)
+ self.turns.append(turn)
+ return turn
+
+ def stream_expect_http_error(
+ self,
+ payload: dict[str, Any],
+ *,
+ expected_status: int,
+ ) -> dict[str, Any]:
+ response = httpx.post(
+ f"{self.server.base_url}/v1/messages",
+ headers=auth_headers(),
+ json=payload,
+ timeout=self.config.timeout_s,
+ )
+ assert response.status_code == expected_status, response.text
+ return response.json()
+
+
+class ProviderMatrixDriver:
+ """Resolve provider models and enforce matrix semantics for product smoke."""
+
+ ALL_PROVIDERS = ("nvidia_nim", "open_router", "deepseek", "lmstudio", "llamacpp")
+
+ def __init__(self, config: SmokeConfig) -> None:
+ self.config = config
+
+ def configured_models(self) -> list[ProviderModel]:
+ selected = self.config.provider_matrix
+ missing_selected = [
+ provider
+ for provider in selected
+ if provider in self.ALL_PROVIDERS
+ and not self.config.has_provider_configuration(provider)
+ ]
+ if missing_selected:
+ fail_missing_env(
+ "selected providers are not configured: "
+ + ", ".join(sorted(missing_selected))
+ )
+
+ models = self.config.provider_models()
+ if not models and os.getenv("FCC_ALLOW_NO_PROVIDER_SMOKE") != "1":
+ fail_missing_env(
+ "no configured provider models; set FCC_ALLOW_NO_PROVIDER_SMOKE=1 "
+ "only for no-provider smoke collection"
+ )
+ return models
+
+ def first_model(self) -> ProviderModel:
+ models = self.configured_models()
+ if not models:
+ pytest.skip("missing_env: no configured provider model")
+ return models[0]
+
+
+class ClientProtocolDriver:
+ """Build recorded/representative client protocol requests."""
+
+ @staticmethod
+ def vscode_headers() -> dict[str, str]:
+ headers = auth_headers()
+ headers.update(
+ {
+ "anthropic-beta": "messages-2023-12-15",
+ "user-agent": "Claude-Code-VSCode product smoke",
+ }
+ )
+ return headers
+
+ @staticmethod
+ def jetbrains_headers(config: SmokeConfig) -> dict[str, str]:
+ headers = auth_headers()
+ token = config.settings.anthropic_auth_token
+ if token:
+ headers.pop("x-api-key", None)
+ headers["authorization"] = f"Bearer {token}"
+ headers["user-agent"] = "JetBrains-ACP product smoke"
+ return headers
+
+ @staticmethod
+ def adaptive_thinking_payload() -> dict[str, Any]:
+ return {
+ "model": "claude-opus-4-7",
+ "max_tokens": 256,
+ "messages": [
+ {"role": "user", "content": "hello"},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "unsigned thought"},
+ {"type": "redacted_thinking", "data": "opaque"},
+ {"type": "text", "text": "Hello."},
+ ],
+ },
+ {"role": "user", "content": "Reply with exactly FCC_SMOKE_CLIENT"},
+ ],
+ "thinking": {"type": "adaptive", "budget_tokens": 1024},
+ }
+
+ @staticmethod
+ def tool_result_payload() -> dict[str, Any]:
+ return {
+ "model": "claude-sonnet-4-5-20250929",
+ "max_tokens": 256,
+ "messages": [
+ {"role": "user", "content": "Use echo_smoke once."},
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "toolu_client_smoke",
+ "name": "echo_smoke",
+ "input": {"value": "FCC_SMOKE_CLIENT"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "toolu_client_smoke",
+ "content": "FCC_SMOKE_CLIENT",
+ }
+ ],
+ },
+ ],
+ "tools": [echo_tool_schema()],
+ "thinking": {"type": "adaptive"},
+ }
+
+ @staticmethod
+ def run_claude_prompt(
+ *,
+ claude_bin: str,
+ server: RunningServer,
+ config: SmokeConfig,
+ cwd: Path,
+ prompt: str,
+ ) -> subprocess.CompletedProcess[str]:
+ env = os.environ.copy()
+ env["ANTHROPIC_BASE_URL"] = server.base_url
+ env["ANTHROPIC_API_URL"] = f"{server.base_url}/v1"
+ env.setdefault("ANTHROPIC_API_KEY", "sk-smoke-proxy")
+ if config.settings.anthropic_auth_token:
+ env["ANTHROPIC_AUTH_TOKEN"] = config.settings.anthropic_auth_token
+ return subprocess.run(
+ [
+ claude_bin,
+ "--bare",
+ "--tools",
+ "",
+ "--system-prompt",
+ "Reply with exactly the requested smoke token and no other text.",
+ "-p",
+ prompt,
+ ],
+ cwd=cwd,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=config.timeout_s,
+ check=False,
+ )
+
+
+class FakePlatform(MessagingPlatform):
+ """In-memory platform that exercises the real message handler."""
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+ self.handler: Callable[[IncomingMessage], Awaitable[None]] | None = None
+ self.sent: list[dict[str, Any]] = []
+ self.edits: list[dict[str, Any]] = []
+ self.deletes: list[dict[str, Any]] = []
+ self._counter = 0
+ self._tasks: list[asyncio.Future[Any]] = []
+ self._pending_voice: dict[tuple[str, str], tuple[str, str]] = {}
+
+ async def start(self) -> None:
+ return None
+
+ async def stop(self) -> None:
+ for task in self._tasks:
+ if not task.done():
+ task.cancel()
+ if self._tasks:
+ await asyncio.gather(*self._tasks, return_exceptions=True)
+
+ @property
+ def is_connected(self) -> bool:
+ return True
+
+ def on_message(self, handler: Callable[[IncomingMessage], Awaitable[None]]) -> None:
+ self.handler = handler
+
+ async def emit(self, incoming: IncomingMessage) -> None:
+ assert self.handler is not None
+ await self.handler(incoming)
+
+ def fire_and_forget(self, task: Awaitable[Any]) -> None:
+ self._tasks.append(asyncio.ensure_future(task))
+
+ async def send_message(
+ self,
+ chat_id: str,
+ text: str,
+ reply_to: str | None = None,
+ parse_mode: str | None = None,
+ message_thread_id: str | None = None,
+ ) -> str:
+ self._counter += 1
+ message_id = f"{self.name}_msg_{self._counter}"
+ self.sent.append(
+ {
+ "chat_id": chat_id,
+ "message_id": message_id,
+ "text": text,
+ "reply_to": reply_to,
+ "parse_mode": parse_mode,
+ "message_thread_id": message_thread_id,
+ }
+ )
+ return message_id
+
+ async def edit_message(
+ self,
+ chat_id: str,
+ message_id: str,
+ text: str,
+ parse_mode: str | None = None,
+ ) -> None:
+ self.edits.append(
+ {
+ "chat_id": chat_id,
+ "message_id": message_id,
+ "text": text,
+ "parse_mode": parse_mode,
+ }
+ )
+
+ async def delete_message(self, chat_id: str, message_id: str) -> None:
+ self.deletes.append({"chat_id": chat_id, "message_id": message_id})
+
+ async def queue_send_message(
+ self,
+ chat_id: str,
+ text: str,
+ reply_to: str | None = None,
+ parse_mode: str | None = None,
+ fire_and_forget: bool = True,
+ message_thread_id: str | None = None,
+ ) -> str | None:
+ message_id = await self.send_message(
+ chat_id,
+ text,
+ reply_to=reply_to,
+ parse_mode=parse_mode,
+ message_thread_id=message_thread_id,
+ )
+ return None if fire_and_forget else message_id
+
+ async def queue_edit_message(
+ self,
+ chat_id: str,
+ message_id: str,
+ text: str,
+ parse_mode: str | None = None,
+ fire_and_forget: bool = True,
+ ) -> None:
+ await self.edit_message(chat_id, message_id, text, parse_mode=parse_mode)
+
+ async def queue_delete_message(
+ self,
+ chat_id: str,
+ message_id: str,
+ fire_and_forget: bool = True,
+ ) -> None:
+ await self.delete_message(chat_id, message_id)
+
+ async def queue_delete_messages(
+ self,
+ chat_id: str,
+ message_ids: Sequence[str],
+ fire_and_forget: bool = True,
+ ) -> None:
+ for message_id in message_ids:
+ await self.queue_delete_message(chat_id, message_id, fire_and_forget=False)
+
+ def register_pending_voice(
+ self, chat_id: str, voice_message_id: str, status_message_id: str
+ ) -> None:
+ self._pending_voice[(chat_id, voice_message_id)] = (
+ voice_message_id,
+ status_message_id,
+ )
+
+ async def cancel_pending_voice(
+ self, chat_id: str, voice_message_id: str
+ ) -> tuple[str, str] | None:
+ return self._pending_voice.pop((chat_id, voice_message_id), None)
+
+
+class FakeCLISession:
+ def __init__(self, events: list[dict[str, Any]]) -> None:
+ self.events = events
+ self.calls: list[dict[str, Any]] = []
+ self.is_busy = False
+
+ async def start_task(
+ self, prompt: str, session_id: str | None = None, fork_session: bool = False
+ ) -> AsyncGenerator[dict[str, Any]]:
+ self.calls.append(
+ {"prompt": prompt, "session_id": session_id, "fork_session": fork_session}
+ )
+ self.is_busy = True
+ try:
+ for event in self.events:
+ await asyncio.sleep(0)
+ yield event
+ finally:
+ self.is_busy = False
+
+
+class FakeCLIManager:
+ def __init__(self, event_batches: list[list[dict[str, Any]]] | None = None) -> None:
+ self.event_batches = event_batches or [default_cli_events("fake_session_1")]
+ self.sessions: list[FakeCLISession] = []
+ self.registered: list[tuple[str, str]] = []
+ self.removed: list[str] = []
+ self.stopped = False
+
+ async def get_or_create_session(
+ self, session_id: str | None = None
+ ) -> tuple[FakeCLISession, str, bool]:
+ index = len(self.sessions)
+ events = self.event_batches[min(index, len(self.event_batches) - 1)]
+ session = FakeCLISession(events)
+ self.sessions.append(session)
+ return session, session_id or f"pending_{index}", session_id is None
+
+ async def register_real_session_id(
+ self, temp_id: str, real_session_id: str
+ ) -> bool:
+ self.registered.append((temp_id, real_session_id))
+ return True
+
+ async def stop_all(self) -> None:
+ self.stopped = True
+
+ async def remove_session(self, session_id: str) -> bool:
+ self.removed.append(session_id)
+ return True
+
+ def get_stats(self) -> dict[str, int]:
+ return {"active_sessions": len(self.sessions), "pending_sessions": 0}
+
+
+@dataclass(slots=True)
+class FakePlatformDriver:
+ platform_name: str
+ tmp_path: Path
+ event_batches: list[list[dict[str, Any]]] | None = None
+ platform: FakePlatform = field(init=False)
+ cli_manager: FakeCLIManager = field(init=False)
+ session_store: SessionStore = field(init=False)
+ handler: ClaudeMessageHandler = field(init=False)
+
+ def __post_init__(self) -> None:
+ self.platform = FakePlatform(self.platform_name)
+ self.cli_manager = FakeCLIManager(self.event_batches)
+ self.session_store = SessionStore(
+ storage_path=str(self.tmp_path / f"{self.platform_name}-sessions.json")
+ )
+ self.handler = ClaudeMessageHandler(
+ self.platform, self.cli_manager, self.session_store
+ )
+ self.platform.on_message(self.handler.handle_message)
+
+ async def send(
+ self,
+ text: str,
+ *,
+ message_id: str | None = None,
+ reply_to: str | None = None,
+ ) -> IncomingMessage:
+ incoming = IncomingMessage(
+ text=text,
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id=message_id or f"in_{uuid.uuid4().hex[:8]}",
+ platform=self.platform_name,
+ reply_to_message_id=reply_to,
+ )
+ await self.platform.emit(incoming)
+ await self.wait_for_idle()
+ return incoming
+
+ async def wait_for_idle(self, *, timeout_s: float = 5.0) -> None:
+ deadline = time.monotonic() + timeout_s
+ while time.monotonic() < deadline:
+ pending = [task for task in self.platform._tasks if not task.done()]
+ if not pending and self._all_tree_nodes_terminal():
+ self.session_store.flush_pending_save()
+ return
+ await asyncio.sleep(0.02)
+ raise AssertionError("fake platform did not become idle")
+
+ def _all_tree_nodes_terminal(self) -> bool:
+ data = self.handler.tree_queue.to_dict()
+ for tree in data.get("trees", {}).values():
+ nodes = tree.get("nodes", {}) if isinstance(tree, dict) else {}
+ for node in nodes.values():
+ if not isinstance(node, dict):
+ continue
+ if node.get("state") in {"pending", "in_progress"}:
+ return False
+ return True
+
+
+class VoiceFixtureDriver:
+ @staticmethod
+ def write_tone_wav(path: Path) -> None:
+ import math
+
+ sample_rate = 16000
+ duration_s = 0.25
+ amplitude = 8000
+ frames = bytearray()
+ for i in range(int(sample_rate * duration_s)):
+ sample = int(amplitude * math.sin(2 * math.pi * 440 * i / sample_rate))
+ frames.extend(sample.to_bytes(2, byteorder="little", signed=True))
+ with wave.open(str(path), "wb") as wav:
+ wav.setnchannels(1)
+ wav.setsampwidth(2)
+ wav.setframerate(sample_rate)
+ wav.writeframes(bytes(frames))
+
+
+def echo_tool_schema() -> dict[str, Any]:
+ return {
+ "name": "echo_smoke",
+ "description": "Echo a test value.",
+ "input_schema": {
+ "type": "object",
+ "properties": {"value": {"type": "string"}},
+ "required": ["value"],
+ },
+ }
+
+
+def assistant_content_from_events(events: list[SSEEvent]) -> list[dict[str, Any]]:
+ blocks: dict[int, dict[str, Any]] = {}
+ block_order: list[int] = []
+ for event in events:
+ if event.event == "content_block_start":
+ index = _event_index(event)
+ block = event.data.get("content_block", {})
+ if isinstance(block, dict):
+ blocks[index] = dict(block)
+ block_order.append(index)
+ continue
+ if event.event == "content_block_delta":
+ index = _event_index(event)
+ block = blocks.get(index)
+ delta = event.data.get("delta", {})
+ if not isinstance(block, dict) or not isinstance(delta, dict):
+ continue
+ delta_type = delta.get("type")
+ if delta_type == "text_delta":
+ block["text"] = str(block.get("text", "")) + str(delta.get("text", ""))
+ elif delta_type == "thinking_delta":
+ block["thinking"] = str(block.get("thinking", "")) + str(
+ delta.get("thinking", "")
+ )
+ elif delta_type == "input_json_delta":
+ block["_partial_json"] = str(block.get("_partial_json", "")) + str(
+ delta.get("partial_json", "")
+ )
+
+ content: list[dict[str, Any]] = []
+ for index in block_order:
+ block = blocks[index]
+ if block.get("type") == "tool_use":
+ partial = str(block.pop("_partial_json", ""))
+ if partial:
+ try:
+ block["input"] = json.loads(partial)
+ except json.JSONDecodeError:
+ block["input"] = {}
+ content.append(block)
+ return content
+
+
+def tool_use_blocks(events: list[SSEEvent]) -> list[dict[str, Any]]:
+ return [
+ block
+ for block in assistant_content_from_events(events)
+ if block.get("type") == "tool_use"
+ ]
+
+
+def default_cli_events(session_id: str) -> list[dict[str, Any]]:
+ return [
+ {"type": "session_info", "session_id": session_id},
+ {
+ "type": "assistant",
+ "message": {
+ "content": [
+ {"type": "thinking", "thinking": "Inspect the request."},
+ {
+ "type": "tool_use",
+ "id": "toolu_fake",
+ "name": "Read",
+ "input": {"file_path": "README.md"},
+ },
+ {
+ "type": "tool_result",
+ "tool_use_id": "toolu_fake",
+ "content": "Free Claude Code",
+ },
+ {"type": "text", "text": "Fake platform answer."},
+ ]
+ },
+ },
+ {"type": "exit", "code": 0, "stderr": None},
+ ]
+
+
+def _event_index(event: SSEEvent) -> int:
+ value = event.data.get("index")
+ assert isinstance(value, int), event.data
+ return value
+
+
+def assert_product_stream(events: list[SSEEvent]) -> None:
+ assert_anthropic_stream_contract(events)
+ assert text_content(events).strip() or has_tool_use(events), (
+ "product stream emitted neither text nor tool_use"
+ )
diff --git a/smoke/lib/report.py b/smoke/lib/report.py
index 448b1d44..c17af261 100644
--- a/smoke/lib/report.py
+++ b/smoke/lib/report.py
@@ -85,6 +85,8 @@ def classify_outcome(*, nodeid: str, outcome: str, detail: str) -> str:
if "harness_bug" in text:
return "harness_bug"
+ if "missing_env" in text:
+ return "missing_env"
if any(
marker in text
for marker in (
diff --git a/smoke/lib/skips.py b/smoke/lib/skips.py
index 8ce03edd..ffadb850 100644
--- a/smoke/lib/skips.py
+++ b/smoke/lib/skips.py
@@ -29,6 +29,10 @@ def skip_upstream_unavailable(reason: str) -> None:
pytest.skip(f"upstream_unavailable: {reason}")
+def fail_missing_env(reason: str) -> None:
+ pytest.fail(f"missing_env: {reason}")
+
+
def skip_if_upstream_unavailable_exception(exc: Exception) -> None:
if isinstance(
exc,
diff --git a/smoke/prereq/__init__.py b/smoke/prereq/__init__.py
new file mode 100644
index 00000000..54472fd5
--- /dev/null
+++ b/smoke/prereq/__init__.py
@@ -0,0 +1 @@
+"""Live prerequisite checks for product smoke."""
diff --git a/smoke/test_api_live.py b/smoke/prereq/test_api_prereq_live.py
similarity index 100%
rename from smoke/test_api_live.py
rename to smoke/prereq/test_api_prereq_live.py
diff --git a/smoke/test_auth_live.py b/smoke/prereq/test_auth_prereq_live.py
similarity index 100%
rename from smoke/test_auth_live.py
rename to smoke/prereq/test_auth_prereq_live.py
diff --git a/smoke/test_cli_live.py b/smoke/prereq/test_cli_prereq_live.py
similarity index 84%
rename from smoke/test_cli_live.py
rename to smoke/prereq/test_cli_prereq_live.py
index 8aa3f8cb..0cbcd158 100644
--- a/smoke/test_cli_live.py
+++ b/smoke/prereq/test_cli_prereq_live.py
@@ -9,6 +9,7 @@ import pytest
from smoke.lib.config import SmokeConfig
from smoke.lib.server import start_server
+from smoke.lib.skips import skip_upstream_unavailable
pytestmark = [pytest.mark.live, pytest.mark.smoke_target("cli")]
@@ -70,5 +71,12 @@ def test_claude_cli_prompt_when_available(
timeout=smoke_config.timeout_s,
check=False,
)
+ server_log = server.log_path.read_text(encoding="utf-8", errors="replace")
assert result.returncode == 0, result.stderr or result.stdout
- assert "FCC_SMOKE_PONG" in result.stdout
+ assert "POST /v1/messages" in server_log, (
+ "Claude CLI did not call the local Anthropic-compatible endpoint"
+ )
+ if "FCC_SMOKE_PONG" not in result.stdout:
+ skip_upstream_unavailable(
+ "Claude CLI reached the local proxy but returned no smoke token"
+ )
diff --git a/smoke/test_client_shapes_live.py b/smoke/prereq/test_client_shapes_prereq_live.py
similarity index 100%
rename from smoke/test_client_shapes_live.py
rename to smoke/prereq/test_client_shapes_prereq_live.py
diff --git a/smoke/test_local_provider_endpoints_live.py b/smoke/prereq/test_local_provider_endpoints_prereq_live.py
similarity index 100%
rename from smoke/test_local_provider_endpoints_live.py
rename to smoke/prereq/test_local_provider_endpoints_prereq_live.py
diff --git a/smoke/test_messaging_live.py b/smoke/prereq/test_messaging_prereq_live.py
similarity index 100%
rename from smoke/test_messaging_live.py
rename to smoke/prereq/test_messaging_prereq_live.py
diff --git a/smoke/test_provider_live.py b/smoke/prereq/test_provider_prereq_live.py
similarity index 100%
rename from smoke/test_provider_live.py
rename to smoke/prereq/test_provider_prereq_live.py
diff --git a/smoke/test_tools_live.py b/smoke/prereq/test_tools_prereq_live.py
similarity index 100%
rename from smoke/test_tools_live.py
rename to smoke/prereq/test_tools_prereq_live.py
diff --git a/smoke/test_voice_live.py b/smoke/prereq/test_voice_prereq_live.py
similarity index 100%
rename from smoke/test_voice_live.py
rename to smoke/prereq/test_voice_prereq_live.py
diff --git a/smoke/product/__init__.py b/smoke/product/__init__.py
new file mode 100644
index 00000000..662aac91
--- /dev/null
+++ b/smoke/product/__init__.py
@@ -0,0 +1 @@
+"""Product-level end-to-end smoke scenarios."""
diff --git a/smoke/product/test_api_product_live.py b/smoke/product/test_api_product_live.py
new file mode 100644
index 00000000..f525221b
--- /dev/null
+++ b/smoke/product/test_api_product_live.py
@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import pytest
+
+from smoke.lib.config import SmokeConfig
+from smoke.lib.e2e import (
+ ConversationDriver,
+ ProviderMatrixDriver,
+ SmokeServerDriver,
+ assert_product_stream,
+ echo_tool_schema,
+)
+
+pytestmark = [pytest.mark.live, pytest.mark.smoke_target("api")]
+
+
+def test_api_basic_conversation_e2e(smoke_config: SmokeConfig) -> None:
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-api-basic",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ turn = ConversationDriver(server, smoke_config).ask(
+ "Reply with one short sentence."
+ )
+
+ assert_product_stream(turn.events)
+ assert turn.text.strip()
+
+
+def test_api_count_tokens_full_payload_e2e(
+ smoke_server,
+ smoke_config: SmokeConfig,
+ smoke_headers: dict[str, str],
+) -> None:
+ payload: dict[str, Any] = {
+ "model": "claude-3-5-sonnet-20241022",
+ "messages": [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Use the image and tool."},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": "iVBORw0KGgo=",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "Need the tool."},
+ {"type": "redacted_thinking", "data": "opaque"},
+ {
+ "type": "tool_use",
+ "id": "toolu_smoke",
+ "name": "echo_smoke",
+ "input": {"value": "FCC"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "toolu_smoke",
+ "content": "FCC",
+ }
+ ],
+ },
+ ],
+ "tools": [echo_tool_schema()],
+ "thinking": {"type": "adaptive", "budget_tokens": 1024},
+ }
+ response = httpx.post(
+ f"{smoke_server.base_url}/v1/messages/count_tokens",
+ headers=smoke_headers,
+ json=payload,
+ timeout=smoke_config.timeout_s,
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["input_tokens"] > 0
+
+
+def test_api_request_optimizations_e2e(
+ smoke_server,
+ smoke_config: SmokeConfig,
+ smoke_headers: dict[str, str],
+) -> None:
+ cases: tuple[tuple[str, dict[str, Any], str], ...] = (
+ (
+ "quota",
+ {
+ "model": "claude-3-5-sonnet-20241022",
+ "max_tokens": 1,
+ "messages": [{"role": "user", "content": "quota"}],
+ },
+ "Quota check passed.",
+ ),
+ (
+ "title",
+ {
+ "model": "claude-3-5-sonnet-20241022",
+ "system": "Generate a title for the new conversation topic.",
+ "messages": [{"role": "user", "content": "hello"}],
+ },
+ "Conversation",
+ ),
+ (
+ "prefix",
+ {
+ "model": "claude-3-5-sonnet-20241022",
+ "messages": [
+ {
+ "role": "user",
+ "content": (
+ "<policy_spec>extract command</policy_spec>\n"
+ "Command: git status --short"
+ ),
+ }
+ ],
+ },
+ "git",
+ ),
+ (
+ "suggestion",
+ {
+ "model": "claude-3-5-sonnet-20241022",
+ "messages": [{"role": "user", "content": "[SUGGESTION MODE: next]"}],
+ },
+ "",
+ ),
+ (
+ "filepath",
+ {
+ "model": "claude-3-5-sonnet-20241022",
+ "system": "Extract any file paths that this command output contains.",
+ "messages": [
+ {
+ "role": "user",
+ "content": (
+ "Command: cat smoke/product/test_api_product_live.py\n"
+ "Output: file contents\n<filepaths>"
+ ),
+ }
+ ],
+ },
+ "smoke/product/test_api_product_live.py",
+ ),
+ )
+ for name, payload, expected_text in cases:
+ response = httpx.post(
+ f"{smoke_server.base_url}/v1/messages",
+ headers=smoke_headers,
+ json=payload,
+ timeout=smoke_config.timeout_s,
+ )
+ assert response.status_code == 200, (name, response.text)
+ text = response.json()["content"][0]["text"]
+ assert expected_text in text
+
+
+def test_api_error_shape_e2e(
+ smoke_server,
+ smoke_config: SmokeConfig,
+ smoke_headers: dict[str, str],
+) -> None:
+ response = httpx.post(
+ f"{smoke_server.base_url}/v1/messages",
+ headers=smoke_headers,
+ json={"model": "claude-3-5-sonnet-20241022", "messages": []},
+ timeout=smoke_config.timeout_s,
+ )
+ assert response.status_code == 400
+ payload = response.json()
+ assert payload["type"] == "error"
+ assert payload["error"]["type"] == "invalid_request_error"
+
+
+def test_api_stop_e2e(smoke_server, smoke_headers: dict[str, str]) -> None:
+ response = httpx.post(
+ f"{smoke_server.base_url}/stop",
+ headers=smoke_headers,
+ timeout=5,
+ )
+ assert response.status_code == 503
+ assert response.json()["detail"] == "Messaging system not initialized"
diff --git a/smoke/product/test_auth_product_live.py b/smoke/product/test_auth_product_live.py
new file mode 100644
index 00000000..6132b9ac
--- /dev/null
+++ b/smoke/product/test_auth_product_live.py
@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from smoke.lib.config import SmokeConfig
+from smoke.lib.e2e import SmokeServerDriver
+
+pytestmark = [pytest.mark.live, pytest.mark.smoke_target("auth")]
+
+
+def test_api_auth_header_variants_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
+ token = "product-smoke-token"
+ env_file = tmp_path / "auth-product.env"
+ env_file.write_text(f'ANTHROPIC_AUTH_TOKEN="{token}"\n', encoding="utf-8")
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-auth",
+ env_overrides={
+ "ANTHROPIC_AUTH_TOKEN": token,
+ "FCC_ENV_FILE": str(env_file),
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ unauth = httpx.get(
+ f"{server.base_url}/v1/models", timeout=smoke_config.timeout_s
+ )
+ x_api_key = httpx.get(
+ f"{server.base_url}/v1/models",
+ headers={"x-api-key": token},
+ timeout=smoke_config.timeout_s,
+ )
+ bearer = httpx.get(
+ f"{server.base_url}/v1/models",
+ headers={"authorization": f"Bearer {token}"},
+ timeout=smoke_config.timeout_s,
+ )
+ anthropic = httpx.get(
+ f"{server.base_url}/v1/models",
+ headers={"anthropic-auth-token": token},
+ timeout=smoke_config.timeout_s,
+ )
+ invalid = httpx.get(
+ f"{server.base_url}/v1/models",
+ headers={"x-api-key": "wrong"},
+ timeout=smoke_config.timeout_s,
+ )
+
+ assert unauth.status_code == 401
+ assert x_api_key.status_code == 200
+ assert bearer.status_code == 200
+ assert anthropic.status_code == 200
+ assert invalid.status_code == 401
diff --git a/smoke/product/test_cli_package_product_live.py b/smoke/product/test_cli_package_product_live.py
new file mode 100644
index 00000000..a0a37f86
--- /dev/null
+++ b/smoke/product/test_cli_package_product_live.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from cli.manager import CLISessionManager
+from cli.session import CLISession
+from smoke.lib.config import SmokeConfig
+
+pytestmark = [pytest.mark.live, pytest.mark.smoke_target("cli")]
+
+
+def test_entrypoint_init_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:
+ env = os.environ.copy()
+ env["HOME"] = str(tmp_path)
+ env["USERPROFILE"] = str(tmp_path)
+ result = subprocess.run(
+ ["uv", "run", "fcc-init"],
+ cwd=smoke_config.root,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=smoke_config.timeout_s,
+ check=False,
+ )
+ assert result.returncode == 0, result.stderr or result.stdout
+ env_file = tmp_path / ".config" / "free-claude-code" / ".env"
+ assert env_file.is_file()
+ assert env_file.read_text(encoding="utf-8").strip()
+
+
+async def test_cli_session_resume_fork_e2e(tmp_path: Path) -> None:
+ session = CLISession(str(tmp_path), "http://127.0.0.1:8082/v1")
+ process = AsyncMock()
+ process.stdout.read.side_effect = [b""]
+ process.stderr.read.return_value = b""
+ process.wait.return_value = 0
+ process.returncode = 0
+
+ with patch("asyncio.create_subprocess_exec", new_callable=AsyncMock) as spawn:
+ spawn.return_value = process
+ async for _event in session.start_task(
+ "resume this",
+ session_id="sess_product",
+ fork_session=True,
+ ):
+ pass
+
+ args = spawn.call_args[0]
+ assert args[:3] == ("claude", "--resume", "sess_product")
+ assert "--fork-session" in args
+ assert "-p" in args
+ assert "resume this" in args
+
+
+async def test_cli_process_cleanup_e2e(tmp_path: Path) -> None:
+ manager = CLISessionManager(
+ workspace_path=str(tmp_path),
+ api_url="http://127.0.0.1:8082/v1",
+ )
+ session, pending_id, is_new = await manager.get_or_create_session()
+ assert is_new is True
+ assert pending_id.startswith("pending_")
+
+ mocked_stop = AsyncMock(return_value=True)
+ with patch.object(session, "stop", mocked_stop):
+ await manager.stop_all()
+
+ mocked_stop.assert_awaited_once()
+ assert manager.get_stats() == {
+ "active_sessions": 0,
+ "pending_sessions": 0,
+ "busy_count": 0,
+ }
+
+
+async def test_cli_session_stop_kills_child_e2e(tmp_path: Path) -> None:
+ session = CLISession(str(tmp_path), "http://127.0.0.1:8082/v1")
+ process = MagicMock()
+ process.pid = 123456
+ process.returncode = None
+ process.wait = AsyncMock(side_effect=[asyncio.TimeoutError, 0])
+ session.process = process
+
+ stopped = await session.stop()
+
+ assert stopped is True
+ process.terminate.assert_called_once()
+ process.kill.assert_called_once()
diff --git a/smoke/product/test_client_product_live.py b/smoke/product/test_client_product_live.py
new file mode 100644
index 00000000..8a841e0b
--- /dev/null
+++ b/smoke/product/test_client_product_live.py
@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+
+from smoke.lib.config import SmokeConfig
+from smoke.lib.e2e import (
+ ClientProtocolDriver,
+ ConversationDriver,
+ ProviderMatrixDriver,
+ SmokeServerDriver,
+ assert_product_stream,
+)
+
+pytestmark = [pytest.mark.live]
+
+
[email protected]_target("clients")
+def test_vscode_protocol_e2e(smoke_config: SmokeConfig) -> None:
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-vscode",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ turn = ConversationDriver(server, smoke_config).stream(
+ ClientProtocolDriver.adaptive_thinking_payload(),
+ headers=ClientProtocolDriver.vscode_headers(),
+ )
+
+ assert_product_stream(turn.events)
+
+
[email protected]_target("clients")
+def test_jetbrains_protocol_e2e(smoke_config: SmokeConfig) -> None:
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-jetbrains",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ driver = ConversationDriver(server, smoke_config)
+ first = driver.stream(
+ ClientProtocolDriver.tool_result_payload(),
+ headers=ClientProtocolDriver.jetbrains_headers(smoke_config),
+ )
+
+ assert_product_stream(first.events)
+
+
[email protected]_target("cli")
+def test_claude_cli_adaptive_thinking_e2e(
+ smoke_config: SmokeConfig, tmp_path: Path
+) -> None:
+ claude_bin = shutil.which(smoke_config.claude_bin)
+ if not claude_bin:
+ pytest.skip(f"missing_env: Claude CLI not found: {smoke_config.claude_bin}")
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-claude-cli-adaptive",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ result = ClientProtocolDriver.run_claude_prompt(
+ claude_bin=claude_bin,
+ server=server,
+ config=smoke_config,
+ cwd=tmp_path,
+ prompt="think hard, then reply with exactly FCC_SMOKE_CLI",
+ )
+ server_log = server.log_path.read_text(encoding="utf-8", errors="replace")
+
+ assert result.returncode == 0, result.stderr or result.stdout
+ assert "POST /v1/messages" in server_log
+ assert " 422 " not in server_log
+ assert 'HTTP/1.1" 422' not in server_log
+ assert "400 Bad Request" not in result.stdout
+ assert "FCC_SMOKE_CLI" in result.stdout
+
+
[email protected]_target("cli")
+def test_claude_cli_multiturn_tool_protocol_e2e(smoke_config: SmokeConfig) -> None:
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-claude-cli-protocol",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run() as server:
+ turn = ConversationDriver(server, smoke_config).stream(
+ ClientProtocolDriver.tool_result_payload()
+ )
+
+ assert_product_stream(turn.events)
diff --git a/smoke/product/test_config_extensibility_product_live.py b/smoke/product/test_config_extensibility_product_live.py
new file mode 100644
index 00000000..627d269f
--- /dev/null
+++ b/smoke/product/test_config_extensibility_product_live.py
@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import os
+import subprocess
+
+import pytest
+
+from config.settings import Settings
+from messaging.platforms.factory import create_messaging_platform
+from providers.registry import PROVIDER_DESCRIPTORS, build_provider_config
+from smoke.lib.config import SmokeConfig
+from smoke.lib.e2e import SmokeServerDriver
+
+pytestmark = [pytest.mark.live]
+
+
[email protected]_target("config")
+def test_env_precedence_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
+ env_file = tmp_path / "product.env"
+ env_file.write_text(
+ 'MODEL="open_router/test/model"\nANTHROPIC_AUTH_TOKEN="dotenv-token"\n',
+ encoding="utf-8",
+ )
+ env = os.environ.copy()
+ env["FCC_ENV_FILE"] = str(env_file)
+ env["MODEL"] = "nvidia_nim/process-model"
+ env["ANTHROPIC_AUTH_TOKEN"] = "process-token"
+ script = (
+ "from config.settings import get_settings; "
+ "s=get_settings(); "
+ "print(s.model); print(s.anthropic_auth_token)"
+ )
+ result = subprocess.run(
+ ["uv", "run", "python", "-c", script],
+ cwd=smoke_config.root,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=smoke_config.timeout_s,
+ check=False,
+ )
+ assert result.returncode == 0, result.stderr
+ lines = result.stdout.splitlines()
+ assert lines == ["nvidia_nim/process-model", "dotenv-token"]
+
+
[email protected]_target("config")
+def test_removed_env_migration_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
+ env_file = tmp_path / "removed.env"
+ env_file.write_text('NIM_ENABLE_THINKING="true"\n', encoding="utf-8")
+ env = os.environ.copy()
+ env["FCC_ENV_FILE"] = str(env_file)
+ result = subprocess.run(
+ [
+ "uv",
+ "run",
+ "python",
+ "-c",
+ "from config.settings import Settings; Settings()",
+ ],
+ cwd=smoke_config.root,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=smoke_config.timeout_s,
+ check=False,
+ )
+ assert result.returncode != 0
+ assert "NIM_ENABLE_THINKING has been removed" in (result.stderr + result.stdout)
+
+
[email protected]_target("config")
+def test_proxy_timeout_config_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
+ env_file = tmp_path / "timeouts.env"
+ env_file.write_text(
+ 'MODEL="open_router/test/model"\n'
+ 'OPENROUTER_API_KEY="key"\n'
+ 'OPENROUTER_PROXY="socks5://127.0.0.1:9999"\n'
+ 'HTTP_READ_TIMEOUT="321"\n'
+ 'HTTP_CONNECT_TIMEOUT="7"\n'
+ 'HTTP_WRITE_TIMEOUT="8"\n',
+ encoding="utf-8",
+ )
+ env = os.environ.copy()
+ env["FCC_ENV_FILE"] = str(env_file)
+ script = (
+ "from config.settings import Settings; "
+ "from providers.registry import PROVIDER_DESCRIPTORS, build_provider_config; "
+ "s=Settings(); c=build_provider_config(PROVIDER_DESCRIPTORS['open_router'], s); "
+ "print(c.proxy); print(c.http_read_timeout); "
+ "print(c.http_connect_timeout); print(c.http_write_timeout)"
+ )
+ result = subprocess.run(
+ ["uv", "run", "python", "-c", script],
+ cwd=smoke_config.root,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=smoke_config.timeout_s,
+ check=False,
+ )
+ assert result.returncode == 0, result.stderr
+ assert result.stdout.splitlines() == [
+ "socks5://127.0.0.1:9999",
+ "321.0",
+ "7.0",
+ "8.0",
+ ]
+
+
[email protected]_target("extensibility")
+def test_provider_registry_e2e() -> None:
+ settings = Settings(
+ open_router_api_key="openrouter-key",
+ deepseek_api_key="deepseek-key",
+ nvidia_nim_api_key="nim-key",
+ lm_studio_base_url="http://localhost:1234/v1",
+ llamacpp_base_url="http://localhost:8080/v1",
+ )
+ for descriptor in PROVIDER_DESCRIPTORS.values():
+ config = build_provider_config(descriptor, settings)
+ assert config.base_url
+ assert config.api_key
+
+
[email protected]_target("extensibility")
+def test_platform_factory_e2e() -> None:
+ assert create_messaging_platform("not-a-platform") is None
+ assert create_messaging_platform("telegram") is None
+ assert create_messaging_platform("discord") is None
+
+
[email protected]_target("cli")
+def test_entrypoint_server_e2e(smoke_config: SmokeConfig) -> None:
+ with SmokeServerDriver(
+ smoke_config,
+ name="product-entrypoint",
+ command=["uv", "run", "free-claude-code"],
+ env_overrides={"MESSAGING_PLATFORM": "none"},
+ ).run() as server:
+ assert server.process.poll() is None
diff --git a/smoke/product/test_live_platform_product_live.py b/smoke/product/test_live_platform_product_live.py
new file mode 100644
index 00000000..bcb242bd
--- /dev/null
+++ b/smoke/product/test_live_platform_product_live.py
@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import os
+import time
+
+import httpx
+import pytest
+
+from smoke.lib.config import SmokeConfig
+
+pytestmark = [pytest.mark.live]
+
+
[email protected]_target("telegram")
+def test_telegram_live_permissions_e2e(smoke_config: SmokeConfig) -> None:
+ token = smoke_config.settings.telegram_bot_token
+ if not token:
+ pytest.skip("missing_env: TELEGRAM_BOT_TOKEN is not configured")
+
+ base_url = f"https://api.telegram.org/bot{token}"
+ get_me = httpx.get(f"{base_url}/getMe", timeout=smoke_config.timeout_s)
+ assert get_me.status_code == 200, get_me.text
+ assert get_me.json()["ok"] is True
+
+ chat_id = os.getenv("FCC_SMOKE_TELEGRAM_CHAT_ID") or (
+ smoke_config.settings.allowed_telegram_user_id or ""
+ )
+ if not chat_id:
+ pytest.skip(
+ "missing_env: FCC_SMOKE_TELEGRAM_CHAT_ID or "
+ "ALLOWED_TELEGRAM_USER_ID required"
+ )
+
+ marker = f"FCC product smoke {int(time.time())}"
+ sent = httpx.post(
+ f"{base_url}/sendMessage",
+ json={"chat_id": chat_id, "text": marker},
+ timeout=smoke_config.timeout_s,
+ )
+ assert sent.status_code == 200, sent.text
+ message_id = sent.json()["result"]["message_id"]
+
+ edited = httpx.post(
+ f"{base_url}/editMessageText",
+ json={"chat_id": chat_id, "message_id": message_id, "text": marker + " edit"},
+ timeout=smoke_config.timeout_s,
+ )
+ assert edited.status_code == 200, edited.text
+
+ deleted = httpx.post(
+ f"{base_url}/deleteMessage",
+ json={"chat_id": chat_id, "message_id": message_id},
+ timeout=smoke_config.timeout_s,
+ )
+ assert deleted.status_code == 200, deleted.text
+
+
[email protected]_target("discord")
+def test_discord_live_permissions_e2e(smoke_config: SmokeConfig) -> None:
+ token = smoke_config.settings.discord_bot_token
+ channel_id = os.getenv("FCC_SMOKE_DISCORD_CHANNEL_ID")
+ if not channel_id and smoke_config.settings.allowed_discord_channels:
+ channel_id = smoke_config.settings.allowed_discord_channels.split(",", 1)[0]
+ if not token:
+ pytest.skip("missing_env: DISCORD_BOT_TOKEN is not configured")
+ if not channel_id:
+ pytest.skip(
+ "missing_env: FCC_SMOKE_DISCORD_CHANNEL_ID or "
+ "ALLOWED_DISCORD_CHANNELS required"
+ )
+
+ headers = {"authorization": f"Bot {token}"}
+ base_url = "https://discord.com/api/v10"
+
+ channel = httpx.get(
+ f"{base_url}/channels/{channel_id}",
+ headers=headers,
+ timeout=smoke_config.timeout_s,
+ )
+ assert channel.status_code == 200, channel.text
+
+ marker = f"FCC product smoke {int(time.time())}"
+ sent = httpx.post(
+ f"{base_url}/channels/{channel_id}/messages",
+ headers=headers,
+ json={"content": marker},
+ timeout=smoke_config.timeout_s,
+ )
+ assert sent.status_code == 200, sent.text
+ message_id = sent.json()["id"]
+
+ edited = httpx.patch(
+ f"{base_url}/channels/{channel_id}/messages/{message_id}",
+ headers=headers,
+ json={"content": marker + " edit"},
+ timeout=smoke_config.timeout_s,
+ )
+ assert edited.status_code == 200, edited.text
+
+ deleted = httpx.delete(
+ f"{base_url}/channels/{channel_id}/messages/{message_id}",
+ headers=headers,
+ timeout=smoke_config.timeout_s,
+ )
+ assert deleted.status_code in {200, 204}, deleted.text
+
+
[email protected]_target("telegram")
+def test_telegram_live_manual_inbound_e2e(smoke_config: SmokeConfig) -> None:
+ if not smoke_config.interactive:
+ pytest.skip("missing_env: set FCC_SMOKE_INTERACTIVE=1 for manual inbound smoke")
+ pytest.skip(
+ "manual product smoke: send the printed nonce to Telegram and verify "
+ "progress edits, final transcript, /stop, /clear, /stats, and voice note "
+ "behavior from the real client"
+ )
+
+
[email protected]_target("discord")
+def test_discord_live_manual_inbound_e2e(smoke_config: SmokeConfig) -> None:
+ if not smoke_config.interactive:
+ pytest.skip("missing_env: set FCC_SMOKE_INTERACTIVE=1 for manual inbound smoke")
+ pytest.skip(
+ "manual product smoke: send the printed nonce to Discord and verify "
+ "progress edits, final transcript, /stop, /clear, /stats, and voice note "
+ "behavior from the real client"
+ )
diff --git a/smoke/product/test_local_provider_product_live.py b/smoke/product/test_local_provider_product_live.py
new file mode 100644
index 00000000..5ac13fb0
--- /dev/null
+++ b/smoke/product/test_local_provider_product_live.py
@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from urllib.parse import urljoin
+
+import httpx
+import pytest
+
+from smoke.lib.config import SmokeConfig
+from smoke.lib.e2e import ConversationDriver, SmokeServerDriver, assert_product_stream
+
+pytestmark = [pytest.mark.live]
+
+
[email protected]_target("lmstudio")
+def test_lmstudio_native_messages_e2e(smoke_config: SmokeConfig) -> None:
+ _local_native_messages_e2e(
+ smoke_config,
+ provider="lmstudio",
+ base_url=smoke_config.settings.lm_studio_base_url,
+ )
+
+
[email protected]_target("llamacpp")
+def test_llamacpp_native_messages_e2e(smoke_config: SmokeConfig) -> None:
+ _local_native_messages_e2e(
+ smoke_config,
+ provider="llamacpp",
+ base_url=smoke_config.settings.llamacpp_base_url,
+ )
+
+
+def _local_native_messages_e2e(
+ smoke_config: SmokeConfig,
+ *,
+ provider: str,
+ base_url: str,
+) -> None:
+ if not base_url.strip():
+ pytest.skip(f"missing_env: {provider} base URL is not configured")
+
+ models_url = urljoin(base_url.rstrip("/") + "/", "models")
+ try:
+ models = httpx.get(models_url, timeout=5)
+ except httpx.ConnectError as exc:
+ pytest.skip(f"upstream_unavailable: {provider} models endpoint: {exc}")
+ except httpx.TimeoutException as exc:
+ pytest.skip(f"upstream_unavailable: {provider} models endpoint: {exc}")
+ assert models.status_code == 200, models.text
+ model_id = _first_local_model_id(models)
+
+ with SmokeServerDriver(
+ smoke_config,
+ name=f"product-{provider}-native",
+ env_overrides={"MODEL": f"{provider}/{model_id}", "MESSAGING_PLATFORM": "none"},
+ ).run() as server:
+ turn = ConversationDriver(server, smoke_config).ask(
+ "Reply with one short sentence."
+ )
+
+ assert_product_stream(turn.events)
+
+
+def _first_local_model_id(response: httpx.Response) -> str:
+ payload = response.json()
+ data = payload.get("data") if isinstance(payload, dict) else None
+ if isinstance(data, list):
+ for item in data:
+ if isinstance(item, dict) and isinstance(item.get("id"), str):
+ return item["id"]
+ pytest.fail("product_failure: local /models did not expose a model id")
diff --git a/smoke/product/test_messaging_product_live.py b/smoke/product/test_messaging_product_live.py
new file mode 100644
index 00000000..202bd971
--- /dev/null
+++ b/smoke/product/test_messaging_product_live.py
@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from messaging.trees.queue_manager import MessageState
+from smoke.lib.e2e import FakePlatformDriver, default_cli_events
+
+pytestmark = [pytest.mark.live, pytest.mark.smoke_target("messaging")]
+
+
[email protected]("platform_name", ["discord", "telegram"])
+async def test_messaging_fake_full_flow_e2e(platform_name: str, tmp_path) -> None:
+ driver = FakePlatformDriver(platform_name, tmp_path)
+
+ incoming = await driver.send("Please inspect README.", message_id="root_1")
+
+ tree = driver.handler.tree_queue.get_tree_for_node(incoming.message_id)
+ assert tree is not None
+ node = tree.get_node(incoming.message_id)
+ assert node is not None
+ assert node.state == MessageState.COMPLETED
+ assert driver.platform.sent
+ assert driver.platform.edits
+ edit_text = "\n".join(edit["text"] for edit in driver.platform.edits)
+ assert "Fake platform answer" in edit_text
+ assert "Read" in edit_text
+
+
[email protected]("platform_name", ["discord", "telegram"])
+async def test_messaging_subagent_control_e2e(platform_name: str, tmp_path) -> None:
+ task_events = [
+ {"type": "session_info", "session_id": "sess_task"},
+ {
+ "type": "assistant",
+ "message": {
+ "content": [
+ {"type": "thinking", "thinking": "Need a focused worker."},
+ {
+ "type": "tool_use",
+ "id": "toolu_task",
+ "name": "Task",
+ "input": {"description": "inspect", "prompt": "inspect"},
+ },
+ {"type": "text", "text": "Subagent result rendered."},
+ ]
+ },
+ },
+ {"type": "exit", "code": 0, "stderr": None},
+ ]
+ driver = FakePlatformDriver(platform_name, tmp_path, event_batches=[task_events])
+
+ await driver.send("Delegate this safely.", message_id="root_task")
+
+ edit_text = "\n".join(edit["text"] for edit in driver.platform.edits)
+ assert "Subagent" in edit_text
+ assert "Tool calls" in edit_text
+
+
[email protected]("platform_name", ["discord", "telegram"])
+async def test_messaging_commands_stop_clear_stats_e2e(
+ platform_name: str, tmp_path
+) -> None:
+ driver = FakePlatformDriver(platform_name, tmp_path)
+ root = await driver.send("start work", message_id="root_1")
+
+ await driver.send("/stats", message_id="stats_1")
+ await driver.send("/stop", message_id="stop_1", reply_to=root.message_id)
+ await driver.send("/clear", message_id="clear_1", reply_to=root.message_id)
+ await driver.send("/clear", message_id="clear_all")
+
+ sent_text = "\n".join(sent["text"] for sent in driver.platform.sent)
+ assert "Stats" in sent_text
+ assert "Stopped" in sent_text
+ assert driver.platform.deletes
+ assert driver.session_store.get_all_trees() == {}
+
+
[email protected]("platform_name", ["discord", "telegram"])
+async def test_tree_threading_e2e(platform_name: str, tmp_path) -> None:
+ batches = [default_cli_events("sess_root"), default_cli_events("sess_branch")]
+ driver = FakePlatformDriver(platform_name, tmp_path, event_batches=batches)
+
+ root = await driver.send("root prompt", message_id="root_1")
+ branch = await driver.send(
+ "branch prompt", message_id="branch_1", reply_to=root.message_id
+ )
+
+ tree = driver.handler.tree_queue.get_tree_for_node(root.message_id)
+ assert tree is not None
+ branch_node = tree.get_node(branch.message_id)
+ assert branch_node is not None
+ assert branch_node.parent_id == root.message_id
+ assert driver.cli_manager.sessions[1].calls[0]["session_id"] == "sess_root"
+ assert driver.cli_manager.sessions[1].calls[0]["fork_session"] is True
+
+
+async def test_restart_restore_and_session_persistence_e2e(tmp_path) -> None:
+ first = FakePlatformDriver("telegram", tmp_path)
+ root = await first.send("persist me", message_id="root_1")
+ first.session_store.flush_pending_save()
+
+ session_file = tmp_path / "telegram-sessions.json"
+ payload = json.loads(session_file.read_text(encoding="utf-8"))
+ assert payload["trees"]
+ assert payload["node_to_tree"]
+ assert payload["message_log"]
+
+ restored = FakePlatformDriver("telegram", tmp_path)
+ saved = restored.session_store.get_all_trees()
+ assert saved
+ assert root.message_id in restored.session_store.get_node_mapping()
+
+
[email protected]("platform_name", ["discord", "telegram"])
+async def test_voice_platform_fake_e2e(platform_name: str, tmp_path) -> None:
+ driver = FakePlatformDriver(platform_name, tmp_path)
+ driver.platform.register_pending_voice("chat_1", "voice_msg_1", "voice_status_1")
+
+ await driver.send("/clear", message_id="clear_voice", reply_to="voice_msg_1")
+
+ deleted = {entry["message_id"] for entry in driver.platform.deletes}
+ assert {"voice_msg_1", "voice_status_1", "clear_voice"} <= deleted
+ sent_text = "\n".join(sent["text"] for sent in driver.platform.sent)
+ assert "Voice note cancelled" in sent_text
diff --git a/smoke/product/test_provider_product_live.py b/smoke/product/test_provider_product_live.py
new file mode 100644
index 00000000..b554920c
--- /dev/null
+++ b/smoke/product/test_provider_product_live.py
@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from smoke.lib.config import ProviderModel, SmokeConfig, auth_headers
+from smoke.lib.e2e import (
+ ConversationDriver,
+ ProviderMatrixDriver,
+ SmokeServerDriver,
+ assert_product_stream,
+ echo_tool_schema,
+ tool_use_blocks,
+)
+from smoke.lib.skips import (
+ skip_if_upstream_unavailable_events,
+ skip_if_upstream_unavailable_exception,
+)
+from smoke.lib.sse import (
+ assert_anthropic_stream_contract,
+ parse_sse_lines,
+ text_content,
+)
+
+pytestmark = [pytest.mark.live, pytest.mark.smoke_target("providers")]
+
+
+def test_provider_matrix_presence_e2e(smoke_config: SmokeConfig) -> None:
+ models = ProviderMatrixDriver(smoke_config).configured_models()
+ assert models or smoke_config.provider_matrix == frozenset()
+
+
+def test_model_mapping_matrix_e2e(smoke_config: SmokeConfig) -> None:
+ models = ProviderMatrixDriver(smoke_config).configured_models()
+ sources = {model.source for model in models}
+ assert sources <= {"MODEL", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"}
+ for model in models:
+ assert model.provider
+ assert model.model_name
+
+
+def test_provider_text_multiturn_e2e(smoke_config: SmokeConfig) -> None:
+ _run_for_each_provider(smoke_config, _scenario_text_multiturn)
+
+
+def test_provider_adaptive_thinking_history_e2e(smoke_config: SmokeConfig) -> None:
+ _run_for_each_provider(smoke_config, _scenario_adaptive_thinking_history)
+
+
+def test_provider_interleaved_thinking_tool_e2e(smoke_config: SmokeConfig) -> None:
+ _run_for_each_provider(smoke_config, _scenario_interleaved_history)
+
+
[email protected]_target("tools")
+def test_provider_tool_result_continuation_e2e(smoke_config: SmokeConfig) -> None:
+ _run_for_each_provider(smoke_config, _scenario_tool_result_continuation)
+
+
[email protected]_target("rate_limit")
+def test_provider_disconnect_e2e(smoke_config: SmokeConfig) -> None:
+ _run_for_each_provider(smoke_config, _scenario_disconnect)
+
+
+def test_provider_error_e2e(smoke_config: SmokeConfig) -> None:
+ provider_model = ProviderMatrixDriver(smoke_config).first_model()
+ broken_model = f"{provider_model.provider}/fcc-smoke-missing-model"
+ with (
+ SmokeServerDriver(
+ smoke_config,
+ name=f"product-provider-error-{provider_model.provider}",
+ env_overrides={"MODEL": broken_model, "MESSAGING_PLATFORM": "none"},
+ ).run() as server,
+ httpx.stream(
+ "POST",
+ f"{server.base_url}/v1/messages",
+ headers=auth_headers(),
+ json={
+ "model": "fcc-smoke-default",
+ "max_tokens": 32,
+ "messages": [{"role": "user", "content": "hello"}],
+ },
+ timeout=smoke_config.timeout_s,
+ ) as response,
+ ):
+ assert response.status_code == 200, response.read()
+ events = parse_sse_lines(response.iter_lines())
+ assert_anthropic_stream_contract(events, allow_error=True)
+ assert any(event.event == "error" for event in events) or text_content(events)
+
+
+def test_openrouter_native_and_rollback_e2e(smoke_config: SmokeConfig) -> None:
+ models = [
+ model
+ for model in ProviderMatrixDriver(smoke_config).configured_models()
+ if model.provider == "open_router"
+ ]
+ if not models:
+ pytest.skip("missing_env: open_router is not configured")
+
+ provider_model = models[0]
+ for transport in ("anthropic", "openai"):
+ with SmokeServerDriver(
+ smoke_config,
+ name=f"product-openrouter-{transport}",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ "OPENROUTER_TRANSPORT": transport,
+ },
+ ).run() as server:
+ turn = ConversationDriver(server, smoke_config).stream(
+ {
+ "model": "claude-opus-4-7",
+ "max_tokens": 256,
+ "messages": [
+ {
+ "role": "user",
+ "content": "Reply with one short sentence.",
+ }
+ ],
+ "thinking": {"type": "adaptive", "budget_tokens": 1024},
+ }
+ )
+ assert_product_stream(turn.events)
+
+
+def _run_for_each_provider(smoke_config: SmokeConfig, scenario) -> None:
+ failures: list[str] = []
+ for provider_model in ProviderMatrixDriver(smoke_config).configured_models():
+ try:
+ scenario(smoke_config, provider_model)
+ except Exception as exc:
+ skip_if_upstream_unavailable_exception(exc)
+ failures.append(
+ f"{provider_model.source}={provider_model.full_model}: "
+ f"{type(exc).__name__}: {exc}"
+ )
+ assert not failures, "\n".join(failures)
+
+
+def _scenario_text_multiturn(
+ smoke_config: SmokeConfig, provider_model: ProviderModel
+) -> None:
+ with _server_for_provider(smoke_config, provider_model, "text") as server:
+ driver = ConversationDriver(server, smoke_config)
+ first = driver.ask("Reply with one short sentence.")
+ second = driver.ask("Reply with a different short sentence.")
+ assert_product_stream(first.events)
+ assert_product_stream(second.events)
+
+
+def _scenario_adaptive_thinking_history(
+ smoke_config: SmokeConfig, provider_model: ProviderModel
+) -> None:
+ payload = {
+ "model": "claude-opus-4-7",
+ "max_tokens": 256,
+ "messages": [
+ {"role": "user", "content": "hello"},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "unsigned hidden thought"},
+ {"type": "redacted_thinking", "data": "opaque"},
+ {"type": "text", "text": "Hello."},
+ ],
+ },
+ {"role": "user", "content": "Reply with one short sentence."},
+ ],
+ "thinking": {"type": "adaptive", "budget_tokens": 1024},
+ }
+ with _server_for_provider(smoke_config, provider_model, "adaptive") as server:
+ turn = ConversationDriver(server, smoke_config).stream(payload)
+ assert_product_stream(turn.events)
+
+
+def _scenario_interleaved_history(
+ smoke_config: SmokeConfig, provider_model: ProviderModel
+) -> None:
+ payload = {
+ "model": "claude-sonnet-4-5-20250929",
+ "max_tokens": 256,
+ "messages": [
+ {"role": "user", "content": "Use the tool."},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "Need to inspect first."},
+ {"type": "text", "text": "I will call the tool."},
+ {
+ "type": "tool_use",
+ "id": "toolu_interleaved",
+ "name": "echo_smoke",
+ "input": {"value": "FCC_INTERLEAVED"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "toolu_interleaved",
+ "content": "FCC_INTERLEAVED",
+ }
+ ],
+ },
+ ],
+ "tools": [echo_tool_schema()],
+ "thinking": {"type": "adaptive"},
+ }
+ with _server_for_provider(smoke_config, provider_model, "interleaved") as server:
+ turn = ConversationDriver(server, smoke_config).stream(payload)
+ assert_product_stream(turn.events)
+
+
+def _scenario_tool_result_continuation(
+ smoke_config: SmokeConfig, provider_model: ProviderModel
+) -> None:
+ first_payload = {
+ "model": "claude-sonnet-4-5-20250929",
+ "max_tokens": 256,
+ "messages": [
+ {"role": "user", "content": "Use echo_smoke once with value FCC_TOOL."}
+ ],
+ "tools": [echo_tool_schema()],
+ "tool_choice": {"type": "tool", "name": "echo_smoke"},
+ "thinking": {"type": "adaptive"},
+ }
+ with _server_for_provider(smoke_config, provider_model, "tool") as server:
+ driver = ConversationDriver(server, smoke_config)
+ first = driver.stream(first_payload)
+ tool_uses = tool_use_blocks(first.events)
+ assert tool_uses, "provider did not emit a tool_use block"
+ tool_use = tool_uses[0]
+ second_payload = {
+ "model": "claude-sonnet-4-5-20250929",
+ "max_tokens": 256,
+ "messages": [
+ first_payload["messages"][0],
+ {"role": "assistant", "content": first.assistant_content},
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": tool_use["id"],
+ "content": "FCC_TOOL",
+ }
+ ],
+ },
+ ],
+ "tools": [echo_tool_schema()],
+ }
+ second = driver.stream(second_payload)
+ assert_product_stream(first.events)
+ assert_product_stream(second.events)
+
+
+def _scenario_disconnect(
+ smoke_config: SmokeConfig, provider_model: ProviderModel
+) -> None:
+ with _server_for_provider(smoke_config, provider_model, "disconnect") as server:
+ with httpx.stream(
+ "POST",
+ f"{server.base_url}/v1/messages",
+ headers=auth_headers(),
+ json={
+ "model": "fcc-smoke-default",
+ "max_tokens": 512,
+ "messages": [{"role": "user", "content": smoke_config.prompt}],
+ },
+ timeout=smoke_config.timeout_s,
+ ) as response:
+ assert response.status_code == 200, response.read()
+ for _line in response.iter_lines():
+ break
+ health = httpx.get(f"{server.base_url}/health", timeout=5)
+ assert health.status_code == 200
+ followup = ConversationDriver(server, smoke_config).ask(
+ "Reply with one short sentence."
+ )
+ skip_if_upstream_unavailable_events(followup.events)
+ assert_product_stream(followup.events)
+
+
+def _server_for_provider(
+ smoke_config: SmokeConfig, provider_model: ProviderModel, name: str
+):
+ return SmokeServerDriver(
+ smoke_config,
+ name=f"product-provider-{provider_model.provider}-{name}",
+ env_overrides={
+ "MODEL": provider_model.full_model,
+ "MESSAGING_PLATFORM": "none",
+ },
+ ).run()
diff --git a/smoke/product/test_voice_product_live.py b/smoke/product/test_voice_product_live.py
new file mode 100644
index 00000000..d1c27f53
--- /dev/null
+++ b/smoke/product/test_voice_product_live.py
@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from messaging.transcription import transcribe_audio
+from smoke.lib.config import SmokeConfig
+from smoke.lib.e2e import VoiceFixtureDriver
+
+pytestmark = [pytest.mark.live]
+
+
[email protected]_target("voice")
+def test_voice_local_backend_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:
+ if not smoke_config.settings.voice_note_enabled:
+ pytest.skip("missing_env: VOICE_NOTE_ENABLED is false")
+ if os.getenv("FCC_SMOKE_RUN_VOICE") != "1":
+ pytest.skip("missing_env: set FCC_SMOKE_RUN_VOICE=1 to run voice product smoke")
+ if smoke_config.settings.whisper_device not in {"cpu", "cuda"}:
+ pytest.skip("missing_env: WHISPER_DEVICE must be cpu or cuda")
+
+ wav_path = tmp_path / "voice-local-product.wav"
+ VoiceFixtureDriver.write_tone_wav(wav_path)
+ try:
+ text = transcribe_audio(
+ wav_path,
+ "audio/wav",
+ whisper_model=smoke_config.settings.whisper_model,
+ whisper_device=smoke_config.settings.whisper_device,
+ )
+ except ImportError as exc:
+ pytest.skip(f"missing_env: {exc}")
+
+ assert isinstance(text, str)
+ assert text.strip()
+
+
[email protected]_target("voice")
+def test_voice_nim_backend_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:
+ if not smoke_config.settings.voice_note_enabled:
+ pytest.skip("missing_env: VOICE_NOTE_ENABLED is false")
+ if os.getenv("FCC_SMOKE_RUN_VOICE") != "1":
+ pytest.skip("missing_env: set FCC_SMOKE_RUN_VOICE=1 to run voice product smoke")
+ if smoke_config.settings.whisper_device != "nvidia_nim":
+ pytest.skip("missing_env: WHISPER_DEVICE must be nvidia_nim")
+ if not smoke_config.settings.nvidia_nim_api_key.strip():
+ pytest.skip("missing_env: NVIDIA_NIM_API_KEY is required")
+
+ wav_path = tmp_path / "voice-nim-product.wav"
+ VoiceFixtureDriver.write_tone_wav(wav_path)
+ text = transcribe_audio(
+ wav_path,
+ "audio/wav",
+ whisper_model=smoke_config.settings.whisper_model,
+ whisper_device="nvidia_nim",
+ )
+
+ assert isinstance(text, str)
+ assert text.strip()
diff --git a/tests/api/test_model_router.py b/tests/api/test_model_router.py
new file mode 100644
index 00000000..52d107bc
--- /dev/null
+++ b/tests/api/test_model_router.py
@@ -0,0 +1,96 @@
+from unittest.mock import patch
+
+import pytest
+
+from api.model_router import ModelRouter
+from api.models.anthropic import Message, MessagesRequest, TokenCountRequest
+from config.settings import Settings
+
+
+def settings():
+ settings = Settings()
+ settings.model = "nvidia_nim/fallback-model"
+ settings.model_opus = None
+ settings.model_sonnet = None
+ settings.model_haiku = None
+ return settings
+
+
+def test_model_router_resolves_default_model(settings):
+ resolved = ModelRouter(settings).resolve("claude-3-opus")
+
+ assert resolved.original_model == "claude-3-opus"
+ assert resolved.provider_id == "nvidia_nim"
+ assert resolved.provider_model == "fallback-model"
+ assert resolved.provider_model_ref == "nvidia_nim/fallback-model"
+
+
+def test_model_router_applies_opus_override(settings):
+ settings.model_opus = "open_router/deepseek/deepseek-r1"
+
+ request = MessagesRequest(
+ model="claude-opus-4-20250514",
+ max_tokens=100,
+ messages=[Message(role="user", content="hello")],
+ )
+ routed = ModelRouter(settings).resolve_messages_request(request)
+
+ assert routed.model == "deepseek/deepseek-r1"
+ assert routed.resolved_provider_model == "open_router/deepseek/deepseek-r1"
+ assert routed.original_model == "claude-opus-4-20250514"
+ assert request.model == "claude-opus-4-20250514"
+
+
+def test_model_router_applies_haiku_override(settings):
+ settings.model_haiku = "lmstudio/qwen2.5-7b"
+
+ routed = ModelRouter(settings).resolve_messages_request(
+ MessagesRequest(
+ model="claude-3-haiku-20240307",
+ max_tokens=100,
+ messages=[Message(role="user", content="hello")],
+ )
+ )
+
+ assert routed.model == "qwen2.5-7b"
+ assert routed.resolved_provider_model == "lmstudio/qwen2.5-7b"
+
+
+def test_model_router_applies_sonnet_override(settings):
+ settings.model_sonnet = "nvidia_nim/meta/llama-3.3-70b-instruct"
+
+ routed = ModelRouter(settings).resolve_messages_request(
+ MessagesRequest(
+ model="claude-sonnet-4-20250514",
+ max_tokens=100,
+ messages=[Message(role="user", content="hello")],
+ )
+ )
+
+ assert routed.model == "meta/llama-3.3-70b-instruct"
+ assert routed.resolved_provider_model == "nvidia_nim/meta/llama-3.3-70b-instruct"
+
+
+def test_model_router_routes_token_count_request(settings):
+ settings.model_haiku = "lmstudio/qwen2.5-7b"
+
+ request = TokenCountRequest(
+ model="claude-3-haiku-20240307",
+ messages=[Message(role="user", content="hello")],
+ )
+ routed = ModelRouter(settings).resolve_token_count_request(request)
+
+ assert routed.model == "qwen2.5-7b"
+ assert request.model == "claude-3-haiku-20240307"
+
+
+def test_model_router_logs_mapping(settings):
+ with patch("api.model_router.logger.debug") as mock_log:
+ ModelRouter(settings).resolve("claude-2.1")
+
+ mock_log.assert_called()
+ args = mock_log.call_args[0]
+ assert "MODEL MAPPING" in args[0]
+ assert args[1] == "claude-2.1"
+ assert args[2] == "fallback-model"
diff --git a/tests/api/test_models_validators.py b/tests/api/test_models_validators.py
index b6089dea..d74da705 100644
--- a/tests/api/test_models_validators.py
+++ b/tests/api/test_models_validators.py
@@ -1,163 +1,113 @@
-from unittest.mock import patch
+from api.models.anthropic import Message, MessagesRequest, TokenCountRequest
-import pytest
-from api.models.anthropic import Message, MessagesRequest, TokenCountRequest
-from config.settings import Settings
-
-
-def mock_settings():
- settings = Settings()
- settings.model = "nvidia_nim/target-model-from-settings"
- settings.model_opus = None
- settings.model_sonnet = None
- settings.model_haiku = None
- return settings
-
-
-def test_messages_request_map_model_claude_to_default(mock_settings):
- with patch("api.models.anthropic.get_settings", return_value=mock_settings):
- request = MessagesRequest(
- model="claude-3-opus",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
-
- assert request.model == "target-model-from-settings"
- assert request.original_model == "claude-3-opus"
-
-
-def test_messages_request_map_model_with_provider_prefix(mock_settings):
- with patch("api.models.anthropic.get_settings", return_value=mock_settings):
- request = MessagesRequest(
- model="anthropic/claude-3-haiku",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
-
- assert request.model == "target-model-from-settings"
-
-
-def test_token_count_request_model_validation(mock_settings):
- with patch("api.models.anthropic.get_settings", return_value=mock_settings):
- request = TokenCountRequest(
- model="claude-3-sonnet", messages=[Message(role="user", content="hello")]
- )
-
- assert request.model == "target-model-from-settings"
-
-
-def test_messages_request_model_mapping_logs(mock_settings):
- with (
- patch("api.models.anthropic.get_settings", return_value=mock_settings),
- patch("api.models.anthropic.logger.debug") as mock_log,
- ):
- MessagesRequest(
- model="claude-2.1",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
-
- mock_log.assert_called()
- args = mock_log.call_args[0][0]
- assert "MODEL MAPPING" in args
- assert "claude-2.1" in args
- assert "target-model-from-settings" in args
-
-
-def test_messages_request_resolved_provider_model_default(mock_settings):
- """resolved_provider_model is set to the full model string."""
- with patch("api.models.anthropic.get_settings", return_value=mock_settings):
- request = MessagesRequest(
- model="claude-3-opus",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
- assert (
- request.resolved_provider_model == "nvidia_nim/target-model-from-settings"
- )
-
-
-def test_messages_request_model_aware_opus_override():
- """Opus model routes to MODEL_OPUS when set."""
- settings = Settings()
- settings.model = "nvidia_nim/fallback-model"
- settings.model_opus = "open_router/deepseek/deepseek-r1"
-
- with patch("api.models.anthropic.get_settings", return_value=settings):
- request = MessagesRequest(
- model="claude-opus-4-20250514",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
- assert request.model == "deepseek/deepseek-r1"
- assert request.resolved_provider_model == "open_router/deepseek/deepseek-r1"
- assert request.original_model == "claude-opus-4-20250514"
-
-
-def test_messages_request_model_aware_haiku_override():
- """Haiku model routes to MODEL_HAIKU when set."""
- settings = Settings()
- settings.model = "nvidia_nim/fallback-model"
- settings.model_haiku = "lmstudio/qwen2.5-7b"
-
- with patch("api.models.anthropic.get_settings", return_value=settings):
- request = MessagesRequest(
- model="claude-3-haiku-20240307",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
- assert request.model == "qwen2.5-7b"
- assert request.resolved_provider_model == "lmstudio/qwen2.5-7b"
-
-
-def test_messages_request_model_aware_sonnet_override():
- """Sonnet model routes to MODEL_SONNET when set."""
- settings = Settings()
- settings.model = "nvidia_nim/fallback-model"
- settings.model_sonnet = "nvidia_nim/meta/llama-3.3-70b-instruct"
-
- with patch("api.models.anthropic.get_settings", return_value=settings):
- request = MessagesRequest(
- model="claude-sonnet-4-20250514",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
- assert request.model == "meta/llama-3.3-70b-instruct"
- assert (
- request.resolved_provider_model == "nvidia_nim/meta/llama-3.3-70b-instruct"
- )
-
-
-def test_messages_request_model_fallback_when_not_set():
- """When model override is None, falls back to MODEL."""
- settings = Settings()
- settings.model = "nvidia_nim/fallback-model"
- settings.model_opus = None
- settings.model_sonnet = None
- settings.model_haiku = None
- # model_opus is None
-
- with patch("api.models.anthropic.get_settings", return_value=settings):
- request = MessagesRequest(
- model="claude-opus-4-20250514",
- max_tokens=100,
- messages=[Message(role="user", content="hello")],
- )
- assert request.model == "fallback-model"
- assert request.resolved_provider_model == "nvidia_nim/fallback-model"
-
-
-def test_token_count_request_model_aware():
- """TokenCountRequest also uses model-aware resolution."""
- settings = Settings()
- settings.model = "nvidia_nim/fallback-model"
- settings.model_haiku = "lmstudio/qwen2.5-7b"
-
- with patch("api.models.anthropic.get_settings", return_value=settings):
- request = TokenCountRequest(
- model="claude-3-haiku-20240307",
- messages=[Message(role="user", content="hello")],
- )
- assert request.model == "qwen2.5-7b"
+def test_messages_request_parses_without_model_mapping_side_effects():
+ request = MessagesRequest(
+ model="claude-3-opus",
+ max_tokens=100,
+ messages=[Message(role="user", content="hello")],
+ )
+
+ assert request.model == "claude-3-opus"
+ assert request.original_model is None
+ assert request.resolved_provider_model is None
+
+
+def test_messages_request_preserves_internal_routing_fields_when_supplied():
+ request = MessagesRequest(
+ model="target-model",
+ original_model="claude-3-opus",
+ resolved_provider_model="nvidia_nim/target-model",
+ max_tokens=100,
+ messages=[Message(role="user", content="hello")],
+ )
+
+ assert request.model == "target-model"
+ assert request.original_model == "claude-3-opus"
+ assert request.resolved_provider_model == "nvidia_nim/target-model"
+
+
+def test_token_count_request_parses_without_model_mapping_side_effects():
+ request = TokenCountRequest(
+ model="claude-3-sonnet", messages=[Message(role="user", content="hello")]
+ )
+
+ assert request.model == "claude-3-sonnet"
+
+
+def test_messages_request_preserves_thinking_signature():
+ request = MessagesRequest.model_validate(
+ {
+ "model": "claude-3-opus",
+ "max_tokens": 100,
+ "messages": [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "thinking",
+ "thinking": "signed thought",
+ "signature": "sig_123",
+ }
+ ],
+ }
+ ],
+ }
+ )
+
+ dumped = request.model_dump(exclude_none=True)
+
+ assert dumped["messages"][0]["content"][0]["signature"] == "sig_123"
+
+
+def test_messages_request_preserves_native_thinking_budget():
+ request = MessagesRequest.model_validate(
+ {
+ "model": "claude-3-opus",
+ "max_tokens": 100,
+ "messages": [{"role": "user", "content": "think hard"}],
+ "thinking": {"type": "enabled", "budget_tokens": 4096},
+ }
+ )
+
+ dumped = request.model_dump(exclude_none=True)
+
+ assert dumped["thinking"]["type"] == "enabled"
+ assert dumped["thinking"]["budget_tokens"] == 4096
+
+
+def test_messages_request_accepts_adaptive_thinking_type():
+ request = MessagesRequest.model_validate(
+ {
+ "model": "claude-3-opus",
+ "max_tokens": 100,
+ "messages": [{"role": "user", "content": "hello"}],
+ "thinking": {"type": "adaptive"},
+ }
+ )
+
+ dumped = request.model_dump(exclude_none=True)
+
+ assert dumped["thinking"]["type"] == "adaptive"
+
+
+def test_messages_request_accepts_redacted_thinking_blocks():
+ request = MessagesRequest.model_validate(
+ {
+ "model": "claude-3-opus",
+ "max_tokens": 100,
+ "messages": [
+ {
+ "role": "assistant",
+ "content": [{"type": "redacted_thinking", "data": "opaque"}],
+ }
+ ],
+ }
+ )
+
+ dumped = request.model_dump(exclude_none=True)
+
+ assert dumped["messages"][0]["content"][0] == {
+ "type": "redacted_thinking",
+ "data": "opaque",
+ }
diff --git a/tests/contracts/test_capability_map.py b/tests/contracts/test_capability_map.py
new file mode 100644
index 00000000..4b6e41a2
--- /dev/null
+++ b/tests/contracts/test_capability_map.py
@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from smoke.capabilities import (
+ CAPABILITY_CONTRACTS,
+ capability_names,
+ contracted_feature_ids,
+)
+from smoke.features import FEATURE_INVENTORY, feature_ids
+
+EXPECTED_CAPABILITIES = {
+ "api_compatibility",
+ "auth",
+ "cli",
+ "config",
+ "extensibility",
+ "local_providers",
+ "messaging",
+ "openrouter",
+ "persistence",
+ "provider_routing",
+ "provider_runtime",
+ "request_behavior",
+ "streaming_conversion",
+ "voice",
+}
+
+
+def test_capability_map_covers_every_public_feature() -> None:
+ assert contracted_feature_ids() == feature_ids()
+
+
+def test_capability_map_has_expected_top_level_groups() -> None:
+ assert capability_names() == EXPECTED_CAPABILITIES
+
+
+def test_capability_contracts_are_decision_complete() -> None:
+ known_features = {feature.feature_id: feature for feature in FEATURE_INVENTORY}
+
+ for contract in CAPABILITY_CONTRACTS:
+ assert contract.feature_id in known_features, contract
+ assert contract.capability.strip(), contract
+ assert contract.subfeature.strip(), contract
+ assert contract.owner.strip(), contract
+ assert contract.inputs.strip(), contract
+ assert contract.outputs.strip(), contract
+ assert contract.failure.strip(), contract
+
+ assert contract.pytest_tests or contract.smoke_tests, contract
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index 71d3deee..2e745ddc 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -12,7 +12,6 @@ from providers.nvidia_nim import NvidiaNimProvider
from providers.open_router import OpenRouterProvider
from smoke.features import FEATURE_INVENTORY, README_FEATURES, feature_ids
-VALID_COVERAGE = {"pytest", "live_smoke", "both"}
VALID_SOURCE = {"readme", "public_surface"}
@@ -32,13 +31,16 @@ def test_feature_inventory_is_unique_and_decision_complete() -> None:
for feature in FEATURE_INVENTORY:
assert feature.source in VALID_SOURCE, feature
- assert feature.coverage in VALID_COVERAGE, feature
assert feature.title.strip(), feature
assert feature.skip_policy.strip(), feature
- if feature.has_pytest_coverage:
- assert feature.pytest_tests, feature
- if feature.has_smoke_coverage:
- assert feature.smoke_tests, feature
+ assert feature.pytest_contract_tests, feature
+ assert feature.has_pytest_coverage, feature
+ if feature.product_e2e_tests:
+ assert feature.smoke_targets, feature
+ assert not feature.product_e2e_reason, feature
+ else:
+ assert feature.product_e2e_reason.strip(), feature
+ if feature.live_prereq_tests:
assert feature.smoke_targets, feature
@@ -48,12 +50,20 @@ def test_feature_inventory_test_owners_exist() -> None:
smoke_names = _collect_test_names(repo_root / "smoke")
for feature in FEATURE_INVENTORY:
- for owner in feature.pytest_tests:
+ for owner in feature.pytest_contract_tests:
_assert_owner_exists(owner, repo_root, pytest_names)
- for owner in feature.smoke_tests:
+ for owner in feature.live_prereq_tests + feature.product_e2e_tests:
assert owner in smoke_names or owner in pytest_names, (feature, owner)
+def test_product_coverage_is_not_satisfied_by_prereq_probes() -> None:
+ for feature in FEATURE_INVENTORY:
+ overlap = set(feature.live_prereq_tests) & set(feature.product_e2e_tests)
+ assert not overlap, (feature.feature_id, sorted(overlap))
+ if feature.product_e2e_tests:
+ assert all("_e2e" in name for name in feature.product_e2e_tests), feature
+
+
def test_provider_and_platform_registries_include_advertised_builtins() -> None:
provider_classes = {
"nvidia_nim": NvidiaNimProvider,
diff --git a/tests/messaging/test_rendering_profiles.py b/tests/messaging/test_rendering_profiles.py
new file mode 100644
index 00000000..0c1abc4a
--- /dev/null
+++ b/tests/messaging/test_rendering_profiles.py
@@ -0,0 +1,17 @@
+from messaging.rendering.profiles import build_rendering_profile
+
+
+def test_discord_rendering_profile_has_plain_parse_mode():
+ profile = build_rendering_profile("discord")
+
+ assert profile.parse_mode is None
+ assert profile.limit_chars == 1900
+ assert profile.format_status("x", "Working", None).startswith("x")
+
+
+def test_telegram_rendering_profile_uses_markdown_v2():
+ profile = build_rendering_profile("telegram")
+
+ assert profile.parse_mode == "MarkdownV2"
+ assert profile.limit_chars == 3900
+ assert profile.format_status("x", "Working", None).startswith("x")
diff --git a/tests/messaging/test_voice_services.py b/tests/messaging/test_voice_services.py
new file mode 100644
index 00000000..55feb16e
--- /dev/null
+++ b/tests/messaging/test_voice_services.py
@@ -0,0 +1,42 @@
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from messaging.voice import PendingVoiceRegistry, VoiceTranscriptionService
+
+
+async def test_pending_voice_registry_tracks_voice_and_status_ids():
+ registry = PendingVoiceRegistry()
+
+ await registry.register("chat", "voice-1", "status-1")
+
+ assert await registry.is_pending("chat", "voice-1") is True
+ assert await registry.cancel("chat", "status-1") == ("voice-1", "status-1")
+ assert await registry.is_pending("chat", "voice-1") is False
+
+
+async def test_pending_voice_registry_complete_removes_entries():
+ registry = PendingVoiceRegistry()
+
+ await registry.register("chat", "voice-1", "status-1")
+ await registry.complete("chat", "voice-1", "status-1")
+
+ assert await registry.cancel("chat", "voice-1") is None
+
+
+async def test_voice_transcription_service_runs_backend():
+ service = VoiceTranscriptionService()
+
+ with patch("messaging.transcription.transcribe_audio", return_value="hello"):
+ text = await service.transcribe(
+ Path("audio.ogg"),
+ "audio/ogg",
+ whisper_model="base",
+ whisper_device="cpu",
+ )
+
+ assert text == "hello"
diff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.py
new file mode 100644
index 00000000..2d9498d9
--- /dev/null
+++ b/tests/providers/test_anthropic_messages.py
@@ -0,0 +1,216 @@
+"""Tests for the shared native Anthropic Messages transport."""
+
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+from providers.anthropic_messages import AnthropicMessagesTransport
+from providers.base import ProviderConfig
+
+
+class NativeProvider(AnthropicMessagesTransport):
+ def __init__(self, config: ProviderConfig):
+ super().__init__(
+ config,
+ provider_name="TEST_NATIVE",
+ default_base_url="https://example.test/v1",
+ )
+
+ def _request_headers(self) -> dict[str, str]:
+ return {"Content-Type": "application/json", "X-Test": "1"}
+
+
+class MockRequest:
+ model = "test-model"
+
+ def __init__(self, *, thinking_enabled: bool = True, body: dict | None = None):
+ self.thinking = MagicMock()
+ self.thinking.enabled = thinking_enabled
+ self._body = body or {
+ "model": self.model,
+ "messages": [{"role": "user", "content": "Hello"}],
+ "extra_body": {"ignored": True},
+ "original_model": "claude",
+ "resolved_provider_model": "native/test-model",
+ "thinking": {"enabled": thinking_enabled},
+ }
+
+ def model_dump(self, exclude_none=True):
+ return dict(self._body)
+
+
+class FakeResponse:
+ def __init__(self, *, status_code=200, lines=None, text=""):
+ self.status_code = status_code
+ self._lines = lines or []
+ self._text = text
+ self.is_closed = False
+ self.request = httpx.Request("POST", "https://example.test/v1/messages")
+
+ async def aiter_lines(self):
+ for line in self._lines:
+ yield line
+
+ async def aread(self):
+ return self._text.encode()
+
+ def raise_for_status(self):
+ response = httpx.Response(
+ self.status_code,
+ request=self.request,
+ text=self._text,
+ )
+ response.raise_for_status()
+
+ async def aclose(self):
+ self.is_closed = True
+
+
+def provider_config():
+ return ProviderConfig(
+ api_key="test-key",
+ base_url="https://custom.test/v1/",
+ proxy="socks5://127.0.0.1:9999",
+ rate_limit=10,
+ rate_window=60,
+ http_read_timeout=600.0,
+ http_write_timeout=15.0,
+ http_connect_timeout=5.0,
+ )
+
+
[email protected](autouse=True)
+def mock_rate_limiter():
+ @asynccontextmanager
+ async def _slot():
+ yield
+
+ with patch("providers.anthropic_messages.GlobalRateLimiter") as mock:
+ instance = mock.get_scoped_instance.return_value
+
+ async def _passthrough(fn, *args, **kwargs):
+ return await fn(*args, **kwargs)
+
+ instance.execute_with_retry = AsyncMock(side_effect=_passthrough)
+ instance.concurrency_slot.side_effect = _slot
+ yield instance
+
+
+def test_init_configures_httpx_client(provider_config):
+ with patch("httpx.AsyncClient") as mock_client:
+ provider = NativeProvider(provider_config)
+
+ assert provider._provider_name == "TEST_NATIVE"
+ assert provider._api_key == "test-key"
+ assert provider._base_url == "https://custom.test/v1"
+ kwargs = mock_client.call_args.kwargs
+ timeout = kwargs["timeout"]
+ assert kwargs["base_url"] == "https://custom.test/v1"
+ assert kwargs["proxy"] == "socks5://127.0.0.1:9999"
+ assert timeout.read == 600.0
+ assert timeout.write == 15.0
+ assert timeout.connect == 5.0
+
+
+def test_default_request_body_strips_internal_fields(provider_config):
+ provider = NativeProvider(provider_config)
+
+ body = provider._build_request_body(MockRequest())
+
+ assert body["model"] == "test-model"
+ assert body["thinking"] == {"type": "enabled"}
+ assert body["max_tokens"] == 81920
+ assert "extra_body" not in body
+ assert "original_model" not in body
+ assert "resolved_provider_model" not in body
+
+
+def test_default_request_body_preserves_thinking_budget(provider_config):
+ provider = NativeProvider(provider_config)
+ req = MockRequest(
+ body={
+ "model": "test-model",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "thinking": {"type": "enabled", "budget_tokens": 4096},
+ }
+ )
+
+ body = provider._build_request_body(req)
+
+ assert body["thinking"] == {"type": "enabled", "budget_tokens": 4096}
+
+
+async def test_stream_uses_retry_builds_request_and_closes_response(
+ provider_config,
+ mock_rate_limiter,
+):
+ provider = NativeProvider(provider_config)
+ req = MockRequest()
+ request_obj = httpx.Request("POST", "https://custom.test/v1/messages")
+ response = FakeResponse(
+ lines=[
+ "event: message_start",
+ 'data: {"type":"message_start"}',
+ "",
+ ]
+ )
+
+ with (
+ patch.object(
+ provider._client, "build_request", return_value=request_obj
+ ) as mock_build,
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ) as mock_send,
+ ):
+ events = [event async for event in provider.stream_response(req)]
+
+ assert events == [
+ "event: message_start\n",
+ 'data: {"type":"message_start"}\n',
+ "\n",
+ ]
+ assert response.is_closed
+ assert mock_build.call_args.args[:2] == ("POST", "/messages")
+ assert mock_build.call_args.kwargs["headers"] == {
+ "Content-Type": "application/json",
+ "X-Test": "1",
+ }
+ assert mock_build.call_args.kwargs["json"]["thinking"] == {"type": "enabled"}
+ mock_send.assert_awaited_once_with(request_obj, stream=True)
+ mock_rate_limiter.execute_with_retry.assert_awaited_once()
+
+
+async def test_stream_maps_non_200_to_error_event_and_closes_response(
+ provider_config,
+):
+ provider = NativeProvider(provider_config)
+ req = MockRequest()
+ response = FakeResponse(status_code=500, text="Internal Server Error")
+
+ with (
+ patch.object(provider._client, "build_request", return_value=MagicMock()),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
+ events = [
+ event async for event in provider.stream_response(req, request_id="REQ_123")
+ ]
+
+ assert response.is_closed
+ assert len(events) == 1
+ assert events[0].startswith("event: error\ndata: {")
+ assert "Internal Server Error" in events[0]
+ assert "REQ_123" in events[0]
diff --git a/tests/providers/test_deepseek.py b/tests/providers/test_deepseek.py
index 965494af..bb00e0a3 100644
--- a/tests/providers/test_deepseek.py
+++ b/tests/providers/test_deepseek.py
@@ -52,7 +52,7 @@ def deepseek_config():
def mock_rate_limiter():
"""Mock the global rate limiter to prevent waiting."""
with patch("providers.openai_compat.GlobalRateLimiter") as mock:
- instance = mock.get_instance.return_value
+ instance = mock.get_scoped_instance.return_value
instance.wait_if_blocked = AsyncMock(return_value=False)
async def _passthrough(fn, *args, **kwargs):
diff --git a/tests/providers/test_nvidia_nim.py b/tests/providers/test_nvidia_nim.py
index 41d1e38d..4aa9aa82 100644
--- a/tests/providers/test_nvidia_nim.py
+++ b/tests/providers/test_nvidia_nim.py
@@ -52,7 +52,7 @@ def _make_bad_request_error(message: str) -> openai.BadRequestError:
def mock_rate_limiter():
"""Mock the global rate limiter to prevent waiting."""
with patch("providers.openai_compat.GlobalRateLimiter") as mock:
- instance = mock.get_instance.return_value
+ instance = mock.get_scoped_instance.return_value
instance.wait_if_blocked = AsyncMock(return_value=False)
# execute_with_retry should call through to the actual function
diff --git a/tests/providers/test_open_router.py b/tests/providers/test_open_router.py
index fbcfd475..1fa2cc37 100644
--- a/tests/providers/test_open_router.py
+++ b/tests/providers/test_open_router.py
@@ -1,12 +1,13 @@
-"""Tests for OpenRouter provider."""
+"""Tests for OpenRouter providers."""
import json
+from contextlib import asynccontextmanager
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from providers.base import ProviderConfig
-from providers.open_router import OpenRouterProvider
+from providers.open_router import OpenRouterChatProvider, OpenRouterProvider
from providers.open_router.request import OPENROUTER_DEFAULT_MAX_TOKENS
@@ -26,13 +27,45 @@ class MockRequest:
self.system = "System prompt"
self.stop_sequences = None
self.tools = []
+ self.tool_choice = None
+ self.metadata = None
self.extra_body = {}
+ self.original_model = "claude-3-sonnet"
+ self.resolved_provider_model = "open_router/stepfun/step-3.5-flash:free"
self.thinking = MagicMock()
self.thinking.enabled = True
for k, v in kwargs.items():
setattr(self, k, v)
+class FakeResponse:
+ def __init__(self, *, status_code=200, lines=None, text=""):
+ self.status_code = status_code
+ self._lines = lines or []
+ self._text = text
+ self.is_closed = False
+
+ async def aiter_lines(self):
+ for line in self._lines:
+ yield line
+
+ async def aread(self):
+ return self._text.encode()
+
+ def raise_for_status(self):
+ import httpx
+
+ response = httpx.Response(
+ self.status_code,
+ request=httpx.Request("POST", "https://openrouter.ai/api/v1/messages"),
+ text=self._text,
+ )
+ response.raise_for_status()
+
+ async def aclose(self):
+ self.is_closed = True
+
+
@pytest.fixture
def open_router_config():
return ProviderConfig(
@@ -45,15 +78,18 @@ def open_router_config():
@pytest.fixture(autouse=True)
def mock_rate_limiter():
- """Mock the global rate limiter to prevent waiting."""
- with patch("providers.openai_compat.GlobalRateLimiter") as mock:
- instance = mock.get_instance.return_value
- instance.wait_if_blocked = AsyncMock(return_value=False)
+ @asynccontextmanager
+ async def _slot():
+ yield
+
+ with patch("providers.anthropic_messages.GlobalRateLimiter") as mock:
+ instance = mock.get_scoped_instance.return_value
async def _passthrough(fn, *args, **kwargs):
return await fn(*args, **kwargs)
instance.execute_with_retry = AsyncMock(side_effect=_passthrough)
+ instance.concurrency_slot.side_effect = _slot
yield instance
@@ -64,15 +100,15 @@ def open_router_provider(open_router_config):
def test_init(open_router_config):
"""Test provider initialization."""
- with patch("providers.openai_compat.AsyncOpenAI") as mock_openai:
+ with patch("httpx.AsyncClient") as mock_client:
provider = OpenRouterProvider(open_router_config)
assert provider._api_key == "test_openrouter_key"
assert provider._base_url == "https://openrouter.ai/api/v1"
- mock_openai.assert_called_once()
+ mock_client.assert_called_once()
def test_init_uses_configurable_timeouts():
- """Test that provider passes configurable read/write/connect timeouts to client."""
+ """Provider passes configurable read/write/connect timeouts to httpx."""
config = ProviderConfig(
api_key="test_openrouter_key",
base_url="https://openrouter.ai/api/v1",
@@ -80,39 +116,39 @@ def test_init_uses_configurable_timeouts():
http_write_timeout=15.0,
http_connect_timeout=5.0,
)
- with patch("providers.openai_compat.AsyncOpenAI") as mock_openai:
+ with patch("httpx.AsyncClient") as mock_client:
OpenRouterProvider(config)
- call_kwargs = mock_openai.call_args[1]
- timeout = call_kwargs["timeout"]
+ timeout = mock_client.call_args.kwargs["timeout"]
assert timeout.read == 600.0
assert timeout.write == 15.0
assert timeout.connect == 5.0
-def test_build_request_body_has_reasoning_extra(open_router_provider):
- """Request body has extra_body.reasoning.enabled for thinking models."""
+def test_build_request_body_is_native_anthropic(open_router_provider):
req = MockRequest()
body = open_router_provider._build_request_body(req)
assert body["model"] == "stepfun/step-3.5-flash:free"
assert body["temperature"] == 0.5
- assert len(body["messages"]) == 2 # System + User
- assert body["messages"][0]["role"] == "system"
- assert body["messages"][0]["content"] == "System prompt"
-
- assert "extra_body" in body
- assert "reasoning" in body["extra_body"]
- assert body["extra_body"]["reasoning"]["enabled"] is True
+ assert body["stream"] is True
+ assert body["messages"] == [{"role": "user", "content": "Hello"}]
+ assert body["system"] == "System prompt"
+ assert body["reasoning"] == {"enabled": True}
+ assert "extra_body" not in body
+ assert "original_model" not in body
+ assert "resolved_provider_model" not in body
-def test_build_request_body_omits_reasoning_when_globally_disabled(open_router_config):
+def test_build_request_body_omits_reasoning_when_globally_disabled(
+ open_router_config,
+):
provider = OpenRouterProvider(
open_router_config.model_copy(update={"enable_thinking": False})
)
- req = MockRequest()
- body = provider._build_request_body(req)
- assert "extra_body" not in body or "reasoning" not in body["extra_body"]
+ body = provider._build_request_body(MockRequest())
+
+ assert "reasoning" not in body
def test_build_request_body_omits_reasoning_when_request_disables_thinking(
@@ -120,283 +156,310 @@ def test_build_request_body_omits_reasoning_when_request_disables_thinking(
):
req = MockRequest()
req.thinking.enabled = False
+
body = open_router_provider._build_request_body(req)
- assert "extra_body" not in body or "reasoning" not in body["extra_body"]
+ assert "reasoning" not in body
-def test_build_request_body_base_url_and_model(open_router_provider):
- """Base URL and model are correct in provider config."""
- assert open_router_provider._base_url == "https://openrouter.ai/api/v1"
- req = MockRequest(model="stepfun/step-3.5-flash:free")
+def test_build_request_body_omits_reasoning_when_native_thinking_disabled(
+ open_router_provider,
+):
+ req = MockRequest(thinking={"type": "disabled"})
+
body = open_router_provider._build_request_body(req)
- assert body["model"] == "stepfun/step-3.5-flash:free"
+
+ assert "reasoning" not in body
+
+
+def test_build_request_body_maps_thinking_budget_to_reasoning_max_tokens(
+ open_router_provider,
+):
+ req = MockRequest(thinking={"type": "enabled", "budget_tokens": 4096})
+
+ body = open_router_provider._build_request_body(req)
+
+ assert body["reasoning"] == {"enabled": True, "max_tokens": 4096}
def test_build_request_body_default_max_tokens(open_router_provider):
- """max_tokens=None uses OPENROUTER_DEFAULT_MAX_TOKENS (81920)."""
req = MockRequest(max_tokens=None)
+
body = open_router_provider._build_request_body(req)
+
assert body["max_tokens"] == OPENROUTER_DEFAULT_MAX_TOKENS
assert body["max_tokens"] == 81920
-async def test_stream_response_text(open_router_provider):
- """Test streaming text response."""
- req = MockRequest()
+def test_build_request_body_strips_unsigned_thinking_history(open_router_provider):
+ req = MockRequest(
+ messages=[
+ MockMessage("user", "hello"),
+ MockMessage(
+ "assistant",
+ [
+ {"type": "thinking", "thinking": "hidden"},
+ {"type": "redacted_thinking", "data": "opaque"},
+ {"type": "text", "text": "Hello"},
+ ],
+ ),
+ MockMessage("user", "can you think hard about 2+2"),
+ ]
+ )
- mock_chunk1 = MagicMock()
- mock_chunk1.choices = [
- MagicMock(
- delta=MagicMock(content="Hello", reasoning_content=None),
- finish_reason=None,
- )
- ]
- mock_chunk1.usage = None
+ body = open_router_provider._build_request_body(req)
- mock_chunk2 = MagicMock()
- mock_chunk2.choices = [
- MagicMock(
- delta=MagicMock(content=" World", reasoning_content=None),
- finish_reason="stop",
- )
- ]
- mock_chunk2.usage = MagicMock(completion_tokens=10)
+ assert body["messages"][1]["content"] == [{"type": "text", "text": "Hello"}]
+
+
+def test_build_request_body_preserves_signed_thinking_history(open_router_provider):
+ req = MockRequest(
+ messages=[
+ MockMessage(
+ "assistant",
+ [
+ {
+ "type": "thinking",
+ "thinking": "signed",
+ "signature": "sig_123",
+ }
+ ],
+ )
+ ]
+ )
- async def mock_stream():
- yield mock_chunk1
- yield mock_chunk2
+ body = open_router_provider._build_request_body(req)
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
+ assert body["messages"][0]["content"] == [
+ {"type": "thinking", "thinking": "signed", "signature": "sig_123"}
+ ]
- events = [e async for e in open_router_provider.stream_response(req)]
- assert len(events) > 0
- assert "event: message_start" in events[0]
+def test_build_request_body_flattens_system_blocks(open_router_provider):
+ req = MockRequest(
+ system=[
+ {"type": "text", "text": "First system block."},
+ {"type": "text", "text": "Second system block."},
+ ]
+ )
- text_content = ""
- for e in events:
- if "event: content_block_delta" in e and '"text_delta"' in e:
- for line in e.splitlines():
- if line.startswith("data: "):
- data = json.loads(line[6:])
- if "delta" in data and "text" in data["delta"]:
- text_content += data["delta"]["text"]
+ body = open_router_provider._build_request_body(req)
- assert "Hello World" in text_content
+ assert body["system"] == "First system block.\n\nSecond system block."
@pytest.mark.asyncio
-async def test_stream_response_reasoning_content(open_router_provider):
- """Test streaming with reasoning_content delta."""
+async def test_stream_response_passes_native_sse_events(open_router_provider):
req = MockRequest()
+ response = FakeResponse(
+ lines=[
+ "event: message_start",
+ 'data: {"type":"message_start","message":{}}',
+ "",
+ "event: content_block_delta",
+ 'data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}',
+ "",
+ "event: message_stop",
+ 'data: {"type":"message_stop"}',
+ "",
+ "event: data",
+ "data: [DONE]",
+ "",
+ ]
+ )
- mock_chunk = MagicMock()
- mock_chunk.choices = [
- MagicMock(
- delta=MagicMock(content=None, reasoning_content="Thinking..."),
- finish_reason=None,
- )
- ]
- mock_chunk.usage = None
-
- async def mock_stream():
- yield mock_chunk
-
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
-
+ with (
+ patch.object(open_router_provider._client, "build_request") as mock_build,
+ patch.object(
+ open_router_provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
events = [e async for e in open_router_provider.stream_response(req)]
- found_thinking = False
- for e in events:
- if (
- "event: content_block_delta" in e
- and '"thinking_delta"' in e
- and "Thinking..." in e
- ):
- found_thinking = True
- assert found_thinking
+ _, kwargs = mock_build.call_args
+ assert kwargs["headers"]["Authorization"] == "Bearer test_openrouter_key"
+ assert kwargs["headers"]["anthropic-version"] == "2023-06-01"
+ assert events[0].startswith("event: message_start")
+ assert events[-1].startswith("event: message_stop")
+ assert any("Hello" in event for event in events)
+ assert "[DONE]" not in "".join(events)
+ assert response.is_closed
@pytest.mark.asyncio
-async def test_stream_response_suppresses_reasoning_when_disabled(open_router_config):
+async def test_stream_response_suppresses_native_thinking_when_disabled(
+ open_router_config,
+):
provider = OpenRouterProvider(
open_router_config.model_copy(update={"enable_thinking": False})
)
- req = MockRequest()
-
- mock_chunk = MagicMock()
- mock_chunk.choices = [
- MagicMock(
- delta=MagicMock(
- content="<think>secret</think>Answer",
- reasoning_content="Thinking...",
- reasoning_details=[{"text": "Step 1"}],
- ),
- finish_reason="stop",
- )
- ]
- mock_chunk.usage = None
-
- async def mock_stream():
- yield mock_chunk
-
- with patch.object(
- provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
+ response = FakeResponse(
+ lines=[
+ "event: content_block_start",
+ 'data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":""}}',
+ "",
+ "event: content_block_delta",
+ 'data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"secret"}}',
+ "",
+ "event: content_block_stop",
+ 'data: {"type":"content_block_stop","index":0}',
+ "",
+ "event: content_block_start",
+ 'data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}',
+ "",
+ "event: content_block_delta",
+ 'data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"Answer"}}',
+ "",
+ "event: content_block_stop",
+ 'data: {"type":"content_block_stop","index":1}',
+ "",
+ ]
+ )
- events = [e async for e in provider.stream_response(req)]
+ with (
+ patch.object(provider._client, "build_request"),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
+ events = [e async for e in provider.stream_response(MockRequest())]
event_text = "".join(events)
assert "thinking_delta" not in event_text
- assert "Thinking..." not in event_text
- assert "Step 1" not in event_text
assert "secret" not in event_text
assert "Answer" in event_text
-
-async def test_stream_response_empty_choices_skipped(open_router_provider):
- """Chunks with empty choices are skipped."""
- req = MockRequest()
-
- async def mock_stream():
- yield MagicMock(choices=[], usage=None)
- yield MagicMock(
- choices=[
- MagicMock(
- delta=MagicMock(content="ok", reasoning_content=None),
- finish_reason="stop",
- )
- ],
- usage=MagicMock(completion_tokens=2),
- )
-
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
- events = [e async for e in open_router_provider.stream_response(req)]
- assert any("content_block_delta" in e and "ok" in e for e in events)
+ text_start = next(event for event in events if "content_block_start" in event)
+ payload = json.loads(text_start.split("data: ", 1)[1])
+ assert payload["index"] == 0
@pytest.mark.asyncio
-async def test_stream_response_delta_none_skipped(open_router_provider):
- """Chunks with delta=None are skipped."""
- req = MockRequest()
+async def test_stream_response_drops_redacted_thinking_when_enabled(
+ open_router_provider,
+):
+ response = FakeResponse(
+ lines=[
+ "event: content_block_start",
+ 'data: {"type":"content_block_start","index":0,"content_block":{"type":"redacted_thinking","data":"opaque"}}',
+ "",
+ "event: content_block_stop",
+ 'data: {"type":"content_block_stop","index":0}',
+ "",
+ "event: content_block_start",
+ 'data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}',
+ "",
+ "event: content_block_delta",
+ 'data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"Answer"}}',
+ "",
+ "event: content_block_stop",
+ 'data: {"type":"content_block_stop","index":1}',
+ "",
+ "event: message_stop",
+ 'data: {"type":"message_stop"}',
+ "",
+ ]
+ )
- async def mock_stream():
- yield MagicMock(
- choices=[MagicMock(delta=None, finish_reason=None)],
- usage=None,
- )
- yield MagicMock(
- choices=[
- MagicMock(
- delta=MagicMock(content="x", reasoning_content=None),
- finish_reason="stop",
- )
- ],
- usage=MagicMock(completion_tokens=1),
- )
+ with (
+ patch.object(open_router_provider._client, "build_request"),
+ patch.object(
+ open_router_provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
+ events = [e async for e in open_router_provider.stream_response(MockRequest())]
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
- events = [e async for e in open_router_provider.stream_response(req)]
- assert any("x" in e for e in events)
+ event_text = "".join(events)
+ assert "redacted_thinking" not in event_text
+ assert "Answer" in event_text
+
+ start_event = next(event for event in events if "content_block_start" in event)
+ payload = json.loads(start_event.split("data: ", 1)[1])
+ assert payload["index"] == 0
+ assert payload["content_block"]["type"] == "text"
@pytest.mark.asyncio
-async def test_stream_response_reasoning_details(open_router_provider):
- """Streaming with reasoning_details (stepfun format)."""
- req = MockRequest()
+async def test_stream_response_closes_overlapping_thinking_before_text(
+ open_router_provider,
+):
+ response = FakeResponse(
+ lines=[
+ "event: content_block_start",
+ 'data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}',
+ "",
+ "event: content_block_delta",
+ 'data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"reason"}}',
+ "",
+ "event: content_block_start",
+ 'data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}',
+ "",
+ "event: content_block_delta",
+ 'data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"Answer"}}',
+ "",
+ "event: content_block_stop",
+ 'data: {"type":"content_block_stop","index":1}',
+ "",
+ "event: content_block_stop",
+ 'data: {"type":"content_block_stop","index":0}',
+ "",
+ ]
+ )
- mock_chunk = MagicMock()
- mock_chunk.choices = [
- MagicMock(
- delta=MagicMock(
- content=None,
- reasoning_content=None,
- reasoning_details=[{"text": "Step 1"}],
- ),
- finish_reason=None,
- )
- ]
- mock_chunk.usage = None
-
- async def mock_stream():
- yield mock_chunk
- yield MagicMock(
- choices=[
- MagicMock(
- delta=MagicMock(
- content=None,
- reasoning_content=None,
- reasoning_details=None,
- ),
- finish_reason="stop",
- )
- ],
- usage=MagicMock(completion_tokens=5),
- )
+ with (
+ patch.object(open_router_provider._client, "build_request"),
+ patch.object(
+ open_router_provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
+ events = [e async for e in open_router_provider.stream_response(MockRequest())]
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
- events = [e async for e in open_router_provider.stream_response(req)]
- assert any("Step 1" in e for e in events)
+ event_text = "".join(events)
+ thinking_stop = event_text.index('"type": "content_block_stop", "index": 0')
+ text_start = event_text.index('"content_block": {"type": "text"')
+ assert thinking_stop < text_start
+ assert event_text.count('"index": 0') == 3
+ assert "Answer" in event_text
@pytest.mark.asyncio
async def test_stream_response_error_path(open_router_provider):
- """Stream raises exception -> error event emitted."""
req = MockRequest()
- async def mock_stream():
- raise RuntimeError("API failed")
- yield # unreachable, makes it a generator
-
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
+ with (
+ patch.object(open_router_provider._client, "build_request"),
+ patch.object(
+ open_router_provider._client,
+ "send",
+ new_callable=AsyncMock,
+ side_effect=RuntimeError("API failed"),
+ ),
+ ):
events = [e async for e in open_router_provider.stream_response(req)]
- # Error is emitted; message_stop/done indicates stream completed
- assert any("API failed" in e for e in events)
- assert any("message_stop" in e for e in events)
+ event_text = "".join(events)
+ assert "message_start" in event_text
+ assert "API failed" in event_text
+ assert "message_stop" in event_text
-async def test_stream_response_finish_reason_only(open_router_provider):
- """Chunk with finish_reason but no content still completes."""
- req = MockRequest()
- async def mock_stream():
- yield MagicMock(
- choices=[
- MagicMock(
- delta=MagicMock(content=None, reasoning_content=None),
- finish_reason="stop",
- )
- ],
- usage=MagicMock(completion_tokens=0),
- )
+def test_openai_chat_rollback_provider_builds_legacy_extra_body(open_router_config):
+ with patch("providers.openai_compat.AsyncOpenAI"):
+ provider = OpenRouterChatProvider(open_router_config)
- with patch.object(
- open_router_provider._client.chat.completions, "create", new_callable=AsyncMock
- ) as mock_create:
- mock_create.return_value = mock_stream()
- events = [e async for e in open_router_provider.stream_response(req)]
- assert any("message_delta" in e for e in events)
- assert any("message_stop" in e for e in events)
+ body = provider._build_request_body(MockRequest())
+
+ assert "extra_body" in body
+ assert body["extra_body"]["reasoning"] == {"enabled": True}
diff --git a/tests/providers/test_provider_rate_limit.py b/tests/providers/test_provider_rate_limit.py
index c8d2061f..7cd00d9d 100644
--- a/tests/providers/test_provider_rate_limit.py
+++ b/tests/providers/test_provider_rate_limit.py
@@ -315,3 +315,20 @@ class TestProviderRateLimiter:
)
assert limiter._concurrency_sem is not None
assert limiter._concurrency_sem._value == 3
+
+ @pytest.mark.asyncio
+ async def test_scoped_instances_are_isolated(self):
+ """Provider-scoped limiters do not share reactive block state."""
+ GlobalRateLimiter.reset_instance()
+ nim = GlobalRateLimiter.get_scoped_instance(
+ "nvidia_nim", rate_limit=10, rate_window=60
+ )
+ openrouter = GlobalRateLimiter.get_scoped_instance(
+ "open_router", rate_limit=20, rate_window=30
+ )
+
+ assert nim is not openrouter
+ nim.set_blocked(1.0)
+
+ assert nim.is_blocked() is True
+ assert openrouter.is_blocked() is False
diff --git a/tests/providers/test_registry.py b/tests/providers/test_registry.py
new file mode 100644
index 00000000..f4fec6a7
--- /dev/null
+++ b/tests/providers/test_registry.py
@@ -0,0 +1,105 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from config.nim import NimSettings
+from providers.deepseek import DeepSeekProvider
+from providers.llamacpp import LlamaCppProvider
+from providers.lmstudio import LMStudioProvider
+from providers.nvidia_nim import NvidiaNimProvider
+from providers.open_router import OpenRouterChatProvider, OpenRouterProvider
+from providers.registry import (
+ PROVIDER_DESCRIPTORS,
+ ProviderRegistry,
+ create_provider,
+)
+
+
+def _make_settings(**overrides):
+ mock = MagicMock()
+ mock.model = "nvidia_nim/meta/llama3"
+ mock.provider_type = "nvidia_nim"
+ mock.nvidia_nim_api_key = "test_key"
+ mock.open_router_api_key = "test_openrouter_key"
+ mock.deepseek_api_key = "test_deepseek_key"
+ mock.lm_studio_base_url = "http://localhost:1234/v1"
+ mock.llamacpp_base_url = "http://localhost:8080/v1"
+ mock.nvidia_nim_proxy = ""
+ mock.open_router_proxy = ""
+ mock.lmstudio_proxy = ""
+ mock.llamacpp_proxy = ""
+ mock.provider_rate_limit = 40
+ mock.provider_rate_window = 60
+ mock.provider_max_concurrency = 5
+ mock.http_read_timeout = 300.0
+ mock.http_write_timeout = 10.0
+ mock.http_connect_timeout = 2.0
+ mock.enable_thinking = True
+ mock.openrouter_transport = "anthropic"
+ mock.nim = NimSettings()
+ for key, value in overrides.items():
+ setattr(mock, key, value)
+ return mock
+
+
+def test_descriptors_cover_advertised_provider_ids():
+ assert set(PROVIDER_DESCRIPTORS) == {
+ "nvidia_nim",
+ "open_router",
+ "deepseek",
+ "lmstudio",
+ "llamacpp",
+ }
+ for descriptor in PROVIDER_DESCRIPTORS.values():
+ assert descriptor.provider_id
+ assert descriptor.transport_type in {"openai_chat", "anthropic_messages"}
+ assert descriptor.capabilities
+
+
+def test_create_provider_uses_native_openrouter_by_default():
+ with patch("httpx.AsyncClient"):
+ provider = create_provider("open_router", _make_settings())
+
+ assert isinstance(provider, OpenRouterProvider)
+
+
+def test_create_provider_can_use_openrouter_openai_rollback():
+ with patch("providers.openai_compat.AsyncOpenAI"):
+ provider = create_provider(
+ "open_router", _make_settings(openrouter_transport="openai")
+ )
+
+ assert isinstance(provider, OpenRouterChatProvider)
+
+
+def test_create_provider_instantiates_each_builtin():
+ settings = _make_settings()
+ cases = {
+ "nvidia_nim": NvidiaNimProvider,
+ "deepseek": DeepSeekProvider,
+ "lmstudio": LMStudioProvider,
+ "llamacpp": LlamaCppProvider,
+ }
+
+ with (
+ patch("providers.openai_compat.AsyncOpenAI"),
+ patch("httpx.AsyncClient"),
+ ):
+ for provider_id, provider_cls in cases.items():
+ assert isinstance(create_provider(provider_id, settings), provider_cls)
+
+
+def test_provider_registry_caches_by_provider_id():
+ registry = ProviderRegistry()
+ settings = _make_settings()
+
+ with patch("providers.openai_compat.AsyncOpenAI"):
+ first = registry.get("nvidia_nim", settings)
+ second = registry.get("nvidia_nim", settings)
+
+ assert first is second
+
+
+def test_unknown_provider_raises_value_error():
+ with pytest.raises(ValueError, match="Unknown provider_type"):
+ create_provider("unknown", _make_settings())