claude-smart 0.2.47 → 0.2.49

package/plugin/vendor/reflexio/reflexio/server/llm/providers/claude_code_provider.py

@@ -62,14 +62,22 @@ _ENV_TIMEOUT = "CLAUDE_SMART_CLI_TIMEOUT"
 _ENV_MODEL = "CLAUDE_SMART_CLI_MODEL"
 _HOST_CODEX = "codex"
 _HOST_CLAUDE_CODE = "claude-code"
+
+
+def _is_windows() -> bool:
+    return os.name == "nt"
+
+
 _CODEX_COMPAT_SCRIPT_NAMES = (
     ("codex-claude-compat.cmd", "codex-claude-compat")
-    if os.name == "nt"
+    if _is_windows()
     else ("codex-claude-compat", "codex-claude-compat.cmd")
 )
 _CODEX_COMPAT_SCRIPT_NAME_SET = set(_CODEX_COMPAT_SCRIPT_NAMES)
 _DEFAULT_TIMEOUT_SECONDS = 120
 _DEFAULT_CLI_MODEL = "claude-sonnet-5"
+_WINDOWS_ARGV_SYSTEM_PROMPT_LIMIT = 3_000
+_WINDOWS_CLI_SUFFIXES = (".cmd", ".exe", ".bat")
 
 _TRUTHY_ENV_VALUES = {"1", "true", "yes"}
 _UNSUPPORTED_PARAMS_WARNED: set[str] = set()
@@ -116,6 +124,40 @@ def _candidate_codex_compat_path() -> Path | None:
     return None
 
 
+def _windows_cli_suffixes() -> tuple[str, ...]:
+    suffixes: list[str] = []
+    for suffix in os.environ.get("PATHEXT", "").split(";"):
+        suffix = suffix.strip().lower()
+        if not suffix:
+            continue
+        suffix = suffix if suffix.startswith(".") else f".{suffix}"
+        # PowerShell scripts require a PowerShell host; do not return them as
+        # directly executable CLI shims for subprocess.run([...]).
+        if suffix == ".ps1":
+            continue
+        suffixes.append(suffix)
+    for suffix in _WINDOWS_CLI_SUFFIXES:
+        if suffix not in suffixes:
+            suffixes.append(suffix)
+    return tuple(suffixes)
+
+
+def _resolve_cli_override_path(cli_path: str) -> str:
+    if not _is_windows():
+        return cli_path
+    path = Path(cli_path)
+    if path.suffix:
+        return cli_path
+
+    # Windows package managers expose extensioned shims while users often
+    # configure the extensionless binary name.
+    for suffix in _windows_cli_suffixes():
+        candidate = path.with_suffix(suffix)
+        if candidate.exists():
+            return str(candidate)
+    return cli_path
+
+
 def _resolve_cli_path() -> str | None:
     """Return the path to the active host CLI, or None if unavailable.
 
@@ -129,7 +171,7 @@ def _resolve_cli_path() -> str | None:
     """
     override = os.environ.get(_ENV_CLI_PATH)
     if override:
-        candidate = Path(override)
+        candidate = Path(_resolve_cli_override_path(override))
         if candidate.is_file() and os.access(candidate, os.X_OK):
             return str(candidate)
         _LOGGER.warning(
@@ -432,6 +474,9 @@ def _run_claude_stream(
 ) -> ParseResult:
     """Invoke ``claude -p --output-format stream-json`` and return a ParseResult."""
     model = os.environ.get(_ENV_MODEL) or _DEFAULT_CLI_MODEL
+    inline_system_prompt = (
+        _is_windows() and len(system_prompt) > _WINDOWS_ARGV_SYSTEM_PROMPT_LIMIT
+    )
     cmd = [
         cli_path,
         "-p",
@@ -442,8 +487,11 @@ def _run_claude_stream(
         "--model",
         model,
     ]
-    if system_prompt:
+    if system_prompt and not inline_system_prompt:
         cmd.extend(["--append-system-prompt", system_prompt])
+    stdin_text = dialogue
+    if inline_system_prompt:
+        stdin_text = f"{system_prompt}\n\n{dialogue}" if dialogue else system_prompt
 
     # Tag the child process so any hooks it fires (e.g. claude-smart's
     # Stop hook) can detect that this is a reflexio-internal invocation
@@ -460,9 +508,11 @@ def _run_claude_stream(
     try:
         proc = subprocess.run(  # noqa: S603 — cmd is constructed from validated parts.
             cmd,
-            input=dialogue,
+            input=stdin_text,
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace" if _is_windows() else "strict",
             timeout=timeout_seconds,
             check=False,
             env=env,
@@ -511,6 +561,8 @@ def _run_codex_stream(
             input=_codex_prompt(prompt=dialogue, system_prompt=system_prompt),
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace" if _is_windows() else "strict",
             timeout=timeout_seconds,
             check=False,
             env=env,

package/plugin/vendor/reflexio/reflexio/server/llm/providers/local_embedding_provider.py

@@ -18,9 +18,23 @@ from __future__ import annotations
 import importlib.util
 import logging
 import os
+import shutil
 import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
 from typing import Any
 
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - Windows only
+    fcntl = None  # type: ignore[assignment]
+
+try:
+    import msvcrt
+except ImportError:  # pragma: no cover - POSIX only
+    msvcrt = None  # type: ignore[assignment]
+
 _LOGGER = logging.getLogger(__name__)
 
 _ENV_ENABLE = "CLAUDE_SMART_USE_LOCAL_EMBEDDING"
@@ -36,6 +50,17 @@ _TARGET_DIM = 512
 # ValueError that ONNXMiniLM_L6_V2 throws on over-length input.
 _MAX_CHARS = 800
 
+# Chroma keeps this file list private inside ONNXMiniLM_L6_V2's download helper.
+# Keep this in sync with chromadb's all-MiniLM-L6-v2 extracted archive layout.
+_MINILM_EXPECTED_FILES = (
+    "config.json",
+    "model.onnx",
+    "special_tokens_map.json",
+    "tokenizer_config.json",
+    "tokenizer.json",
+    "vocab.txt",
+)
+
 
 class LocalEmbedderError(RuntimeError):
     """Raised when the local embedder is called without chromadb installed."""
@@ -98,9 +123,54 @@ class LocalEmbedder:
         """
         ef = self._load()
         safe_inputs = [(text or "")[:_MAX_CHARS] for text in texts]
-        raw = ef(safe_inputs)
+        try:
+            raw = ef(safe_inputs)
+        except Exception as exc:  # noqa: BLE001 - Chroma raises varied cache errors.
+            raw = self._retry_embed_after_cache_clear(ef, exc, safe_inputs)
         return [_pad(vec) for vec in raw]
 
+    def _retry_embed_after_cache_clear(
+        self, failed_ef: Any, exc: Exception, safe_inputs: list[str]
+    ) -> Any:
+        with self._ef_lock:
+            if self._ef is not None and self._ef is not failed_ef:
+                return self._ef(safe_inputs)
+
+            embedding_cls = type(failed_ef)
+            recovery = _recoverable_minilm_cache(embedding_cls, exc)
+            if recovery is None:
+                raise exc
+            cache_path, cache_was_complete = recovery
+
+            with _exclusive_file_lock(_minilm_cache_lock_path(cache_path)):
+                if _should_clear_minilm_cache(
+                    embedding_cls, cache_path, exc, cache_was_complete
+                ):
+                    shutil.rmtree(cache_path, ignore_errors=True)
+                    recovery_action = "clearing"
+                    _LOGGER.warning(
+                        "Failed to use local MiniLM embedder; cleared cache %s "
+                        "and retrying once",
+                        cache_path,
+                        exc_info=True,
+                    )
+                else:
+                    recovery_action = "waiting for another process to refresh"
+                    _LOGGER.info(
+                        "MiniLM cache %s was refreshed by another process; retrying",
+                        cache_path,
+                    )
+                try:
+                    fresh_ef = embedding_cls()
+                    self._ef = fresh_ef
+                    return fresh_ef(safe_inputs)
+                except Exception as retry_exc:
+                    raise LocalEmbedderError(
+                        "Local MiniLM cache recovery failed after "
+                        f"{recovery_action} {cache_path}. Delete this cache "
+                        "directory, restart Reflexio, and retry local embedding."
+                    ) from retry_exc
+
 
 def _pad(vec: Any) -> list[float]:
     """Zero-pad a 384-dim vector to ``_TARGET_DIM`` as a plain list[float]."""
@@ -113,6 +183,118 @@ def _pad(vec: Any) -> list[float]:
     return floats + [0.0] * (_TARGET_DIM - len(floats))
 
 
+def _recoverable_minilm_cache(
+    embedding_cls: Any, exc: Exception
+) -> tuple[Path, bool] | None:
+    cache_path = _minilm_cache_path(embedding_cls)
+    if cache_path is None:
+        return None
+    cache_was_complete = _minilm_cache_complete(embedding_cls, cache_path)
+    if cache_was_complete and not _complete_minilm_cache_error_identifies_cache(
+        embedding_cls, cache_path, exc
+    ):
+        return None
+
+    return cache_path, cache_was_complete
+
+
+def _minilm_cache_path(embedding_cls: Any) -> Path | None:
+    download_path = getattr(embedding_cls, "DOWNLOAD_PATH", None)
+    if not download_path:
+        return None
+
+    model_name = getattr(embedding_cls, "MODEL_NAME", None)
+    cache_path = Path(str(download_path)).expanduser()
+    if not model_name or cache_path.name != model_name:
+        return None
+
+    return cache_path
+
+
+def _minilm_cache_lock_path(cache_path: Path) -> Path:
+    return cache_path.parent / f".{cache_path.name}.lock"
+
+
+@contextmanager
+def _exclusive_file_lock(lock_path: Path) -> Iterator[None]:
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+b") as lock_file:
+        lock_file.seek(0)
+        if lock_file.read(1) == b"":
+            lock_file.write(b"\0")
+            lock_file.flush()
+        lock_file.seek(0)
+
+        if fcntl is not None:
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+        elif msvcrt is not None:
+            msvcrt.locking(  # type: ignore[reportAttributeAccessIssue]
+                lock_file.fileno(),
+                msvcrt.LK_LOCK,  # type: ignore[reportAttributeAccessIssue]
+                1,
+            )
+            try:
+                yield
+            finally:
+                lock_file.seek(0)
+                msvcrt.locking(  # type: ignore[reportAttributeAccessIssue]
+                    lock_file.fileno(),
+                    msvcrt.LK_UNLCK,  # type: ignore[reportAttributeAccessIssue]
+                    1,
+                )
+        else:
+            yield
+
+
+def _should_clear_minilm_cache(
+    embedding_cls: Any, cache_path: Path, exc: Exception, cache_was_complete: bool
+) -> bool:
+    cache_is_complete = _minilm_cache_complete(embedding_cls, cache_path)
+    if not cache_is_complete:
+        return True
+
+    if not cache_was_complete:
+        return False
+
+    return _complete_minilm_cache_error_identifies_cache(embedding_cls, cache_path, exc)
+
+
+def _complete_minilm_cache_error_identifies_cache(
+    embedding_cls: Any, cache_path: Path, exc: Exception
+) -> bool:
+    chain = _exception_chain(exc)
+    archive_name = str(getattr(embedding_cls, "ARCHIVE_FILENAME", ""))
+    messages = "\n".join(str(chain_exc) for chain_exc in chain)
+    return (
+        str(cache_path) in messages
+        or bool(archive_name and archive_name in messages)
+        or "does not match expected SHA256" in messages
+    )
+
+
+def _minilm_cache_complete(embedding_cls: Any, cache_path: Path) -> bool:
+    extracted_folder = str(getattr(embedding_cls, "EXTRACTED_FOLDER_NAME", "onnx"))
+    return all(
+        (cache_path / extracted_folder / file_name).exists()
+        for file_name in _MINILM_EXPECTED_FILES
+    )
+
+
+def _exception_chain(exc: Exception) -> list[BaseException]:
+    chain: list[BaseException] = []
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        chain.append(current)
+        current = current.__cause__ or current.__context__
+    return chain
+
+
 _REGISTERED = False
 
 

package/plugin/vendor/reflexio/reflexio/server/middleware.py

@@ -0,0 +1,244 @@
+"""HTTP middleware for the OSS FastAPI app (Tier3 A2 extraction from api.py).
+
+Holds the five middleware classes ``create_app`` wires in (in that order) plus
+the request-limit / CORS-origin helpers and their tunable constants. No
+middleware reads mutable module-global app state — every read is of an
+import-time constant or an env var — so this extraction is behavior-preserving.
+"""
+
+import asyncio
+import logging
+import os
+
+from anyio.to_thread import current_default_thread_limiter
+from fastapi import Request, status
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import Response
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from reflexio.server.correlation import correlation_id_var, generate_correlation_id
+
+logger = logging.getLogger(__name__)
+
+# Bot protection configuration
+REQUEST_TIMEOUT_SECONDS = 60
+SYNC_REQUEST_TIMEOUT_SECONDS = (
+    600  # Longer timeout for synchronous processing (wait_for_response=true)
+)
+SUSPICIOUS_USER_AGENTS = ["bot", "crawler", "spider", "scraper", "curl", "wget"]
+ALLOWED_EMPTY_UA_PATHS = ["/health", "/"]  # Paths that allow empty user agents
+DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024
+
+
+def _resolve_cors_origins() -> list[str]:
+    """Resolve browser origins allowed to make credentialed CORS requests."""
+    configured_origins = os.getenv("REFLEXIO_ALLOWED_ORIGINS", "").strip()
+    if configured_origins:
+        origins = [
+            origin.strip().rstrip("/")
+            for origin in configured_origins.split(",")
+            if origin.strip()
+        ]
+        return origins or ["http://localhost:8080"]
+
+    frontend_url = os.getenv("FRONTEND_URL", "").strip()
+    if frontend_url:
+        return [frontend_url.rstrip("/")]
+
+    return ["http://localhost:8080"]
+
+
+def _max_body_bytes_from_env() -> int:
+    raw_value = os.getenv("REFLEXIO_MAX_BODY_BYTES", str(DEFAULT_MAX_BODY_BYTES))
+    try:
+        max_bytes = int(raw_value)
+    except ValueError:
+        logger.warning(
+            "Ignoring invalid REFLEXIO_MAX_BODY_BYTES=%r; using %s",
+            raw_value,
+            DEFAULT_MAX_BODY_BYTES,
+        )
+        return DEFAULT_MAX_BODY_BYTES
+    if max_bytes <= 0:
+        logger.warning(
+            "Ignoring non-positive REFLEXIO_MAX_BODY_BYTES=%r; using %s",
+            raw_value,
+            DEFAULT_MAX_BODY_BYTES,
+        )
+        return DEFAULT_MAX_BODY_BYTES
+    return max_bytes
+
+
+class BotProtectionMiddleware(BaseHTTPMiddleware):
+    """Middleware to detect and block suspicious bot-like requests."""
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        """Process request and block suspicious patterns.
+
+        Args:
+            request (Request): The incoming request
+            call_next (RequestResponseEndpoint): Next middleware/handler in chain
+
+        Returns:
+            Response: The response from the next handler or a 403 JSON response
+        """
+        from starlette.responses import JSONResponse
+
+        user_agent = request.headers.get("user-agent", "").lower()
+        path = request.url.path
+
+        # Allow health check and root without user agent
+        if path not in ALLOWED_EMPTY_UA_PATHS:
+            # Block requests with no user agent
+            if not user_agent:
+                return JSONResponse(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    content={"detail": "Forbidden: Missing user agent"},
+                )
+
+            # Block requests with suspicious user agents
+            for suspicious in SUSPICIOUS_USER_AGENTS:
+                if suspicious in user_agent:
+                    return JSONResponse(
+                        status_code=status.HTTP_403_FORBIDDEN,
+                        content={"detail": "Forbidden: Suspicious user agent"},
+                    )
+
+        return await call_next(request)
+
+
+class TimeoutMiddleware(BaseHTTPMiddleware):
+    """Middleware to enforce request timeout."""
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        """Process request with timeout enforcement.
+
+        Args:
+            request (Request): The incoming request
+            call_next (RequestResponseEndpoint): Next middleware/handler in chain
+
+        Returns:
+            Response: The response from the next handler or a 504 JSON response
+        """
+        from starlette.responses import JSONResponse
+
+        # Use longer timeout for synchronous processing requests
+        timeout = REQUEST_TIMEOUT_SECONDS
+        if request.query_params.get("wait_for_response", "").lower() == "true":
+            timeout = SYNC_REQUEST_TIMEOUT_SECONDS
+
+        try:
+            return await asyncio.wait_for(call_next(request), timeout=timeout)
+        except TimeoutError:
+            return JSONResponse(
+                status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+                content={"detail": "Request timeout"},
+            )
+
+
+class _RequestBodyTooLargeError(Exception):
+    """Raised when the streamed request body exceeds the configured limit."""
+
+
+class BodySizeLimitMiddleware:
+    """Reject requests whose declared or streamed body size exceeds the limit."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        from starlette.responses import JSONResponse
+
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        max_body_bytes = _max_body_bytes_from_env()
+        content_length = None
+        for name, value in scope.get("headers", []):
+            if name.lower() == b"content-length":
+                content_length = value.decode("latin-1")
+                break
+
+        if content_length is not None:
+            try:
+                body_bytes = int(content_length)
+            except ValueError:
+                body_bytes = 0
+            if body_bytes > max_body_bytes:
+                await JSONResponse(
+                    status_code=status.HTTP_413_CONTENT_TOO_LARGE,
+                    content={"detail": "Request body too large"},
+                )(scope, receive, send)
+                return
+
+        consumed_bytes = 0
+
+        async def limited_receive() -> Message:
+            nonlocal consumed_bytes
+            message = await receive()
+            if message["type"] == "http.request":
+                consumed_bytes += len(message.get("body", b""))
+                if consumed_bytes > max_body_bytes:
+                    raise _RequestBodyTooLargeError
+            return message
+
+        try:
+            await self.app(scope, limited_receive, send)
+        except _RequestBodyTooLargeError:
+            await JSONResponse(
+                status_code=status.HTTP_413_CONTENT_TOO_LARGE,
+                content={"detail": "Request body too large"},
+            )(scope, receive, send)
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Attach conservative browser security headers to every response."""
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        if (
+            request.url.scheme == "https"
+            or request.headers.get("x-forwarded-proto", "").lower() == "https"
+        ):
+            response.headers["Strict-Transport-Security"] = (
+                "max-age=31536000; includeSubDomains"
+            )
+        return response
+
+
+class CorrelationIdMiddleware(BaseHTTPMiddleware):
+    """Middleware that assigns a unique correlation ID to each request.
+
+    The ID is stored in a ContextVar so it propagates to log records
+    (via CorrelationIdFilter) and to ThreadPoolExecutor workers when
+    ``contextvars.copy_context()`` is used.
+    """
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        cid = generate_correlation_id()
+        correlation_id_var.set(cid)
+        try:
+            stats = current_default_thread_limiter().statistics()
+            request.state.tp_borrowed = stats.borrowed_tokens
+            request.state.tp_total = stats.total_tokens
+            request.state.tp_waiting = stats.tasks_waiting
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("Failed to snapshot threadpool limiter stats: %s", exc)
+            request.state.tp_borrowed = None
+            request.state.tp_total = None
+            request.state.tp_waiting = None
+        response = await call_next(request)
+        response.headers["X-Correlation-ID"] = cid
+        return response

package/plugin/vendor/reflexio/reflexio/server/operation_limiter.py

@@ -62,6 +62,11 @@ def _limit_for(operation: OperationName) -> int:
     return _DEFAULT_LIMITS[operation]
 
 
+def operation_limit_value(operation: OperationName) -> int:
+    """Return the configured concurrency limit for an operation."""
+    return _limit_for(operation)
+
+
 def _timeout_for(operation: OperationName) -> float:
     raw = os.getenv(_env_key(operation, "TIMEOUT_SECONDS"), "").strip()
     if raw:
@@ -403,6 +408,7 @@ def operation_limit(
     *,
     timeout_seconds: float | None = None,
     wait_forever: bool = False,
+    log_timeout: bool = True,
 ) -> Any:
     """Acquire the per-org limiter for an operation, recording wait metrics."""
     state = _state_for(org_id, operation)
@@ -448,7 +454,7 @@ def operation_limit(
                 limit=state.limit,
                 active=active,
             )
-            if operation == "publish":
+            if operation == "publish" and log_timeout:
                 logger.warning(
                     "publish_limiter_timeout org_id=%s limit=%s active=%s "
                     "waiting=%s wait_ms=%s timeout_seconds=%s hardware=%s",
@@ -504,12 +510,14 @@ def run_with_operation_limit[T](
     fn: Callable[[], T],
     timeout_seconds: float | None = None,
     wait_forever: bool = False,
+    log_timeout: bool = True,
 ) -> T:
     with operation_limit(
         org_id,
         operation,
         timeout_seconds=timeout_seconds,
         wait_forever=wait_forever,
+        log_timeout=log_timeout,
     ):
         return fn()
 

package/plugin/vendor/reflexio/reflexio/server/rate_limit.py

@@ -0,0 +1,79 @@
+"""Shared slowapi rate limiter for the OSS FastAPI app (Tier3 A2).
+
+The ``limiter`` singleton and ``configure_rate_limiter`` live here so the domain
+route modules can decorate handlers with ``@limiter.limit(...)`` without importing
+from ``reflexio.server.api`` (which would be circular — ``api`` aggregates the
+route modules). ``reflexio.server.api`` re-exports ``limiter`` and
+``configure_rate_limiter`` so the existing enterprise imports keep resolving.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Request
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from reflexio.server.tracing import profile_step
+
+
+def get_rate_limit_key(request: Request) -> str:
+    """Get rate limit key based on IP address.
+
+    Args:
+        request (Request): The incoming request
+
+    Returns:
+        str: Rate limit key (IP address)
+    """
+    return get_remote_address(request)
+
+
+def _storage_backend_name(limiter_obj: Limiter) -> str:
+    storage = getattr(limiter_obj, "_storage", None)
+    if storage is None:
+        return "unknown"
+    return storage.__class__.__name__
+
+
+def _trace_external_rate_limit_backend(limiter_obj: Limiter) -> None:
+    """Trace rate-limit storage hits when the backend is an external service."""
+    backend = _storage_backend_name(limiter_obj)
+    if backend == "MemoryStorage":
+        return
+
+    strategy = getattr(limiter_obj, "limiter", None)
+    if strategy is None or getattr(strategy, "_reflexio_traced", False):
+        return
+
+    original_hit = strategy.hit
+
+    def traced_hit(item: Any, *identifiers: str, cost: int = 1) -> bool:
+        with profile_step(
+            "rate_limit.backend_hit",
+            storage_backend=backend,
+            strategy=strategy.__class__.__name__,
+            cost=cost,
+        ):
+            return original_hit(item, *identifiers, cost=cost)
+
+    strategy.hit = traced_hit
+    strategy._reflexio_traced = True
+
+
+# Initialize rate limiter
+limiter = Limiter(key_func=get_rate_limit_key)
+_trace_external_rate_limit_backend(limiter)
+
+
+def configure_rate_limiter(key_func: Callable[..., str]) -> None:
+    """
+    Replace the rate limiter's key function.
+
+    This is the supported way to override the default IP-based key function
+    (e.g. with an org-scoped or token-scoped variant in the enterprise layer).
+
+    Args:
+        key_func: A callable that accepts a Request and returns a string key.
+    """
+    limiter._key_func = key_func  # type: ignore[reportAttributeAccessIssue]