free-claude-code 6.2.64__py3-none-any.whl

free_claude_code/config/logging_config.py

@@ -0,0 +1,197 @@
+"""Loguru-based structured logging configuration.
+
+Structured logs are written as JSON lines to a configurable path (default
+``logs/server.log``). Stdlib logging is intercepted and funneled to loguru.
+Context vars (request_id, node_id, chat_id) from contextualize() are
+included at top level for easy grep/filter.
+"""
+
+import json
+import logging
+import re
+import threading
+from pathlib import Path
+
+from loguru import logger
+
+_configured = False
+_current_path: Path | None = None
+_current_level = "INFO"
+_current_verbose: bool | None = None
+_sink_id: int | None = None
+
+_THIRD_PARTY_LOGGERS = (
+    "openai",
+    "httpx",
+    "httpcore",
+    "httpcore.http11",
+    "httpcore.connection",
+    "telegram",
+    "telegram.ext",
+)
+
+# Loguru ``logger.bind()`` key used by structured TRACE payloads; ``core/trace.py``
+# uses the identical string constant ``TRACE_PAYLOAD_BINDING``.
+_TRACE_PAYLOAD_BINDING = "trace_payload"
+
+# Context keys we promote to top-level JSON for traceability / grep
+_CONTEXT_KEYS = (
+    "request_id",
+    "node_id",
+    "chat_id",
+    "claude_session_id",
+    "http_method",
+    "http_path",
+)
+
+_TELEGRAM_BOT_RE = re.compile(
+    r"(https?://api\.telegram\.org/)bot([0-9]+:[A-Za-z0-9_-]+)(/?)",
+    re.IGNORECASE,
+)
+# Authorization: Bearer <token> (HTTP client / proxy debug lines)
+_AUTH_BEARER_RE = re.compile(
+    r"(\bAuthorization\s*:\s*Bearer\s+)([^\s'\"]+)",
+    re.IGNORECASE,
+)
+
+
+def _redact_sensitive_substrings(message: str) -> str:
+    """Remove obvious API tokens and secrets before JSON log line emission."""
+    text = _TELEGRAM_BOT_RE.sub(r"\1bot<redacted>\3", message)
+    return _AUTH_BEARER_RE.sub(r"\1<redacted>", text)
+
+
+def _serialize_with_context(record) -> str:
+    """Format record as JSON with context vars at top level.
+    Returns a format template; we inject _json into record for output.
+    """
+    extra = record.get("extra", {})
+    out = {
+        "time": str(record["time"]),
+        "level": record["level"].name,
+        "message": _redact_sensitive_substrings(str(record["message"])),
+        "module": record["name"],
+        "function": record["function"],
+        "line": record["line"],
+    }
+    trace_payload = extra.get(_TRACE_PAYLOAD_BINDING)
+    for key in _CONTEXT_KEYS:
+        if key in extra and extra[key] is not None:
+            out[key] = extra[key]
+    if isinstance(trace_payload, dict):
+        for tk, tv in trace_payload.items():
+            if tk in out:
+                continue
+            out[tk] = tv
+        out["trace"] = True
+    record["_json"] = json.dumps(out, default=str)
+    return "{_json}\n"
+
+
+class InterceptHandler(logging.Handler):
+    """Redirect stdlib logging to loguru."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._local = threading.local()
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if getattr(self._local, "active", False):
+            # Avoid deadlock when nested stdlib records fire during a loguru emit.
+            return
+        self._local.active = True
+        try:
+            try:
+                level = logger.level(record.levelname).name
+            except ValueError:
+                level = record.levelno
+
+            frame, depth = logging.currentframe(), 2
+            while frame is not None and frame.f_code.co_filename == logging.__file__:
+                frame = frame.f_back
+                depth += 1
+
+            logger.opt(depth=depth, exception=record.exc_info).log(
+                level, record.getMessage()
+            )
+        finally:
+            self._local.active = False
+
+
+def _set_third_party_levels(verbose: bool) -> None:
+    level = logging.NOTSET if verbose else logging.WARNING
+    for name in _THIRD_PARTY_LOGGERS:
+        logging.getLogger(name).setLevel(level)
+
+
+def _add_file_sink(log_file: str | Path, level: str) -> int:
+    log_path = Path(log_file)
+    return logger.add(
+        log_path,
+        level=level,
+        format=_serialize_with_context,
+        encoding="utf-8",
+        mode="a",
+        rotation="50 MB",
+        retention=5,
+        enqueue=True,
+    )
+
+
+def configure_logging(
+    log_file: str | Path,
+    *,
+    force: bool = False,
+    verbose_third_party: bool = False,
+    level: str = "INFO",
+) -> None:
+    """Configure loguru with JSON output to log_file and intercept stdlib logging.
+
+    Idempotent: skips if already configured with the same path, level, and verbosity.
+    On path or level change, replaces only the file sink without truncating.
+    On verbosity change alone, updates only the third-party logger levels.
+    Use force=True to reconfigure from scratch.
+
+    When ``verbose_third_party`` is false, managed noisy third-party loggers
+    are capped at WARNING unless explicitly configured otherwise.
+    """
+    global _configured, _current_path, _current_level, _current_verbose, _sink_id
+
+    log_path = Path(log_file).expanduser().resolve()
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if (
+        _configured
+        and not force
+        and log_path == _current_path
+        and level == _current_level
+        and verbose_third_party == _current_verbose
+    ):
+        return
+
+    if not _configured or force:
+        _configured = True
+
+        logger.remove()
+
+        log_path.write_text("")
+
+        _sink_id = _add_file_sink(log_path, level)
+
+        intercept = InterceptHandler()
+        logging.root.handlers = [intercept]
+        logging.root.setLevel(logging.DEBUG)
+
+        _set_third_party_levels(verbose_third_party)
+    elif log_path != _current_path or level != _current_level:
+        if _sink_id is not None:
+            logger.remove(_sink_id)
+        _sink_id = _add_file_sink(log_path, level)
+        if verbose_third_party != _current_verbose:
+            _set_third_party_levels(verbose_third_party)
+    else:
+        _set_third_party_levels(verbose_third_party)
+
+    _current_path = log_path
+    _current_level = level
+    _current_verbose = verbose_third_party

free_claude_code/config/model_refs.py

@@ -0,0 +1,118 @@
+"""Provider-prefixed model reference helpers."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol
+
+from .constants import DEFAULT_MODEL
+
+RETIRED_PROVIDER_IDS = frozenset({"github_models"})
+
+
+def is_retired_model_ref(model_ref: str) -> bool:
+    """Recognize complete references owned by a retired provider."""
+
+    provider, separator, model = model_ref.strip().partition("/")
+    return provider in RETIRED_PROVIDER_IDS and bool(separator and model.strip())
+
+
+def parse_model_fallbacks(value: object) -> object:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        if not value.strip():
+            return None
+        return tuple(part.strip() for part in value.split(","))
+    if isinstance(value, list | tuple) and not value:
+        return None
+    return value
+
+
+def normalize_retired_model_settings(
+    values: Mapping[str, str], *, preserve_empty_overrides: bool
+) -> dict[str, str]:
+    """Repair one source without changing its precedence or unrelated validation."""
+
+    normalized = dict(values)
+    for key in ("MODEL", "MODEL_FABLE", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"):
+        if is_retired_model_ref(normalized.get(key, "")):
+            if preserve_empty_overrides:
+                normalized[key] = DEFAULT_MODEL if key == "MODEL" else ""
+            else:
+                normalized.pop(key)
+    fallbacks = parse_model_fallbacks(normalized.get("MODEL_FALLBACKS"))
+    if isinstance(fallbacks, tuple) and all(fallbacks):
+        retained = tuple(ref for ref in fallbacks if not is_retired_model_ref(ref))
+        if retained != fallbacks:
+            if retained or preserve_empty_overrides:
+                normalized["MODEL_FALLBACKS"] = ",".join(retained)
+            else:
+                normalized.pop("MODEL_FALLBACKS")
+    return normalized
+
+
+@dataclass(frozen=True, slots=True)
+class ConfiguredChatModelRef:
+    """A unique configured chat model reference."""
+
+    model_ref: str
+    provider_id: str
+    model_id: str
+
+
+class ChatModelConfig(Protocol):
+    model: str
+    model_fable: str | None
+    model_opus: str | None
+    model_sonnet: str | None
+    model_haiku: str | None
+    model_fallbacks: tuple[str, ...] | None
+
+
+def split_provider_model_ref(model_ref: str) -> tuple[str, str]:
+    """Split one complete ``provider/model`` reference."""
+
+    provider_id, separator, model_id = model_ref.partition("/")
+    if not separator or not provider_id or not model_id:
+        raise ValueError("Model reference must contain provider and model names.")
+    return provider_id, model_id
+
+
+def parse_provider_type(model_ref: str) -> str:
+    """Extract provider type from any 'provider/model' string."""
+
+    return split_provider_model_ref(model_ref)[0]
+
+
+def parse_model_name(model_ref: str) -> str:
+    """Extract model name from any 'provider/model' string."""
+
+    return split_provider_model_ref(model_ref)[1]
+
+
+def configured_chat_model_refs(
+    settings: ChatModelConfig,
+) -> tuple[ConfiguredChatModelRef, ...]:
+    """Return unique configured chat provider/model refs."""
+
+    model_refs = dict.fromkeys(
+        model_ref
+        for model_ref in (
+            settings.model,
+            settings.model_fable,
+            settings.model_opus,
+            settings.model_sonnet,
+            settings.model_haiku,
+            *(settings.model_fallbacks or ()),
+        )
+        if model_ref is not None
+    )
+
+    return tuple(
+        ConfiguredChatModelRef(
+            model_ref=model_ref,
+            provider_id=parse_provider_type(model_ref),
+            model_id=parse_model_name(model_ref),
+        )
+        for model_ref in model_refs
+    )

free_claude_code/config/nim.py

@@ -0,0 +1,121 @@
+"""NVIDIA NIM settings (fixed values, no env config)."""
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+
+
+class NimSettings(BaseModel):
+    """Fixed NVIDIA NIM settings (not configurable via env)."""
+
+    temperature: float = Field(
+        1.0, ge=0.0, le=2.0, description="Sampling temperature, must be >=0 and <=2."
+    )
+    top_p: float = Field(
+        0.95,
+        ge=0.95,
+        le=0.95,
+        description="FCC's fixed NVIDIA NIM nucleus sampling probability.",
+    )
+    top_k: int = -1
+    max_tokens: int = Field(
+        ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+        ge=1,
+        description="Maximum number of tokens in output.",
+    )
+    presence_penalty: float = Field(0.0, ge=-2.0, le=2.0)
+    frequency_penalty: float = Field(0.0, ge=-2.0, le=2.0)
+    min_p: float = Field(
+        0.0, ge=0.0, le=1.0, description="Minimum probability threshold [0,1]."
+    )
+    repetition_penalty: float = Field(
+        1.0, ge=0.0, description="Penalty for repeated tokens. Must be >=0."
+    )
+    seed: int | None = None
+    stop: str | None = None
+    parallel_tool_calls: bool = True
+    ignore_eos: bool = False
+    min_tokens: int = Field(0, ge=0, description="Minimum tokens in the response.")
+    chat_template: str | None = None
+    request_id: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("top_k", mode="before")
+    @classmethod
+    def validate_top_k(cls, v, info: ValidationInfo):
+        if v is None or v == "":
+            return -1
+        int_v = int(v)
+        if int_v < -1:
+            raise ValueError(f"{info.field_name} must be -1 or >= 0")
+        return int_v
+
+    @field_validator(
+        "temperature",
+        "top_p",
+        "min_p",
+        "presence_penalty",
+        "frequency_penalty",
+        "repetition_penalty",
+        mode="before",
+    )
+    @classmethod
+    def validate_float_fields(cls, v, info: ValidationInfo):
+        field_defaults = {
+            "temperature": 1.0,
+            "top_p": 0.95,
+            "min_p": 0.0,
+            "presence_penalty": 0.0,
+            "frequency_penalty": 0.0,
+            "repetition_penalty": 1.0,
+        }
+        if v is None or v == "":
+            key = info.field_name or "temperature"
+            return field_defaults.get(key, 1.0)
+        try:
+            val = float(v)
+        except (TypeError, ValueError) as err:
+            raise ValueError(
+                f"{info.field_name} must be a float. Got {type(v).__name__}."
+            ) from err
+        return val
+
+    @field_validator("max_tokens", "min_tokens", mode="before")
+    @classmethod
+    def validate_int_fields(cls, v, info: ValidationInfo):
+        field_defaults = {
+            "max_tokens": ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+            "min_tokens": 0,
+        }
+        if v is None or v == "":
+            key = info.field_name or "max_tokens"
+            return field_defaults.get(key, ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS)
+        try:
+            val = int(v)
+        except (TypeError, ValueError) as err:
+            raise ValueError(
+                f"{info.field_name} must be an int. Got {type(v).__name__}."
+            ) from err
+        return val
+
+    @field_validator("seed", mode="before")
+    @classmethod
+    def parse_optional_int(cls, v, info: ValidationInfo):
+        if v == "" or v is None:
+            return None
+        try:
+            return int(v)
+        except (TypeError, ValueError) as err:
+            raise ValueError(
+                f"{info.field_name} must be an int or empty/None."
+            ) from err
+
+    @field_validator("stop", "chat_template", "request_id", mode="before")
+    @classmethod
+    def parse_optional_str(cls, v, info: ValidationInfo):
+        if v == "":
+            return None
+        if v is not None and not isinstance(v, str):
+            return str(v)
+        return v

free_claude_code/config/paths.py

@@ -0,0 +1,104 @@
+"""Shared filesystem paths for Free Claude Code configuration."""
+
+from pathlib import Path
+
+FCC_CONFIG_DIRNAME = ".fcc"
+FCC_ENV_FILENAME = ".env"
+LEGACY_REPO_DIRNAME = "free-claude-code"
+LEGACY_XDG_CONFIG_DIRNAME = ".config"
+MESSAGING_STATE_DIRNAME = "agent_workspace"
+FCC_LOGS_DIRNAME = "logs"
+SERVER_LOG_FILENAME = "server.log"
+CODEX_MODEL_CATALOG_FILENAME = "codex-model-catalog.json"
+AUTH_DIRNAME = "auth"
+OPENAI_AUTH_FILENAME = "openai.json"
+OPENAI_AUTH_LOCK_FILENAME = "openai.lock"
+CONFIG_LOCK_FILENAME = "config.lock"
+FCC_TEMP_DIRNAME = "tmp"
+LAUNCHER_TEMP_DIRNAME = "launchers"
+CODE_STATE_DIRNAME = "code"
+CODE_DATABASE_FILENAME = "code.db"
+CODE_LOCK_FILENAME = "code.lock"
+
+
+def config_dir_path() -> Path:
+    """Return the default user config directory."""
+
+    return Path.home() / FCC_CONFIG_DIRNAME
+
+
+def managed_env_path() -> Path:
+    """Return the default user-managed env file path."""
+
+    return config_dir_path() / FCC_ENV_FILENAME
+
+
+def config_lock_path() -> Path:
+    """Return the cross-process managed-config migration lock path."""
+
+    return config_dir_path() / CONFIG_LOCK_FILENAME
+
+
+def launcher_temp_dir_path() -> Path:
+    """Return the base directory for private native launcher configuration."""
+
+    return config_dir_path() / FCC_TEMP_DIRNAME / LAUNCHER_TEMP_DIRNAME
+
+
+def code_database_path() -> Path:
+    """Return the managed Code sessions database path."""
+    return config_dir_path() / CODE_STATE_DIRNAME / CODE_DATABASE_FILENAME
+
+
+def code_lock_path() -> Path:
+    """Return the exclusive Code sessions process-lock path."""
+    return config_dir_path() / CODE_STATE_DIRNAME / CODE_LOCK_FILENAME
+
+
+def legacy_env_paths() -> tuple[Path, ...]:
+    """Return legacy user env paths that can be migrated to ~/.fcc/.env."""
+
+    home = Path.home()
+    return (
+        home / LEGACY_REPO_DIRNAME / FCC_ENV_FILENAME,
+        home / LEGACY_XDG_CONFIG_DIRNAME / LEGACY_REPO_DIRNAME / FCC_ENV_FILENAME,
+    )
+
+
+def messaging_state_dir_path() -> Path:
+    """Return the managed messaging state directory."""
+
+    return config_dir_path() / MESSAGING_STATE_DIRNAME
+
+
+def server_log_path() -> Path:
+    """Return the canonical server log path."""
+
+    return config_dir_path() / FCC_LOGS_DIRNAME / SERVER_LOG_FILENAME
+
+
+def codex_model_catalog_path() -> Path:
+    """Return the generated Codex model catalog path."""
+
+    return config_dir_path() / CODEX_MODEL_CATALOG_FILENAME
+
+
+def claude_desktop_disconnect_path() -> Path:
+    return config_dir_path() / "claude-desktop-disconnect.json"
+
+
+def openai_auth_path() -> Path:
+    """Return FCC's private ChatGPT credential file path."""
+
+    return config_dir_path() / AUTH_DIRNAME / OPENAI_AUTH_FILENAME
+
+
+def openai_auth_lock_path() -> Path:
+    """Return the cross-process lock path for ChatGPT credentials."""
+
+    return config_dir_path() / AUTH_DIRNAME / OPENAI_AUTH_LOCK_FILENAME
+
+
+def github_copilot_auth_path() -> Path:
+    """Return FCC connection state; native Copilot retains credentials."""
+    return config_dir_path() / AUTH_DIRNAME / "github_copilot.json"