hack/tools/scripts/llm-key-hunter/results/_cache/content/aayushsoam_clawbot-agent.json

{"repo": "aayushsoam/clawbot-agent", "files": {"clawbot_cli/auth.py": {"1e9c7af902bdb628e84f05ba434f634811655eca": {"t": 1785595167.95729, "n": 273568, "h": "1c8da1435721e456", "c": "\"\"\"\nMulti-provider authentication system for Clawbot Agent.\n\nSupports OAuth device code flows (Soam Portal, future: OpenAI Codex) and\ntraditional API key providers (OpenRouter, custom endpoints). Auth state\nis persisted in ~/.clawbot/auth.json with cross-process file locking.\n\nArchitecture:\n- ProviderConfig registry defines known OAuth providers\n- Auth store (auth.json) holds per-provider credential state\n- resolve_provider() picks the active provider via priority chain\n- resolve_*_runtime_credentials() handles token refresh and key minting\n- logout_command() is the CLI entry point for clearing auth\n\nSoam authentication paths:\n- Invoke JWT (preferred): use a scoped access_token directly for inference.\n- Legacy session key (fallback): mint an opaque 24h key when JWT auth is\n  unavailable, or when CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS is set for\n  debugging or rollback.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport shutil\nimport shlex\nimport ssl\nimport stat\nimport sys\nimport base64\nimport hashlib\nimport subprocess\nimport threading\nimport time\nimport uuid\nimport webbrowser\nfrom contextlib import contextmanager\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\nfrom pathlib import Path\nfrom typing import Any, Callable, Dict, List, Optional, Tuple\nfrom urllib.parse import parse_qs, urlencode, urlparse\n\nimport httpx\nimport yaml\n\nfrom clawbot_cli.config import get_clawbot_home, get_config_path, read_raw_config\nfrom clawbot_constants import OPENROUTER_BASE_URL\nfrom utils import atomic_replace, atomic_yaml_write, is_truthy_value\n\nlogger = logging.getLogger(__name__)\n\ntry:\n    import fcntl\nexcept Exception:\n    fcntl = None\ntry:\n    import msvcrt\nexcept Exception:\n    msvcrt = None\n\n# =============================================================================\n# Constants\n# =============================================================================\n\nAUTH_STORE_VERSION = 1\nAUTH_LOCK_TIMEOUT_SECONDS = 15.0\n\n# Soam Portal defaults\nDEFAULT_SOAM_PORTAL_URL = \"https://portal.aayushsoam.com\"\nDEFAULT_SOAM_INFERENCE_URL = \"https://inference-api.aayushsoam.com/v1\"\nDEFAULT_SOAM_CLIENT_ID = \"\"\nDEFAULT_GROQ_BASE_URL = \"https://api.groq.com/openai/v1\"\nSOAM_LEGACY_AGENT_KEY_SCOPE = \"inference:mint_agent_key\"\nSOAM_INFERENCE_INVOKE_SCOPE = \"inference:invoke\"\nDEFAULT_SOAM_SCOPE = f\"{SOAM_INFERENCE_INVOKE_SCOPE} {SOAM_LEGACY_AGENT_KEY_SCOPE}\"\nSOAM_LEGACY_SESSION_KEYS_ENV = \"CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS\"\nSOAM_DEVICE_CODE_SOURCE = \"device_code\"\nSOAM_INFERENCE_AUTH_MODE_AUTO = \"auto\"\nSOAM_INFERENCE_AUTH_MODE_FRESH = \"fresh\"\nSOAM_INFERENCE_AUTH_MODE_LEGACY = \"legacy\"\nSOAM_INFERENCE_AUTH_MODES = frozenset({\n    SOAM_INFERENCE_AUTH_MODE_AUTO,\n    SOAM_INFERENCE_AUTH_MODE_FRESH,\n    SOAM_INFERENCE_AUTH_MODE_LEGACY,\n})\nSOAM_AUTH_PATH_INVOKE_JWT = \"\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE = \"legacy_session_key_cache\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT = \"legacy_session_key_mint\"\nDEFAULT_AGENT_KEY_MIN_TTL_SECONDS = 30 * 60  # 30 minutes\nACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120       # refresh 2 min before expiry\nSOAM_INVOKE_JWT_MIN_TTL_SECONDS = ACCESS_TOKEN_REFRESH_SKEW_SECONDS\nDEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS = 1     # poll at most every 1s\nDEFAULT_CODEX_BASE_URL = \"https://chatgpt.com/backend-api/codex\"\nDEFAULT_XAI_OAUTH_BASE_URL = \"https://api.x.ai/v1\"\nMINIMAX_OAUTH_CLIENT_ID = \"\"\nMINIMAX_OAUTH_SCOPE = \"group_id profile model.completion\"\nMINIMAX_OAUTH_GRANT_TYPE = \"urn:ietf:params:oauth:grant-type:user_code\"\nMINIMAX_OAUTH_GLOBAL_BASE = \"https://api.minimax.io\"\nMINIMAX_OAUTH_CN_BASE = \"https://api.minimaxi.com\"\nMINIMAX_OAUTH_GLOBAL_INFERENCE = \"https://api.minimax.io/anthropic\"\nMINIMAX_OAUTH_CN_INFERENCE = \"https://api.minimaxi.com/anthropic\"\nMINIMAX_OAUTH_REFRESH_SKEW_SECONDS = 60\nDEFAULT_QWEN_BASE_URL = \"https://portal.qwen.ai/v1\"\nDEFAULT_GITHUB_MODELS_BASE_URL = \"https://api.githubcopilot.com\"\nDEFAULT_COPILOT_ACP_BASE_URL = \"acp://copilot\"\nDEFAULT_OLLAMA_CLOUD_BASE_URL = \"https://ollama.com/v1\"\nSTEPFUN_STEP_PLAN_INTL_BASE_URL = \"https://api.stepfun.ai/step_plan/v1\"\nSTEPFUN_STEP_PLAN_CN_BASE_URL = \"https://api.stepfun.com/step_plan/v1\"\nCODEX_OAUTH_CLIENT_ID = \"\"\nCODEX_OAUTH_TOKEN_URL = \"https://auth.openai.com/oauth/token\"\nCODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nXAI_OAUTH_ISSUER = \"https://auth.x.ai\"\nXAI_OAUTH_DISCOVERY_URL = f\"{XAI_OAUTH_ISSUER}/.well-known/openid-configuration\"\nXAI_OAUTH_CLIENT_ID = \"\"\nXAI_OAUTH_SCOPE = \"openid profile email offline_access grok-cli:access api:access\"\nXAI_OAUTH_REDIRECT_HOST = \"127.0.0.1\"\nXAI_OAUTH_REDIRECT_PORT = 56121\nXAI_OAUTH_REDIRECT_PATH = \"/callback\"\nXAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nQWEN_OAUTH_CLIENT_ID = \"\"\nQWEN_OAUTH_TOKEN_URL = \"https://chat.qwen.ai/api/v1/oauth2/token\"\nQWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nDEFAULT_SPOTIFY_ACCOUNTS_BASE_URL = \"https://accounts.spotify.com\"\nDEFAULT_SPOTIFY_API_BASE_URL = \"https://api.spotify.com/v1\"\nDEFAULT_SPOTIFY_REDIRECT_URI = \"http://127.0.0.1:43827/spotify/callback\"\nSPOTIFY_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/user-guide/features/spotify\"\nSPOTIFY_DASHBOARD_URL = \"https://developer.spotify.com/dashboard\"\nSPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\n\nXAI_OAUTH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/xai-grok-oauth\"\nOAUTH_OVER_SSH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/oauth-over-ssh\"\nDEFAULT_SPOTIFY_SCOPE = \" \".join((\n    \"user-modify-playback-state\",\n    \"user-read-playback-state\",\n    \"user-read-currently-playing\",\n    \"user-read-recently-played\",\n    \"playlist-read-private\",\n    \"playlist-read-collaborative\",\n    \"playlist-modify-public\",\n    \"playlist-modify-private\",\n    \"user-library-read\",\n    \"user-library-modify\",\n))\nSERVICE_PROVIDER_NAMES: Dict[str, str] = {\n    \"spotify\": \"Spotify\",\n}\n\n# Google Gemini OAuth (google-gemini-cli provider, Cloud Code Assist backend)\nDEFAULT_GEMINI_CLOUDCODE_BASE_URL = \"cloudcode-pa://google\"\nGEMINI_OAUTH_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 60  # refresh 60s before expiry\n\n# LM Studio's default no-auth mode still requires *some* non-empty bearer for\n# the API-key code paths (auxiliary_client, runtime resolver) to treat the\n# provider as configured. This sentinel is sent only to LM Studio, never to\n# any remote service.\nLMSTUDIO_NOAUTH_PLACEHOLDER = \"dummy-lm-api-key\"\n\n\n# =============================================================================\n# Provider Registry\n# =============================================================================\n\n@dataclass\nclass ProviderConfig:\n    \"\"\"Describes a known inference provider.\"\"\"\n    id: str\n    name: str\n    auth_type: str  # \"oauth_device_code\", \"oauth_external\", \"oauth_minimax\", or \"api_key\"\n    portal_base_url: str = \"\"\n    inference_base_url: str = \"\"\n    client_id: str = \"\"\n    scope: str = \"\"\n    extra: Dict[str, Any] = field(default_factory=dict)\n    # For API-key providers: env vars to check (in priority order)\n    api_key_env_vars: tuple = ()\n    # Optional env var for base URL override\n    base_url_env_var: str = \"\"\n\n\nPROVIDER_REGISTRY: Dict[str, ProviderConfig] = {\n    \"groq\": ProviderConfig(\n        id=\"groq\",\n        name=\"Groq\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_GROQ_BASE_URL,\n        api_key_env_vars=(\"GROQ_API_KEY\",),\n        base_url_env_var=\"GROQ_BASE_URL\",\n    ),\n    \"openai-codex\": ProviderConfig(\n        id=\"openai-codex\",\n        name=\"OpenAI Codex\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_CODEX_BASE_URL,\n    ),\n    \"xai-oauth\": ProviderConfig(\n        id=\"xai-oauth\",\n        name=\"xAI Grok OAuth (SuperGrok Subscription)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_XAI_OAUTH_BASE_URL,\n    ),\n    \"qwen-oauth\": ProviderConfig(\n        id=\"qwen-oauth\",\n        name=\"Qwen OAuth\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_QWEN_BASE_URL,\n    ),\n    \"google-gemini-cli\": ProviderConfig(\n        id=\"google-gemini-cli\",\n        name=\"Google Gemini (OAuth)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_GEMINI_CLOUDCODE_BASE_URL,\n    ),\n    \"lmstudio\": ProviderConfig(\n        id=\"lmstudio\",\n        name=\"LM Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"http://127.0.0.1:1234/v1\",\n        api_key_env_vars=(\"LM_API_KEY\",),\n        base_url_env_var=\"LM_BASE_URL\",\n    ),\n    \"copilot\": ProviderConfig(\n        id=\"copilot\",\n        name=\"GitHub Copilot\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_GITHUB_MODELS_BASE_URL,\n        api_key_env_vars=(\"COPILOT_GITHUB_TOKEN\", \"GH_TOKEN\", \"GITHUB_TOKEN\"),\n        base_url_env_var=\"COPILOT_API_BASE_URL\",\n    ),\n    \"copilot-acp\": ProviderConfig(\n        id=\"copilot-acp\",\n        name=\"GitHub Copilot ACP\",\n        auth_type=\"external_process\",\n        inference_base_url=DEFAULT_COPILOT_ACP_BASE_URL,\n        base_url_env_var=\"COPILOT_ACP_BASE_URL\",\n    ),\n    \"gemini\": ProviderConfig(\n        id=\"gemini\",\n        name=\"Google AI Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://generativelanguage.googleapis.com/v1beta\",\n        api_key_env_vars=(\"GOOGLE_API_KEY\", \"GEMINI_API_KEY\"),\n        base_url_env_var=\"GEMINI_BASE_URL\",\n    ),\n    \"zai\": ProviderConfig(\n        id=\"zai\",\n        name=\"Z.AI / GLM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.z.ai/api/paas/v4\",\n        api_key_env_vars=(\"GLM_API_KEY\", \"ZAI_API_KEY\", \"Z_AI_API_KEY\"),\n        base_url_env_var=\"GLM_BASE_URL\",\n    ),\n    \"kimi-coding\": ProviderConfig(\n        id=\"kimi-coding\",\n        name=\"Kimi / Moonshot\",\n        auth_type=\"api_key\",\n        # Legacy platform.moonshot.ai keys use this endpoint (OpenAI-compat).\n        # sk-kimi- (Kimi Code) keys are auto-redirected to api.kimi.com/coding\n        # by _resolve_kimi_base_url() below.\n        inference_base_url=\"https://api.moonshot.ai/v1\",\n        api_key_env_vars=(\"KIMI_API_KEY\", \"KIMI_CODING_API_KEY\"),\n        base_url_env_var=\"KIMI_BASE_URL\",\n    ),\n    \"kimi-coding-cn\": ProviderConfig(\n        id=\"kimi-coding-cn\",\n        name=\"Kimi / Moonshot (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.moonshot.cn/v1\",\n        api_key_env_vars=(\"KIMI_CN_API_KEY\",),\n    ),\n    \"stepfun\": ProviderConfig(\n        id=\"stepfun\",\n        name=\"StepFun Step Plan\",\n        auth_type=\"api_key\",\n        inference_base_url=STEPFUN_STEP_PLAN_INTL_BASE_URL,\n        api_key_env_vars=(\"STEPFUN_API_KEY\",),\n        base_url_env_var=\"STEPFUN_BASE_URL\",\n    ),\n    \"arcee\": ProviderConfig(\n        id=\"arcee\",\n        name=\"Arcee AI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.arcee.ai/api/v1\",\n        api_key_env_vars=(\"ARCEEAI_API_KEY\",),\n        base_url_env_var=\"ARCEE_BASE_URL\",\n    ),\n    \"gmi\": ProviderConfig(\n        id=\"gmi\",\n        name=\"GMI Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.gmi-serving.com/v1\",\n        api_key_env_vars=(\"GMI_API_KEY\",),\n        base_url_env_var=\"GMI_BASE_URL\",\n    ),\n    \"minimax\": ProviderConfig(\n        id=\"minimax\",\n        name=\"MiniMax\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimax.io/anthropic\",\n        api_key_env_vars=(\"MINIMAX_API_KEY\",),\n        base_url_env_var=\"MINIMAX_BASE_URL\",\n    ),\n    \"minimax-oauth\": ProviderConfig(\n        id=\"minimax-oauth\",\n        name=\"MiniMax (OAuth \\u00b7 minimax.io)\",\n        auth_type=\"oauth_minimax\",\n        portal_base_url=MINIMAX_OAUTH_GLOBAL_BASE,\n        inference_base_url=MINIMAX_OAUTH_GLOBAL_INFERENCE,\n        client_id=MINIMAX_OAUTH_CLIENT_ID,\n        scope=MINIMAX_OAUTH_SCOPE,\n        extra={\"region\": \"global\", \"cn_portal_base_url\": MINIMAX_OAUTH_CN_BASE,\n               \"cn_inference_base_url\": MINIMAX_OAUTH_CN_INFERENCE},\n    ),\n    \"anthropic\": ProviderConfig(\n        id=\"anthropic\",\n        name=\"Anthropic\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.anthropic.com\",\n        api_key_env_vars=(\"ANTHROPIC_API_KEY\", \"ANTHROPIC_TOKEN\", \"CLAUDE_CODE_OAUTH_TOKEN\"),\n        base_url_env_var=\"ANTHROPIC_BASE_URL\",\n    ),\n    \"alibaba\": ProviderConfig(\n        id=\"alibaba\",\n        name=\"Qwen Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://dashscope-intl.aliyuncs.com/compatible-mode/v1\",\n        api_key_env_vars=(\"DASHSCOPE_API_KEY\",),\n        base_url_env_var=\"DASHSCOPE_BASE_URL\",\n    ),\n    \"alibaba-coding-plan\": ProviderConfig(\n        id=\"alibaba-coding-plan\",\n        name=\"Alibaba Cloud (Coding Plan)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://coding-intl.dashscope.aliyuncs.com/v1\",\n        api_key_env_vars=(\"ALIBABA_CODING_PLAN_API_KEY\", \"DASHSCOPE_API_KEY\"),\n        base_url_env_var=\"ALIBABA_CODING_PLAN_BASE_URL\",\n    ),\n    \"minimax-cn\": ProviderConfig(\n        id=\"minimax-cn\",\n        name=\"MiniMax (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimaxi.com/anthropic\",\n        api_key_env_vars=(\"MINIMAX_CN_API_KEY\",),\n        base_url_env_var=\"MINIMAX_CN_BASE_URL\",\n    ),\n    \"deepseek\": ProviderConfig(\n        id=\"deepseek\",\n        name=\"DeepSeek\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.deepseek.com/v1\",\n        api_key_env_vars=(\"DEEPSEEK_API_KEY\",),\n        base_url_env_var=\"DEEPSEEK_BASE_URL\",\n    ),\n    \"xai\": ProviderConfig(\n        id=\"xai\",\n        name=\"xAI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.x.ai/v1\",\n        api_key_env_vars=(\"XAI_API_KEY\",),\n        base_url_env_var=\"XAI_BASE_URL\",\n    ),\n    \"nvidia\": ProviderConfig(\n        id=\"nvidia\",\n        name=\"NVIDIA NIM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://integrate.api.nvidia.com/v1\",\n        api_key_env_vars=(\"NVIDIA_API_KEY\",),\n        base_url_env_var=\"NVIDIA_BASE_URL\",\n    ),\n    \"ai-gateway\": ProviderConfig(\n        id=\"ai-gateway\",\n        name=\"Vercel AI Gateway\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://ai-gateway.vercel.sh/v1\",\n        api_key_env_vars=(\"AI_GATEWAY_API_KEY\",),\n        base_url_env_var=\"AI_GATEWAY_BASE_URL\",\n    ),\n    \"opencode-zen\": ProviderConfig(\n        id=\"opencode-zen\",\n        name=\"OpenCode Zen\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://opencode.ai/zen/v1\",\n        api_key_env_vars=(\"OPENCODE_ZEN_API_KEY\",),\n        base_url_env_var=\"OPENCODE_ZEN_BASE_URL\",\n    ),\n    \"opencode-go\": ProviderConfig(\n        id=\"opencode-go\",\n        name=\"OpenCode Go\",\n        auth_type=\"api_key\",\n        # OpenCode Go mixes API surfaces by model:\n        # - GLM / Kimi use OpenAI-compatible chat completions under /v1\n        # - MiniMax models use Anthropic Messages under /v1/messages\n        # Keep the provider base at /v1 and select api_mode per-model.\n        inference_base_url=\"https://opencode.ai/zen/go/v1\",\n        api_key_env_vars=(\"OPENCODE_GO_API_KEY\",),\n        base_url_env_var=\"OPENCODE_GO_BASE_URL\",\n    ),\n    \"kilocode\": ProviderConfig(\n        id=\"kilocode\",\n        name=\"Kilo Code\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.kilo.ai/api/gateway\",\n        api_key_env_vars=(\"KILOCODE_API_KEY\",),\n        base_url_env_var=\"KILOCODE_BASE_URL\",\n    ),\n    \"huggingface\": ProviderConfig(\n        id=\"huggingface\",\n        name=\"Hugging Face\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://router.huggingface.co/v1\",\n        api_key_env_vars=(\"HF_TOKEN\",),\n        base_url_env_var=\"HF_BASE_URL\",\n    ),\n    \"xiaomi\": ProviderConfig(\n        id=\"xiaomi\",\n        name=\"Xiaomi MiMo\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.xiaomimimo.com/v1\",\n        api_key_env_vars=(\"XIAOMI_API_KEY\",),\n        base_url_env_var=\"XIAOMI_BASE_URL\",\n    ),\n    \"tencent-tokenhub\": ProviderConfig(\n        id=\"tencent-tokenhub\",\n        name=\"Tencent TokenHub\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://tokenhub.tencentmaas.com/v1\",\n        api_key_env_vars=(\"TOKENHUB_API_KEY\",),\n        base_url_env_var=\"TOKENHUB_BASE_URL\",\n    ),\n    \"ollama-cloud\": ProviderConfig(\n        id=\"ollama-cloud\",\n        name=\"Ollama Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_OLLAMA_CLOUD_BASE_URL,\n        api_key_env_vars=(\"OLLAMA_API_KEY\",),\n        base_url_env_var=\"OLLAMA_BASE_URL\",\n    ),\n    \"bedrock\": ProviderConfig(\n        id=\"bedrock\",\n        name=\"AWS Bedrock\",\n        auth_type=\"aws_sdk\",\n        inference_base_url=\"https://bedrock-runtime.us-east-1.amazonaws.com\",\n        api_key_env_vars=(),\n        base_url_env_var=\"BEDROCK_BASE_URL\",\n    ),\n    \"azure-foundry\": ProviderConfig(\n        id=\"azure-foundry\",\n        name=\"Azure Foundry\",\n        auth_type=\"api_key\",\n        inference_base_url=\"\",  # User-provided endpoint\n        api_key_env_vars=(\"AZURE_FOUNDRY_API_KEY\",),\n        base_url_env_var=\"AZURE_FOUNDRY_BASE_URL\",\n    ),\n}\n\n# Auto-extend PROVIDER_REGISTRY with any api-key provider registered in\n# providers/ that is not already declared above.  New providers only need a\n# plugins/model-providers/<name>/ plugin — no edits to this file required.\ntry:\n    from providers import list_providers as _list_providers_for_registry\n    for _pp in _list_providers_for_registry():\n        if _pp.name in PROVIDER_REGISTRY:\n            continue\n        if _pp.auth_type != \"api_key\" or not _pp.env_vars:\n            continue\n        # Skip providers that need custom token resolution or are special-cased\n        # in resolve_provider() (copilot/kimi/zai have bespoke token refresh;\n        # openrouter/custom are aggregator/user-supplied and handled outside\n        # the registry — adding them here breaks runtime_provider resolution\n        # that relies on `openrouter not in PROVIDER_REGISTRY`).\n        if _pp.name in {\"copilot\", \"kimi-coding\", \"kimi-coding-cn\", \"zai\", \"openrouter\", \"custom\"}:\n            continue\n        _api_key_vars = tuple(v for v in _pp.env_vars if not v.endswith(\"_BASE_URL\") and not v.endswith(\"_URL\"))\n        _base_url_var = next((v for v in _pp.env_vars if v.endswith(\"_BASE_URL\") or v.endswith(\"_URL\")), None)\n        PROVIDER_REGISTRY[_pp.name] = ProviderConfig(\n            id=_pp.name,\n            name=_pp.display_name or _pp.name,\n            auth_type=\"api_key\",\n            inference_base_url=_pp.base_url,\n            api_key_env_vars=_api_key_vars or _pp.env_vars,\n            base_url_env_var=_base_url_var or \"\",\n        )\n        # Also register aliases so resolve_provider() resolves them\n        for _alias in _pp.aliases:\n            if _alias not in PROVIDER_REGISTRY:\n                PROVIDER_REGISTRY[_alias] = PROVIDER_REGISTRY[_pp.name]\nexcept Exception:\n    pass\n\n\n# =============================================================================\n# Anthropic Key Helper\n# =============================================================================\n\ndef get_anthropic_key() -> str:\n    \"\"\"Return the first usable Anthropic credential, or ``\"\"``.\n\n    Checks both the ``.env`` file (via ``get_env_value``) and the process\n    environment (``os.getenv``).  The fallback order mirrors the\n    ``PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars`` tuple:\n\n        ANTHROPIC_API_KEY -> ANTHROPIC_TOKEN -> CLAUDE_CODE_OAUTH_TOKEN\n    \"\"\"\n    from clawbot_cli.config import get_env_value\n\n    for var in PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars:\n        value = get_env_value(var) or os.getenv(var, \"\")\n        if value:\n            return value\n    return \"\"\n\n\n# =============================================================================\n# Kimi Code Endpoint Detection\n# =============================================================================\n\n# Kimi Code (kimi.com/code) issues keys prefixed \"sk-kimi-\" that only work\n# on api.kimi.com/coding.  Legacy keys from platform.moonshot.ai work on\n# api.moonshot.ai/v1 (the old default).  Auto-detect when user hasn't set\n# KIMI_BASE_URL explicitly.\n#\n# Note: the base URL intentionally has NO /v1 suffix.  The /coding endpoint\n# speaks the Anthropic Messages protocol, and the anthropic SDK appends\n# \"/v1/messages\" internally — so \"/coding\" + SDK suffix → \"/coding/v1/messages\"\n# (the correct target). Using \"/coding/v1\" here would produce\n# \"/coding/v1/v1/messages\" (a 404).\nKIMI_CODE_BASE_URL = \"https://api.kimi.com/coding\"\n\n\ndef _resolve_kimi_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Kimi base URL based on the API key prefix.\n\n    If the user has explicitly set KIMI_BASE_URL, that always wins.\n    Otherwise, sk-kimi- prefixed keys route to api.kimi.com/coding/v1.\n    \"\"\"\n    if env_override:\n        return env_override\n    # No key → nothing to infer from.  Return default without inspecting.\n    if not api_key:\n        return default_url\n    if api_key.startswith(\"sk-kimi-\"):\n        return KIMI_CODE_BASE_URL\n    return default_url\n\n\n\n_PLACEHOLDER_SECRET_VALUES = {\n    \"*\",\n    \"**\",\n    \"***\",\n    \"changeme\",\n    \"your_api_key\",\n    \"your-api-key\",\n    \"placeholder\",\n    \"example\",\n    \"dummy\",\n    \"null\",\n    \"none\",\n}\n\n\ndef has_usable_secret(value: Any, *, min_length: int = 4) -> bool:\n    \"\"\"Return True when a configured secret looks usable, not empty/placeholder.\"\"\"\n    if not isinstance(value, str):\n        return False\n    cleaned = value.strip()\n    if len(cleaned) < min_length:\n        return False\n    if cleaned.lower() in _PLACEHOLDER_SECRET_VALUES:\n        return False\n    return True\n\n\ndef _resolve_api_key_provider_secret(\n    provider_id: str, pconfig: ProviderConfig\n) -> tuple[str, str]:\n    \"\"\"Resolve an API-key provider's token and indicate where it came from.\"\"\"\n    if provider_id == \"copilot\":\n        # Use the dedicated copilot auth module for proper token validation\n        try:\n            from clawbot_cli.copilot_auth import resolve_copilot_token, get_copilot_api_token\n            token, source = resolve_copilot_token()\n            if token:\n                return get_copilot_api_token(token), source\n        except ValueError as exc:\n            logger.warning(\"Copilot token validation failed: %s\", exc)\n        except Exception:\n            pass\n        return \"\", \"\"\n\n    from clawbot_cli.config import get_env_value\n    for env_var in pconfig.api_key_env_vars:\n        # Check both os.environ and ~/.clawbot/.env file\n        val = (get_env_value(env_var) or \"\").strip()\n        if has_usable_secret(val):\n            return val, env_var\n\n    # Fallback: try credential pool (e.g. zai key stored via auth.json)\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(provider_id)\n        if pool and pool.has_credentials():\n            entry = pool.peek()\n            if entry:\n                key = getattr(entry, \"access_token\", \"\") or getattr(entry, \"runtime_api_key\", \"\")\n                key = str(key).strip()\n                if has_usable_secret(key):\n                    return key, f\"credential_pool:{provider_id}\"\n    except Exception:\n        pass\n\n    return \"\", \"\"\n\n\n# =============================================================================\n# Z.AI Endpoint Detection\n# =============================================================================\n\n# Z.AI has separate billing for general vs coding plans, and global vs China\n# endpoints.  A key that works on one may return \"Insufficient balance\" on\n# another.  We probe at setup time and store the working endpoint.\n# Each entry lists candidate models to try in order — newer coding plan accounts\n# may only have access to recent models (glm-5.1, glm-5v-turbo) while older\n# ones still use glm-4.7.\n\nZAI_ENDPOINTS = [\n    # (id, base_url, probe_models, label)\n    (\"global\",        \"https://api.z.ai/api/paas/v4\",        [\"glm-5\"],   \"Global\"),\n    (\"cn\",            \"https://open.bigmodel.cn/api/paas/v4\", [\"glm-5\"],   \"China\"),\n    (\"coding-global\", \"https://api.z.ai/api/coding/paas/v4\",  [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"Global (Coding Plan)\"),\n    (\"coding-cn\",     \"https://open.bigmodel.cn/api/coding/paas/v4\", [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"China (Coding Plan)\"),\n]\n\n\ndef detect_zai_endpoint(api_key: str, timeout: float = 8.0) -> Optional[Dict[str, str]]:\n    \"\"\"Probe z.ai endpoints to find one that accepts this API key.\n\n    Returns {\"id\": ..., \"base_url\": ..., \"model\": ..., \"label\": ...} for the\n    first working endpoint, or None if all fail.  For endpoints with multiple\n    candidate models, tries each in order and returns the first that succeeds.\n    \"\"\"\n    for ep_id, base_url, probe_models, label in ZAI_ENDPOINTS:\n        for model in probe_models:\n            try:\n                resp = httpx.post(\n                    f\"{base_url}/chat/completions\",\n                    headers={\n                        \"Authorization\": f\"Bearer {api_key}\",\n                        \"Content-Type\": \"application/json\",\n                    },\n                    json={\n                        \"model\": model,\n                        \"stream\": False,\n                        \"max_tokens\": 1,\n                        \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}],\n                    },\n                    timeout=timeout,\n                )\n                if resp.status_code == 200:\n                    logger.debug(\"Z.AI endpoint probe: %s (%s) model=%s OK\", ep_id, base_url, model)\n                    return {\n                        \"id\": ep_id,\n                        \"base_url\": base_url,\n                        \"model\": model,\n                        \"label\": label,\n                    }\n                logger.debug(\"Z.AI endpoint probe: %s model=%s returned %s\", ep_id, model, resp.status_code)\n            except Exception as exc:\n                logger.debug(\"Z.AI endpoint probe: %s model=%s failed: %s\", ep_id, model, exc)\n    return None\n\n\ndef _resolve_zai_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Z.AI base URL by probing endpoints.\n\n    If the user has explicitly set GLM_BASE_URL, that always wins.\n    Otherwise, probe the candidate endpoints to find one that accepts the\n    key.  The detected endpoint is cached in provider state (auth.json) keyed\n    on a hash of the API key so subsequent starts skip the probe.\n    \"\"\"\n    if env_override:\n        return env_override\n\n    # No API key set → don't probe (would fire N×M HTTPS requests with an\n    # empty Bearer token, all returning 401).  This path is hit during\n    # auxiliary-client auto-detection when the user has no Z.AI credentials\n    # at all — the caller discards the result immediately, so the probe is\n    # pure latency for every AIAgent construction.\n    if not api_key:\n        return default_url\n\n    # Check provider-state cache for a previously-detected endpoint.\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"zai\") or {}\n    cached = state.get(\"detected_endpoint\")\n    if isinstance(cached, dict) and cached.get(\"base_url\"):\n        key_hash = cached.get(\"key_hash\", \"\")\n        if key_hash == hashlib.sha256(api_key.encode()).hexdigest()[:16]:\n            logger.debug(\"Z.AI: using cached endpoint %s\", cached[\"base_url\"])\n            return cached[\"base_url\"]\n\n    # Probe — may take up to ~8s per endpoint.\n    detected = detect_zai_endpoint(api_key)\n    if detected and detected.get(\"base_url\"):\n        # Persist the detection result keyed on the API key hash.\n        key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]\n        state[\"detected_endpoint\"] = {\n            \"base_url\": detected[\"base_url\"],\n            \"endpoint_id\": detected.get(\"id\", \"\"),\n            \"model\": detected.get(\"model\", \"\"),\n            \"label\": detected.get(\"label\", \"\"),\n            \"key_hash\": key_hash,\n        }\n        _save_provider_state(auth_store, \"zai\", state)\n        logger.info(\"Z.AI: auto-detected endpoint %s (%s)\", detected[\"label\"], detected[\"base_url\"])\n        return detected[\"base_url\"]\n\n    logger.debug(\"Z.AI: probe failed, falling back to default %s\", default_url)\n    return default_url\n\n\n# =============================================================================\n# Error Types\n# =============================================================================\n\nclass AuthError(RuntimeError):\n    \"\"\"Structured auth error with UX mapping hints.\"\"\"\n\n    def __init__(\n        self,\n        message: str,\n        *,\n        provider: str = \"\",\n        code: Optional[str] = None,\n        relogin_required: bool = False,\n    ) -> None:\n        super().__init__(message)\n        self.provider = provider\n        self.code = code\n        self.relogin_required = relogin_required\n\n\ndef format_auth_error(error: Exception) -> str:\n    \"\"\"Map auth failures to concise user-facing guidance.\"\"\"\n    if not isinstance(error, AuthError):\n        return str(error)\n\n    if error.relogin_required:\n        return f\"{error} Run `clawbot model` to re-authenticate.\"\n\n    if error.code == \"subscription_required\":\n        return (\n            \"No active paid subscription found on Soam Portal. \"\n            \"Please purchase/activate a subscription, then retry.\"\n        )\n\n    if error.code == \"insufficient_credits\":\n        return (\n            \"Subscription credits are exhausted. \"\n            \"Top up/renew credits in Soam Portal, then retry.\"\n        )\n\n    if error.code == \"temporarily_unavailable\":\n        return f\"{error} Please retry in a few seconds.\"\n\n    return str(error)\n\n\ndef _token_fingerprint(token: Any) -> Optional[str]:\n    \"\"\"Return a short hash fingerprint for telemetry without leaking token bytes.\"\"\"\n    if not isinstance(token, str):\n        return None\n    cleaned = token.strip()\n    if not cleaned:\n        return None\n    return hashlib.sha256(cleaned.encode(\"utf-8\")).hexdigest()[:12]\n\n\ndef _oauth_trace_enabled() -> bool:\n    raw = os.getenv(\"CLAWBOT_OAUTH_TRACE\", \"\").strip().lower()\n    return raw in {\"1\", \"true\", \"yes\", \"on\"}\n\n\ndef _oauth_trace(event: str, *, sequence_id: Optional[str] = None, **fields: Any) -> None:\n    if not _oauth_trace_enabled():\n        return\n    payload: Dict[str, Any] = {\"event\": event}\n    if sequence_id:\n        payload[\"sequence_id\"] = sequence_id\n    payload.update(fields)\n    logger.info(\"oauth_trace %s\", json.dumps(payload, sort_keys=True, ensure_ascii=False))\n\n\n# =============================================================================\n# Auth Store — persistence layer for ~/.clawbot/auth.json\n# =============================================================================\n\ndef _auth_file_path() -> Path:\n    path = get_clawbot_home() / \"auth.json\"\n    # Seat belt: if pytest is running and CLAWBOT_HOME resolves to the real\n    # user's auth store, refuse rather than silently corrupt it. This catches\n    # tests that forgot to monkeypatch CLAWBOT_HOME, tests invoked without the\n    # clawbotic conftest, or sandbox escapes via threads/subprocesses. In\n    # production (no PYTEST_CURRENT_TEST) this is a single dict lookup.\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_auth = (Path.home() / \".clawbot\" / \"auth.json\").resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_auth:\n            raise RuntimeError(\n                f\"Refusing to touch real user auth store during test run: {path}. \"\n                \"Set CLAWBOT_HOME to a tmp_path in your test fixture, or run \"\n                \"via scripts/run_tests.sh for clawbotic CI-parity env.\"\n            )\n    return path\n\n\ndef _global_auth_file_path() -> Optional[Path]:\n    \"\"\"Return the global-root auth.json when the process is in profile mode.\n\n    Returns ``None`` when the profile and global root resolve to the same\n    directory (classic mode, or custom CLAWBOT_HOME that is not a profile).\n    Used by read-only fallback paths so providers authed at the root are\n    visible to profile processes that haven't configured them locally.\n\n    See issue #18594 follow-up (credential_pool shadowing).\n    \"\"\"\n    try:\n        from clawbot_constants import get_default_clawbot_root\n        global_root = get_default_clawbot_root()\n    except Exception:\n        return None\n    profile_home = get_clawbot_home()\n    try:\n        if profile_home.resolve(strict=False) == global_root.resolve(strict=False):\n            return None\n    except Exception:\n        if profile_home == global_root:\n            return None\n    # No pytest seat belt here: this is a pure read-only path, and\n    # ``_load_global_auth_store()`` wraps the read in a try/except so an\n    # unreadable global file can never break the profile process.  The\n    # write-side seat belt still lives on ``_auth_file_path()`` where it\n    # belongs (that's what protects the real user's auth store from being\n    # corrupted by a mis-configured test).\n    return global_root / \"auth.json\"\n\n\ndef _load_global_auth_store() -> Dict[str, Any]:\n    \"\"\"Load the global-root auth store (read-only fallback).\n\n    Returns an empty dict when no global fallback exists (classic mode,\n    or the global auth.json is absent). Never raises on missing file.\n\n    Seat belt: under pytest, refuses to read the real user's\n    ``~/.clawbot/auth.json`` even when CLAWBOT_HOME is set to a profile\n    path. The clawbotic conftest does not redirect ``HOME``, so\n    ``get_default_clawbot_root()`` for a profile-shaped CLAWBOT_HOME can\n    still resolve to the real user's home on a dev machine. That would\n    leak real credentials into tests. This guard uses the unmodified\n    ``HOME`` env var (what ``os.path.expanduser('~')`` would resolve to),\n    not ``Path.home()``, because ``Path.home`` is sometimes monkeypatched\n    by fixtures that want to relocate the global root to a tmp path.\n    \"\"\"\n    global_path = _global_auth_file_path()\n    if global_path is None or not global_path.exists():\n        return {}\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_env = os.environ.get(\"HOME\", \"\")\n        if real_home_env:\n            real_root = Path(real_home_env) / \".clawbot\" / \"auth.json\"\n            try:\n                if global_path.resolve(strict=False) == real_root.resolve(strict=False):\n                    return {}\n            except Exception:\n                pass\n    try:\n        return _load_auth_store(global_path)\n    except Exception:\n        # A malformed global store must not break profile reads. The\n        # profile's own auth store is still authoritative.\n        return {}\n\n\ndef _auth_lock_path() -> Path:\n    return _auth_file_path().with_suffix(\".lock\")\n\n\n_auth_lock_holder = threading.local()\n\n\n@contextmanager\ndef _file_lock(\n    lock_path: Path,\n    holder: threading.local,\n    timeout_seconds: float,\n    timeout_message: str,\n):\n    \"\"\"Cross-process advisory flock helper.\n\n    Reentrant per-thread via ``holder.depth``. Falls back to a depth-only\n    guard when neither ``fcntl`` nor ``msvcrt`` is available (rare).\n    Callers supply their own ``threading.local`` so independent locks\n    (e.g. profile auth.json vs shared Soam store) don't share reentrancy\n    state — that would let one lock's reentrant acquisition silently skip\n    the other's kernel-level flock.\n    \"\"\"\n    if getattr(holder, \"depth\", 0) > 0:\n        holder.depth += 1\n        try:\n            yield\n        finally:\n            holder.depth -= 1\n        return\n\n    lock_path.parent.mkdir(parents=True, exist_ok=True)\n\n    if fcntl is None and msvcrt is None:\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n        return\n\n    # On Windows, msvcrt.locking needs the file to have content and the\n    # file pointer at position 0. Ensure the lock file has at least 1 byte.\n    if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):\n        lock_path.write_text(\" \", encoding=\"utf-8\")\n\n    with lock_path.open(\"r+\" if msvcrt else \"a+\", encoding=\"utf-8\") as lock_file:\n        deadline = time.monotonic() + max(1.0, timeout_seconds)\n        while True:\n            try:\n                if fcntl:\n                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)\n                else:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)\n                break\n            except (BlockingIOError, OSError, PermissionError):\n                if time.monotonic() >= deadline:\n                    raise TimeoutError(timeout_message)\n                time.sleep(0.05)\n\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n            if fcntl:\n                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n            elif msvcrt:\n                try:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)\n                except (OSError, IOError):\n                    pass\n\n\n@contextmanager\ndef _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-process advisory lock for auth.json reads+writes.  Reentrant.\n\n    Lock ordering invariant: when this lock is held together with\n    ``_soam_shared_store_lock``, acquire ``_auth_store_lock`` FIRST\n    (outer) and the shared Soam lock SECOND (inner). All runtime\n    refresh paths follow this order; violating it risks deadlock\n    against a concurrent import on the shared store.\n    \"\"\"\n    with _file_lock(\n        _auth_lock_path(),\n        _auth_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for auth store lock\",\n    ):\n        yield\n\n\ndef _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:\n    auth_file = auth_file or _auth_file_path()\n    if not auth_file.exists():\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    try:\n        raw = json.loads(auth_file.read_text())\n    except Exception as exc:\n        corrupt_path = auth_file.with_suffix(\".json.corrupt\")\n        try:\n            import shutil\n            shutil.copy2(auth_file, corrupt_path)\n        except Exception:\n            pass\n        logger.warning(\n            \"auth: failed to parse %s (%s) — starting with empty store. \"\n            \"Corrupt file preserved at %s\",\n            auth_file, exc, corrupt_path,\n        )\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    if isinstance(raw, dict) and (\n        isinstance(raw.get(\"providers\"), dict)\n        or isinstance(raw.get(\"credential_pool\"), dict)\n    ):\n        raw.setdefault(\"providers\", {})\n        return raw\n\n    # Migrate from PR's \"systems\" format if present\n    if isinstance(raw, dict) and isinstance(raw.get(\"systems\"), dict):\n        systems = raw[\"systems\"]\n        providers = {}\n        if \"soam_portal\" in systems:\n            providers[\"soam\"] = systems[\"soam_portal\"]\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": providers,\n                \"active_provider\": \"soam\" if providers else None}\n\n    return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n\ndef _save_auth_store(auth_store: Dict[str, Any]) -> Path:\n    auth_file = _auth_file_path()\n    auth_file.parent.mkdir(parents=True, exist_ok=True)\n    # Tighten parent dir to 0o700 so siblings can't traverse to creds.\n    # No-op on Windows (POSIX mode bits not enforced); ignore failures.\n    try:\n        os.chmod(auth_file.parent, 0o700)\n    except OSError:\n        pass\n    auth_store[\"version\"] = AUTH_STORE_VERSION\n    auth_store[\"updated_at\"] = datetime.now(timezone.utc).isoformat()\n    payload = json.dumps(auth_store, indent=2) + \"\\n\"\n    tmp_path = auth_file.with_name(f\"{auth_file.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    try:\n        # Create with 0o600 atomically via os.open(O_EXCL) + fdopen to close\n        # the TOCTOU window where default umask (often 0o644) briefly exposed\n        # OAuth tokens to other local users between open() and chmod().\n        # Mirrors agent/google_oauth.py (#19673) and tools/mcp_oauth.py (#21148).\n        fd = os.open(\n            str(tmp_path),\n            os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n            stat.S_IRUSR | stat.S_IWUSR,\n        )\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as handle:\n            handle.write(payload)\n            handle.flush()\n            os.fsync(handle.fileno())\n        atomic_replace(tmp_path, auth_file)\n        try:\n            dir_fd = os.open(str(auth_file.parent), os.O_RDONLY)\n        except OSError:\n            dir_fd = None\n        if dir_fd is not None:\n            try:\n                os.fsync(dir_fd)\n            finally:\n                os.close(dir_fd)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    # Restrict file permissions to owner only\n    try:\n        auth_file.chmod(stat.S_IRUSR | stat.S_IWUSR)\n    except OSError:\n        pass\n    return auth_file\n\n\ndef _load_provider_state(auth_store: Dict[str, Any], provider_id: str) -> Optional[Dict[str, Any]]:\n    providers = auth_store.get(\"providers\")\n    if not isinstance(providers, dict):\n        return None\n    state = providers.get(provider_id)\n    return dict(state) if isinstance(state, dict) else None\n\n\ndef _save_provider_state(auth_store: Dict[str, Any], provider_id: str, state: Dict[str, Any]) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    auth_store[\"active_provider\"] = provider_id\n\n\ndef _store_provider_state(\n    auth_store: Dict[str, Any],\n    provider_id: str,\n    state: Dict[str, Any],\n    *,\n    set_active: bool = True,\n) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    if set_active:\n        auth_store[\"active_provider\"] = provider_id\n\n\ndef is_known_auth_provider(provider_id: str) -> bool:\n    normalized = (provider_id or \"\").strip().lower()\n    return normalized in PROVIDER_REGISTRY or normalized in SERVICE_PROVIDER_NAMES\n\n\ndef get_auth_provider_display_name(provider_id: str) -> str:\n    normalized = (provider_id or \"\").strip().lower()\n    if normalized in PROVIDER_REGISTRY:\n        return PROVIDER_REGISTRY[normalized].name\n    return SERVICE_PROVIDER_NAMES.get(normalized, provider_id)\n\n\ndef read_credential_pool(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Return the persisted credential pool, or one provider slice.\n\n    In profile mode, the profile's credential pool is authoritative. If a\n    provider has no entries in the profile, entries from the global-root\n    ``auth.json`` are used as a read-only fallback — so workers spawned in a\n    profile can see providers that were only authenticated at global scope.\n\n    Profile entries always win: the global fallback only applies per-provider\n    when the profile has zero entries for that provider. Once the user runs\n    ``clawbot auth add <provider>`` inside the profile, profile entries\n    fully shadow global for that provider on the next read.\n\n    Writes always go to the profile (``write_credential_pool`` is unchanged).\n    See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        pool = {}\n\n    global_pool: Dict[str, Any] = {}\n    global_store = _load_global_auth_store()\n    maybe_global_pool = global_store.get(\"credential_pool\") if global_store else None\n    if isinstance(maybe_global_pool, dict):\n        global_pool = maybe_global_pool\n\n    if provider_id is None:\n        merged = dict(pool)\n        for gp_key, gp_entries in global_pool.items():\n            if not isinstance(gp_entries, list) or not gp_entries:\n                continue\n            # Per-provider shadowing: profile wins whenever it has ANY entries.\n            existing = merged.get(gp_key)\n            if isinstance(existing, list) and existing:\n                continue\n            merged[gp_key] = list(gp_entries)\n        return merged\n\n    provider_entries = pool.get(provider_id)\n    if isinstance(provider_entries, list) and provider_entries:\n        return list(provider_entries)\n    # Profile has no entries for this provider — fall back to global.\n    global_entries = global_pool.get(provider_id)\n    return list(global_entries) if isinstance(global_entries, list) else []\n\n\ndef write_credential_pool(provider_id: str, entries: List[Dict[str, Any]]) -> Path:\n    \"\"\"Persist one provider's credential pool under auth.json.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n        pool[provider_id] = list(entries)\n        return _save_auth_store(auth_store)\n\n\ndef suppress_credential_source(provider_id: str, source: str) -> None:\n    \"\"\"Mark a credential source as suppressed so it won't be re-seeded.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.setdefault(\"suppressed_sources\", {})\n        provider_list = suppressed.setdefault(provider_id, [])\n        if source not in provider_list:\n            provider_list.append(source)\n        _save_auth_store(auth_store)\n\n\ndef is_source_suppressed(provider_id: str, source: str) -> bool:\n    \"\"\"Check if a credential source has been suppressed by the user.\"\"\"\n    try:\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\", {})\n        return source in suppressed.get(provider_id, [])\n    except Exception:\n        return False\n\n\ndef unsuppress_credential_source(provider_id: str, source: str) -> bool:\n    \"\"\"Clear a suppression marker so the source will be re-seeded on the next load.\n\n    Returns True if a marker was cleared, False if no marker existed.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\")\n        if not isinstance(suppressed, dict):\n            return False\n        provider_list = suppressed.get(provider_id)\n        if not isinstance(provider_list, list) or source not in provider_list:\n            return False\n        provider_list.remove(source)\n        if not provider_list:\n            suppressed.pop(provider_id, None)\n        if not suppressed:\n            auth_store.pop(\"suppressed_sources\", None)\n        _save_auth_store(auth_store)\n        return True\n\n\ndef get_provider_auth_state(provider_id: str) -> Optional[Dict[str, Any]]:\n    \"\"\"Return persisted auth state for a provider, or None.\n\n    In profile mode, falls back to the global-root ``auth.json`` when the\n    profile has no state for this provider. Profile state always wins when\n    present. Writes (``_save_auth_store`` / ``persist_*_credentials``) are\n    unchanged — they still target the profile only. This mirrors\n    ``read_credential_pool``'s per-provider shadowing semantics so that\n    ``_seed_from_singletons`` can reseed a profile's credential pool from\n    global-scope provider state (e.g. a globally-authenticated Anthropic\n    OAuth or Soam device-code session). See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, provider_id)\n    if state is not None:\n        return state\n    global_store = _load_global_auth_store()\n    if not global_store:\n        return None\n    return _load_provider_state(global_store, provider_id)\n\n\ndef get_active_provider() -> Optional[str]:\n    \"\"\"Return the currently active provider ID from auth store.\"\"\"\n    auth_store = _load_auth_store()\n    return auth_store.get(\"active_provider\")\n\n\ndef is_provider_explicitly_configured(provider_id: str) -> bool:\n    \"\"\"Return True only if the user has explicitly configured this provider.\n\n    Checks:\n      1. active_provider in auth.json matches\n      2. model.provider in config.yaml matches\n      3. Provider-specific env vars are set (e.g. ANTHROPIC_API_KEY)\n\n    This is used to gate auto-discovery of external credentials (e.g.\n    Claude Code's ~/.claude/.credentials.json) so they are never used\n    without the user's explicit choice.  See PR #4210 for the same\n    pattern applied to the setup wizard gate.\n    \"\"\"\n    normalized = (provider_id or \"\").strip().lower()\n\n    # 1. Check auth.json active_provider\n    try:\n        auth_store = _load_auth_store()\n        active = (auth_store.get(\"active_provider\") or \"\").strip().lower()\n        if active and active == normalized:\n            return True\n    except Exception:\n        pass\n\n    # 2. Check config.yaml model.provider\n    try:\n        from clawbot_cli.config import load_config\n        cfg = load_config()\n        model_cfg = cfg.get(\"model\")\n        if isinstance(model_cfg, dict):\n            cfg_provider = (model_cfg.get(\"provider\") or \"\").strip().lower()\n            if cfg_provider == normalized:\n                return True\n    except Exception:\n        pass\n\n    # 3. Check provider-specific env vars\n    # Exclude CLAUDE_CODE_OAUTH_TOKEN — it's set by Claude Code itself,\n    # not by the user explicitly configuring anthropic in Clawbot.\n    _IMPLICIT_ENV_VARS = {\"CLAUDE_CODE_OAUTH_TOKEN\"}\n    pconfig = PROVIDER_REGISTRY.get(normalized)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        for env_var in pconfig.api_key_env_vars:\n            if env_var in _IMPLICIT_ENV_VARS:\n                continue\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return True\n\n    return False\n\n\ndef clear_provider_auth(provider_id: Optional[str] = None) -> bool:\n    \"\"\"\n    Clear auth state for a provider. Used by `clawbot logout`.\n    If provider_id is None, clears the active provider.\n    Returns True if something was cleared.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        target = provider_id or auth_store.get(\"active_provider\")\n        if not target:\n            return False\n\n        providers = auth_store.get(\"providers\", {})\n        if not isinstance(providers, dict):\n            providers = {}\n            auth_store[\"providers\"] = providers\n\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n\n        cleared = False\n        if target in providers:\n            del providers[target]\n            cleared = True\n        if target in pool:\n            del pool[target]\n            cleared = True\n\n        if auth_store.get(\"active_provider\") == target:\n            auth_store[\"active_provider\"] = None\n            cleared = True\n\n        if not cleared:\n            return False\n        _save_auth_store(auth_store)\n    return True\n\n\ndef deactivate_provider() -> None:\n    \"\"\"\n    Clear active_provider in auth.json without deleting credentials.\n    Used when the user switches to a non-OAuth provider (OpenRouter, custom)\n    so auto-resolution doesn't keep picking the OAuth provider.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = None\n        _save_auth_store(auth_store)\n\n\n# =============================================================================\n# Provider Resolution — picks which provider to use\n# =============================================================================\n\n\ndef _get_config_hint_for_unknown_provider(provider_name: str) -> str:\n    \"\"\"Return a helpful hint string when provider resolution fails.\n\n    Checks for common config.yaml mistakes (malformed custom_providers, etc.)\n    and returns a human-readable diagnostic, or empty string if nothing found.\n    \"\"\"\n    try:\n        from clawbot_cli.config import validate_config_structure\n        issues = validate_config_structure()\n        if not issues:\n            return \"\"\n\n        lines = [\"Config issue detected — run 'clawbot doctor' for full diagnostics:\"]\n        for ci in issues:\n            prefix = \"ERROR\" if ci.severity == \"error\" else \"WARNING\"\n            lines.append(f\"  [{prefix}] {ci.message}\")\n            # Show first line of hint\n            first_hint = ci.hint.splitlines()[0] if ci.hint else \"\"\n            if first_hint:\n                lines.append(f\"    → {first_hint}\")\n        return \"\\n\".join(lines)\n    except Exception:\n        return \"\"\n\n\ndef resolve_provider(\n    requested: Optional[str] = None,\n    *,\n    explicit_api_key: Optional[str] = None,\n    explicit_base_url: Optional[str] = None,\n) -> str:\n    \"\"\"\n    Determine which inference provider to use.\n\n    Priority (when requested=\"auto\" or None):\n    1. active_provider in auth.json with valid credentials\n    2. Explicit CLI api_key/base_url -> \"openrouter\"\n    3. OPENAI_API_KEY or OPENROUTER_API_KEY env vars -> \"openrouter\"\n    4. Provider-specific API keys (GLM, Kimi, MiniMax) -> that provider\n    5. Fallback: \"openrouter\"\n    \"\"\"\n    normalized = (requested or \"auto\").strip().lower()\n\n    # Normalize provider aliases\n    _PROVIDER_ALIASES = {\n        \"glm\": \"zai\", \"z-ai\": \"zai\", \"z.ai\": \"zai\", \"zhipu\": \"zai\",\n        \"google\": \"gemini\", \"google-gemini\": \"gemini\", \"google-ai-studio\": \"gemini\",\n        \"x-ai\": \"xai\", \"x.ai\": \"xai\", \"grok\": \"xai\",\n        \"xai-oauth\": \"xai-oauth\", \"x-ai-oauth\": \"xai-oauth\",\n        \"grok-oauth\": \"xai-oauth\", \"xai-grok-oauth\": \"xai-oauth\",\n        \"kimi\": \"kimi-coding\", \"kimi-for-coding\": \"kimi-coding\", \"moonshot\": \"kimi-coding\",\n        \"kimi-cn\": \"kimi-coding-cn\", \"moonshot-cn\": \"kimi-coding-cn\",\n        \"step\": \"stepfun\", \"stepfun-coding-plan\": \"stepfun\",\n        \"arcee-ai\": \"arcee\", \"arceeai\": \"arcee\",\n        \"gmi-cloud\": \"gmi\", \"gmicloud\": \"gmi\",\n        \"minimax-china\": \"minimax-cn\", \"minimax_cn\": \"minimax-cn\",\n        \"minimax-portal\": \"minimax-oauth\", \"minimax-global\": \"minimax-oauth\", \"minimax_oauth\": \"minimax-oauth\",\n        \"alibaba_coding\": \"alibaba-coding-plan\", \"alibaba-coding\": \"alibaba-coding-plan\",\n        \"alibaba_coding_plan\": \"alibaba-coding-plan\",\n        \"claude\": \"anthropic\", \"claude-code\": \"anthropic\",\n        \"github\": \"copilot\", \"github-copilot\": \"copilot\",\n        \"github-models\": \"copilot\", \"github-model\": \"copilot\",\n        \"github-copilot-acp\": \"copilot-acp\", \"copilot-acp-agent\": \"copilot-acp\",\n        \"aigateway\": \"ai-gateway\", \"vercel\": \"ai-gateway\", \"vercel-ai-gateway\": \"ai-gateway\",\n        \"opencode\": \"opencode-zen\", \"zen\": \"opencode-zen\",\n        \"qwen-portal\": \"qwen-oauth\", \"qwen-cli\": \"qwen-oauth\", \"qwen-oauth\": \"qwen-oauth\", \"google-gemini-cli\": \"google-gemini-cli\", \"gemini-cli\": \"google-gemini-cli\", \"gemini-oauth\": \"google-gemini-cli\",\n        \"hf\": \"huggingface\", \"hugging-face\": \"huggingface\", \"huggingface-hub\": \"huggingface\",\n        \"mimo\": \"xiaomi\", \"xiaomi-mimo\": \"xiaomi\",\n        \"tencent\": \"tencent-tokenhub\", \"tokenhub\": \"tencent-tokenhub\",\n        \"tencent-cloud\": \"tencent-tokenhub\", \"tencentmaas\": \"tencent-tokenhub\",\n        \"aws\": \"bedrock\", \"aws-bedrock\": \"bedrock\", \"amazon-bedrock\": \"bedrock\", \"amazon\": \"bedrock\",\n        \"go\": \"opencode-go\", \"opencode-go-sub\": \"opencode-go\",\n        \"kilo\": \"kilocode\", \"kilo-code\": \"kilocode\", \"kilo-gateway\": \"kilocode\",\n        \"lmstudio\": \"lmstudio\", \"lm-studio\": \"lmstudio\", \"lm_studio\": \"lmstudio\",\n        # Local server aliases — route through the generic custom provider\n        \"ollama\": \"custom\", \"ollama_cloud\": \"ollama-cloud\",\n        \"vllm\": \"custom\", \"llamacpp\": \"custom\",\n        \"llama.cpp\": \"custom\", \"llama-cpp\": \"custom\",\n    }\n    # Extend with aliases declared in plugins/model-providers/<name>/ that aren't already mapped.\n    # This keeps providers/ as the single source for new aliases while the\n    # hardcoded dict above remains authoritative for existing ones.\n    try:\n        from providers import list_providers as _lp\n        for _pp in _lp():\n            for _alias in _pp.aliases:\n                if _alias not in _PROVIDER_ALIASES:\n                    _PROVIDER_ALIASES[_alias] = _pp.name\n    except Exception:\n        pass\n    normalized = _PROVIDER_ALIASES.get(normalized, normalized)\n\n    if normalized == \"openrouter\":\n        return \"openrouter\"\n    if normalized == \"custom\":\n        return \"custom\"\n    if normalized in PROVIDER_REGISTRY:\n        return normalized\n    if normalized != \"auto\":\n        # Check for common config.yaml issues that cause this error\n        _config_hint = _get_config_hint_for_unknown_provider(normalized)\n        msg = f\"Unknown provider '{normalized}'.\"\n        if _config_hint:\n            msg += f\"\\n\\n{_config_hint}\"\n        else:\n            msg += \" Check 'clawbot model' for available providers, or run 'clawbot doctor' to diagnose config issues.\"\n        raise AuthError(msg, code=\"invalid_provider\")\n\n    # Explicit one-off CLI creds always mean openrouter/custom\n    if explicit_api_key or explicit_base_url:\n        return \"openrouter\"\n\n    # Check auth store for an active OAuth provider\n    try:\n        auth_store = _load_auth_store()\n        active = auth_store.get(\"active_provider\")\n        if active and active in PROVIDER_REGISTRY:\n            status = get_auth_status(active)\n            if status.get(\"logged_in\"):\n                return active\n    except Exception as e:\n        logger.debug(\"Could not detect active auth provider: %s\", e)\n\n    if has_usable_secret(os.getenv(\"OPENAI_API_KEY\")) or has_usable_secret(os.getenv(\"OPENROUTER_API_KEY\")):\n        return \"openrouter\"\n\n    # Auto-detect API-key providers by checking their env vars\n    for pid, pconfig in PROVIDER_REGISTRY.items():\n        if pconfig.auth_type != \"api_key\":\n            continue\n        # GitHub tokens are commonly present for repo/tool access but should not\n        # hijack inference auto-selection unless the user explicitly chooses\n        # Copilot/GitHub Models as the provider. LM Studio is a local server\n        # whose availability isn't implied by LM_API_KEY presence (it may be\n        # offline, and the no-auth setup uses a placeholder value), so it\n        # also requires explicit selection.\n        if pid in {\"copilot\", \"lmstudio\"}:\n            continue\n        for env_var in pconfig.api_key_env_vars:\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return pid\n\n    # AWS Bedrock — detect via boto3 credential chain (IAM roles, SSO, env vars).\n    # This runs after API-key providers so explicit keys always win.\n    try:\n        from agent.bedrock_adapter import has_aws_credentials\n        if has_aws_credentials():\n            return \"bedrock\"\n    except ImportError:\n        pass  # boto3 not installed — skip Bedrock auto-detection\n\n    raise AuthError(\n        \"No inference provider configured. Run 'clawbot model' to choose a \"\n        \"provider and model, or set an API key (OPENROUTER_API_KEY, \"\n        \"OPENAI_API_KEY, etc.) in ~/.clawbot/.env.\",\n        code=\"no_provider_configured\",\n    )\n\n\n# =============================================================================\n# Timestamp / TTL helpers\n# =============================================================================\n\ndef _parse_iso_timestamp(value: Any) -> Optional[float]:\n    if not isinstance(value, str) or not value:\n        return None\n    text = value.strip()\n    if not text:\n        return None\n    if text.endswith(\"Z\"):\n        text = text[:-1] + \"+00:00\"\n    try:\n        parsed = datetime.fromisoformat(text)\n    except Exception:\n        return None\n    if parsed.tzinfo is None:\n        parsed = parsed.replace(tzinfo=timezone.utc)\n    return parsed.timestamp()\n\n\ndef _is_expiring(expires_at_iso: Any, skew_seconds: int) -> bool:\n    expires_epoch = _parse_iso_timestamp(expires_at_iso)\n    if expires_epoch is None:\n        return True\n    return expires_epoch <= (time.time() + skew_seconds)\n\n\ndef _coerce_ttl_seconds(expires_in: Any) -> int:\n    try:\n        ttl = int(expires_in)\n    except Exception:\n        ttl = 0\n    return max(0, ttl)\n\n\ndef _optional_base_url(value: Any) -> Optional[str]:\n    if not isinstance(value, str):\n        return None\n    cleaned = value.strip().rstrip(\"/\")\n    return cleaned if cleaned else None\n\n\ndef _decode_jwt_claims(token: Any) -> Dict[str, Any]:\n    if not isinstance(token, str) or token.count(\".\") != 2:\n        return {}\n    payload = token.split(\".\")[1]\n    payload += \"=\" * ((4 - len(payload) % 4) % 4)\n    try:\n        raw = base64.urlsafe_b64decode(payload.encode(\"utf-8\"))\n        claims = json.loads(raw.decode(\"utf-8\"))\n    except Exception:\n        return {}\n    return claims if isinstance(claims, dict) else {}\n\n\ndef _scope_values(raw_scope: Any) -> set[str]:\n    # OAuth token responses normally return a space-separated string. Keep\n    # collection support for JWT ``scp`` claims and older stored test fixtures.\n    scopes: set[str] = set()\n    if isinstance(raw_scope, str):\n        for part in raw_scope.replace(\",\", \" \").split():\n            cleaned = part.strip()\n            if cleaned:\n                scopes.add(cleaned)\n    elif isinstance(raw_scope, (list, tuple, set, frozenset)):\n        for item in raw_scope:\n            if isinstance(item, str):\n                scopes.update(_scope_values(item))\n    return scopes\n\n\ndef _soam_legacy_session_keys_forced() -> bool:\n    return is_truthy_value(os.getenv(SOAM_LEGACY_SESSION_KEYS_ENV), default=False)\n\n\ndef _soam_scope_has_invoke(raw_scope: Any) -> bool:\n    return SOAM_INFERENCE_INVOKE_SCOPE in _scope_values(raw_scope)\n\n\ndef _normalize_soam_inference_auth_mode(inference_auth_mode: Optional[str]) -> str:\n    mode = str(inference_auth_mode or SOAM_INFERENCE_AUTH_MODE_AUTO).strip().lower()\n    if mode not in SOAM_INFERENCE_AUTH_MODES:\n        allowed = \", \".join(sorted(SOAM_INFERENCE_AUTH_MODES))\n        raise ValueError(\n            \"Invalid Soam inference auth mode \"\n            f\"{inference_auth_mode!r}; expected one of: {allowed}\"\n        )\n    return mode\n\n\ndef _soam_invoke_jwt_status(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> Optional[str]:\n    \"\"\"Return None when the token can be used for inference, else a reason.\"\"\"\n    claims = _decode_jwt_claims(token)\n    if not claims:\n        return \"access_token_not_jwt\"\n    scopes = (\n        _scope_values(scope)\n        | _scope_values(claims.get(\"scope\"))\n        | _scope_values(claims.get(\"scp\"))\n    )\n    if SOAM_INFERENCE_INVOKE_SCOPE not in scopes:\n        return \"missing_inference_invoke_scope\"\n    exp = claims.get(\"exp\")\n    skew = max(0, int(min_ttl_seconds))\n    if isinstance(exp, (int, float)):\n        if float(exp) <= (time.time() + skew):\n            return \"invoke_jwt_expiring\"\n        return None\n    if _is_expiring(expires_at, skew):\n        return \"invoke_jwt_expiry_unknown_or_expiring\"\n    return None\n\n\ndef _soam_invoke_jwt_is_usable(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> bool:\n    return (\n        _soam_invoke_jwt_status(\n            token,\n            scope=scope,\n            expires_at=expires_at,\n            min_ttl_seconds=min_ttl_seconds,\n        )\n        is None\n    )\n\n\ndef _soam_legacy_session_key_reason(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> str:\n    if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY:\n        return \"forced_legacy_session_key\"\n    if _soam_legacy_session_keys_forced():\n        return \"forced_legacy_session_keys\"\n    return (\n        _soam_invoke_jwt_status(token, scope=scope, expires_at=expires_at)\n        or \"invoke_jwt_unavailable\"\n    )\n\n\ndef _choose_soam_inference_auth_path(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Tuple[str, Optional[str]]:\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    token = state.get(\"access_token\") if access_token is None else access_token\n    if (\n        not _soam_legacy_session_keys_forced()\n        and inference_auth_mode != SOAM_INFERENCE_AUTH_MODE_LEGACY\n        and _soam_invoke_jwt_is_usable(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n        )\n    ):\n        return SOAM_AUTH_PATH_INVOKE_JWT, None\n    if (\n        inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_AUTO\n        and _agent_key_is_usable(\n            state,\n            max(60, int(min_key_ttl_seconds)),\n        )\n    ):\n        return SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE, None\n    return (\n        SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT,\n        _soam_legacy_session_key_reason(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n            inference_auth_mode=inference_auth_mode,\n        ),\n    )\n\n\ndef _log_soam_invoke_jwt_selected(\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\"Soam inference auth: using NAS invoke JWT\")\n    _oauth_trace(\n        \"soam_invoke_jwt_selected\",\n        sequence_id=sequence_id,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _log_soam_legacy_session_key_selected(\n    reason: str,\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\n        \"Soam inference auth: using legacy session key path (%s)\",\n        reason,\n    )\n    _oauth_trace(\n        \"soam_legacy_session_key_selected\",\n        sequence_id=sequence_id,\n        reason=reason,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _soam_jwt_expires_at(token: Any, fallback_expires_at: Any = None) -> Optional[str]:\n    claims = _decode_jwt_claims(token)\n    exp = claims.get(\"exp\")\n    if isinstance(exp, (int, float)):\n        try:\n            return datetime.fromtimestamp(float(exp), tz=timezone.utc).isoformat()\n        except Exception:\n            pass\n    return fallback_expires_at if isinstance(fallback_expires_at, str) else None\n\n\ndef _set_soam_agent_key_from_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    obtained_at: Optional[str] = None,\n) -> None:\n    access_token = state.get(\"access_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        return\n    now = datetime.now(timezone.utc)\n    existing_obtained_at = state.get(\"agent_key_obtained_at\")\n    if obtained_at:\n        effective_obtained_at = obtained_at\n    elif (\n        state.get(\"agent_key\") == access_token\n        and isinstance(existing_obtained_at, str)\n        and existing_obtained_at.strip()\n    ):\n        effective_obtained_at = existing_obtained_at\n    else:\n        effective_obtained_at = now.isoformat()\n    expires_at = _soam_jwt_expires_at(access_token, state.get(\"expires_at\"))\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"expires_in\"))\n    )\n    if expires_at:\n        state[\"expires_at\"] = expires_at\n        state[\"expires_in\"] = expires_in\n    state[\"agent_key\"] = access_token\n    state[\"agent_key_id\"] = None\n    state[\"agent_key_expires_at\"] = expires_at\n    state[\"agent_key_expires_in\"] = expires_in\n    state[\"agent_key_reused\"] = False\n    state[\"agent_key_obtained_at\"] = effective_obtained_at\n\n\ndef _select_soam_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    sequence_id: Optional[str] = None,\n) -> None:\n    if isinstance(access_token, str) and access_token.strip():\n        state[\"access_token\"] = access_token\n    _set_soam_agent_key_from_invoke_jwt(state)\n    _log_soam_invoke_jwt_selected(\n        access_token=state.get(\"access_token\"),\n        sequence_id=sequence_id,\n    )\n\n\n_SOAM_EFFECTIVE_STATE_IGNORED_KEYS = frozenset({\n    # These are derived from expires_at/JWT exp and naturally tick down between\n    # reads. Persisting only these changes makes auth.json noisy and defeats\n    # the mtime-keyed auth-status cache.\n    \"expires_in\",\n    \"agent_key_expires_in\",\n})\n\n\ndef _soam_effective_provider_state(state: Dict[str, Any]) -> Dict[str, Any]:\n    return {\n        key: value\n        for key, value in state.items()\n        if key not in _SOAM_EFFECTIVE_STATE_IGNORED_KEYS\n    }\n\n\ndef _codex_access_token_is_expiring(access_token: Any, skew_seconds: int) -> bool:\n    claims = _decode_jwt_claims(access_token)\n    exp = claims.get(\"exp\")\n    if not isinstance(exp, (int, float)):\n        return False\n    return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n\n\ndef _qwen_cli_auth_path() -> Path:\n    return Path.home() / \".qwen\" / \"oauth_creds.json\"\n\n\ndef _read_qwen_cli_tokens() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    if not auth_path.exists():\n        raise AuthError(\n            \"Qwen CLI credentials not found. Run 'qwen auth qwen-oauth' first.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_missing\",\n        )\n    try:\n        data = json.loads(auth_path.read_text(encoding=\"utf-8\"))\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to read Qwen CLI credentials from {auth_path}: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_read_failed\",\n        ) from exc\n    if not isinstance(data, dict):\n        raise AuthError(\n            f\"Invalid Qwen CLI credentials in {auth_path}.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_invalid\",\n        )\n    return data\n\n\ndef _save_qwen_cli_tokens(tokens: Dict[str, Any]) -> Path:\n    auth_path = _qwen_cli_auth_path()\n    auth_path.parent.mkdir(parents=True, exist_ok=True)\n    try:\n        os.chmod(auth_path.parent, 0o700)\n    except OSError:\n        pass\n    # Per-process random temp suffix avoids collisions between concurrent\n    # writers and stale leftovers from a crashed prior write.\n    tmp_path = auth_path.with_name(f\"{auth_path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n    # window where write_text() + post-write chmod briefly exposed tokens\n    # at process umask (typically 0o644). See #19673, #21148.\n    fd = os.open(\n        str(tmp_path),\n        os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n        stat.S_IRUSR | stat.S_IWUSR,\n    )\n    try:\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n            fh.write(json.dumps(tokens, indent=2, sort_keys=True) + \"\\n\")\n            fh.flush()\n            os.fsync(fh.fileno())\n        atomic_replace(tmp_path, auth_path)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    return auth_path\n\n\ndef _qwen_access_token_is_expiring(expiry_date_ms: Any, skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS) -> bool:\n    try:\n        expiry_ms = int(expiry_date_ms)\n    except Exception:\n        return True\n    return (time.time() + max(0, int(skew_seconds))) * 1000 >= expiry_ms\n\n\ndef _refresh_qwen_cli_tokens(tokens: Dict[str, Any], timeout_seconds: float = 20.0) -> Dict[str, Any]:\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Qwen OAuth refresh token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_token_missing\",\n        )\n\n    try:\n        response = httpx.post(\n            QWEN_OAUTH_TOKEN_URL,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": QWEN_OAUTH_CLIENT_ID,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh failed: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        body = response.text.strip()\n        raise AuthError(\n            \"Qwen OAuth refresh failed. Re-run 'qwen auth qwen-oauth'.\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh returned invalid JSON: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_json\",\n        ) from exc\n\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Qwen OAuth refresh response missing access_token.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_response\",\n        )\n\n    expires_in = payload.get(\"expires_in\")\n    try:\n        expires_in_seconds = int(expires_in)\n    except Exception:\n        expires_in_seconds = 6 * 60 * 60\n\n    refreshed = {\n        \"access_token\": str(payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(payload.get(\"refresh_token\", refresh_token) or refresh_token).strip(),\n        \"token_type\": str(payload.get(\"token_type\", tokens.get(\"token_type\", \"Bearer\")) or \"Bearer\").strip() or \"Bearer\",\n        \"resource_url\": str(payload.get(\"resource_url\", tokens.get(\"resource_url\", \"portal.qwen.ai\")) or \"portal.qwen.ai\").strip(),\n        \"expiry_date\": int(time.time() * 1000) + max(1, expires_in_seconds) * 1000,\n    }\n    _save_qwen_cli_tokens(refreshed)\n    return refreshed\n\n\ndef resolve_qwen_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    tokens = _read_qwen_cli_tokens()\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    should_refresh = bool(force_refresh)\n    if not should_refresh and refresh_if_expiring:\n        should_refresh = _qwen_access_token_is_expiring(tokens.get(\"expiry_date\"), refresh_skew_seconds)\n    if should_refresh:\n        tokens = _refresh_qwen_cli_tokens(tokens)\n        access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Qwen OAuth access token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_access_token_missing\",\n        )\n\n    base_url = os.getenv(\"CLAWBOT_QWEN_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_QWEN_BASE_URL\n    return {\n        \"provider\": \"qwen-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"qwen-cli\",\n        \"expires_at_ms\": tokens.get(\"expiry_date\"),\n        \"auth_file\": str(_qwen_cli_auth_path()),\n    }\n\n\ndef get_qwen_auth_status() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    try:\n        creds = resolve_qwen_runtime_credentials(refresh_if_expiring=False)\n        return {\n            \"logged_in\": True,\n            \"auth_file\": str(auth_path),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n            \"expires_at_ms\": creds.get(\"expires_at_ms\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": str(exc),\n        }\n\n\n# =============================================================================\n# Google Gemini OAuth (google-gemini-cli) — PKCE flow + Cloud Code Assist.\n#\n# Tokens live in ~/.clawbot/auth/google_oauth.json (managed by agent.google_oauth).\n# The `base_url` here is the marker \"cloudcode-pa://google\" that run_agent.py\n# uses to construct a GeminiCloudCodeClient instead of the default OpenAI SDK.\n# Actual HTTP traffic goes to https://cloudcode-pa.googleapis.com/v1internal:*.\n# =============================================================================\n\ndef resolve_gemini_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime OAuth creds for google-gemini-cli.\"\"\"\n    try:\n        from agent.google_oauth import (\n            GoogleOAuthError,\n            _credentials_path,\n            get_valid_access_token,\n            load_credentials,\n        )\n    except ImportError as exc:\n        raise AuthError(\n            f\"agent.google_oauth is not importable: {exc}\",\n            provider=\"google-gemini-cli\",\n            code=\"google_oauth_module_missing\",\n        ) from exc\n\n    try:\n        access_token = get_valid_access_token(force_refresh=force_refresh)\n    except GoogleOAuthError as exc:\n        raise AuthError(\n            str(exc),\n            provider=\"google-gemini-cli\",\n            code=exc.code,\n        ) from exc\n\n    creds = load_credentials()\n    base_url = DEFAULT_GEMINI_CLOUDCODE_BASE_URL\n    return {\n        \"provider\": \"google-gemini-cli\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"google-oauth\",\n        \"expires_at_ms\": (creds.expires_ms if creds else None),\n        \"auth_file\": str(_credentials_path()),\n        \"email\": (creds.email if creds else \"\") or \"\",\n        \"project_id\": (creds.project_id if creds else \"\") or \"\",\n    }\n\n\ndef get_gemini_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return a status dict for `clawbot auth list` / `clawbot status`.\"\"\"\n    try:\n        from agent.google_oauth import _credentials_path, load_credentials\n    except ImportError:\n        return {\"logged_in\": False, \"error\": \"agent.google_oauth unavailable\"}\n    auth_path = _credentials_path()\n    creds = load_credentials()\n    if creds is None or not creds.access_token:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": \"not logged in\",\n        }\n    return {\n        \"logged_in\": True,\n        \"auth_file\": str(auth_path),\n        \"source\": \"google-oauth\",\n        \"api_key\": creds.access_token,\n        \"expires_at_ms\": creds.expires_ms,\n        \"email\": creds.email,\n        \"project_id\": creds.project_id,\n    }\n# Spotify auth — PKCE tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\n\ndef _spotify_scope_list(raw_scope: Optional[str] = None) -> List[str]:\n    scope_text = (raw_scope or DEFAULT_SPOTIFY_SCOPE).strip()\n    scopes = [part for part in scope_text.split() if part]\n    seen: set[str] = set()\n    ordered: List[str] = []\n    for scope in scopes:\n        if scope not in seen:\n            seen.add(scope)\n            ordered.append(scope)\n    return ordered\n\n\ndef _spotify_scope_string(raw_scope: Optional[str] = None) -> str:\n    return \" \".join(_spotify_scope_list(raw_scope))\n\n\ndef _spotify_client_id(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\"),\n        get_env_value(\"SPOTIFY_CLIENT_ID\"),\n        state.get(\"client_id\") if isinstance(state, dict) else None,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    raise AuthError(\n        \"Spotify client_id is required. Set CLAWBOT_SPOTIFY_CLIENT_ID or pass --client-id.\",\n        provider=\"spotify\",\n        code=\"spotify_client_id_missing\",\n    )\n\n\ndef _spotify_redirect_uri(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\"),\n        get_env_value(\"SPOTIFY_REDIRECT_URI\"),\n        state.get(\"redirect_uri\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_REDIRECT_URI,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_REDIRECT_URI\n\n\ndef _spotify_api_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_API_BASE_URL\"),\n        state.get(\"api_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_API_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_API_BASE_URL\n\n\ndef _spotify_accounts_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_ACCOUNTS_BASE_URL\"),\n        state.get(\"accounts_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL\n\n\ndef _spotify_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _spotify_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _oauth_pkce_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _oauth_pkce_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _spotify_build_authorize_url(\n    *,\n    client_id: str,\n    redirect_uri: str,\n    scope: str,\n    state: str,\n    code_challenge: str,\n    accounts_base_url: str,\n) -> str:\n    query = urlencode({\n        \"client_id\": client_id,\n        \"response_type\": \"code\",\n        \"redirect_uri\": redirect_uri,\n        \"scope\": scope,\n        \"state\": state,\n        \"code_challenge_method\": \"S256\",\n        \"code_challenge\": code_challenge,\n    })\n    return f\"{accounts_base_url}/authorize?{query}\"\n\n\ndef _spotify_validate_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must use http://localhost or http://127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host not in {\"127.0.0.1\", \"localhost\"}:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must point to localhost or 127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must include an explicit localhost port.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _make_spotify_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _SpotifyCallbackHandler(BaseHTTPRequestHandler):\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>Spotify authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>Spotify authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _SpotifyCallbackHandler, result\n\n\ndef _spotify_wait_for_callback(\n    redirect_uri: str,\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    host, port, path = _spotify_validate_redirect_uri(redirect_uri)\n    handler_cls, result = _make_spotify_callback_handler(path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    try:\n        server = _ReuseHTTPServer((host, port), handler_cls)\n    except OSError as exc:\n        raise AuthError(\n            f\"Could not bind Spotify callback server on {host}:{port}: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_callback_bind_failed\",\n        ) from exc\n\n    thread = threading.Thread(target=server.serve_forever, kwargs={\"poll_interval\": 0.1}, daemon=True)\n    thread.start()\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"Spotify authorization timed out waiting for the local callback.\",\n        provider=\"spotify\",\n        code=\"spotify_callback_timeout\",\n    )\n\n\ndef _xai_validate_loopback_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"xAI OAuth redirect_uri must use http://127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host != XAI_OAUTH_REDIRECT_HOST:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must point to 127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must include an explicit localhost port.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _xai_callback_cors_origin(origin: Optional[str]) -> str:\n    # CORS allowlist for the loopback callback.  Only xAI's own auth origins\n    # are accepted; the redirect_uri itself is bound to 127.0.0.1 and gated by\n    # PKCE+state, so additional dev/3p origins are not needed here.\n    allowed = {\n        \"https://accounts.x.ai\",\n        \"https://auth.x.ai\",\n    }\n    return origin if origin in allowed else \"\"\n\n\ndef _make_xai_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _XAICallbackHandler(BaseHTTPRequestHandler):\n        def _maybe_write_cors_headers(self) -> None:\n            origin = self.headers.get(\"Origin\")\n            allow_origin = _xai_callback_cors_origin(origin)\n            if allow_origin:\n                self.send_header(\"Access-Control-Allow-Origin\", allow_origin)\n                self.send_header(\"Access-Control-Allow-Methods\", \"GET, OPTIONS\")\n                self.send_header(\"Access-Control-Allow-Headers\", \"Content-Type\")\n                self.send_header(\"Access-Control-Allow-Private-Network\", \"true\")\n                self.send_header(\"Vary\", \"Origin\")\n\n        def do_OPTIONS(self) -> None:  # noqa: N802\n            self.send_response(204)\n            self._maybe_write_cors_headers()\n            self.end_headers()\n\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self._maybe_write_cors_headers()\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>xAI authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _XAICallbackHandler, result\n\n\ndef _xai_start_callback_server(\n    preferred_port: int = XAI_OAUTH_REDIRECT_PORT,\n) -> tuple[HTTPServer, threading.Thread, dict[str, Any], str]:\n    host = XAI_OAUTH_REDIRECT_HOST\n    expected_path = XAI_OAUTH_REDIRECT_PATH\n    handler_cls, result = _make_xai_callback_handler(expected_path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    ports_to_try = [preferred_port]\n    if preferred_port != 0:\n        ports_to_try.append(0)\n    server = None\n    last_error: Optional[OSError] = None\n    for port in ports_to_try:\n        try:\n            server = _ReuseHTTPServer((host, port), handler_cls)\n            break\n        except OSError as exc:\n            last_error = exc\n    if server is None:\n        raise AuthError(\n            f\"Could not bind xAI callback server on {host}:{preferred_port}: {last_error}\",\n            provider=\"xai-oauth\",\n            code=\"xai_callback_bind_failed\",\n        ) from last_error\n\n    actual_port = int(server.server_address[1])\n    redirect_uri = f\"http://{host}:{actual_port}{expected_path}\"\n    thread = threading.Thread(\n        target=server.serve_forever,\n        kwargs={\"poll_interval\": 0.1},\n        daemon=True,\n    )\n    thread.start()\n    return server, thread, result, redirect_uri\n\n\ndef _xai_wait_for_callback(\n    server: HTTPServer,\n    thread: threading.Thread,\n    result: dict[str, Any],\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"xAI authorization timed out waiting for the local callback.\",\n        provider=\"xai-oauth\",\n        code=\"xai_callback_timeout\",\n    )\n\n\ndef _spotify_token_payload_to_state(\n    token_payload: Dict[str, Any],\n    *,\n    client_id: str,\n    redirect_uri: str,\n    requested_scope: str,\n    accounts_base_url: str,\n    api_base_url: str,\n    previous_state: Optional[Dict[str, Any]] = None,\n) -> Dict[str, Any]:\n    now = datetime.now(timezone.utc)\n    expires_in = _coerce_ttl_seconds(token_payload.get(\"expires_in\", 0))\n    expires_at = datetime.fromtimestamp(now.timestamp() + expires_in, tz=timezone.utc)\n    state = dict(previous_state or {})\n    state.update({\n        \"client_id\": client_id,\n        \"redirect_uri\": redirect_uri,\n        \"accounts_base_url\": accounts_base_url,\n        \"api_base_url\": api_base_url,\n        \"scope\": requested_scope,\n        \"granted_scope\": str(token_payload.get(\"scope\") or requested_scope).strip(),\n        \"token_type\": str(token_payload.get(\"token_type\", \"Bearer\") or \"Bearer\").strip() or \"Bearer\",\n        \"access_token\": str(token_payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(\n            token_payload.get(\"refresh_token\")\n            or state.get(\"refresh_token\")\n            or \"\"\n        ).strip(),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": expires_at.isoformat(),\n        \"expires_in\": expires_in,\n        \"auth_type\": \"oauth_pkce\",\n    })\n    return state\n\n\ndef _spotify_exchange_code_for_tokens(\n    *,\n    client_id: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    accounts_base_url: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"client_id\": client_id,\n                \"grant_type\": \"authorization_code\",\n                \"code\": code,\n                \"redirect_uri\": redirect_uri,\n                \"code_verifier\": code_verifier,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token exchange failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token exchange failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        )\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify token response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _refresh_spotify_oauth_state(\n    state: Dict[str, Any],\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Spotify refresh token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_token_missing\",\n            relogin_required=True,\n        )\n\n    client_id = _spotify_client_id(state=state)\n    accounts_base_url = _spotify_accounts_base_url(state)\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": client_id,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token refresh failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token refresh failed. Run `clawbot auth spotify` again.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n            relogin_required=True,\n        )\n\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify refresh response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_invalid\",\n            relogin_required=True,\n        )\n\n    return _spotify_token_payload_to_state(\n        payload,\n        client_id=client_id,\n        redirect_uri=_spotify_redirect_uri(state=state),\n        requested_scope=str(state.get(\"scope\") or DEFAULT_SPOTIFY_SCOPE),\n        accounts_base_url=accounts_base_url,\n        api_base_url=_spotify_api_base_url(state),\n        previous_state=state,\n    )\n\n\ndef resolve_spotify_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = SPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"spotify\")\n        if not state:\n            raise AuthError(\n                \"Spotify is not authenticated. Run `clawbot auth spotify` first.\",\n                provider=\"spotify\",\n                code=\"spotify_auth_missing\",\n                relogin_required=True,\n            )\n\n        should_refresh = bool(force_refresh)\n        if not should_refresh and refresh_if_expiring:\n            should_refresh = _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds)\n        if should_refresh:\n            state = _refresh_spotify_oauth_state(state)\n            _store_provider_state(auth_store, \"spotify\", state, set_active=False)\n            _save_auth_store(auth_store)\n\n    access_token = str(state.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Spotify access token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_access_token_missing\",\n            relogin_required=True,\n        )\n\n    return {\n        \"provider\": \"spotify\",\n        \"access_token\": access_token,\n        \"api_key\": access_token,\n        \"token_type\": str(state.get(\"token_type\", \"Bearer\") or \"Bearer\"),\n        \"base_url\": _spotify_api_base_url(state),\n        \"scope\": str(state.get(\"granted_scope\") or state.get(\"scope\") or \"\").strip(),\n        \"client_id\": _spotify_client_id(state=state),\n        \"redirect_uri\": _spotify_redirect_uri(state=state),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"refresh_token\": str(state.get(\"refresh_token\", \"\") or \"\").strip(),\n    }\n\n\ndef get_spotify_auth_status() -> Dict[str, Any]:\n    state = get_provider_auth_state(\"spotify\")\n    if not state:\n        return {\"logged_in\": False}\n\n    expires_at = state.get(\"expires_at\")\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    return {\n        \"logged_in\": bool(refresh_token or not _is_expiring(expires_at, 0)),\n        \"auth_type\": state.get(\"auth_type\", \"oauth_pkce\"),\n        \"client_id\": state.get(\"client_id\"),\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n        \"scope\": state.get(\"granted_scope\") or state.get(\"scope\"),\n        \"expires_at\": expires_at,\n        \"api_base_url\": state.get(\"api_base_url\"),\n        \"has_refresh_token\": bool(refresh_token),\n    }\n\n\ndef _spotify_interactive_setup(redirect_uri_hint: str) -> str:\n    \"\"\"Walk the user through creating a Spotify developer app, persist the\n    resulting client_id to ~/.clawbot/.env, and return it.\n\n    Raises SystemExit if the user aborts or submits an empty value.\n    \"\"\"\n    from clawbot_cli.config import save_env_value\n\n    print()\n    print(\"=\" * 70)\n    print(\"Spotify first-time setup\")\n    print(\"=\" * 70)\n    print()\n    print(\"Spotify requires every user to register their own lightweight\")\n    print(\"developer app. This takes about two minutes and only has to be\")\n    print(\"done once per machine.\")\n    print()\n    print(f\"Full guide: {SPOTIFY_DOCS_URL}\")\n    print()\n    print(\"Steps:\")\n    print(f\"  1. Opening {SPOTIFY_DASHBOARD_URL} in your browser...\")\n    print(\"  2. Click 'Create app' and fill in:\")\n    print(\"       App name:     anything (e.g. clawbot-agent)\")\n    print(\"       Description:  anything\")\n    print(f\"       Redirect URI: {redirect_uri_hint}\")\n    print(\"       API/SDK:      Web API\")\n    print(\"  3. Agree to the terms, click Save.\")\n    print(\"  4. Open the app's Settings page and copy the Client ID.\")\n    print(\"  5. Paste it below.\")\n    print()\n\n    if not _is_remote_session():\n        try:\n            webbrowser.open(SPOTIFY_DASHBOARD_URL)\n        except Exception:\n            pass\n\n    try:\n        raw = input(\"Spotify Client ID: \").strip()\n    except (EOFError, KeyboardInterrupt):\n        print()\n        raise SystemExit(\"Spotify setup cancelled.\")\n\n    if not raw:\n        print()\n        print(f\"No Client ID entered. See {SPOTIFY_DOCS_URL} for the full guide.\")\n        raise SystemExit(\"Spotify setup cancelled: empty Client ID.\")\n\n    # Persist so subsequent `clawbot auth spotify` runs skip the wizard.\n    save_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\", raw)\n    # Only persist the redirect URI if it's non-default, to avoid pinning\n    # users to a value the default might later change to.\n    if redirect_uri_hint and redirect_uri_hint != DEFAULT_SPOTIFY_REDIRECT_URI:\n        save_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\", redirect_uri_hint)\n\n    print()\n    print(\"Saved CLAWBOT_SPOTIFY_CLIENT_ID to ~/.clawbot/.env\")\n    print()\n    return raw\n\n\ndef login_spotify_command(args) -> None:\n    existing_state = get_provider_auth_state(\"spotify\") or {}\n\n    # Interactive wizard: if no client_id is configured anywhere, walk the\n    # user through creating the Spotify developer app instead of crashing\n    # with \"CLAWBOT_SPOTIFY_CLIENT_ID is required\".\n    explicit_client_id = getattr(args, \"client_id\", None)\n    try:\n        client_id = _spotify_client_id(explicit_client_id, existing_state)\n    except AuthError as exc:\n        if getattr(exc, \"code\", \"\") != \"spotify_client_id_missing\":\n            raise\n        client_id = _spotify_interactive_setup(\n            redirect_uri_hint=getattr(args, \"redirect_uri\", None) or DEFAULT_SPOTIFY_REDIRECT_URI,\n        )\n\n    redirect_uri = _spotify_redirect_uri(getattr(args, \"redirect_uri\", None), existing_state)\n    scope = _spotify_scope_string(getattr(args, \"scope\", None) or existing_state.get(\"scope\"))\n    accounts_base_url = _spotify_accounts_base_url(existing_state)\n    api_base_url = _spotify_api_base_url(existing_state)\n    open_browser = not getattr(args, \"no_browser\", False)\n\n    code_verifier = _spotify_code_verifier()\n    code_challenge = _spotify_code_challenge(code_verifier)\n    state_nonce = uuid.uuid4().hex\n    authorize_url = _spotify_build_authorize_url(\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        scope=scope,\n        state=state_nonce,\n        code_challenge=code_challenge,\n        accounts_base_url=accounts_base_url,\n    )\n\n    print(\"Starting Spotify PKCE login...\")\n    print(f\"Client ID: {client_id}\")\n    print(f\"Redirect URI: {redirect_uri}\")\n    print(\"Make sure this redirect URI is allow-listed in your Spotify app settings.\")\n    print()\n    print(\"Open this URL to authorize Clawbot:\")\n    print(authorize_url)\n    print()\n    print(f\"Full setup guide: {SPOTIFY_DOCS_URL}\")\n    print()\n\n    _print_loopback_ssh_hint(redirect_uri, docs_url=SPOTIFY_DOCS_URL)\n\n    if open_browser and not _is_remote_session():\n        try:\n            opened = webbrowser.open(authorize_url)\n        except Exception:\n            opened = False\n        if opened:\n            print(\"Browser opened for Spotify authorization.\")\n        else:\n            print(\"Could not open the browser automatically; use the URL above.\")\n\n    callback = _spotify_wait_for_callback(\n        redirect_uri,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 180.0),\n    )\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise SystemExit(f\"Spotify authorization failed: {detail}\")\n    if callback.get(\"state\") != state_nonce:\n        raise SystemExit(\"Spotify authorization failed: state mismatch.\")\n\n    token_payload = _spotify_exchange_code_for_tokens(\n        client_id=client_id,\n        code=str(callback.get(\"code\") or \"\"),\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        accounts_base_url=accounts_base_url,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 20.0),\n    )\n    spotify_state = _spotify_token_payload_to_state(\n        token_payload,\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        requested_scope=scope,\n        accounts_base_url=accounts_base_url,\n        api_base_url=api_base_url,\n    )\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _store_provider_state(auth_store, \"spotify\", spotify_state, set_active=False)\n        saved_to = _save_auth_store(auth_store)\n\n    print(\"Spotify login successful!\")\n    print(f\"  Auth state: {saved_to}\")\n    print(\"  Provider state saved under providers.spotify\")\n    print(f\"  Docs: {SPOTIFY_DOCS_URL}\")\n\n# =============================================================================\n# SSH / remote session detection\n# =============================================================================\n\ndef _is_remote_session() -> bool:\n    \"\"\"Detect if running in an SSH session where webbrowser.open() won't work.\"\"\"\n    return bool(os.getenv(\"SSH_CLIENT\") or os.getenv(\"SSH_TTY\"))\n\n\ndef _print_loopback_ssh_hint(redirect_uri: str, *, docs_url: str | None = None) -> None:\n    \"\"\"Print an SSH tunnel hint when running a loopback-redirect OAuth flow on a\n    remote host. The auth server (xAI, Spotify, ...) will redirect the user's\n    browser to ``127.0.0.1:<port>/callback``. If the browser is on a different\n    machine than the loopback listener (the usual SSH case), the redirect can't\n    reach the listener without a local port forward.\n\n    The hint is best-effort: silent if we don't think we're remote, or if we\n    can't parse a host/port out of the redirect URI.\n\n    Pass ``docs_url`` for a provider-specific guide (e.g. the xAI Grok OAuth\n    page); the generic OAuth-over-SSH guide is always shown after it.\n    \"\"\"\n    if not _is_remote_session():\n        return\n    try:\n        parsed = urlparse(redirect_uri)\n    except Exception:\n        return\n    host = parsed.hostname or \"\"\n    port = parsed.port\n    if host not in {\"127.0.0.1\", \"::1\", \"localhost\"} or not port:\n        return\n    print()\n    print(\"Remote session detected. Your browser will redirect to\")\n    print(f\"  {redirect_uri}\")\n    print(\"which the loopback listener on THIS machine is waiting on. If your\")\n    print(\"browser is on a different machine, forward the port first from your\")\n    print(\"local machine in a separate terminal:\")\n    print()\n    print(f\"  ssh -N -L {port}:127.0.0.1:{port} <user>@<this-host>\")\n    print()\n    print(\"Then open the authorize URL above in your local browser.\")\n    if docs_url:\n        print(f\"Provider docs:      {docs_url}\")\n    print(f\"SSH/jump-box guide: {OAUTH_OVER_SSH_DOCS_URL}\")\n    print()\n\n\n# =============================================================================\n# OpenAI Codex auth — tokens stored in ~/.clawbot/auth.json (not ~/.codex/)\n#\n# Clawbot maintains its own Codex OAuth session separate from the Codex CLI\n# and VS Code extension. This prevents refresh token rotation conflicts\n# where one app's refresh invalidates the other's session.\n# =============================================================================\n\ndef _read_codex_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    \"\"\"Read Codex OAuth tokens from Clawbot auth store (~/.clawbot/auth.json).\n    \n    Returns dict with 'tokens' (access_token, refresh_token) and 'last_refresh'.\n    Raises AuthError if no Codex tokens are stored.\n    \"\"\"\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"openai-codex\")\n    if not state:\n        raise AuthError(\n            \"No Codex credentials stored. Run `clawbot auth` to authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"Codex auth state is missing tokens. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = tokens.get(\"access_token\")\n    refresh_token = tokens.get(\"refresh_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        raise AuthError(\n            \"Codex auth is missing access_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n    }\n\n\ndef _save_codex_tokens(tokens: Dict[str, str], last_refresh: str = None) -> None:\n    \"\"\"Save Codex OAuth tokens to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"openai-codex\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"chatgpt\"\n        _save_provider_state(auth_store, \"openai-codex\", state)\n        _save_auth_store(auth_store)\n\n\ndef refresh_codex_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Codex OAuth tokens without mutating Clawbot auth state.\"\"\"\n    del access_token  # Access token is only used by callers to decide whether to refresh.\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            CODEX_OAUTH_TOKEN_URL,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": CODEX_OAUTH_CLIENT_ID,\n            },\n        )\n\n    if response.status_code != 200:\n        code = \"codex_refresh_failed\"\n        message = f\"Codex token refresh failed with status {response.status_code}.\"\n        relogin_required = False\n        try:\n            err = response.json()\n            if isinstance(err, dict):\n                err_obj = err.get(\"error\")\n                # OpenAI shape: {\"error\": {\"code\": \"...\", \"message\": \"...\", \"type\": \"...\"}}\n                if isinstance(err_obj, dict):\n                    nested_code = err_obj.get(\"code\") or err_obj.get(\"type\")\n                    if isinstance(nested_code, str) and nested_code.strip():\n                        code = nested_code.strip()\n                    nested_msg = err_obj.get(\"message\")\n                    if isinstance(nested_msg, str) and nested_msg.strip():\n                        message = f\"Codex token refresh failed: {nested_msg.strip()}\"\n                # OAuth spec shape: {\"error\": \"code_str\", \"error_description\": \"...\"}\n                elif isinstance(err_obj, str) and err_obj.strip():\n                    code = err_obj.strip()\n                    err_desc = err.get(\"error_description\") or err.get(\"message\")\n                    if isinstance(err_desc, str) and err_desc.strip():\n                        message = f\"Codex token refresh failed: {err_desc.strip()}\"\n        except Exception:\n            pass\n        if code in {\"invalid_grant\", \"invalid_token\", \"invalid_request\"}:\n            relogin_required = True\n        if code == \"refresh_token_reused\":\n            message = (\n                \"Codex refresh token was already consumed by another client \"\n                \"(e.g. Codex CLI or VS Code extension). \"\n                \"Run `codex` in your terminal to generate fresh tokens, \"\n                \"then run `clawbot auth` to re-authenticate.\"\n            )\n            relogin_required = True\n        # A 401/403 from the token endpoint always means the refresh token\n        # is invalid/expired — force relogin even if the body error code\n        # wasn't one of the known strings above.\n        if response.status_code in {401, 403} and not relogin_required:\n            relogin_required = True\n        raise AuthError(\n            message,\n            provider=\"openai-codex\",\n            code=code,\n            relogin_required=relogin_required,\n        )\n\n    try:\n        refresh_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            \"Codex token refresh returned invalid JSON.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_invalid_json\",\n            relogin_required=True,\n        ) from exc\n\n    refreshed_access = refresh_payload.get(\"access_token\")\n    if not isinstance(refreshed_access, str) or not refreshed_access.strip():\n        raise AuthError(\n            \"Codex token refresh response was missing access_token.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n\n    updated = {\n        \"access_token\": refreshed_access.strip(),\n        \"refresh_token\": refresh_token.strip(),\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    next_refresh = refresh_payload.get(\"refresh_token\")\n    if isinstance(next_refresh, str) and next_refresh.strip():\n        updated[\"refresh_token\"] = next_refresh.strip()\n    return updated\n\n\ndef _refresh_codex_auth_tokens(\n    tokens: Dict[str, str],\n    timeout_seconds: float,\n) -> Dict[str, str]:\n    \"\"\"Refresh Codex access token using the refresh token.\n    \n    Saves the new tokens to Clawbot auth store automatically.\n    \"\"\"\n    refreshed = refresh_codex_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n\n    _save_codex_tokens(updated_tokens)\n    return updated_tokens\n\n\ndef _import_codex_cli_tokens() -> Optional[Dict[str, str]]:\n    \"\"\"Try to read tokens from ~/.codex/auth.json (Codex CLI shared file).\n    \n    Returns tokens dict if valid and not expired, None otherwise.\n    Does NOT write to the shared file.\n    \"\"\"\n    codex_home = os.getenv(\"CODEX_HOME\", \"\").strip()\n    if not codex_home:\n        codex_home = str(Path.home() / \".codex\")\n    auth_path = Path(codex_home).expanduser() / \"auth.json\"\n    if not auth_path.is_file():\n        return None\n    try:\n        payload = json.loads(auth_path.read_text())\n        tokens = payload.get(\"tokens\")\n        if not isinstance(tokens, dict):\n            return None\n        access_token = tokens.get(\"access_token\")\n        refresh_token = tokens.get(\"refresh_token\")\n        if not access_token or not refresh_token:\n            return None\n        # Reject expired tokens — importing stale tokens from ~/.codex/\n        # that can't be refreshed leaves the user stuck with \"Login successful!\"\n        # but no working credentials.\n        if _codex_access_token_is_expiring(access_token, 0):\n            logger.debug(\n                \"Codex CLI tokens at %s are expired — skipping import.\", auth_path,\n            )\n            return None\n        return dict(tokens)\n    except Exception:\n        return None\n\n\ndef resolve_codex_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime credentials from Clawbot's own Codex token store.\"\"\"\n    data = _read_codex_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_CODEX_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        # Re-read under lock to avoid racing with other Clawbot processes\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_codex_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n\n            if should_refresh:\n                tokens = _refresh_codex_auth_tokens(tokens, refresh_timeout_seconds)\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"provider\": \"openai-codex\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"chatgpt\",\n    }\n\n\n# =============================================================================\n# xAI Grok OAuth — tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\ndef _read_xai_oauth_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"xai-oauth\")\n    if not state:\n        raise AuthError(\n            \"No xAI OAuth credentials stored. Select xAI Grok OAuth (SuperGrok Subscription) in `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"xAI OAuth state is missing tokens. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI OAuth state is missing access_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI OAuth state is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n        \"discovery\": state.get(\"discovery\") or {},\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n    }\n\n\ndef _save_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    discovery: Optional[Dict[str, Any]] = None,\n    redirect_uri: str = \"\",\n    last_refresh: Optional[str] = None,\n) -> None:\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"xai-oauth\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"oauth_pkce\"\n        if discovery:\n            state[\"discovery\"] = discovery\n        if redirect_uri:\n            state[\"redirect_uri\"] = redirect_uri\n        _save_provider_state(auth_store, \"xai-oauth\", state)\n        _save_auth_store(auth_store)\n\n\ndef _xai_access_token_is_expiring(access_token: str, skew_seconds: int = 0) -> bool:\n    if not isinstance(access_token, str) or \".\" not in access_token:\n        return False\n    try:\n        parts = access_token.split(\".\")\n        if len(parts) < 2:\n            return False\n        payload_b64 = parts[1]\n        payload_b64 += \"=\" * (-len(payload_b64) % 4)\n        payload = json.loads(base64.urlsafe_b64decode(payload_b64.encode(\"ascii\")).decode(\"utf-8\"))\n        exp = payload.get(\"exp\")\n        if not isinstance(exp, (int, float)):\n            return False\n        return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n    except Exception:\n        return False\n\n\ndef _xai_validate_oauth_endpoint(url: str, *, field: str) -> str:\n    \"\"\"Refuse any OIDC discovery endpoint that isn't HTTPS on the xAI origin.\n\n    The OIDC discovery response is a long-lived, low-frequency request whose\n    output is cached in ``~/.clawbot/auth.json``. A single MITM during initial\n    login could substitute a malicious ``token_endpoint``; that URL would\n    then receive the refresh_token on every subsequent refresh — a permanent\n    credential leak from a one-time MITM. Validating scheme + host pins the\n    cached endpoint to the xAI auth origin (or a future ``*.x.ai`` subdomain\n    if xAI migrates) so the cache poisoning loses its persistence guarantee.\n\n    RFC 8414 §2 requires the issuer to be ``https://`` and SHOULD-keeps the\n    token_endpoint on the same origin; we enforce both. ``x.ai`` is the\n    bare apex, so we accept either exact host match or any ``.x.ai`` suffix.\n    \"\"\"\n    parsed = urlparse(url)\n    if parsed.scheme != \"https\":\n        raise AuthError(\n            f\"xAI OIDC discovery returned a non-HTTPS {field}: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    host = (parsed.hostname or \"\").lower()\n    if not host:\n        raise AuthError(\n            f\"xAI OIDC discovery {field} is missing a hostname: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    if host != \"x.ai\" and not host.endswith(\".x.ai\"):\n        raise AuthError(\n            f\"xAI OIDC discovery {field} host {host!r} is not on the xAI origin \"\n            f\"(expected x.ai or a *.x.ai subdomain). Refusing to use a cached \"\n            f\"endpoint that may have been substituted by a MITM during initial \"\n            f\"discovery; re-authenticate with `clawbot model` to re-fetch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    return url\n\n\ndef _xai_oauth_discovery(timeout_seconds: float = 15.0) -> Dict[str, str]:\n    try:\n        response = httpx.get(\n            XAI_OAUTH_DISCOVERY_URL,\n            headers={\"Accept\": \"application/json\"},\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        ) from exc\n    if response.status_code != 200:\n        raise AuthError(\n            f\"xAI OIDC discovery returned status {response.status_code}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI OIDC discovery response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    authorization_endpoint = str(payload.get(\"authorization_endpoint\", \"\") or \"\").strip()\n    token_endpoint = str(payload.get(\"token_endpoint\", \"\") or \"\").strip()\n    if not authorization_endpoint or not token_endpoint:\n        raise AuthError(\n            \"xAI OIDC discovery response was missing required endpoints.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    _xai_validate_oauth_endpoint(authorization_endpoint, field=\"authorization_endpoint\")\n    _xai_validate_oauth_endpoint(token_endpoint, field=\"token_endpoint\")\n    return {\n        \"authorization_endpoint\": authorization_endpoint,\n        \"token_endpoint\": token_endpoint,\n    }\n\n\ndef refresh_xai_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    token_endpoint: str = \"\",\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    del access_token\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"xAI OAuth is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    endpoint = token_endpoint.strip() or _xai_oauth_discovery(timeout_seconds)[\"token_endpoint\"]\n    # Re-validate cached endpoints on the refresh hot path: an auth.json\n    # written by an older Clawbot (or hand-edited) may carry a non-xAI\n    # token_endpoint that would receive every future refresh_token in\n    # plaintext if we trusted it blindly. Cheap suffix check; fast-fail\n    # with a clear error so the user can re-run `clawbot model` to refetch.\n    _xai_validate_oauth_endpoint(endpoint, field=\"token_endpoint\")\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            endpoint,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": XAI_OAUTH_CLIENT_ID,\n                \"refresh_token\": refresh_token,\n            },\n        )\n    if response.status_code != 200:\n        detail = response.text.strip()\n        raise AuthError(\n            \"xAI token refresh failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_failed\",\n            relogin_required=(response.status_code in {400, 401, 403}),\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token refresh returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token refresh response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_response\",\n            relogin_required=True,\n        )\n    refreshed_access = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    if not refreshed_access:\n        raise AuthError(\n            \"xAI token refresh response was missing access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n    updated = {\n        \"access_token\": refreshed_access,\n        \"refresh_token\": str(payload.get(\"refresh_token\") or refresh_token).strip(),\n        \"id_token\": str(payload.get(\"id_token\") or \"\").strip(),\n        \"expires_in\": payload.get(\"expires_in\"),\n        \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    return updated\n\n\ndef _refresh_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    token_endpoint: str,\n    redirect_uri: str = \"\",\n    timeout_seconds: float,\n) -> Dict[str, Any]:\n    refreshed = refresh_xai_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        token_endpoint=token_endpoint,\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n    if refreshed.get(\"id_token\"):\n        updated_tokens[\"id_token\"] = refreshed[\"id_token\"]\n    if refreshed.get(\"expires_in\") is not None:\n        updated_tokens[\"expires_in\"] = refreshed[\"expires_in\"]\n    if refreshed.get(\"token_type\"):\n        updated_tokens[\"token_type\"] = refreshed[\"token_type\"]\n    _save_xai_oauth_tokens(\n        updated_tokens,\n        discovery={\"token_endpoint\": token_endpoint},\n        redirect_uri=redirect_uri,\n        last_refresh=refreshed[\"last_refresh\"],\n    )\n    return updated_tokens\n\n\ndef resolve_xai_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = XAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    data = _read_xai_oauth_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_XAI_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n    discovery = dict(data.get(\"discovery\") or {})\n    token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n    redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_xai_oauth_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n            discovery = dict(data.get(\"discovery\") or {})\n            token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n            redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n            if should_refresh:\n                if not token_endpoint:\n                    token_endpoint = _xai_oauth_discovery(refresh_timeout_seconds)[\"token_endpoint\"]\n                tokens = _refresh_xai_oauth_tokens(\n                    tokens,\n                    token_endpoint=token_endpoint,\n                    redirect_uri=redirect_uri,\n                    timeout_seconds=refresh_timeout_seconds,\n                )\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"provider\": \"xai-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"oauth_pkce\",\n    }\n\n\n# =============================================================================\n# TLS verification helper\n# =============================================================================\n\ndef _default_verify() -> bool | ssl.SSLContext:\n    \"\"\"Platform-aware default SSL verify for httpx clients.\n\n    On macOS with Homebrew Python, the system OpenSSL cannot locate the\n    system trust store and valid public certs fail verification. When\n    certifi is importable we pin its bundle explicitly; elsewhere we\n    defer to httpx's built-in default (certifi via its own dependency).\n    Mirrors the weixin fix in 3a0ec1d93.\n    \"\"\"\n    if sys.platform == \"darwin\":\n        try:\n            import certifi\n            return ssl.create_default_context(cafile=certifi.where())\n        except ImportError:\n            pass\n    return True\n\n\ndef _resolve_verify(\n    *,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    auth_state: Optional[Dict[str, Any]] = None,\n) -> bool | ssl.SSLContext:\n    tls_state = auth_state.get(\"tls\") if isinstance(auth_state, dict) else {}\n    tls_state = tls_state if isinstance(tls_state, dict) else {}\n\n    effective_insecure = (\n        is_truthy_value(insecure, default=False) if insecure is not None\n        else is_truthy_value(tls_state.get(\"insecure\", False), default=False)\n    )\n    effective_ca = (\n        ca_bundle\n        or tls_state.get(\"ca_bundle\")\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n        or os.getenv(\"REQUESTS_CA_BUNDLE\")\n    )\n\n    if effective_insecure:\n        return False\n    if effective_ca:\n        ca_path = str(effective_ca)\n        if not os.path.isfile(ca_path):\n            logger.warning(\n                \"CA bundle path does not exist: %s — falling back to default certificates\",\n                ca_path,\n            )\n            return _default_verify()\n        return ssl.create_default_context(cafile=ca_path)\n    return _default_verify()\n\n\n# =============================================================================\n# OAuth Device Code Flow — generic, parameterized by provider\n# =============================================================================\n\ndef _request_device_code(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: Optional[str],\n) -> Dict[str, Any]:\n    \"\"\"POST to the device code endpoint. Returns device_code, user_code, etc.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/device/code\",\n        data={\n            \"client_id\": client_id,\n            **({\"scope\": scope} if scope else {}),\n        },\n    )\n    response.raise_for_status()\n    data = response.json()\n\n    required_fields = [\n        \"device_code\", \"user_code\", \"verification_uri\",\n        \"verification_uri_complete\", \"expires_in\", \"interval\",\n    ]\n    missing = [f for f in required_fields if f not in data]\n    if missing:\n        raise ValueError(f\"Device code response missing fields: {', '.join(missing)}\")\n    return data\n\n\ndef _is_soam_invoke_scope_refusal(exc: Exception) -> bool:\n    if not isinstance(exc, httpx.HTTPStatusError):\n        return False\n    response = exc.response\n    if response.status_code not in {400, 401, 403}:\n        return False\n    try:\n        payload = response.json()\n    except Exception:\n        payload = {}\n    text = \" \".join(\n        str(value)\n        for value in (\n            payload.get(\"error\") if isinstance(payload, dict) else None,\n            payload.get(\"error_description\") if isinstance(payload, dict) else None,\n            response.text,\n        )\n        if value\n    ).lower()\n    if not text:\n        return False\n    return (\n        \"invalid_scope\" in text\n        or \"unsupported_scope\" in text\n        or \"scope\" in text and SOAM_INFERENCE_INVOKE_SCOPE in text\n    )\n\n\ndef _soam_device_scope_with_env_override(\n    requested_scope: Optional[str],\n    *,\n    default_scope: str = DEFAULT_SOAM_SCOPE,\n) -> Tuple[str, bool]:\n    explicit_scope = requested_scope is not None\n    scope = requested_scope or default_scope\n    if _soam_legacy_session_keys_forced():\n        scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n    return scope, explicit_scope\n\n\ndef _request_soam_device_code_with_scope_fallback(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: str,\n    allow_legacy_fallback: bool,\n) -> Tuple[Dict[str, Any], str]:\n    try:\n        return (\n            _request_device_code(\n                client=client,\n                portal_base_url=portal_base_url,\n                client_id=client_id,\n                scope=scope,\n            ),\n            scope,\n        )\n    except Exception as exc:\n        if (\n            allow_legacy_fallback\n            and _soam_scope_has_invoke(scope)\n            and _is_soam_invoke_scope_refusal(exc)\n        ):\n            logger.info(\"Soam inference auth: NAS refused invoke scope, retrying legacy scope\")\n            _oauth_trace(\"soam_device_code_invoke_scope_refused\")\n            retry_scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n            return (\n                _request_device_code(\n                    client=client,\n                    portal_base_url=portal_base_url,\n                    client_id=client_id,\n                    scope=retry_scope,\n                ),\n                retry_scope,\n            )\n        raise\n\n\ndef _poll_for_token(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    device_code: str,\n    expires_in: int,\n    poll_interval: int,\n) -> Dict[str, Any]:\n    \"\"\"Poll the token endpoint until the user approves or the code expires.\"\"\"\n    deadline = time.monotonic() + max(1, expires_in)\n    current_interval = max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n\n    while time.monotonic() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/api/oauth/token\",\n            data={\n                \"grant_type\": \"urn:ietf:params:oauth:grant-type:device_code\",\n                \"client_id\": client_id,\n                \"device_code\": device_code,\n            },\n        )\n\n        if response.status_code == 200:\n            payload = response.json()\n            if \"access_token\" not in payload:\n                raise ValueError(\"Token response did not include access_token\")\n            return payload\n\n        try:\n            error_payload = response.json()\n        except Exception:\n            response.raise_for_status()\n            raise RuntimeError(\"Token endpoint returned a non-JSON error response\")\n\n        error_code = error_payload.get(\"error\", \"\")\n        if error_code == \"authorization_pending\":\n            time.sleep(current_interval)\n            continue\n        if error_code == \"slow_down\":\n            current_interval = min(current_interval + 1, 30)\n            time.sleep(current_interval)\n            continue\n\n        description = error_payload.get(\"error_description\") or \"Unknown authentication error\"\n        raise RuntimeError(f\"{error_code}: {description}\")\n\n    raise TimeoutError(\"Timed out waiting for device authorization\")\n\n\n# =============================================================================\n# Soam Portal — token refresh, agent key minting, model discovery\n# =============================================================================\n\n# -----------------------------------------------------------------------------\n# Shared Soam token store — lets OAuth credentials persist across profiles\n# so a new `clawbot --profile <name> auth add soam --type oauth` can one-tap\n# import instead of running the full device-code flow every time.\n#\n# File lives at ${CLAWBOT_SHARED_AUTH_DIR}/soam_auth.json, defaulting to\n# ``<clawbot-root>/shared/soam_auth.json`` where ``<clawbot-root>`` is what\n# ``get_default_clawbot_root()`` returns — ``~/.clawbot`` on Linux/macOS,\n# ``%LOCALAPPDATA%\\clawbot`` on native Windows, or the Docker/custom root.\n# It is OUTSIDE any named profile's CLAWBOT_HOME so named profiles (which\n# typically live under ``<clawbot-root>/profiles/<name>/``) all see the\n# same file.\n#\n# Written on successful login and on every runtime refresh so the stored\n# refresh_token stays current even if one profile refreshes and rotates it.\n# If ever the stored refresh_token does go stale server-side, import fails\n# gracefully and the user falls back to the normal device-code flow.\n# -----------------------------------------------------------------------------\n\nSOAM_SHARED_STORE_FILENAME = \"soam_auth.json\"\n_soam_shared_lock_holder = threading.local()\n\n\ndef _soam_shared_auth_dir() -> Path:\n    \"\"\"Resolve the directory that holds the shared Soam token store.\n\n    Honors ``CLAWBOT_SHARED_AUTH_DIR`` so tests can redirect it to a tmp\n    path without touching the real user's home. Defaults to\n    ``<clawbot-root>/shared/``, where ``<clawbot-root>`` is what\n    :func:`clawbot_constants.get_default_clawbot_root` returns — so\n    Linux/macOS classic installs land at ``~/.clawbot/shared/``, native\n    Windows installs at ``%LOCALAPPDATA%\\\\clawbot\\\\shared\\\\``, and\n    Docker / custom ``CLAWBOT_HOME`` deployments at\n    ``<CLAWBOT_HOME>/shared/``. Sits outside any named profile so all\n    profiles under the same root share the store.\n    \"\"\"\n    override = os.getenv(\"CLAWBOT_SHARED_AUTH_DIR\", \"\").strip()\n    if override:\n        return Path(override).expanduser()\n    from clawbot_constants import get_default_clawbot_root\n    return get_default_clawbot_root() / \"shared\"\n\n\ndef _soam_shared_store_path() -> Path:\n    path = _soam_shared_auth_dir() / SOAM_SHARED_STORE_FILENAME\n    # Seat belt: if pytest is running and this resolves to a path under the\n    # real user's Clawbot root, refuse rather than silently corrupt cross-profile\n    # state. Tests must set CLAWBOT_SHARED_AUTH_DIR to a tmp_path (conftest\n    # does not do this automatically — mirror the _auth_file_path() guard\n    # so forgetting to set it fails loudly instead of writing to the real\n    # shared store).\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        from clawbot_constants import get_default_clawbot_root\n        real_home_shared = (\n            get_default_clawbot_root() / \"shared\" / SOAM_SHARED_STORE_FILENAME\n        ).resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_shared:\n            raise RuntimeError(\n                f\"Refusing to touch real user shared Soam auth store during test run: \"\n                f\"{path}. Set CLAWBOT_SHARED_AUTH_DIR to a tmp_path in your test fixture.\"\n            )\n    return path\n\n\n@contextmanager\ndef _soam_shared_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-profile lock for the shared Soam OAuth store.\n\n    Lock ordering invariant: if both this and ``_auth_store_lock`` need\n    to be held, acquire ``_auth_store_lock`` FIRST. All runtime refresh\n    paths follow this order. The one exception is\n    ``_try_import_shared_soam_state``, which holds this lock alone for\n    the entire refresh+mint cycle so concurrent imports on sibling\n    profiles can't race on the single-use shared refresh token; that\n    helper must NOT be called with ``_auth_store_lock`` already held.\n    \"\"\"\n    try:\n        lock_path = _soam_shared_store_path().with_suffix(\".lock\")\n    except RuntimeError:\n        # No CLAWBOT_HOME yet (pre-setup): fall through without locking.\n        yield\n        return\n\n    with _file_lock(\n        lock_path,\n        _soam_shared_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for shared Soam auth lock\",\n    ):\n        yield\n\n\ndef _merge_shared_soam_oauth_state(state: Dict[str, Any]) -> bool:\n    \"\"\"Copy fresher shared OAuth tokens into a profile-local Soam state.\"\"\"\n    shared = _read_shared_soam_state()\n    if not shared:\n        return False\n\n    shared_refresh = shared.get(\"refresh_token\")\n    if not isinstance(shared_refresh, str) or not shared_refresh.strip():\n        return False\n\n    local_refresh = state.get(\"refresh_token\")\n    shared_access_exp = _parse_iso_timestamp(shared.get(\"expires_at\")) or 0.0\n    local_access_exp = _parse_iso_timestamp(state.get(\"expires_at\")) or 0.0\n    refresh_changed = shared_refresh.strip() != str(local_refresh or \"\").strip()\n    fresher_access = shared_access_exp > local_access_exp\n    if not refresh_changed and not fresher_access:\n        return False\n\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"token_type\",\n        \"scope\",\n        \"client_id\",\n        \"portal_base_url\",\n        \"inference_base_url\",\n        \"obtained_at\",\n        \"expires_at\",\n    ):\n        value = shared.get(key)\n        if value not in {None, \"\"}:\n            state[key] = value\n    return True\n\n\ndef _write_shared_soam_state(state: Dict[str, Any]) -> None:\n    \"\"\"Persist a minimal copy of the Soam OAuth state to the shared store.\n\n    Best-effort: any failure is swallowed after logging. The shared store\n    is a convenience layer; the per-profile auth.json remains the source\n    of truth.\n\n    We deliberately omit the runtime ``agent_key`` compatibility field\n    (either an invoke JWT or legacy opaque session key) — only OAuth tokens\n    are cross-profile useful.\n    \"\"\"\n    refresh_token = state.get(\"refresh_token\")\n    access_token = state.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        # No refresh_token = nothing worth sharing across profiles\n        return\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return\n\n    shared = {\n        \"_schema\": 1,\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"token_type\": state.get(\"token_type\") or \"Bearer\",\n        \"scope\": state.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n        \"client_id\": state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": state.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n        \"inference_base_url\": state.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n        \"obtained_at\": state.get(\"obtained_at\"),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"updated_at\": datetime.now(timezone.utc).isoformat(),\n    }\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            path.parent.mkdir(parents=True, exist_ok=True)\n            try:\n                os.chmod(path.parent, 0o700)\n            except OSError:\n                pass\n            tmp = path.with_name(f\"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n            # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n            # window where write_text() + post-write chmod briefly exposed Soam\n            # refresh_token at process umask. See #19673, #21148.\n            fd = os.open(\n                str(tmp),\n                os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n                stat.S_IRUSR | stat.S_IWUSR,\n            )\n            try:\n                with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n                    fh.write(json.dumps(shared, indent=2, sort_keys=True))\n                    fh.flush()\n                    os.fsync(fh.fileno())\n                os.replace(tmp, path)\n            finally:\n                try:\n                    if tmp.exists():\n                        tmp.unlink()\n                except OSError:\n                    pass\n        _oauth_trace(\n            \"soam_shared_store_written\",\n            path=str(path),\n            refresh_token_fp=_token_fingerprint(refresh_token),\n        )\n    except Exception as exc:\n        logger.debug(\"Failed to write shared Soam auth store: %s\", exc)\n\n\ndef _read_shared_soam_state() -> Optional[Dict[str, Any]]:\n    \"\"\"Return the shared Soam OAuth state if present and well-formed.\n\n    Returns ``None`` when the file is missing, unreadable, malformed, or\n    lacks required fields. Callers should treat ``None`` as \"no shared\n    credentials available — fall through to device-code\".\n    \"\"\"\n    try:\n        path = _soam_shared_store_path()\n    except RuntimeError:\n        # Test seat belt tripped — treat as missing\n        return None\n    if not path.is_file():\n        return None\n    try:\n        payload = json.loads(path.read_text())\n    except (OSError, ValueError) as exc:\n        logger.debug(\"Shared Soam auth store at %s is unreadable: %s\", path, exc)\n        return None\n    if not isinstance(payload, dict):\n        return None\n    refresh_token = payload.get(\"refresh_token\")\n    access_token = payload.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        return None\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return None\n    return payload\n\n\ndef _clear_shared_soam_state(reason: str) -> None:\n    \"\"\"Remove the shared Soam OAuth store after a terminal token failure.\"\"\"\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            try:\n                path.unlink()\n            except FileNotFoundError:\n                pass\n        _oauth_trace(\"soam_shared_store_cleared\", reason=reason)\n    except Exception as exc:\n        logger.debug(\"Failed to clear shared Soam auth store: %s\", exc)\n\n\ndef _is_terminal_soam_refresh_error(exc: Exception) -> bool:\n    \"\"\"True when retrying the same Soam refresh token cannot succeed.\"\"\"\n    return (\n        isinstance(exc, AuthError)\n        and exc.provider == \"soam\"\n        and exc.code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n        and bool(exc.relogin_required)\n    )\n\n\ndef _quarantine_soam_oauth_state(\n    state: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> None:\n    \"\"\"Keep routing metadata but remove dead OAuth material so it is not replayed.\"\"\"\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"expires_at\",\n        \"expires_in\",\n        \"obtained_at\",\n        \"agent_key\",\n        \"agent_key_id\",\n        \"agent_key_expires_at\",\n        \"agent_key_expires_in\",\n        \"agent_key_reused\",\n        \"agent_key_obtained_at\",\n    ):\n        state.pop(key, None)\n    state[\"last_auth_error\"] = {\n        \"provider\": \"soam\",\n        \"code\": error.code,\n        \"message\": str(error),\n        \"reason\": reason,\n        \"relogin_required\": True,\n        \"at\": datetime.now(timezone.utc).isoformat(),\n    }\n    _clear_shared_soam_state(reason)\n    invalidate_soam_auth_status_cache()\n\n\ndef _quarantine_soam_pool_entries(\n    auth_store: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> bool:\n    \"\"\"Remove singleton-seeded Soam pool entries that contain dead OAuth state.\"\"\"\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        return False\n    entries = pool.get(\"soam\")\n    if not isinstance(entries, list):\n        return False\n\n    retained = []\n    removed = False\n    singleton_sources = {SOAM_DEVICE_CODE_SOURCE, f\"manual:{SOAM_DEVICE_CODE_SOURCE}\"}\n    for entry in entries:\n        if isinstance(entry, dict) and entry.get(\"source\") in singleton_sources:\n            removed = True\n            continue\n        retained.append(entry)\n\n    if removed:\n        pool[\"soam\"] = retained\n        _oauth_trace(\n            \"soam_pool_device_code_quarantined\",\n            reason=reason,\n            error_code=error.code,\n        )\n    return removed\n\n\ndef _try_import_shared_soam_state(\n    *,\n    timeout_seconds: float = 15.0,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Optional[Dict[str, Any]]:\n    \"\"\"Attempt to rehydrate Soam OAuth state from the shared store.\n\n    Reads the shared file (if present), runs a forced refresh+mint using\n    the stored refresh_token to produce a fresh access_token + agent_key\n    scoped to this profile, and returns the full auth_state dict ready\n    for ``persist_soam_credentials()``.\n\n    Returns ``None`` when no shared state is available or the rehydrate\n    fails for any reason (expired refresh_token, portal unreachable,\n    etc.) — caller should then fall through to the normal device-code\n    flow.\n    \"\"\"\n    try:\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            shared = _read_shared_soam_state()\n            if not shared:\n                return None\n\n            # Build a full state dict so refresh_soam_oauth_from_state has every\n            # field it needs. force_refresh=True gets us a fresh access_token\n            # for this profile; fresh auth mode avoids stale cached legacy keys.\n            state: Dict[str, Any] = {\n                \"access_token\": shared.get(\"access_token\"),\n                \"refresh_token\": shared.get(\"refresh_token\"),\n                \"client_id\": shared.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n                \"portal_base_url\": shared.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n                \"inference_base_url\": shared.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n                \"token_type\": shared.get(\"token_type\") or \"Bearer\",\n                \"scope\": shared.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n                \"obtained_at\": shared.get(\"obtained_at\"),\n                \"expires_at\": shared.get(\"expires_at\"),\n                \"agent_key\": None,\n                \"agent_key_expires_at\": None,\n                \"tls\": {\"insecure\": False, \"ca_bundle\": None},\n            }\n\n            def _persist_shared_refresh(updated_state: Dict[str, Any], _reason: str) -> None:\n                _write_shared_soam_state(updated_state)\n\n            refreshed = refresh_soam_oauth_from_state(\n                state,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                timeout_seconds=timeout_seconds,\n                force_refresh=True,\n                inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n                on_state_update=_persist_shared_refresh,\n            )\n            _write_shared_soam_state(refreshed)\n    except AuthError as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n            error_code=getattr(exc, \"code\", None),\n        )\n        if _is_terminal_soam_refresh_error(exc):\n            _clear_shared_soam_state(\"shared_import_terminal_refresh_failure\")\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n    except Exception as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n        )\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n\n    return refreshed\n\n\ndef _refresh_access_token(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    refresh_token: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/token\",\n        headers={\"x-soam-refresh-token\": refresh_token},\n        data={\n            \"grant_type\": \"refresh_token\",\n            \"client_id\": client_id,\n        },\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"access_token\" not in payload:\n            raise AuthError(\"Refresh response missing access_token\",\n                            provider=\"soam\", code=\"invalid_token\", relogin_required=True)\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Refresh token exchange failed\",\n                        provider=\"soam\", relogin_required=True) from exc\n\n    code = str(error_payload.get(\"error\", \"invalid_grant\"))\n    description = str(error_payload.get(\"error_description\") or \"Refresh token exchange failed\")\n    relogin = code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n\n    # Detect the OAuth 2.1 \"refresh token reuse\" signal from the Soam portal\n    # server and surface an actionable message.  This fires when an external\n    # process (health-check script, monitoring tool, custom self-heal hook)\n    # called POST /api/oauth/token with Clawbot's refresh_token without\n    # persisting the rotated token back to auth.json — the server then\n    # retires the original RT, Clawbot's next refresh uses it, and the whole\n    # session chain gets revoked as a token-theft signal (#15099).\n    lowered = description.lower()\n    if code == \"refresh_token_reused\" or \"reuse\" in lowered or \"reuse detected\" in lowered:\n        description = (\n            \"Soam Portal detected refresh-token reuse and revoked this session.\\n\"\n            \"This usually means an external process (monitoring script, \"\n            \"custom self-heal hook, or another Clawbot install sharing \"\n            \"~/.clawbot/auth.json) called POST /api/oauth/token with Clawbot's \"\n            \"refresh token without persisting the rotated token back.\\n\"\n            \"Soam refresh tokens are single-use — only Clawbot may call the \"\n            \"refresh endpoint. For health checks, use `clawbot auth status` \"\n            \"instead.\\n\"\n            \"Re-authenticate with: clawbot auth add soam\"\n        )\n        relogin = True\n\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef _mint_agent_key(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    access_token: str,\n    min_ttl_seconds: int,\n) -> Dict[str, Any]:\n    \"\"\"Mint (or reuse) a short-lived inference API key.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/agent-key\",\n        headers={\"Authorization\": f\"Bearer {access_token}\"},\n        json={\"min_ttl_seconds\": max(60, int(min_ttl_seconds))},\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"api_key\" not in payload:\n            raise AuthError(\"Mint response missing api_key\",\n                            provider=\"soam\", code=\"server_error\")\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Agent key mint request failed\",\n                        provider=\"soam\", code=\"server_error\") from exc\n\n    code = str(error_payload.get(\"error\", \"server_error\"))\n    description = str(error_payload.get(\"error_description\") or \"Agent key mint request failed\")\n    relogin = code in {\"invalid_token\", \"invalid_grant\"}\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef fetch_soam_models(\n    *,\n    inference_base_url: str,\n    api_key: str,\n    timeout_seconds: float = 15.0,\n    verify: bool | str = True,\n) -> List[str]:\n    \"\"\"Fetch available model IDs from the Soam inference API.\"\"\"\n    timeout = httpx.Timeout(timeout_seconds)\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        response = client.get(\n            f\"{inference_base_url.rstrip('/')}/models\",\n            headers={\"Authorization\": f\"Bearer {api_key}\"},\n        )\n\n    if response.status_code != 200:\n        description = f\"/models request failed with status {response.status_code}\"\n        try:\n            err = response.json()\n            description = str(err.get(\"error_description\") or err.get(\"error\") or description)\n        except Exception as e:\n            logger.debug(\"Could not parse error response JSON: %s\", e)\n        raise AuthError(description, provider=\"soam\", code=\"models_fetch_failed\")\n\n    payload = response.json()\n    data = payload.get(\"data\")\n    if not isinstance(data, list):\n        return []\n\n    model_ids: List[str] = []\n    for item in data:\n        if not isinstance(item, dict):\n            continue\n        model_id = item.get(\"id\")\n        if isinstance(model_id, str) and model_id.strip():\n            mid = model_id.strip()\n            # Skip Clawbot models — they're not reliable for agentic tool-calling\n            if \"clawbot\" in mid.lower():\n                continue\n            model_ids.append(mid)\n\n    # Sort: prefer opus > pro > haiku/flash > sonnet (sonnet is cheap/fast,\n    # users who want the best model should see opus first).\n    def _model_priority(mid: str) -> tuple:\n        low = mid.lower()\n        if \"opus\" in low:\n            return (0, mid)\n        if \"pro\" in low and \"sonnet\" not in low:\n            return (1, mid)\n        if \"sonnet\" in low:\n            return (3, mid)\n        return (2, mid)\n\n    model_ids.sort(key=_model_priority)\n    return list(dict.fromkeys(model_ids))\n\n\ndef _agent_key_is_usable(state: Dict[str, Any], min_ttl_seconds: int) -> bool:\n    key = state.get(\"agent_key\")\n    if not isinstance(key, str) or not key.strip():\n        return False\n    if _decode_jwt_claims(key):\n        if _soam_legacy_session_keys_forced():\n            return False\n        return _soam_invoke_jwt_is_usable(\n            key,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"agent_key_expires_at\"),\n        )\n    return not _is_expiring(state.get(\"agent_key_expires_at\"), min_ttl_seconds)\n\n\ndef resolve_soam_access_token(\n    *,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    refresh_skew_seconds: int = ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> str:\n    \"\"\"Resolve a refresh-aware Soam Portal access token for managed tool gateways.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\n                \"Clawbot is not logged into Soam Portal.\",\n                provider=\"soam\",\n                relogin_required=True,\n            )\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            merged_shared = _merge_shared_soam_oauth_state(state)\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\n                    \"No access token found for Soam Portal login.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            if not _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds):\n                if merged_shared:\n                    _save_provider_state(auth_store, \"soam\", state)\n                    _save_auth_store(auth_store)\n                return access_token\n\n            if not isinstance(refresh_token, str) or not refresh_token:\n                raise AuthError(\n                    \"Session expired and no refresh token is available.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n            with httpx.Client(\n                timeout=timeout,\n                headers={\"Accept\": \"application/json\"},\n                verify=verify,\n            ) as client:\n                try:\n                    refreshed = _refresh_access_token(\n                        client=client,\n                        portal_base_url=portal_base_url,\n                        client_id=client_id,\n                        refresh_token=refresh_token,\n                    )\n                except AuthError as exc:\n                    if _is_terminal_soam_refresh_error(exc):\n                        _quarantine_soam_oauth_state(\n                            state,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _quarantine_soam_pool_entries(\n                            auth_store,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _save_provider_state(auth_store, \"soam\", state)\n                        _save_auth_store(auth_store)\n                    raise\n\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl,\n                tz=timezone.utc,\n            ).isoformat()\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n            _save_provider_state(auth_store, \"soam\", state)\n            _save_auth_store(auth_store)\n            _write_shared_soam_state(state)\n            return state[\"access_token\"]\n\n\ndef refresh_soam_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    client_id: str,\n    portal_base_url: str,\n    inference_base_url: str,\n    *,\n    token_type: str = \"Bearer\",\n    scope: str = DEFAULT_SOAM_SCOPE,\n    obtained_at: Optional[str] = None,\n    expires_at: Optional[str] = None,\n    agent_key: Optional[str] = None,\n    agent_key_expires_at: Optional[str] = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth state without mutating auth.json directly.\n\n    ``on_state_update`` is called after a successful access-token refresh and\n    before any subsequent agent-key mint. Callers that own persistent state can\n    use it to save the newly rotated refresh token before later work can fail.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    state: Dict[str, Any] = {\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"client_id\": client_id or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": (portal_base_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\"),\n        \"inference_base_url\": (inference_base_url or DEFAULT_SOAM_INFERENCE_URL).rstrip(\"/\"),\n        \"token_type\": token_type or \"Bearer\",\n        \"scope\": scope or DEFAULT_SOAM_SCOPE,\n        \"obtained_at\": obtained_at,\n        \"expires_at\": expires_at,\n        \"agent_key\": agent_key,\n        \"agent_key_expires_at\": agent_key_expires_at,\n        \"tls\": {\n            \"insecure\": bool(insecure),\n            \"ca_bundle\": ca_bundle,\n        },\n    }\n    verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n    timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        min_agent_key_ttl = max(60, int(min_key_ttl_seconds))\n        legacy_session_keys = _soam_legacy_session_keys_forced()\n        current_invoke_jwt_usable = (\n            not legacy_session_keys\n            and _soam_invoke_jwt_is_usable(\n                state.get(\"access_token\"),\n                scope=state.get(\"scope\"),\n                expires_at=state.get(\"expires_at\"),\n            )\n        )\n        if (\n            force_refresh\n            or (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            )\n        ):\n            refreshed = _refresh_access_token(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                client_id=state[\"client_id\"],\n                refresh_token=state[\"refresh_token\"],\n            )\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or state[\"refresh_token\"]\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n            if refreshed_url:\n                state[\"inference_base_url\"] = refreshed_url\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl, tz=timezone.utc\n            ).isoformat()\n            if on_state_update is not None:\n                on_state_update(dict(state), \"post_refresh_access_token\")\n\n        selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n            state,\n            min_key_ttl_seconds=min_agent_key_ttl,\n            inference_auth_mode=inference_auth_mode,\n        )\n        if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n            _select_soam_invoke_jwt(state)\n        elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT:\n            _log_soam_legacy_session_key_selected(\n                fallback_reason or \"legacy_session_key_required\",\n                access_token=state.get(\"access_token\"),\n            )\n            mint_payload = _mint_agent_key(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                access_token=state[\"access_token\"],\n                min_ttl_seconds=min_key_ttl_seconds,\n            )\n            now = datetime.now(timezone.utc)\n            state[\"agent_key\"] = mint_payload.get(\"api_key\")\n            state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n            state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n            state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n            state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n            state[\"agent_key_obtained_at\"] = now.isoformat()\n            minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n            if minted_url:\n                state[\"inference_base_url\"] = minted_url\n\n    return state\n\n\ndef refresh_soam_oauth_from_state(\n    state: Dict[str, Any],\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth from a state dict. Thin wrapper around refresh_soam_oauth_pure.\"\"\"\n    tls = state.get(\"tls\") or {}\n    return refresh_soam_oauth_pure(\n        state.get(\"access_token\", \"\"),\n        state.get(\"refresh_token\", \"\"),\n        state.get(\"client_id\", \"clawbot-cli\"),\n        state.get(\"portal_base_url\", DEFAULT_SOAM_PORTAL_URL),\n        state.get(\"inference_base_url\", DEFAULT_SOAM_INFERENCE_URL),\n        token_type=state.get(\"token_type\", \"Bearer\"),\n        scope=state.get(\"scope\", DEFAULT_SOAM_SCOPE),\n        obtained_at=state.get(\"obtained_at\"),\n        expires_at=state.get(\"expires_at\"),\n        agent_key=state.get(\"agent_key\"),\n        agent_key_expires_at=state.get(\"agent_key_expires_at\"),\n        min_key_ttl_seconds=min_key_ttl_seconds,\n        timeout_seconds=timeout_seconds,\n        insecure=tls.get(\"insecure\"),\n        ca_bundle=tls.get(\"ca_bundle\"),\n        force_refresh=force_refresh,\n        inference_auth_mode=inference_auth_mode,\n        on_state_update=on_state_update,\n    )\n\n\ndef persist_soam_credentials(\n    creds: Dict[str, Any],\n    *,\n    label: Optional[str] = None,\n):\n    \"\"\"Persist minted Soam OAuth credentials as the singleton provider state\n    and ensure the credential pool is in sync.\n\n    Soam credentials are read at runtime from two independent locations:\n\n    - ``providers.soam``: singleton state read by\n      ``resolve_soam_runtime_credentials()`` during 401 recovery and by\n      ``_seed_from_singletons()`` during pool load.\n    - ``credential_pool.soam``: used by the runtime ``pool.select()`` path.\n\n    Historically ``clawbot auth add soam`` wrote a ``manual:device_code`` pool\n    entry only, skipping ``providers.soam``.  When the 24h agent_key TTL\n    expired, the recovery path read the empty singleton state and raised\n    ``AuthError`` silently (``logger.debug`` at INFO level).\n\n    This helper writes ``providers.soam`` then calls ``load_pool(\"soam\")`` so\n    ``_seed_from_singletons`` materialises the canonical ``device_code`` pool\n    entry from the singleton.  Re-running login upserts the same entry in\n    place; the pool never accumulates duplicate device_code rows.\n\n    ``label`` is an optional user-chosen display name (from\n    ``clawbot auth add soam --label <name>``).  It gets embedded in the\n    singleton state so that ``_seed_from_singletons`` uses it as the pool\n    entry's label on every subsequent ``load_pool(\"soam\")`` instead of the\n    auto-derived token fingerprint.  When ``None``, the auto-derived label\n    via ``label_from_token`` is used (unchanged default behaviour).\n\n    Returns the upserted :class:`PooledCredential` entry (or ``None`` if\n    seeding somehow produced no match — shouldn't happen).\n    \"\"\"\n    from agent.credential_pool import load_pool\n\n    state = dict(creds)\n    if label and str(label).strip():\n        state[\"label\"] = str(label).strip()\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"soam\", state)\n        _save_auth_store(auth_store)\n\n    # Mirror to the shared store so a new profile can one-tap import\n    # these credentials via `clawbot auth add soam --type oauth`. Best-\n    # effort: any I/O failure is logged and swallowed (the per-profile\n    # auth.json is still the source of truth).\n    _write_shared_soam_state(state)\n\n    pool = load_pool(\"soam\")\n    return next(\n        (e for e in pool.entries() if e.source == SOAM_DEVICE_CODE_SOURCE),\n        None,\n    )\n\n\ndef _sync_soam_pool_from_auth_store() -> None:\n    \"\"\"Best-effort pool reseed after providers.soam changes; never fail login.\"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        load_pool(\"soam\")\n    except Exception as exc:\n        logger.debug(\"Failed to sync Soam credential pool from auth store: %s\", exc)\n\n\ndef resolve_soam_runtime_credentials(\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Dict[str, Any]:\n    \"\"\"\n    Resolve Soam inference credentials for runtime use.\n\n    Ensures access_token is valid (refreshes if needed) and a short-lived\n    inference key is present with minimum TTL (mints/reuses as needed).\n    Concurrent processes coordinate through the auth store file lock.\n\n    Returns dict with: provider, base_url, api_key, key_id, expires_at,\n    expires_in, source (\"invoke_jwt\", \"cache\", or \"portal\"), and auth_path.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    min_key_ttl_seconds = max(60, int(min_key_ttl_seconds))\n    sequence_id = uuid.uuid4().hex[:12]\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\"Clawbot is not logged into Soam Portal.\",\n                            provider=\"soam\", relogin_required=True)\n\n        persisted_state = dict(state)\n        state_persisted = False\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        inference_base_url = (\n            _optional_base_url(state.get(\"inference_base_url\"))\n            or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n            or DEFAULT_SOAM_INFERENCE_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n\n        def _persist_state(reason: str) -> None:\n            nonlocal persisted_state, state_persisted\n            # Skip writes where only derived TTL countdowns changed; this keeps\n            # the mtime-keyed Soam auth-status cache warm during read paths.\n            if (\n                _soam_effective_provider_state(state)\n                == _soam_effective_provider_state(persisted_state)\n            ):\n                _oauth_trace(\n                    \"soam_state_persist_skipped\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                )\n                return\n            try:\n                _save_provider_state(auth_store, \"soam\", state)\n                _save_auth_store(auth_store)\n            except Exception as exc:\n                _oauth_trace(\n                    \"soam_state_persist_failed\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                    error_type=type(exc).__name__,\n                )\n                raise\n            _oauth_trace(\n                \"soam_state_persisted\",\n                sequence_id=sequence_id,\n                reason=reason,\n                refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n                access_token_fp=_token_fingerprint(state.get(\"access_token\")),\n            )\n            persisted_state = dict(state)\n            state_persisted = True\n            # Mirror post-refresh state to the shared store so sibling\n            # profiles don't hold stale refresh_tokens after rotation.\n            # Best-effort — any failure is logged and swallowed inside\n            # _write_shared_soam_state.\n            _write_shared_soam_state(state)\n\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n        timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n        _oauth_trace(\n            \"soam_runtime_credentials_start\",\n            sequence_id=sequence_id,\n            inference_auth_mode=inference_auth_mode,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n        )\n\n        with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\"No access token found for Soam Portal login.\",\n                                provider=\"soam\", relogin_required=True)\n\n            # Step 1: refresh access token if expiring. If the access token\n            # is already a valid invoke JWT, trust its own exp claim even when\n            # older auth.json metadata has a stale/missing expires_at.\n            current_invoke_jwt_usable = (\n                not _soam_legacy_session_keys_forced()\n                and _soam_invoke_jwt_is_usable(\n                    access_token,\n                    scope=state.get(\"scope\"),\n                    expires_at=state.get(\"expires_at\"),\n                )\n            )\n            if (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            ):\n                with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                    if _merge_shared_soam_oauth_state(state):\n                        access_token = state.get(\"access_token\")\n                        refresh_token = state.get(\"refresh_token\")\n                        _persist_state(\"post_shared_merge_access_expiring\")\n\n                    if (\n                        _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                        and not _soam_invoke_jwt_is_usable(\n                            access_token,\n                            scope=state.get(\"scope\"),\n                            expires_at=state.get(\"expires_at\"),\n                        )\n                    ):\n                        if not isinstance(refresh_token, str) or not refresh_token:\n                            raise AuthError(\"Session expired and no refresh token is available.\",\n                                            provider=\"soam\", relogin_required=True)\n\n                        _oauth_trace(\n                            \"refresh_start\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        try:\n                            refreshed = _refresh_access_token(\n                                client=client, portal_base_url=portal_base_url,\n                                client_id=client_id, refresh_token=refresh_token,\n                            )\n                        except AuthError as exc:\n                            if _is_terminal_soam_refresh_error(exc):\n                                _quarantine_soam_oauth_state(\n                                    state,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _quarantine_soam_pool_entries(\n                                    auth_store,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _persist_state(\"terminal_runtime_access_refresh_failure\")\n                            raise\n                        now = datetime.now(timezone.utc)\n                        access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                        previous_refresh_token = refresh_token\n                        state[\"access_token\"] = refreshed[\"access_token\"]\n                        state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n                        state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                        state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                        refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                        if refreshed_url:\n                            inference_base_url = refreshed_url\n                        state[\"obtained_at\"] = now.isoformat()\n                        state[\"expires_in\"] = access_ttl\n                        state[\"expires_at\"] = datetime.fromtimestamp(\n                            now.timestamp() + access_ttl, tz=timezone.utc\n                        ).isoformat()\n                        access_token = state[\"access_token\"]\n                        refresh_token = state[\"refresh_token\"]\n                        _oauth_trace(\n                            \"refresh_success\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            previous_refresh_token_fp=_token_fingerprint(previous_refresh_token),\n                            new_refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        # Persist immediately so downstream mint failures cannot drop rotated refresh tokens.\n                        _persist_state(\"post_refresh_access_expiring\")\n\n            # Step 2: resolve the compatibility ``agent_key`` field. Preferred\n            # path stores the NAS invoke JWT there; legacy path mints/reuses\n            # the opaque session key.\n            used_cached_key = False\n            mint_payload: Optional[Dict[str, Any]] = None\n            selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n                state,\n                access_token=access_token,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                inference_auth_mode=inference_auth_mode,\n            )\n\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                _select_soam_invoke_jwt(\n                    state,\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n            elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE:\n                used_cached_key = True\n                logger.info(\"Soam inference auth: using cached agent_key\")\n                _oauth_trace(\"agent_key_reuse\", sequence_id=sequence_id)\n            else:\n                _log_soam_legacy_session_key_selected(\n                    fallback_reason or \"legacy_session_key_required\",\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n                try:\n                    _oauth_trace(\n                        \"mint_start\",\n                        sequence_id=sequence_id,\n                        access_token_fp=_token_fingerprint(access_token),\n                    )\n                    mint_payload = _mint_agent_key(\n                        client=client, portal_base_url=portal_base_url,\n                        access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                    )\n                except AuthError as exc:\n                    _oauth_trace(\n                        \"mint_error\",\n                        sequence_id=sequence_id,\n                        code=exc.code,\n                    )\n                    # Retry path: access token may be stale server-side despite local checks\n                    latest_refresh_token = state.get(\"refresh_token\")\n                    if (\n                        exc.code in {\"invalid_token\", \"invalid_grant\"}\n                        and isinstance(latest_refresh_token, str)\n                        and latest_refresh_token\n                    ):\n                        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                            if _merge_shared_soam_oauth_state(state):\n                                access_token = state.get(\"access_token\")\n                                latest_refresh_token = state.get(\"refresh_token\")\n                                _persist_state(\"post_shared_merge_mint_retry\")\n                            else:\n                                _oauth_trace(\n                                    \"refresh_start\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                )\n                                try:\n                                    refreshed = _refresh_access_token(\n                                        client=client, portal_base_url=portal_base_url,\n                                        client_id=client_id, refresh_token=latest_refresh_token,\n                                    )\n                                except AuthError as exc:\n                                    if _is_terminal_soam_refresh_error(exc):\n                                        _quarantine_soam_oauth_state(\n                                            state,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _quarantine_soam_pool_entries(\n                                            auth_store,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _persist_state(\"terminal_runtime_mint_retry_refresh_failure\")\n                                    raise\n                                now = datetime.now(timezone.utc)\n                                access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                                state[\"access_token\"] = refreshed[\"access_token\"]\n                                state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or latest_refresh_token\n                                state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                                state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                                refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                                if refreshed_url:\n                                    inference_base_url = refreshed_url\n                                state[\"obtained_at\"] = now.isoformat()\n                                state[\"expires_in\"] = access_ttl\n                                state[\"expires_at\"] = datetime.fromtimestamp(\n                                    now.timestamp() + access_ttl, tz=timezone.utc\n                                ).isoformat()\n                                access_token = state[\"access_token\"]\n                                refresh_token = state[\"refresh_token\"]\n                                _oauth_trace(\n                                    \"refresh_success\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    previous_refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                    new_refresh_token_fp=_token_fingerprint(refresh_token),\n                                )\n                                # Persist retry refresh immediately for crash safety and cross-process visibility.\n                                _persist_state(\"post_refresh_mint_retry\")\n\n                        retry_inference_auth_mode = (\n                            SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            else SOAM_INFERENCE_AUTH_MODE_FRESH\n                        )\n                        retry_auth_path, _ = _choose_soam_inference_auth_path(\n                            state,\n                            access_token=access_token,\n                            min_key_ttl_seconds=min_key_ttl_seconds,\n                            inference_auth_mode=retry_inference_auth_mode,\n                        )\n                        if retry_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                            mint_payload = None\n                            selected_auth_path = SOAM_AUTH_PATH_INVOKE_JWT\n                            _select_soam_invoke_jwt(\n                                state,\n                                access_token=access_token,\n                                sequence_id=sequence_id,\n                            )\n                        else:\n                            mint_payload = _mint_agent_key(\n                                client=client, portal_base_url=portal_base_url,\n                                access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                            )\n                    else:\n                        raise\n\n            if mint_payload is not None:\n                now = datetime.now(timezone.utc)\n                state[\"agent_key\"] = mint_payload.get(\"api_key\")\n                state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n                state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n                state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n                state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n                state[\"agent_key_obtained_at\"] = now.isoformat()\n                minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n                if minted_url:\n                    inference_base_url = minted_url\n                _oauth_trace(\n                    \"mint_success\",\n                    sequence_id=sequence_id,\n                    reused=bool(mint_payload.get(\"reused\", False)),\n                )\n\n            # Persist routing and TLS metadata for non-interactive refresh/mint\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"inference_base_url\"] = inference_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n\n        _persist_state(\"resolve_soam_runtime_credentials_final\")\n\n    if state_persisted:\n        _sync_soam_pool_from_auth_store()\n\n    api_key = state.get(\"agent_key\")\n    if not isinstance(api_key, str) or not api_key:\n        raise AuthError(\"Failed to resolve a Soam inference API key\",\n                        provider=\"soam\", code=\"server_error\")\n\n    expires_at = state.get(\"agent_key_expires_at\")\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"agent_key_expires_in\"))\n    )\n\n    return {\n        \"provider\": \"soam\",\n        \"base_url\": inference_base_url,\n        \"api_key\": api_key,\n        \"key_id\": state.get(\"agent_key_id\"),\n        \"expires_at\": expires_at,\n        \"expires_in\": expires_in,\n        \"source\": (\n            SOAM_AUTH_PATH_INVOKE_JWT\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT\n            else (\"cache\" if used_cached_key else \"portal\")\n        ),\n        \"auth_path\": selected_auth_path,\n    }\n\n\n# =============================================================================\n# Status helpers\n# =============================================================================\n\ndef _empty_soam_auth_status() -> Dict[str, Any]:\n    return {\n        \"logged_in\": False,\n        \"portal_base_url\": None,\n        \"inference_base_url\": None,\n        \"access_expires_at\": None,\n        \"agent_key_expires_at\": None,\n        \"has_refresh_token\": False,\n    }\n\n\ndef _snapshot_soam_pool_status() -> Dict[str, Any]:\n    \"\"\"Best-effort status from the credential pool.\n\n    This is a fallback only. The auth-store provider state is the runtime source\n    of truth because it is what ``resolve_soam_runtime_credentials()`` refreshes\n    and mints against.\n    \"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"soam\")\n        if not pool or not pool.has_credentials():\n            return _empty_soam_auth_status()\n\n        entries = list(pool.entries())\n        if not entries:\n            return _empty_soam_auth_status()\n\n        def _entry_sort_key(entry: Any) -> tuple[float, float, int]:\n            agent_exp = _parse_iso_timestamp(getattr(entry, \"agent_key_expires_at\", None)) or 0.0\n            access_exp = _parse_iso_timestamp(getattr(entry, \"expires_at\", None)) or 0.0\n            priority = int(getattr(entry, \"priority\", 0) or 0)\n            return (agent_exp, access_exp, -priority)\n\n        entry = max(entries, key=_entry_sort_key)\n        access_token = (\n            getattr(entry, \"access_token\", None)\n            or getattr(entry, \"runtime_api_key\", \"\")\n        )\n        if not access_token:\n            return _empty_soam_auth_status()\n\n        return {\n            \"logged_in\": True,\n            \"portal_base_url\": getattr(entry, \"portal_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"inference_base_url\": getattr(entry, \"inference_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"access_token\": access_token,\n            \"access_expires_at\": getattr(entry, \"expires_at\", None),\n            \"agent_key_expires_at\": getattr(entry, \"agent_key_expires_at\", None),\n            \"has_refresh_token\": bool(getattr(entry, \"refresh_token\", None)),\n            \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n        }\n    except Exception:\n        return _empty_soam_auth_status()\n\n\n# ── Process-level memo for get_soam_auth_status() ──\n# get_soam_auth_status() validates state by calling resolve_soam_runtime_credentials(),\n# which does a synchrosoam OAuth refresh POST to portal.aayushsoam.com. That can take\n# ~350ms even on the failure path, and read-only UI surfaces (`clawbot tools`, status panels,\n# subscription-feature checks) call it many times per render — `clawbot tools` → \"All Platforms\"\n# was firing the refresh ~31× during one menu paint, racking up >13s of HTTP and burning\n# single-use refresh tokens. Cache the snapshot for a few seconds, keyed on the auth.json\n# mtime so that `clawbot auth login/logout/add/remove` invalidate naturally on the next call.\n_SOAM_AUTH_STATUS_CACHE_TTL = 15.0  # seconds\n_soam_auth_status_cache: Optional[Tuple[float, Optional[float], Dict[str, Any]]] = None\n\n\ndef _auth_file_mtime() -> Optional[float]:\n    try:\n        return _auth_file_path().stat().st_mtime\n    except FileNotFoundError:\n        return None\n    except Exception:\n        return None\n\n\ndef invalidate_soam_auth_status_cache() -> None:\n    \"\"\"Clear the get_soam_auth_status() process-level memo.\n\n    Call this from any code path that mutates Soam auth state without going\n    through resolve_soam_runtime_credentials() (e.g. tests). Login/logout\n    flows touch auth.json, so the mtime check below invalidates them\n    automatically — explicit invalidation is the belt-and-braces option.\n    \"\"\"\n    global _soam_auth_status_cache\n    _soam_auth_status_cache = None\n\n\ndef get_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Soam auth.\n\n    Prefer the auth-store provider state, because that is the live source of\n    truth for refresh + mint operations. When provider state exists, validate it\n    by resolving runtime credentials so revoked refresh sessions do not show up\n    as a healthy login. If provider state is absent, fall back to the credential\n    pool for the just-logged-in / not-yet-promoted case.\n\n    The returned snapshot is memoised for ~15s keyed on the auth.json mtime,\n    so menu/status surfaces that ask repeatedly don't trigger one refresh POST\n    per call. Login/logout flows write to auth.json and therefore invalidate\n    the cache automatically; tests can also call\n    ``invalidate_soam_auth_status_cache()`` explicitly.\n    \"\"\"\n    global _soam_auth_status_cache\n    now = time.monotonic()\n    mtime = _auth_file_mtime()\n    cached = _soam_auth_status_cache\n    if cached is not None:\n        cached_at, cached_mtime, cached_status = cached\n        if (\n            cached_mtime == mtime\n            and (now - cached_at) < _SOAM_AUTH_STATUS_CACHE_TTL\n        ):\n            return dict(cached_status)\n\n    status = _compute_soam_auth_status()\n    _soam_auth_status_cache = (now, mtime, dict(status))\n    return status\n\n\ndef _compute_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Uncached implementation of get_soam_auth_status(). See that function.\"\"\"\n    state = get_provider_auth_state(\"soam\")\n    if state:\n        base_status = {\n            \"logged_in\": bool(state.get(\"access_token\")),\n            \"portal_base_url\": state.get(\"portal_base_url\"),\n            \"inference_base_url\": state.get(\"inference_base_url\"),\n            \"access_expires_at\": state.get(\"expires_at\"),\n            \"agent_key_expires_at\": state.get(\"agent_key_expires_at\"),\n            \"has_refresh_token\": bool(state.get(\"refresh_token\")),\n            \"access_token\": state.get(\"access_token\"),\n            \"source\": \"auth_store\",\n        }\n        try:\n            creds = resolve_soam_runtime_credentials(min_key_ttl_seconds=60)\n            refreshed_state = get_provider_auth_state(\"soam\") or state\n            base_status.update(\n                {\n                    \"logged_in\": True,\n                    \"portal_base_url\": refreshed_state.get(\"portal_base_url\") or base_status.get(\"portal_base_url\"),\n                    \"inference_base_url\": creds.get(\"base_url\")\n                    or refreshed_state.get(\"inference_base_url\")\n                    or base_status.get(\"inference_base_url\"),\n                    \"access_expires_at\": refreshed_state.get(\"expires_at\") or base_status.get(\"access_expires_at\"),\n                    \"agent_key_expires_at\": creds.get(\"expires_at\")\n                    or refreshed_state.get(\"agent_key_expires_at\")\n                    or base_status.get(\"agent_key_expires_at\"),\n                    \"has_refresh_token\": bool(refreshed_state.get(\"refresh_token\")),\n                    \"source\": f\"runtime:{creds.get('source', 'portal')}\",\n                    \"key_id\": creds.get(\"key_id\"),\n                }\n            )\n            return base_status\n        except AuthError as exc:\n            base_status.update({\n                \"logged_in\": False,\n                \"error\": str(exc),\n                \"relogin_required\": bool(getattr(exc, \"relogin_required\", False)),\n                \"error_code\": getattr(exc, \"code\", None),\n            })\n            return base_status\n\n    return _snapshot_soam_pool_status()\n\n\ndef get_codex_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Codex auth.\n    \n    Checks the credential pool first (where `clawbot auth` stores credentials),\n    then falls back to the legacy provider state.\n    \"\"\"\n    # Check credential pool first — this is where `clawbot auth` and\n    # `clawbot model` store device_code tokens.\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(\"openai-codex\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _codex_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"chatgpt\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    # Fall back to legacy provider state\n    try:\n        creds = resolve_codex_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_xai_oauth_auth_status() -> Dict[str, Any]:\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"xai-oauth\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _xai_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"oauth_pkce\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    try:\n        creds = resolve_xai_oauth_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_api_key_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for API-key providers (z.ai, Kimi, MiniMax).\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        return {\"configured\": False}\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"configured\": bool(api_key),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"key_source\": key_source,\n        \"base_url\": base_url,\n        \"logged_in\": bool(api_key),  # compat with OAuth status shape\n    }\n\n\ndef get_external_process_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for providers that run a local subprocess.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        return {\"configured\": False}\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    resolved_command = shutil.which(command) if command else None\n    return {\n        \"configured\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"command\": command,\n        \"args\": args,\n        \"resolved_command\": resolved_command,\n        \"base_url\": base_url,\n        \"logged_in\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n    }\n\n\ndef get_auth_status(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Generic auth status dispatcher.\"\"\"\n    target = provider_id or get_active_provider()\n    if target == \"spotify\":\n        return get_spotify_auth_status()\n    if target == \"soam\":\n        return get_soam_auth_status()\n    if target == \"openai-codex\":\n        return get_codex_auth_status()\n    if target == \"xai-oauth\":\n        return get_xai_oauth_auth_status()\n    if target == \"qwen-oauth\":\n        return get_qwen_auth_status()\n    if target == \"google-gemini-cli\":\n        return get_gemini_oauth_auth_status()\n    if target == \"minimax-oauth\":\n        return get_minimax_oauth_auth_status()\n    if target == \"copilot-acp\":\n        return get_external_process_provider_status(target)\n    # API-key providers\n    pconfig = PROVIDER_REGISTRY.get(target)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        return get_api_key_provider_status(target)\n    # AWS SDK providers (Bedrock) — check via boto3 credential chain\n    if pconfig and pconfig.auth_type == \"aws_sdk\":\n        try:\n            from agent.bedrock_adapter import has_aws_credentials\n            return {\"logged_in\": has_aws_credentials(), \"provider\": target}\n        except ImportError:\n            return {\"logged_in\": False, \"provider\": target, \"error\": \"boto3 not installed\"}\n    return {\"logged_in\": False}\n\n\ndef resolve_api_key_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve API key and base URL for an API-key provider.\n\n    Returns dict with: provider, api_key, base_url, source.\n    \"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an API-key provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    # No-auth LM Studio: substitute a placeholder so runtime / auxiliary_client\n    # see the local server as configured. doctor still reports unconfigured\n    # because get_api_key_provider_status uses the raw secret resolver.\n    if not api_key and provider_id == \"lmstudio\":\n        api_key = LMSTUDIO_NOAUTH_PLACEHOLDER\n        key_source = key_source or \"default\"\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif provider_id == \"zai\":\n        base_url = _resolve_zai_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url.rstrip(\"/\")\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": api_key,\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"source\": key_source or \"default\",\n    }\n\n\ndef resolve_external_process_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve runtime details for local subprocess-backed providers.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an external-process provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    resolved_command = shutil.which(command) if command else None\n    if not resolved_command and not base_url.startswith(\"acp+tcp://\"):\n        raise AuthError(\n            f\"Could not find the Copilot CLI command '{command}'. \"\n            \"Install GitHub Copilot CLI or set CLAWBOT_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH.\",\n            provider=provider_id,\n            code=\"missing_copilot_cli\",\n        )\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": \"copilot-acp\",\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"command\": resolved_command or command,\n        \"args\": args,\n        \"source\": \"process\",\n    }\n\n\n# =============================================================================\n# CLI Commands — login / logout\n# =============================================================================\n\ndef _update_config_for_provider(\n    provider_id: str,\n    inference_base_url: str,\n    default_model: Optional[str] = None,\n) -> Path:\n    \"\"\"Update config.yaml and auth.json to reflect the active provider.\n\n    When *default_model* is provided the function also writes it as the\n    ``model.default`` value.  This prevents a race condition where the\n    gateway (which re-reads config per-message) picks up the new provider\n    before the caller has finished model selection, resulting in a\n    mismatched model/provider (e.g. ``anthropic/claude-opus-4.6`` sent to\n    MiniMax's API).\n    \"\"\"\n    # Set active_provider in auth.json so auto-resolution picks this provider\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = provider_id\n        _save_auth_store(auth_store)\n\n    # Update config.yaml model section\n    config_path = get_config_path()\n    config_path.parent.mkdir(parents=True, exist_ok=True)\n\n    config = read_raw_config()\n\n    current_model = config.get(\"model\")\n    if isinstance(current_model, dict):\n        model_cfg = dict(current_model)\n    elif isinstance(current_model, str) and current_model.strip():\n        model_cfg = {\"default\": current_model.strip()}\n    else:\n        model_cfg = {}\n\n    model_cfg[\"provider\"] = provider_id\n    if inference_base_url and inference_base_url.strip():\n        model_cfg[\"base_url\"] = inference_base_url.rstrip(\"/\")\n    else:\n        # Clear stale base_url to prevent contamination when switching providers\n        model_cfg.pop(\"base_url\", None)\n\n    # Clear stale api_key/api_mode left over from a previous custom provider.\n    # When the user switches from e.g. a MiniMax custom endpoint\n    # (api_mode=anthropic_messages, api_key=mxp-...) to a built-in provider\n    # (e.g. OpenRouter), the stale api_key/api_mode would override the new\n    # provider's credentials and transport choice.  Built-in providers that\n    # need a specific api_mode (copilot, xai) set it at request-resolution\n    # time via `_copilot_runtime_api_mode` / `_detect_api_mode_for_url`, so\n    # removing the persisted value here is safe.\n    model_cfg.pop(\"api_key\", None)\n    model_cfg.pop(\"api_mode\", None)\n\n    # When switching to a non-OpenRouter provider, ensure model.default is\n    # valid for the new provider.  An OpenRouter-formatted name like\n    # \"anthropic/claude-opus-4.6\" will fail on direct-API providers.\n    if default_model:\n        cur_default = model_cfg.get(\"default\", \"\")\n        if not cur_default or \"/\" in cur_default:\n            model_cfg[\"default\"] = default_model\n\n    config[\"model\"] = model_cfg\n\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _get_config_provider() -> Optional[str]:\n    \"\"\"Return model.provider from config.yaml, normalized, if present.\"\"\"\n    try:\n        config = read_raw_config()\n    except Exception:\n        return None\n    if not config:\n        return None\n    model = config.get(\"model\")\n    if not isinstance(model, dict):\n        return None\n    provider = model.get(\"provider\")\n    if not isinstance(provider, str):\n        return None\n    provider = provider.strip().lower()\n    return provider or None\n\n\ndef _config_provider_matches(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when config.yaml currently selects *provider_id*.\"\"\"\n    if not provider_id:\n        return False\n    return _get_config_provider() == provider_id.strip().lower()\n\n\ndef _should_reset_config_provider_on_logout(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when logout should reset the model provider config.\"\"\"\n    if not provider_id:\n        return False\n    normalized = provider_id.strip().lower()\n    return normalized in PROVIDER_REGISTRY and _config_provider_matches(normalized)\n\n\ndef _logout_default_provider_from_config() -> Optional[str]:\n    \"\"\"Fallback logout target when auth.json has no active provider.\n\n    `clawbot logout` historically keyed off auth.json.active_provider only.\n    That left users stuck when auth state had already been cleared but\n    config.yaml still selected an OAuth provider such as openai-codex for the\n    agent model: there was no active auth provider to target, so logout printed\n    \"No provider is currently logged in\" and never reset model.provider.\n    \"\"\"\n    provider = _get_config_provider()\n    if provider in {\"soam\", \"openai-codex\", \"xai-oauth\"}:\n        return provider\n    return None\n\n\ndef _reset_config_provider() -> Path:\n    \"\"\"Reset config.yaml provider back to auto after logout.\"\"\"\n    config_path = get_config_path()\n    if not config_path.exists():\n        return config_path\n\n    config = read_raw_config()\n    if not config:\n        return config_path\n\n    model = config.get(\"model\")\n    if isinstance(model, dict):\n        model[\"provider\"] = \"auto\"\n        if \"base_url\" in model:\n            model[\"base_url\"] = OPENROUTER_BASE_URL\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _prompt_model_selection(\n    model_ids: List[str],\n    current_model: str = \"\",\n    pricing: Optional[Dict[str, Dict[str, str]]] = None,\n    unavailable_models: Optional[List[str]] = None,\n    portal_url: str = \"\",\n) -> Optional[str]:\n    \"\"\"Interactive model selection. Puts current_model first with a marker. Returns chosen model ID or None.\n\n    If *pricing* is provided (``{model_id: {prompt, completion}}``), a compact\n    price indicator is shown next to each model in aligned columns.\n\n    If *unavailable_models* is provided, those models are shown grayed out\n    and unselectable, with an upgrade link to *portal_url*.\n    \"\"\"\n    from clawbot_cli.models import _format_price_per_mtok\n\n    _unavailable = unavailable_models or []\n\n    # Reorder: current model first, then the rest (deduplicated)\n    ordered = []\n    if current_model and current_model in model_ids:\n        ordered.append(current_model)\n    for mid in model_ids:\n        if mid not in ordered:\n            ordered.append(mid)\n\n    # All models for column-width computation (selectable + unavailable)\n    all_models = list(ordered) + list(_unavailable)\n\n    # Column-aligned labels when pricing is available\n    has_pricing = bool(pricing and any(pricing.get(m) for m in all_models))\n    name_col = max((len(m) for m in all_models), default=0) + 2 if has_pricing else 0\n\n    # Pre-compute formatted prices and dynamic column widths\n    _price_cache: dict[str, tuple[str, str, str]] = {}\n    price_col = 3  # minimum width\n    cache_col = 0  # only set if any model has cache pricing\n    has_cache = False\n    if has_pricing:\n        for mid in all_models:\n            p = pricing.get(mid)  # type: ignore[union-attr]\n            if p:\n                inp = _format_price_per_mtok(p.get(\"prompt\", \"\"))\n                out = _format_price_per_mtok(p.get(\"completion\", \"\"))\n                cache_read = p.get(\"input_cache_read\", \"\")\n                cache = _format_price_per_mtok(cache_read) if cache_read else \"\"\n                if cache:\n                    has_cache = True\n            else:\n                inp, out, cache = \"\", \"\", \"\"\n            _price_cache[mid] = (inp, out, cache)\n            price_col = max(price_col, len(inp), len(out))\n            cache_col = max(cache_col, len(cache))\n        if has_cache:\n            cache_col = max(cache_col, 5)  # minimum: \"Cache\" header\n\n    def _label(mid):\n        if has_pricing:\n            inp, out, cache = _price_cache.get(mid, (\"\", \"\", \"\"))\n            price_part = f\" {inp:>{price_col}}  {out:>{price_col}}\"\n            if has_cache:\n                price_part += f\"  {cache:>{cache_col}}\"\n            base = f\"{mid:<{name_col}}{price_part}\"\n        else:\n            base = mid\n        if mid == current_model:\n            base += \"  ← currently in use\"\n        return base\n\n    # Default cursor on the current model (index 0 if it was reordered to top)\n    default_idx = 0\n\n    # Build a pricing header hint for the menu title\n    menu_title = \"Select default model:\"\n    if has_pricing:\n        # Align the header with the model column.\n        # Each choice is \"  {label}\" (2 spaces) and simple_term_menu prepends\n        # a 3-char cursor region (\"-> \" or \"   \"), so content starts at col 5.\n        pad = \" \" * 5\n        header = f\"\\n{pad}{'':>{name_col}} {'In':>{price_col}}  {'Out':>{price_col}}\"\n        if has_cache:\n            header += f\"  {'Cache':>{cache_col}}\"\n        menu_title += header + \"  /Mtok\"\n\n    # ANSI escape for dim text\n    _DIM = \"\\033[2m\"\n    _RESET = \"\\033[0m\"\n\n    # Try arrow-key menu first, fall back to number input\n    try:\n        from simple_term_menu import TerminalMenu\n\n        choices = [f\"  {_label(mid)}\" for mid in ordered]\n        choices.append(\"  Enter custom model name\")\n        choices.append(\"  Skip (keep current)\")\n\n        # Print the unavailable block BEFORE the menu via regular print().\n        # simple_term_menu pads title lines to terminal width (causes wrapping),\n        # so we keep the title minimal and use stdout for the static block.\n        # clear_screen=False means our printed output stays visible above.\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        if _unavailable:\n            print(menu_title)\n            print()\n            for mid in _unavailable:\n                print(f\"{_DIM}     {_label(mid)}{_RESET}\")\n            print()\n            print(f\"{_DIM}  ── Upgrade at {_upgrade_url} for paid models ──{_RESET}\")\n            print()\n            effective_title = \"Available free models:\"\n        else:\n            effective_title = menu_title\n\n        menu = TerminalMenu(\n            choices,\n            cursor_index=default_idx,\n            menu_cursor=\"-> \",\n            menu_cursor_style=(\"fg_green\", \"bold\"),\n            menu_highlight_style=(\"fg_green\",),\n            cycle_cursor=True,\n            clear_screen=False,\n            title=effective_title,\n        )\n        idx = menu.show()\n        from clawbot_cli.curses_ui import flush_stdin\n        flush_stdin()\n        if idx is None:\n            return None\n        print()\n        if idx < len(ordered):\n            return ordered[idx]\n        elif idx == len(ordered):\n            custom = input(\"Enter model name: \").strip()\n            return custom if custom else None\n        return None\n    except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError):\n        pass\n\n    # Fallback: numbered list\n    print(menu_title)\n    num_width = len(str(len(ordered) + 2))\n    for i, mid in enumerate(ordered, 1):\n        print(f\"  {i:>{num_width}}. {_label(mid)}\")\n    n = len(ordered)\n    print(f\"  {n + 1:>{num_width}}. Enter custom model name\")\n    print(f\"  {n + 2:>{num_width}}. Skip (keep current)\")\n\n    if _unavailable:\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        print()\n        print(f\"  {_DIM}── Unavailable models (requires paid tier — upgrade at {_upgrade_url}) ──{_RESET}\")\n        for mid in _unavailable:\n            print(f\"  {'':>{num_width}}  {_DIM}{_label(mid)}{_RESET}\")\n    print()\n\n    while True:\n        try:\n            choice = input(f\"Choice [1-{n + 2}] (default: skip): \").strip()\n            if not choice:\n                return None\n            idx = int(choice)\n            if 1 <= idx <= n:\n                return ordered[idx - 1]\n            elif idx == n + 1:\n                custom = input(\"Enter model name: \").strip()\n                return custom if custom else None\n            elif idx == n + 2:\n                return None\n            print(f\"Please enter 1-{n + 2}\")\n        except ValueError:\n            print(\"Please enter a number\")\n        except (KeyboardInterrupt, EOFError):\n            return None\n\n\ndef _save_model_choice(model_id: str) -> None:\n    \"\"\"Save the selected model to config.yaml (single source of truth).\n\n    The model is stored in config.yaml only — NOT in .env.  This avoids\n    conflicts in multi-agent setups where env vars would stomp each other.\n    \"\"\"\n    from clawbot_cli.config import save_config, load_config\n\n    config = load_config()\n    # Always use dict format so provider/base_url can be stored alongside\n    if isinstance(config.get(\"model\"), dict):\n        config[\"model\"][\"default\"] = model_id\n    else:\n        config[\"model\"] = {\"default\": model_id}\n    save_config(config)\n\n\ndef login_command(args) -> None:\n    \"\"\"Deprecated: use 'clawbot model' or 'clawbot setup' instead.\"\"\"\n    print(\"The 'clawbot login' command has been removed.\")\n    print(\"Use 'clawbot auth' to manage credentials,\")\n    print(\"'clawbot model' to select a provider, or 'clawbot setup' for full setup.\")\n    raise SystemExit(0)\n\n\ndef _login_openai_codex(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    \"\"\"OpenAI Codex login via device code flow. Tokens stored in ~/.clawbot/auth.json.\"\"\"\n\n    del args, pconfig  # kept for parity with other provider login helpers\n\n    # Check for existing Clawbot-owned credentials\n    if not force_new_login:\n        try:\n            existing = resolve_codex_runtime_credentials()\n            # Verify the resolved token is actually usable (not expired).\n            # resolve_codex_runtime_credentials attempts refresh, so if we get\n            # here the token should be valid — but double-check before telling\n            # the user \"Login successful!\".\n            _resolved_key = existing.get(\"api_key\", \"\")\n            if isinstance(_resolved_key, str) and _resolved_key and not _codex_access_token_is_expiring(_resolved_key, 60):\n                print(\"Existing Codex credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\"openai-codex\", existing.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                    return\n            else:\n                print(\"Existing Codex credentials are expired. Starting fresh login...\")\n        except AuthError:\n            pass\n\n    # Check for existing Codex CLI tokens we can import\n    if not force_new_login:\n        cli_tokens = _import_codex_cli_tokens()\n        if cli_tokens:\n            print(\"Found existing Codex CLI credentials at ~/.codex/auth.json\")\n            print(\"Clawbot will create its own session to avoid conflicts with Codex CLI / VS Code.\")\n            try:\n                do_import = input(\"Import these credentials? (a separate login is recommended) [y/N]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"n\"\n            if do_import in {\"y\", \"yes\"}:\n                _save_codex_tokens(cli_tokens)\n                base_url = os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_CODEX_BASE_URL\n                config_path = _update_config_for_provider(\"openai-codex\", base_url)\n                print()\n                print(\"Credentials imported. Note: if Codex CLI refreshes its token,\")\n                print(\"Clawbot will keep working independently with its own session.\")\n                print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                return\n\n    # Run a fresh device code flow — Clawbot gets its own OAuth session\n    print()\n    print(\"Signing in to OpenAI Codex...\")\n    print(\"(Clawbot creates its own session — won't affect Codex CLI or VS Code)\")\n    print()\n\n    creds = _codex_device_code_login()\n\n    # Save tokens to Clawbot auth store\n    _save_codex_tokens(creds[\"tokens\"], creds.get(\"last_refresh\"))\n    config_path = _update_config_for_provider(\"openai-codex\", creds.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n\n\ndef _login_xai_oauth(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    del pconfig\n\n    if not force_new_login:\n        try:\n            existing = resolve_xai_oauth_runtime_credentials()\n            api_key = existing.get(\"api_key\", \"\")\n            if isinstance(api_key, str) and api_key and not _xai_access_token_is_expiring(api_key, 60):\n                print(\"Existing xAI OAuth credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\n                        \"xai-oauth\",\n                        existing.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL),\n                    )\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n                    return\n        except AuthError:\n            pass\n\n    print()\n    print(\"Signing in to xAI Grok OAuth (SuperGrok Subscription)...\")\n    print(\"(Clawbot creates its own local OAuth session)\")\n    print()\n\n    timeout_seconds = float(getattr(args, \"timeout\", None) or 20.0)\n    open_browser = not getattr(args, \"no_browser\", False)\n    if _is_remote_session():\n        open_browser = False\n\n    creds = _xai_oauth_loopback_login(timeout_seconds=timeout_seconds, open_browser=open_browser)\n    _save_xai_oauth_tokens(\n        creds[\"tokens\"],\n        discovery=creds.get(\"discovery\"),\n        redirect_uri=creds.get(\"redirect_uri\", \"\"),\n        last_refresh=creds.get(\"last_refresh\"),\n    )\n    config_path = _update_config_for_provider(\"xai-oauth\", creds.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n\n\ndef _xai_oauth_build_authorize_url(\n    *,\n    authorization_endpoint: str,\n    redirect_uri: str,\n    code_challenge: str,\n    state: str,\n    nonce: str,\n) -> str:\n    # `plan=generic` opts the consent screen into xAI's generic OAuth plan\n    # tier instead of falling back to the per-account default. Without it,\n    # accounts.x.ai rejects loopback OAuth from non-allowlisted clients.\n    # `referrer=clawbot-agent` lets xAI attribute Clawbot-originated logins\n    # in their OAuth server logs (we still impersonate the upstream Grok-CLI\n    # client_id; this is best-effort attribution until xAI mints us our own).\n    authorize_params = {\n        \"response_type\": \"code\",\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"redirect_uri\": redirect_uri,\n        \"scope\": XAI_OAUTH_SCOPE,\n        \"code_challenge\": code_challenge,\n        \"code_challenge_method\": \"S256\",\n        \"state\": state,\n        \"nonce\": nonce,\n        \"plan\": \"generic\",\n        \"referrer\": \"clawbot-agent\",\n    }\n    return f\"{authorization_endpoint}?{urlencode(authorize_params)}\"\n\n\ndef _xai_oauth_exchange_code_for_tokens(\n    *,\n    token_endpoint: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    code_challenge: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"POST the authorization code to xAI's token endpoint and return\n    the parsed JSON payload.\n\n    Sends ``code_verifier`` as required by RFC 7636 §4.5.  Also echoes\n    ``code_challenge`` + ``code_challenge_method`` in the request body\n    as a defense-in-depth measure for OAuth servers (xAI's among them,\n    per #26990) that re-validate the challenge at the token step\n    instead of relying solely on server-side session state captured\n    during the authorize step.  Echoing the challenge is harmless for\n    strict RFC-compliant servers — RFC 7636 doesn't forbid additional\n    parameters at the token endpoint — and decisively fixes the\n    ``code_challenge is required`` failure mode users hit on the\n    loopback flow.\n\n    Raises :class:`AuthError` on any non-2xx response or transport\n    failure; the error message embeds the HTTP status code and the\n    full response body so users can disambiguate cause at a glance.\n    \"\"\"\n    # Paranoia: if upstream call sites ever drop ``code_verifier`` we\n    # want to surface a precise, local error rather than send a\n    # missing-PKCE request to xAI and receive their generic \"code\n    # challenge required\" message back.\n    if not code_verifier:\n        raise AuthError(\n            \"xAI token exchange refused locally: PKCE code_verifier is empty. \"\n            \"This is a bug in Clawbot — please report at \"\n            \"https://github.com/aayushsoam/clawbot-agent/issues/26990.\",\n            provider=\"xai-oauth\",\n            code=\"xai_pkce_verifier_missing\",\n        )\n\n    data = {\n        \"grant_type\": \"authorization_code\",\n        \"code\": code,\n        \"redirect_uri\": redirect_uri,\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"code_verifier\": code_verifier,\n    }\n    # Defense-in-depth: include the original ``code_challenge`` and\n    # ``code_challenge_method``.  Some OAuth servers (including xAI's\n    # auth.x.ai implementation, per the symptom reported in #26990)\n    # validate these at the token endpoint instead of relying purely on\n    # state captured during the authorize step — without them, xAI\n    # rejects the exchange with ``code_challenge is required`` even\n    # though we sent a valid ``code_verifier``.\n    if code_challenge:\n        data[\"code_challenge\"] = code_challenge\n        data[\"code_challenge_method\"] = \"S256\"\n\n    try:\n        response = httpx.post(\n            token_endpoint,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data=data,\n            timeout=max(20.0, timeout_seconds),\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code != 200:\n        body = response.text.strip()\n        raise AuthError(\n            f\"xAI token exchange failed (HTTP {response.status_code}).\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token exchange response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _xai_oauth_loopback_login(\n    *,\n    timeout_seconds: float = 20.0,\n    open_browser: bool = True,\n) -> Dict[str, Any]:\n    discovery = _xai_oauth_discovery(timeout_seconds)\n    authorization_endpoint = discovery[\"authorization_endpoint\"]\n    token_endpoint = discovery[\"token_endpoint\"]\n\n    server, thread, callback_result, redirect_uri = _xai_start_callback_server()\n    try:\n        _xai_validate_loopback_redirect_uri(redirect_uri)\n        code_verifier = _oauth_pkce_code_verifier()\n        code_challenge = _oauth_pkce_code_challenge(code_verifier)\n        state = uuid.uuid4().hex\n        nonce = uuid.uuid4().hex\n        authorize_url = _xai_oauth_build_authorize_url(\n            authorization_endpoint=authorization_endpoint,\n            redirect_uri=redirect_uri,\n            code_challenge=code_challenge,\n            state=state,\n            nonce=nonce,\n        )\n\n        print(\"Open this URL to authorize Clawbot with xAI:\")\n        print(authorize_url)\n        print()\n        print(f\"Waiting for callback on {redirect_uri}\")\n\n        _print_loopback_ssh_hint(redirect_uri, docs_url=XAI_OAUTH_DOCS_URL)\n\n        if open_browser and not _is_remote_session():\n            try:\n                opened = webbrowser.open(authorize_url)\n            except Exception:\n                opened = False\n            if opened:\n                print(\"Browser opened for xAI authorization.\")\n            else:\n                print(\"Could not open the browser automatically; use the URL above.\")\n\n        callback = _xai_wait_for_callback(\n            server,\n            thread,\n            callback_result,\n            timeout_seconds=max(30.0, timeout_seconds * 9),\n        )\n    except Exception:\n        try:\n            server.shutdown()\n            server.server_close()\n        except Exception:\n            pass\n        try:\n            thread.join(timeout=1.0)\n        except Exception:\n            pass\n        raise\n\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise AuthError(\n            f\"xAI authorization failed: {detail}\",\n            provider=\"xai-oauth\",\n            code=\"xai_authorization_failed\",\n        )\n    if callback.get(\"state\") != state:\n        raise AuthError(\n            \"xAI authorization failed: state mismatch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_state_mismatch\",\n        )\n    code = str(callback.get(\"code\") or \"\").strip()\n    if not code:\n        raise AuthError(\n            \"xAI authorization failed: missing authorization code.\",\n            provider=\"xai-oauth\",\n            code=\"xai_code_missing\",\n        )\n\n    payload = _xai_oauth_exchange_code_for_tokens(\n        token_endpoint=token_endpoint,\n        code=code,\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        code_challenge=code_challenge,\n        timeout_seconds=timeout_seconds,\n    )\n    access_token = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(payload.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI token exchange did not return an access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI token exchange did not return a refresh_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n            \"id_token\": str(payload.get(\"id_token\", \"\") or \"\").strip(),\n            \"expires_in\": payload.get(\"expires_in\"),\n            \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        },\n        \"discovery\": discovery,\n        \"redirect_uri\": redirect_uri,\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"source\": \"oauth-loopback\",\n    }\n\n\ndef _codex_device_code_login() -> Dict[str, Any]:\n    \"\"\"Run the OpenAI device code login flow and return credentials dict.\"\"\"\n    import time as _time\n\n    issuer = \"https://auth.openai.com\"\n    client_id = CODEX_OAUTH_CLIENT_ID\n\n    # Step 1: Request device code\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            resp = client.post(\n                f\"{issuer}/api/accounts/deviceauth/usercode\",\n                json={\"client_id\": client_id},\n                headers={\"Content-Type\": \"application/json\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to request device code: {exc}\",\n            provider=\"openai-codex\", code=\"device_code_request_failed\",\n        )\n\n    if resp.status_code != 200:\n        raise AuthError(\n            f\"Device code request returned status {resp.status_code}.\",\n            provider=\"openai-codex\", code=\"device_code_request_error\",\n        )\n\n    device_data = resp.json()\n    user_code = device_data.get(\"user_code\", \"\")\n    device_auth_id = device_data.get(\"device_auth_id\", \"\")\n    poll_interval = max(3, int(device_data.get(\"interval\", \"5\")))\n\n    if not user_code or not device_auth_id:\n        raise AuthError(\n            \"Device code response missing required fields.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete\",\n        )\n\n    # Step 2: Show user the code\n    print(\"To continue, follow these steps:\\n\")\n    print(\"  1. Open this URL in your browser:\")\n    print(f\"     \\033[94m{issuer}/codex/device\\033[0m\\n\")\n    print(\"  2. Enter this code:\")\n    print(f\"     \\033[94m{user_code}\\033[0m\\n\")\n    print(\"Waiting for sign-in... (press Ctrl+C to cancel)\")\n\n    # Step 3: Poll for authorization code\n    max_wait = 15 * 60  # 15 minutes\n    start = _time.monotonic()\n    code_resp = None\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            while _time.monotonic() - start < max_wait:\n                _time.sleep(poll_interval)\n                poll_resp = client.post(\n                    f\"{issuer}/api/accounts/deviceauth/token\",\n                    json={\"device_auth_id\": device_auth_id, \"user_code\": user_code},\n                    headers={\"Content-Type\": \"application/json\"},\n                )\n\n                if poll_resp.status_code == 200:\n                    code_resp = poll_resp.json()\n                    break\n                elif poll_resp.status_code in {403, 404}:\n                    continue  # User hasn't completed login yet\n                else:\n                    raise AuthError(\n                        f\"Device auth polling returned status {poll_resp.status_code}.\",\n                        provider=\"openai-codex\", code=\"device_code_poll_error\",\n                    )\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n\n    if code_resp is None:\n        raise AuthError(\n            \"Login timed out after 15 minutes.\",\n            provider=\"openai-codex\", code=\"device_code_timeout\",\n        )\n\n    # Step 4: Exchange authorization code for tokens\n    authorization_code = code_resp.get(\"authorization_code\", \"\")\n    code_verifier = code_resp.get(\"code_verifier\", \"\")\n    redirect_uri = f\"{issuer}/deviceauth/callback\"\n\n    if not authorization_code or not code_verifier:\n        raise AuthError(\n            \"Device auth response missing authorization_code or code_verifier.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete_exchange\",\n        )\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            token_resp = client.post(\n                CODEX_OAUTH_TOKEN_URL,\n                data={\n                    \"grant_type\": \"authorization_code\",\n                    \"code\": authorization_code,\n                    \"redirect_uri\": redirect_uri,\n                    \"client_id\": client_id,\n                    \"code_verifier\": code_verifier,\n                },\n                headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Token exchange failed: {exc}\",\n            provider=\"openai-codex\", code=\"token_exchange_failed\",\n        )\n\n    if token_resp.status_code != 200:\n        raise AuthError(\n            f\"Token exchange returned status {token_resp.status_code}.\",\n            provider=\"openai-codex\", code=\"token_exchange_error\",\n        )\n\n    tokens = token_resp.json()\n    access_token = tokens.get(\"access_token\", \"\")\n    refresh_token = tokens.get(\"refresh_token\", \"\")\n\n    if not access_token:\n        raise AuthError(\n            \"Token exchange did not return an access_token.\",\n            provider=\"openai-codex\", code=\"token_exchange_no_access_token\",\n        )\n\n    # Return tokens for the caller to persist (no longer writes to ~/.codex/)\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n        },\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"auth_mode\": \"chatgpt\",\n        \"source\": \"device-code\",\n    }\n\n\n# ==================== MiniMax Portal OAuth ====================\n\ndef _minimax_pkce_pair() -> tuple:\n    \"\"\"Generate (code_verifier, code_challenge_S256, state) for MiniMax OAuth.\"\"\"\n    import secrets\n    verifier = secrets.token_urlsafe(64)[:96]\n    challenge = base64.urlsafe_b64encode(\n        hashlib.sha256(verifier.encode()).digest()\n    ).decode().rstrip(\"=\")\n    state = secrets.token_urlsafe(16)\n    return verifier, challenge, state\n\n\ndef _minimax_request_user_code(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    code_challenge: str, state: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/oauth/code\",\n        data={\n            \"response_type\": \"code\",\n            \"client_id\": client_id,\n            \"scope\": MINIMAX_OAUTH_SCOPE,\n            \"code_challenge\": code_challenge,\n            \"code_challenge_method\": \"S256\",\n            \"state\": state,\n        },\n        headers={\n            \"Content-Type\": \"application/x-www-form-urlencoded\",\n            \"Accept\": \"application/json\",\n            \"x-request-id\": str(uuid.uuid4()),\n        },\n    )\n    if response.status_code != 200:\n        raise AuthError(\n            f\"MiniMax OAuth authorization failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"authorization_failed\",\n        )\n    payload = response.json()\n    for field in (\"user_code\", \"verification_uri\", \"expired_in\"):\n        if field not in payload:\n            raise AuthError(\n                f\"MiniMax OAuth response missing field: {field}\",\n                provider=\"minimax-oauth\", code=\"authorization_incomplete\",\n            )\n    if payload.get(\"state\") != state:\n        raise AuthError(\n            \"MiniMax OAuth state mismatch (possible CSRF).\",\n            provider=\"minimax-oauth\", code=\"state_mismatch\",\n        )\n    return payload\n\n\ndef _minimax_expired_in_looks_like_unix_ms(expired_in: int, *, now_ms: int) -> bool:\n    \"\"\"True if ``expired_in`` is plausibly a unix-ms absolute time (vs TTL seconds).\"\"\"\n    return int(expired_in) > (now_ms // 2)\n\n\ndef _minimax_resolve_token_expiry_unix(expired_in: int, *, now: datetime) -> float:\n    \"\"\"Return access-token expiry as unix seconds (MiniMax uses ms epoch or TTL seconds).\"\"\"\n    raw = int(expired_in)\n    now_ms = int(now.timestamp() * 1000)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        return raw / 1000.0\n    return now.timestamp() + max(1, raw)\n\n\ndef _minimax_poll_token(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    user_code: str, code_verifier: str, expired_in: int, interval_ms: Optional[int],\n) -> Dict[str, Any]:\n    # OpenClaw treats expired_in as a unix-ms timestamp (Date.now() < expireTimeMs).\n    # Defensive parsing: if it's small enough to be a duration, treat as seconds.\n    import time as _time\n    now_ms = int(_time.time() * 1000)\n    raw = int(expired_in)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        deadline = raw / 1000.0\n    else:\n        deadline = _time.time() + max(1, raw)\n    interval = max(2.0, (interval_ms or 2000) / 1000.0)\n\n    while _time.time() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": MINIMAX_OAUTH_GRANT_TYPE,\n                \"client_id\": client_id,\n                \"user_code\": user_code,\n                \"code_verifier\": code_verifier,\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n        try:\n            payload = response.json() if response.text else {}\n        except Exception:\n            payload = {}\n\n        if response.status_code != 200:\n            msg = (payload.get(\"base_resp\", {}) or {}).get(\"status_msg\") or response.text\n            raise AuthError(\n                f\"MiniMax OAuth error: {msg or 'unknown'}\",\n                provider=\"minimax-oauth\", code=\"token_exchange_failed\",\n            )\n\n        status = payload.get(\"status\")\n        if status == \"error\":\n            raise AuthError(\n                \"MiniMax OAuth reported an error. Please try again later.\",\n                provider=\"minimax-oauth\", code=\"authorization_denied\",\n            )\n        if status == \"success\":\n            if not all(payload.get(k) for k in (\"access_token\", \"refresh_token\", \"expired_in\")):\n                raise AuthError(\n                    \"MiniMax OAuth success payload missing required token fields.\",\n                    provider=\"minimax-oauth\", code=\"token_incomplete\",\n                )\n            return payload\n        # \"pending\" or any other status -> keep polling\n        _time.sleep(interval)\n\n    raise AuthError(\n        \"MiniMax OAuth timed out before authorization completed.\",\n        provider=\"minimax-oauth\", code=\"timeout\",\n    )\n\n\ndef _minimax_save_auth_state(auth_state: Dict[str, Any]) -> None:\n    \"\"\"Persist MiniMax OAuth state to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"minimax-oauth\", auth_state)\n        _save_auth_store(auth_store)\n\n\ndef _minimax_oauth_login(\n    *, region: str = \"global\", open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n) -> Dict[str, Any]:\n    \"\"\"Run MiniMax OAuth flow, persist tokens, return auth state dict.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"minimax-oauth\"]\n    if region == \"cn\":\n        portal_base_url = pconfig.extra[\"cn_portal_base_url\"]\n        inference_base_url = pconfig.extra[\"cn_inference_base_url\"]\n    else:\n        portal_base_url = pconfig.portal_base_url\n        inference_base_url = pconfig.inference_base_url\n\n    verifier, challenge, state = _minimax_pkce_pair()\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via MiniMax ({region}) OAuth...\")\n    print(f\"Portal: {portal_base_url}\")\n\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      headers={\"Accept\": \"application/json\"},\n                      follow_redirects=True) as client:\n        code_data = _minimax_request_user_code(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            code_challenge=challenge, state=state,\n        )\n        verification_url = str(code_data[\"verification_uri\"])\n        user_code = str(code_data[\"user_code\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n        if open_browser:\n            if webbrowser.open(verification_url):\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically -- use the URL above.\")\n\n        interval_raw = code_data.get(\"interval\")\n        interval_ms = int(interval_raw) if interval_raw is not None else None\n        print(\"Waiting for approval...\")\n\n        token_data = _minimax_poll_token(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            user_code=user_code, code_verifier=verifier,\n            expired_in=int(code_data[\"expired_in\"]),\n            interval_ms=interval_ms,\n        )\n\n    now = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(token_data[\"expired_in\"]), now=now,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now.timestamp()))\n\n    auth_state = {\n        \"provider\": \"minimax-oauth\",\n        \"region\": region,\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": inference_base_url,\n        \"client_id\": pconfig.client_id,\n        \"scope\": MINIMAX_OAUTH_SCOPE,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data[\"refresh_token\"],\n        \"resource_url\": token_data.get(\"resource_url\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    }\n\n    _minimax_save_auth_state(auth_state)\n    print(\"\\u2713 MiniMax OAuth login successful.\")\n    if msg := token_data.get(\"notification_message\"):\n        print(f\"Note from MiniMax: {msg}\")\n    return auth_state\n\n\ndef _refresh_minimax_oauth_state(\n    state: Dict[str, Any], *, timeout_seconds: float = 15.0,\n    force: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Refresh MiniMax OAuth access token if close to expiry (or forced).\"\"\"\n    if not state.get(\"refresh_token\"):\n        raise AuthError(\n            \"MiniMax OAuth state has no refresh_token; please re-login.\",\n            provider=\"minimax-oauth\", code=\"no_refresh_token\", relogin_required=True,\n        )\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n    except Exception:\n        expires_at = 0.0\n    now = time.time()\n    if not force and (expires_at - now) > MINIMAX_OAUTH_REFRESH_SKEW_SECONDS:\n        return state\n\n    portal_base_url = state[\"portal_base_url\"]\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      follow_redirects=True) as client:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": state[\"client_id\"],\n                \"refresh_token\": state[\"refresh_token\"],\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n    if response.status_code != 200:\n        body = response.text.lower()\n        relogin = any(m in body for m in\n                      (\"invalid_grant\", \"refresh_token_reused\", \"invalid_refresh_token\"))\n        raise AuthError(\n            f\"MiniMax OAuth refresh failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=relogin,\n        )\n    payload = response.json()\n    if payload.get(\"status\") != \"success\":\n        raise AuthError(\n            \"MiniMax OAuth refresh did not return success.\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=True,\n        )\n    now_dt = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(payload[\"expired_in\"]), now=now_dt,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now_dt.timestamp()))\n    new_state = dict(state)\n    new_state.update({\n        \"access_token\": payload[\"access_token\"],\n        \"refresh_token\": payload.get(\"refresh_token\", state[\"refresh_token\"]),\n        \"obtained_at\": now_dt.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    })\n    _minimax_save_auth_state(new_state)\n    return new_state\n\n\ndef resolve_minimax_oauth_runtime_credentials(\n    *, min_token_ttl_seconds: int = MINIMAX_OAUTH_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Return {provider, api_key, base_url, source} for minimax-oauth.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        raise AuthError(\n            \"Not logged into MiniMax OAuth. Run `clawbot model` and select \"\n            \"MiniMax (OAuth).\",\n            provider=\"minimax-oauth\", code=\"not_logged_in\", relogin_required=True,\n        )\n    state = _refresh_minimax_oauth_state(state)\n    return {\n        \"provider\": \"minimax-oauth\",\n        \"api_key\": state[\"access_token\"],\n        \"base_url\": state[\"inference_base_url\"].rstrip(\"/\"),\n        \"source\": \"oauth\",\n    }\n\n\ndef get_minimax_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return auth status dict for MiniMax OAuth provider.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        return {\"logged_in\": False, \"provider\": \"minimax-oauth\"}\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n        token_valid = (expires_at - time.time()) > 0\n    except Exception:\n        token_valid = bool(state.get(\"access_token\"))\n    return {\n        \"logged_in\": token_valid,\n        \"provider\": \"minimax-oauth\",\n        \"region\": state.get(\"region\", \"global\"),\n        \"expires_at\": state.get(\"expires_at\"),\n    }\n\n\ndef _login_minimax_oauth(args, pconfig: ProviderConfig) -> None:\n    \"\"\"CLI entry for MiniMax OAuth login.\"\"\"\n    region = getattr(args, \"region\", None) or \"global\"\n    open_browser = not getattr(args, \"no_browser\", False)\n    timeout = getattr(args, \"timeout\", None) or 15.0\n    try:\n        _minimax_oauth_login(\n            region=region, open_browser=open_browser, timeout_seconds=timeout,\n        )\n    except AuthError as exc:\n        print(format_auth_error(exc))\n        raise SystemExit(1)\n\n\ndef _soam_device_code_login(\n    *,\n    portal_base_url: Optional[str] = None,\n    inference_base_url: Optional[str] = None,\n    client_id: Optional[str] = None,\n    scope: Optional[str] = None,\n    open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n    insecure: bool = False,\n    ca_bundle: Optional[str] = None,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Dict[str, Any]:\n    \"\"\"Run the Soam device-code flow and return full OAuth state without persisting.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"soam\"]\n    portal_base_url = (\n        portal_base_url\n        or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n        or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n        or pconfig.portal_base_url\n    ).rstrip(\"/\")\n    requested_inference_url = (\n        inference_base_url\n        or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n        or pconfig.inference_base_url\n    ).rstrip(\"/\")\n    client_id = client_id or pconfig.client_id\n    scope, explicit_scope = _soam_device_scope_with_env_override(\n        scope,\n        default_scope=pconfig.scope,\n    )\n    timeout = httpx.Timeout(timeout_seconds)\n    verify: bool | str = False if insecure else (ca_bundle if ca_bundle else True)\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via {pconfig.name}...\")\n    print(f\"Portal: {portal_base_url}\")\n    if insecure:\n        print(\"TLS verification: disabled (--insecure)\")\n    elif ca_bundle:\n        print(f\"TLS verification: custom CA bundle ({ca_bundle})\")\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        device_data, scope = _request_soam_device_code_with_scope_fallback(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            scope=scope,\n            allow_legacy_fallback=not explicit_scope,\n        )\n\n        verification_url = str(device_data[\"verification_uri_complete\"])\n        user_code = str(device_data[\"user_code\"])\n        expires_in = int(device_data[\"expires_in\"])\n        interval = int(device_data[\"interval\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n\n        if open_browser:\n            opened = webbrowser.open(verification_url)\n            if opened:\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically — use the URL above.\")\n\n        effective_interval = max(1, min(interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n        print(f\"Waiting for approval (polling every {effective_interval}s)...\")\n\n        token_data = _poll_for_token(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            device_code=str(device_data[\"device_code\"]),\n            expires_in=expires_in,\n            poll_interval=interval,\n        )\n\n    now = datetime.now(timezone.utc)\n    token_expires_in = _coerce_ttl_seconds(token_data.get(\"expires_in\", 0))\n    expires_at = now.timestamp() + token_expires_in\n    resolved_inference_url = (\n        _optional_base_url(token_data.get(\"inference_base_url\"))\n        or requested_inference_url\n    )\n    if resolved_inference_url != requested_inference_url:\n        print(f\"Using portal-provided inference URL: {resolved_inference_url}\")\n\n    auth_state = {\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": resolved_inference_url,\n        \"client_id\": client_id,\n        \"scope\": token_data.get(\"scope\") or scope,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data.get(\"refresh_token\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(),\n        \"expires_in\": token_expires_in,\n        \"tls\": {\n            \"insecure\": verify is False,\n            \"ca_bundle\": verify if isinstance(verify, str) else None,\n        },\n        \"agent_key\": None,\n        \"agent_key_id\": None,\n        \"agent_key_expires_at\": None,\n        \"agent_key_expires_in\": None,\n        \"agent_key_reused\": None,\n        \"agent_key_obtained_at\": None,\n    }\n    try:\n        return refresh_soam_oauth_from_state(\n            auth_state,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            timeout_seconds=timeout_seconds,\n            force_refresh=False,\n            inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n        )\n    except AuthError as exc:\n        if exc.code == \"subscription_required\":\n            portal_url = auth_state.get(\n                \"portal_base_url\", DEFAULT_SOAM_PORTAL_URL\n            ).rstrip(\"/\")\n            print()\n            print(\"Your Soam Portal account does not have an active subscription.\")\n            print(f\"  Subscribe here: {portal_url}/billing\")\n            print()\n            print(\"After subscribing, run `clawbot model` again to finish setup.\")\n            raise SystemExit(1)\n        raise\n\n\ndef _login_soam(args, pconfig: ProviderConfig) -> None:\n    \"\"\"Soam Portal device authorization flow.\"\"\"\n    timeout_seconds = getattr(args, \"timeout\", None) or 15.0\n    insecure = bool(getattr(args, \"insecure\", False))\n    ca_bundle = (\n        getattr(args, \"ca_bundle\", None)\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n    )\n\n    try:\n        auth_state = None\n\n        # Codex-style auto-import: before launching a fresh device-code\n        # flow, check the shared store for an existing Soam credential\n        # from any other profile. If present, offer to rehydrate it.\n        shared = _read_shared_soam_state()\n        if shared:\n            try:\n                shared_path = _soam_shared_store_path()\n            except RuntimeError:\n                shared_path = None\n            print()\n            if shared_path:\n                print(f\"Found existing Soam OAuth credentials at {shared_path}\")\n            else:\n                print(\"Found existing shared Soam OAuth credentials\")\n            try:\n                do_import = input(\"Import these credentials? [Y/n]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"y\"\n            if do_import in {\"\", \"y\", \"yes\"}:\n                print(\"Rehydrating Soam session from shared credentials...\")\n                auth_state = _try_import_shared_soam_state(\n                    timeout_seconds=timeout_seconds,\n                    min_key_ttl_seconds=5 * 60,\n                )\n                if auth_state is None:\n                    print(\"Could not refresh shared credentials — falling back to device-code login.\")\n\n        if auth_state is None:\n            auth_state = _soam_device_code_login(\n                portal_base_url=getattr(args, \"portal_url\", None),\n                inference_base_url=getattr(args, \"inference_url\", None),\n                client_id=getattr(args, \"client_id\", None) or pconfig.client_id,\n                scope=getattr(args, \"scope\", None),\n                open_browser=not getattr(args, \"no_browser\", False),\n                timeout_seconds=timeout_seconds,\n                insecure=insecure,\n                ca_bundle=ca_bundle,\n                min_key_ttl_seconds=5 * 60,\n            )\n\n        inference_base_url = auth_state[\"inference_base_url\"]\n\n        # Snapshot the prior active_provider BEFORE _save_provider_state\n        # overwrites it to \"soam\".  If the user picks \"Skip (keep current)\"\n        # during model selection below, we restore this so the user's previous\n        # provider (e.g. openrouter) is preserved.\n        with _auth_store_lock():\n            _prior_store = _load_auth_store()\n            prior_active_provider = _prior_store.get(\"active_provider\")\n\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n            _save_provider_state(auth_store, \"soam\", auth_state)\n            saved_to = _save_auth_store(auth_store)\n\n        # Mirror to the shared store so other profiles can one-tap import\n        # these credentials. Best-effort: any I/O failure is logged and\n        # swallowed inside the helper.\n        _write_shared_soam_state(auth_state)\n        _sync_soam_pool_from_auth_store()\n\n        print()\n        print(\"Login successful!\")\n        print(f\"  Auth state: {saved_to}\")\n\n        # Resolve model BEFORE writing provider to config.yaml so we never\n        # leave the config in a half-updated state (provider=soam but model\n        # still set to the previous provider's model, e.g. opus from\n        # OpenRouter).  The auth.json active_provider was already set above.\n        selected_model = None\n        try:\n            runtime_key = auth_state.get(\"agent_key\") or auth_state.get(\"access_token\")\n            if not isinstance(runtime_key, str) or not runtime_key:\n                raise AuthError(\n                    \"No runtime API key available to fetch models\",\n                    provider=\"soam\",\n                    code=\"invalid_token\",\n                )\n\n            from clawbot_cli.models import (\n                get_curated_soam_model_ids, get_pricing_for_provider,\n                check_soam_free_tier, partition_soam_models_by_tier,\n                union_with_portal_free_recommendations,\n                union_with_portal_paid_recommendations,\n            )\n            model_ids = get_curated_soam_model_ids()\n\n            print()\n            unavailable_models: list = []\n            if model_ids:\n                pricing = get_pricing_for_provider(\"soam\")\n                free_tier = check_soam_free_tier()\n                _portal_for_recs = auth_state.get(\"portal_base_url\", \"\")\n                if free_tier:\n                    # The Portal's freeRecommendedModels endpoint is the\n                    # source of truth for what's free *right now*. Augment\n                    # the curated list with anything new the Portal flags\n                    # as free so users on older Clawbot builds still see\n                    # newly-launched free models without a CLI release.\n                    model_ids, pricing = union_with_portal_free_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n                    model_ids, unavailable_models = partition_soam_models_by_tier(\n                        model_ids, pricing, free_tier=True,\n                    )\n                else:\n                    # Paid-tier mirror: pull paidRecommendedModels so newly\n                    # launched paid models surface in the picker even if\n                    # the in-repo curated list and docs-hosted manifest\n                    # haven't caught up yet.\n                    model_ids, pricing = union_with_portal_paid_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n            _portal = auth_state.get(\"portal_base_url\", \"\")\n            if model_ids:\n                print(f\"Showing {len(model_ids)} curated models — use \\\"Enter custom model name\\\" for others.\")\n                selected_model = _prompt_model_selection(\n                    model_ids, pricing=pricing,\n                    unavailable_models=unavailable_models,\n                    portal_url=_portal,\n                )\n            elif unavailable_models:\n                _url = (_portal or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n                print(\"No free models currently available.\")\n                print(f\"Upgrade at {_url} to access paid models.\")\n            else:\n                print(\"No curated models available for Soam Portal.\")\n        except Exception as exc:\n            message = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc)\n            print()\n            print(f\"Login succeeded, but could not fetch available models. Reason: {message}\")\n\n        # Write provider + model atomically so config is never mismatched.\n        # If no model was selected (user picked \"Skip (keep current)\",\n        # model list fetch failed, or no curated models were available),\n        # preserve the user's previous provider — don't silently switch\n        # them to Soam with a mismatched model.  The Soam OAuth tokens\n        # stay saved for future use.\n        if not selected_model:\n            # Restore the prior active_provider that _save_provider_state\n            # overwrote to \"soam\".  config.yaml model.provider is left\n            # untouched, so the user's previous provider is fully preserved.\n            with _auth_store_lock():\n                auth_store = _load_auth_store()\n                if prior_active_provider:\n                    auth_store[\"active_provider\"] = prior_active_provider\n                else:\n                    auth_store.pop(\"active_provider\", None)\n                _save_auth_store(auth_store)\n            print()\n            print(\"No provider change. Soam credentials saved for future use.\")\n            print(\"  Run `clawbot model` again to switch to Soam Portal.\")\n            return\n\n        config_path = _update_config_for_provider(\n            \"soam\", inference_base_url, default_model=selected_model,\n        )\n        if selected_model:\n            _save_model_choice(selected_model)\n            print(f\"Default model set to: {selected_model}\")\n        print(f\"  Config updated: {config_path} (model.provider=soam)\")\n\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n    except Exception as exc:\n        print(f\"Login failed: {exc}\")\n        raise SystemExit(1)\n\n\ndef logout_command(args) -> None:\n    \"\"\"Clear auth state for a provider.\"\"\"\n    provider_id = getattr(args, \"provider\", None)\n\n    if provider_id and not is_known_auth_provider(provider_id):\n        print(f\"Unknown provider: {provider_id}\")\n        raise SystemExit(1)\n\n    active = get_active_provider()\n    target = provider_id or active or _logout_default_provider_from_config()\n\n    if not target:\n        print(\"No provider is currently logged in.\")\n        return\n\n    should_reset_config = _should_reset_config_provider_on_logout(target)\n    provider_name = get_auth_provider_display_name(target)\n\n    if clear_provider_auth(target) or should_reset_config:\n        if should_reset_config:\n            _reset_config_provider()\n        print(f\"Logged out of {provider_name}.\")\n        if should_reset_config and os.getenv(\"OPENROUTER_API_KEY\"):\n            print(\"Clawbot will use OpenRouter for inference.\")\n        elif should_reset_config:\n            print(\"Run `clawbot model` or configure an API key to use Clawbot.\")\n        else:\n            print(\"Model provider configuration was unchanged.\")\n    else:\n        print(f\"No auth state found for {provider_name}.\")\n"}, "efa0f8d65cc3a57b5b1e96383408802ff96fd7f8": {"t": 1785763615.1467369, "n": 273568, "h": "1c8da1435721e456", "c": "\"\"\"\nMulti-provider authentication system for Clawbot Agent.\n\nSupports OAuth device code flows (Soam Portal, future: OpenAI Codex) and\ntraditional API key providers (OpenRouter, custom endpoints). Auth state\nis persisted in ~/.clawbot/auth.json with cross-process file locking.\n\nArchitecture:\n- ProviderConfig registry defines known OAuth providers\n- Auth store (auth.json) holds per-provider credential state\n- resolve_provider() picks the active provider via priority chain\n- resolve_*_runtime_credentials() handles token refresh and key minting\n- logout_command() is the CLI entry point for clearing auth\n\nSoam authentication paths:\n- Invoke JWT (preferred): use a scoped access_token directly for inference.\n- Legacy session key (fallback): mint an opaque 24h key when JWT auth is\n  unavailable, or when CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS is set for\n  debugging or rollback.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport shutil\nimport shlex\nimport ssl\nimport stat\nimport sys\nimport base64\nimport hashlib\nimport subprocess\nimport threading\nimport time\nimport uuid\nimport webbrowser\nfrom contextlib import contextmanager\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\nfrom pathlib import Path\nfrom typing import Any, Callable, Dict, List, Optional, Tuple\nfrom urllib.parse import parse_qs, urlencode, urlparse\n\nimport httpx\nimport yaml\n\nfrom clawbot_cli.config import get_clawbot_home, get_config_path, read_raw_config\nfrom clawbot_constants import OPENROUTER_BASE_URL\nfrom utils import atomic_replace, atomic_yaml_write, is_truthy_value\n\nlogger = logging.getLogger(__name__)\n\ntry:\n    import fcntl\nexcept Exception:\n    fcntl = None\ntry:\n    import msvcrt\nexcept Exception:\n    msvcrt = None\n\n# =============================================================================\n# Constants\n# =============================================================================\n\nAUTH_STORE_VERSION = 1\nAUTH_LOCK_TIMEOUT_SECONDS = 15.0\n\n# Soam Portal defaults\nDEFAULT_SOAM_PORTAL_URL = \"https://portal.aayushsoam.com\"\nDEFAULT_SOAM_INFERENCE_URL = \"https://inference-api.aayushsoam.com/v1\"\nDEFAULT_SOAM_CLIENT_ID = \"\"\nDEFAULT_GROQ_BASE_URL = \"https://api.groq.com/openai/v1\"\nSOAM_LEGACY_AGENT_KEY_SCOPE = \"inference:mint_agent_key\"\nSOAM_INFERENCE_INVOKE_SCOPE = \"inference:invoke\"\nDEFAULT_SOAM_SCOPE = f\"{SOAM_INFERENCE_INVOKE_SCOPE} {SOAM_LEGACY_AGENT_KEY_SCOPE}\"\nSOAM_LEGACY_SESSION_KEYS_ENV = \"CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS\"\nSOAM_DEVICE_CODE_SOURCE = \"device_code\"\nSOAM_INFERENCE_AUTH_MODE_AUTO = \"auto\"\nSOAM_INFERENCE_AUTH_MODE_FRESH = \"fresh\"\nSOAM_INFERENCE_AUTH_MODE_LEGACY = \"legacy\"\nSOAM_INFERENCE_AUTH_MODES = frozenset({\n    SOAM_INFERENCE_AUTH_MODE_AUTO,\n    SOAM_INFERENCE_AUTH_MODE_FRESH,\n    SOAM_INFERENCE_AUTH_MODE_LEGACY,\n})\nSOAM_AUTH_PATH_INVOKE_JWT = \"\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE = \"legacy_session_key_cache\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT = \"legacy_session_key_mint\"\nDEFAULT_AGENT_KEY_MIN_TTL_SECONDS = 30 * 60  # 30 minutes\nACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120       # refresh 2 min before expiry\nSOAM_INVOKE_JWT_MIN_TTL_SECONDS = ACCESS_TOKEN_REFRESH_SKEW_SECONDS\nDEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS = 1     # poll at most every 1s\nDEFAULT_CODEX_BASE_URL = \"https://chatgpt.com/backend-api/codex\"\nDEFAULT_XAI_OAUTH_BASE_URL = \"https://api.x.ai/v1\"\nMINIMAX_OAUTH_CLIENT_ID = \"\"\nMINIMAX_OAUTH_SCOPE = \"group_id profile model.completion\"\nMINIMAX_OAUTH_GRANT_TYPE = \"urn:ietf:params:oauth:grant-type:user_code\"\nMINIMAX_OAUTH_GLOBAL_BASE = \"https://api.minimax.io\"\nMINIMAX_OAUTH_CN_BASE = \"https://api.minimaxi.com\"\nMINIMAX_OAUTH_GLOBAL_INFERENCE = \"https://api.minimax.io/anthropic\"\nMINIMAX_OAUTH_CN_INFERENCE = \"https://api.minimaxi.com/anthropic\"\nMINIMAX_OAUTH_REFRESH_SKEW_SECONDS = 60\nDEFAULT_QWEN_BASE_URL = \"https://portal.qwen.ai/v1\"\nDEFAULT_GITHUB_MODELS_BASE_URL = \"https://api.githubcopilot.com\"\nDEFAULT_COPILOT_ACP_BASE_URL = \"acp://copilot\"\nDEFAULT_OLLAMA_CLOUD_BASE_URL = \"https://ollama.com/v1\"\nSTEPFUN_STEP_PLAN_INTL_BASE_URL = \"https://api.stepfun.ai/step_plan/v1\"\nSTEPFUN_STEP_PLAN_CN_BASE_URL = \"https://api.stepfun.com/step_plan/v1\"\nCODEX_OAUTH_CLIENT_ID = \"\"\nCODEX_OAUTH_TOKEN_URL = \"https://auth.openai.com/oauth/token\"\nCODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nXAI_OAUTH_ISSUER = \"https://auth.x.ai\"\nXAI_OAUTH_DISCOVERY_URL = f\"{XAI_OAUTH_ISSUER}/.well-known/openid-configuration\"\nXAI_OAUTH_CLIENT_ID = \"\"\nXAI_OAUTH_SCOPE = \"openid profile email offline_access grok-cli:access api:access\"\nXAI_OAUTH_REDIRECT_HOST = \"127.0.0.1\"\nXAI_OAUTH_REDIRECT_PORT = 56121\nXAI_OAUTH_REDIRECT_PATH = \"/callback\"\nXAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nQWEN_OAUTH_CLIENT_ID = \"\"\nQWEN_OAUTH_TOKEN_URL = \"https://chat.qwen.ai/api/v1/oauth2/token\"\nQWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nDEFAULT_SPOTIFY_ACCOUNTS_BASE_URL = \"https://accounts.spotify.com\"\nDEFAULT_SPOTIFY_API_BASE_URL = \"https://api.spotify.com/v1\"\nDEFAULT_SPOTIFY_REDIRECT_URI = \"http://127.0.0.1:43827/spotify/callback\"\nSPOTIFY_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/user-guide/features/spotify\"\nSPOTIFY_DASHBOARD_URL = \"https://developer.spotify.com/dashboard\"\nSPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\n\nXAI_OAUTH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/xai-grok-oauth\"\nOAUTH_OVER_SSH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/oauth-over-ssh\"\nDEFAULT_SPOTIFY_SCOPE = \" \".join((\n    \"user-modify-playback-state\",\n    \"user-read-playback-state\",\n    \"user-read-currently-playing\",\n    \"user-read-recently-played\",\n    \"playlist-read-private\",\n    \"playlist-read-collaborative\",\n    \"playlist-modify-public\",\n    \"playlist-modify-private\",\n    \"user-library-read\",\n    \"user-library-modify\",\n))\nSERVICE_PROVIDER_NAMES: Dict[str, str] = {\n    \"spotify\": \"Spotify\",\n}\n\n# Google Gemini OAuth (google-gemini-cli provider, Cloud Code Assist backend)\nDEFAULT_GEMINI_CLOUDCODE_BASE_URL = \"cloudcode-pa://google\"\nGEMINI_OAUTH_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 60  # refresh 60s before expiry\n\n# LM Studio's default no-auth mode still requires *some* non-empty bearer for\n# the API-key code paths (auxiliary_client, runtime resolver) to treat the\n# provider as configured. This sentinel is sent only to LM Studio, never to\n# any remote service.\nLMSTUDIO_NOAUTH_PLACEHOLDER = \"dummy-lm-api-key\"\n\n\n# =============================================================================\n# Provider Registry\n# =============================================================================\n\n@dataclass\nclass ProviderConfig:\n    \"\"\"Describes a known inference provider.\"\"\"\n    id: str\n    name: str\n    auth_type: str  # \"oauth_device_code\", \"oauth_external\", \"oauth_minimax\", or \"api_key\"\n    portal_base_url: str = \"\"\n    inference_base_url: str = \"\"\n    client_id: str = \"\"\n    scope: str = \"\"\n    extra: Dict[str, Any] = field(default_factory=dict)\n    # For API-key providers: env vars to check (in priority order)\n    api_key_env_vars: tuple = ()\n    # Optional env var for base URL override\n    base_url_env_var: str = \"\"\n\n\nPROVIDER_REGISTRY: Dict[str, ProviderConfig] = {\n    \"groq\": ProviderConfig(\n        id=\"groq\",\n        name=\"Groq\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_GROQ_BASE_URL,\n        api_key_env_vars=(\"GROQ_API_KEY\",),\n        base_url_env_var=\"GROQ_BASE_URL\",\n    ),\n    \"openai-codex\": ProviderConfig(\n        id=\"openai-codex\",\n        name=\"OpenAI Codex\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_CODEX_BASE_URL,\n    ),\n    \"xai-oauth\": ProviderConfig(\n        id=\"xai-oauth\",\n        name=\"xAI Grok OAuth (SuperGrok Subscription)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_XAI_OAUTH_BASE_URL,\n    ),\n    \"qwen-oauth\": ProviderConfig(\n        id=\"qwen-oauth\",\n        name=\"Qwen OAuth\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_QWEN_BASE_URL,\n    ),\n    \"google-gemini-cli\": ProviderConfig(\n        id=\"google-gemini-cli\",\n        name=\"Google Gemini (OAuth)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_GEMINI_CLOUDCODE_BASE_URL,\n    ),\n    \"lmstudio\": ProviderConfig(\n        id=\"lmstudio\",\n        name=\"LM Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"http://127.0.0.1:1234/v1\",\n        api_key_env_vars=(\"LM_API_KEY\",),\n        base_url_env_var=\"LM_BASE_URL\",\n    ),\n    \"copilot\": ProviderConfig(\n        id=\"copilot\",\n        name=\"GitHub Copilot\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_GITHUB_MODELS_BASE_URL,\n        api_key_env_vars=(\"COPILOT_GITHUB_TOKEN\", \"GH_TOKEN\", \"GITHUB_TOKEN\"),\n        base_url_env_var=\"COPILOT_API_BASE_URL\",\n    ),\n    \"copilot-acp\": ProviderConfig(\n        id=\"copilot-acp\",\n        name=\"GitHub Copilot ACP\",\n        auth_type=\"external_process\",\n        inference_base_url=DEFAULT_COPILOT_ACP_BASE_URL,\n        base_url_env_var=\"COPILOT_ACP_BASE_URL\",\n    ),\n    \"gemini\": ProviderConfig(\n        id=\"gemini\",\n        name=\"Google AI Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://generativelanguage.googleapis.com/v1beta\",\n        api_key_env_vars=(\"GOOGLE_API_KEY\", \"GEMINI_API_KEY\"),\n        base_url_env_var=\"GEMINI_BASE_URL\",\n    ),\n    \"zai\": ProviderConfig(\n        id=\"zai\",\n        name=\"Z.AI / GLM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.z.ai/api/paas/v4\",\n        api_key_env_vars=(\"GLM_API_KEY\", \"ZAI_API_KEY\", \"Z_AI_API_KEY\"),\n        base_url_env_var=\"GLM_BASE_URL\",\n    ),\n    \"kimi-coding\": ProviderConfig(\n        id=\"kimi-coding\",\n        name=\"Kimi / Moonshot\",\n        auth_type=\"api_key\",\n        # Legacy platform.moonshot.ai keys use this endpoint (OpenAI-compat).\n        # sk-kimi- (Kimi Code) keys are auto-redirected to api.kimi.com/coding\n        # by _resolve_kimi_base_url() below.\n        inference_base_url=\"https://api.moonshot.ai/v1\",\n        api_key_env_vars=(\"KIMI_API_KEY\", \"KIMI_CODING_API_KEY\"),\n        base_url_env_var=\"KIMI_BASE_URL\",\n    ),\n    \"kimi-coding-cn\": ProviderConfig(\n        id=\"kimi-coding-cn\",\n        name=\"Kimi / Moonshot (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.moonshot.cn/v1\",\n        api_key_env_vars=(\"KIMI_CN_API_KEY\",),\n    ),\n    \"stepfun\": ProviderConfig(\n        id=\"stepfun\",\n        name=\"StepFun Step Plan\",\n        auth_type=\"api_key\",\n        inference_base_url=STEPFUN_STEP_PLAN_INTL_BASE_URL,\n        api_key_env_vars=(\"STEPFUN_API_KEY\",),\n        base_url_env_var=\"STEPFUN_BASE_URL\",\n    ),\n    \"arcee\": ProviderConfig(\n        id=\"arcee\",\n        name=\"Arcee AI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.arcee.ai/api/v1\",\n        api_key_env_vars=(\"ARCEEAI_API_KEY\",),\n        base_url_env_var=\"ARCEE_BASE_URL\",\n    ),\n    \"gmi\": ProviderConfig(\n        id=\"gmi\",\n        name=\"GMI Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.gmi-serving.com/v1\",\n        api_key_env_vars=(\"GMI_API_KEY\",),\n        base_url_env_var=\"GMI_BASE_URL\",\n    ),\n    \"minimax\": ProviderConfig(\n        id=\"minimax\",\n        name=\"MiniMax\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimax.io/anthropic\",\n        api_key_env_vars=(\"MINIMAX_API_KEY\",),\n        base_url_env_var=\"MINIMAX_BASE_URL\",\n    ),\n    \"minimax-oauth\": ProviderConfig(\n        id=\"minimax-oauth\",\n        name=\"MiniMax (OAuth \\u00b7 minimax.io)\",\n        auth_type=\"oauth_minimax\",\n        portal_base_url=MINIMAX_OAUTH_GLOBAL_BASE,\n        inference_base_url=MINIMAX_OAUTH_GLOBAL_INFERENCE,\n        client_id=MINIMAX_OAUTH_CLIENT_ID,\n        scope=MINIMAX_OAUTH_SCOPE,\n        extra={\"region\": \"global\", \"cn_portal_base_url\": MINIMAX_OAUTH_CN_BASE,\n               \"cn_inference_base_url\": MINIMAX_OAUTH_CN_INFERENCE},\n    ),\n    \"anthropic\": ProviderConfig(\n        id=\"anthropic\",\n        name=\"Anthropic\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.anthropic.com\",\n        api_key_env_vars=(\"ANTHROPIC_API_KEY\", \"ANTHROPIC_TOKEN\", \"CLAUDE_CODE_OAUTH_TOKEN\"),\n        base_url_env_var=\"ANTHROPIC_BASE_URL\",\n    ),\n    \"alibaba\": ProviderConfig(\n        id=\"alibaba\",\n        name=\"Qwen Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://dashscope-intl.aliyuncs.com/compatible-mode/v1\",\n        api_key_env_vars=(\"DASHSCOPE_API_KEY\",),\n        base_url_env_var=\"DASHSCOPE_BASE_URL\",\n    ),\n    \"alibaba-coding-plan\": ProviderConfig(\n        id=\"alibaba-coding-plan\",\n        name=\"Alibaba Cloud (Coding Plan)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://coding-intl.dashscope.aliyuncs.com/v1\",\n        api_key_env_vars=(\"ALIBABA_CODING_PLAN_API_KEY\", \"DASHSCOPE_API_KEY\"),\n        base_url_env_var=\"ALIBABA_CODING_PLAN_BASE_URL\",\n    ),\n    \"minimax-cn\": ProviderConfig(\n        id=\"minimax-cn\",\n        name=\"MiniMax (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimaxi.com/anthropic\",\n        api_key_env_vars=(\"MINIMAX_CN_API_KEY\",),\n        base_url_env_var=\"MINIMAX_CN_BASE_URL\",\n    ),\n    \"deepseek\": ProviderConfig(\n        id=\"deepseek\",\n        name=\"DeepSeek\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.deepseek.com/v1\",\n        api_key_env_vars=(\"DEEPSEEK_API_KEY\",),\n        base_url_env_var=\"DEEPSEEK_BASE_URL\",\n    ),\n    \"xai\": ProviderConfig(\n        id=\"xai\",\n        name=\"xAI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.x.ai/v1\",\n        api_key_env_vars=(\"XAI_API_KEY\",),\n        base_url_env_var=\"XAI_BASE_URL\",\n    ),\n    \"nvidia\": ProviderConfig(\n        id=\"nvidia\",\n        name=\"NVIDIA NIM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://integrate.api.nvidia.com/v1\",\n        api_key_env_vars=(\"NVIDIA_API_KEY\",),\n        base_url_env_var=\"NVIDIA_BASE_URL\",\n    ),\n    \"ai-gateway\": ProviderConfig(\n        id=\"ai-gateway\",\n        name=\"Vercel AI Gateway\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://ai-gateway.vercel.sh/v1\",\n        api_key_env_vars=(\"AI_GATEWAY_API_KEY\",),\n        base_url_env_var=\"AI_GATEWAY_BASE_URL\",\n    ),\n    \"opencode-zen\": ProviderConfig(\n        id=\"opencode-zen\",\n        name=\"OpenCode Zen\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://opencode.ai/zen/v1\",\n        api_key_env_vars=(\"OPENCODE_ZEN_API_KEY\",),\n        base_url_env_var=\"OPENCODE_ZEN_BASE_URL\",\n    ),\n    \"opencode-go\": ProviderConfig(\n        id=\"opencode-go\",\n        name=\"OpenCode Go\",\n        auth_type=\"api_key\",\n        # OpenCode Go mixes API surfaces by model:\n        # - GLM / Kimi use OpenAI-compatible chat completions under /v1\n        # - MiniMax models use Anthropic Messages under /v1/messages\n        # Keep the provider base at /v1 and select api_mode per-model.\n        inference_base_url=\"https://opencode.ai/zen/go/v1\",\n        api_key_env_vars=(\"OPENCODE_GO_API_KEY\",),\n        base_url_env_var=\"OPENCODE_GO_BASE_URL\",\n    ),\n    \"kilocode\": ProviderConfig(\n        id=\"kilocode\",\n        name=\"Kilo Code\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.kilo.ai/api/gateway\",\n        api_key_env_vars=(\"KILOCODE_API_KEY\",),\n        base_url_env_var=\"KILOCODE_BASE_URL\",\n    ),\n    \"huggingface\": ProviderConfig(\n        id=\"huggingface\",\n        name=\"Hugging Face\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://router.huggingface.co/v1\",\n        api_key_env_vars=(\"HF_TOKEN\",),\n        base_url_env_var=\"HF_BASE_URL\",\n    ),\n    \"xiaomi\": ProviderConfig(\n        id=\"xiaomi\",\n        name=\"Xiaomi MiMo\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.xiaomimimo.com/v1\",\n        api_key_env_vars=(\"XIAOMI_API_KEY\",),\n        base_url_env_var=\"XIAOMI_BASE_URL\",\n    ),\n    \"tencent-tokenhub\": ProviderConfig(\n        id=\"tencent-tokenhub\",\n        name=\"Tencent TokenHub\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://tokenhub.tencentmaas.com/v1\",\n        api_key_env_vars=(\"TOKENHUB_API_KEY\",),\n        base_url_env_var=\"TOKENHUB_BASE_URL\",\n    ),\n    \"ollama-cloud\": ProviderConfig(\n        id=\"ollama-cloud\",\n        name=\"Ollama Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_OLLAMA_CLOUD_BASE_URL,\n        api_key_env_vars=(\"OLLAMA_API_KEY\",),\n        base_url_env_var=\"OLLAMA_BASE_URL\",\n    ),\n    \"bedrock\": ProviderConfig(\n        id=\"bedrock\",\n        name=\"AWS Bedrock\",\n        auth_type=\"aws_sdk\",\n        inference_base_url=\"https://bedrock-runtime.us-east-1.amazonaws.com\",\n        api_key_env_vars=(),\n        base_url_env_var=\"BEDROCK_BASE_URL\",\n    ),\n    \"azure-foundry\": ProviderConfig(\n        id=\"azure-foundry\",\n        name=\"Azure Foundry\",\n        auth_type=\"api_key\",\n        inference_base_url=\"\",  # User-provided endpoint\n        api_key_env_vars=(\"AZURE_FOUNDRY_API_KEY\",),\n        base_url_env_var=\"AZURE_FOUNDRY_BASE_URL\",\n    ),\n}\n\n# Auto-extend PROVIDER_REGISTRY with any api-key provider registered in\n# providers/ that is not already declared above.  New providers only need a\n# plugins/model-providers/<name>/ plugin — no edits to this file required.\ntry:\n    from providers import list_providers as _list_providers_for_registry\n    for _pp in _list_providers_for_registry():\n        if _pp.name in PROVIDER_REGISTRY:\n            continue\n        if _pp.auth_type != \"api_key\" or not _pp.env_vars:\n            continue\n        # Skip providers that need custom token resolution or are special-cased\n        # in resolve_provider() (copilot/kimi/zai have bespoke token refresh;\n        # openrouter/custom are aggregator/user-supplied and handled outside\n        # the registry — adding them here breaks runtime_provider resolution\n        # that relies on `openrouter not in PROVIDER_REGISTRY`).\n        if _pp.name in {\"copilot\", \"kimi-coding\", \"kimi-coding-cn\", \"zai\", \"openrouter\", \"custom\"}:\n            continue\n        _api_key_vars = tuple(v for v in _pp.env_vars if not v.endswith(\"_BASE_URL\") and not v.endswith(\"_URL\"))\n        _base_url_var = next((v for v in _pp.env_vars if v.endswith(\"_BASE_URL\") or v.endswith(\"_URL\")), None)\n        PROVIDER_REGISTRY[_pp.name] = ProviderConfig(\n            id=_pp.name,\n            name=_pp.display_name or _pp.name,\n            auth_type=\"api_key\",\n            inference_base_url=_pp.base_url,\n            api_key_env_vars=_api_key_vars or _pp.env_vars,\n            base_url_env_var=_base_url_var or \"\",\n        )\n        # Also register aliases so resolve_provider() resolves them\n        for _alias in _pp.aliases:\n            if _alias not in PROVIDER_REGISTRY:\n                PROVIDER_REGISTRY[_alias] = PROVIDER_REGISTRY[_pp.name]\nexcept Exception:\n    pass\n\n\n# =============================================================================\n# Anthropic Key Helper\n# =============================================================================\n\ndef get_anthropic_key() -> str:\n    \"\"\"Return the first usable Anthropic credential, or ``\"\"``.\n\n    Checks both the ``.env`` file (via ``get_env_value``) and the process\n    environment (``os.getenv``).  The fallback order mirrors the\n    ``PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars`` tuple:\n\n        ANTHROPIC_API_KEY -> ANTHROPIC_TOKEN -> CLAUDE_CODE_OAUTH_TOKEN\n    \"\"\"\n    from clawbot_cli.config import get_env_value\n\n    for var in PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars:\n        value = get_env_value(var) or os.getenv(var, \"\")\n        if value:\n            return value\n    return \"\"\n\n\n# =============================================================================\n# Kimi Code Endpoint Detection\n# =============================================================================\n\n# Kimi Code (kimi.com/code) issues keys prefixed \"sk-kimi-\" that only work\n# on api.kimi.com/coding.  Legacy keys from platform.moonshot.ai work on\n# api.moonshot.ai/v1 (the old default).  Auto-detect when user hasn't set\n# KIMI_BASE_URL explicitly.\n#\n# Note: the base URL intentionally has NO /v1 suffix.  The /coding endpoint\n# speaks the Anthropic Messages protocol, and the anthropic SDK appends\n# \"/v1/messages\" internally — so \"/coding\" + SDK suffix → \"/coding/v1/messages\"\n# (the correct target). Using \"/coding/v1\" here would produce\n# \"/coding/v1/v1/messages\" (a 404).\nKIMI_CODE_BASE_URL = \"https://api.kimi.com/coding\"\n\n\ndef _resolve_kimi_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Kimi base URL based on the API key prefix.\n\n    If the user has explicitly set KIMI_BASE_URL, that always wins.\n    Otherwise, sk-kimi- prefixed keys route to api.kimi.com/coding/v1.\n    \"\"\"\n    if env_override:\n        return env_override\n    # No key → nothing to infer from.  Return default without inspecting.\n    if not api_key:\n        return default_url\n    if api_key.startswith(\"sk-kimi-\"):\n        return KIMI_CODE_BASE_URL\n    return default_url\n\n\n\n_PLACEHOLDER_SECRET_VALUES = {\n    \"*\",\n    \"**\",\n    \"***\",\n    \"changeme\",\n    \"your_api_key\",\n    \"your-api-key\",\n    \"placeholder\",\n    \"example\",\n    \"dummy\",\n    \"null\",\n    \"none\",\n}\n\n\ndef has_usable_secret(value: Any, *, min_length: int = 4) -> bool:\n    \"\"\"Return True when a configured secret looks usable, not empty/placeholder.\"\"\"\n    if not isinstance(value, str):\n        return False\n    cleaned = value.strip()\n    if len(cleaned) < min_length:\n        return False\n    if cleaned.lower() in _PLACEHOLDER_SECRET_VALUES:\n        return False\n    return True\n\n\ndef _resolve_api_key_provider_secret(\n    provider_id: str, pconfig: ProviderConfig\n) -> tuple[str, str]:\n    \"\"\"Resolve an API-key provider's token and indicate where it came from.\"\"\"\n    if provider_id == \"copilot\":\n        # Use the dedicated copilot auth module for proper token validation\n        try:\n            from clawbot_cli.copilot_auth import resolve_copilot_token, get_copilot_api_token\n            token, source = resolve_copilot_token()\n            if token:\n                return get_copilot_api_token(token), source\n        except ValueError as exc:\n            logger.warning(\"Copilot token validation failed: %s\", exc)\n        except Exception:\n            pass\n        return \"\", \"\"\n\n    from clawbot_cli.config import get_env_value\n    for env_var in pconfig.api_key_env_vars:\n        # Check both os.environ and ~/.clawbot/.env file\n        val = (get_env_value(env_var) or \"\").strip()\n        if has_usable_secret(val):\n            return val, env_var\n\n    # Fallback: try credential pool (e.g. zai key stored via auth.json)\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(provider_id)\n        if pool and pool.has_credentials():\n            entry = pool.peek()\n            if entry:\n                key = getattr(entry, \"access_token\", \"\") or getattr(entry, \"runtime_api_key\", \"\")\n                key = str(key).strip()\n                if has_usable_secret(key):\n                    return key, f\"credential_pool:{provider_id}\"\n    except Exception:\n        pass\n\n    return \"\", \"\"\n\n\n# =============================================================================\n# Z.AI Endpoint Detection\n# =============================================================================\n\n# Z.AI has separate billing for general vs coding plans, and global vs China\n# endpoints.  A key that works on one may return \"Insufficient balance\" on\n# another.  We probe at setup time and store the working endpoint.\n# Each entry lists candidate models to try in order — newer coding plan accounts\n# may only have access to recent models (glm-5.1, glm-5v-turbo) while older\n# ones still use glm-4.7.\n\nZAI_ENDPOINTS = [\n    # (id, base_url, probe_models, label)\n    (\"global\",        \"https://api.z.ai/api/paas/v4\",        [\"glm-5\"],   \"Global\"),\n    (\"cn\",            \"https://open.bigmodel.cn/api/paas/v4\", [\"glm-5\"],   \"China\"),\n    (\"coding-global\", \"https://api.z.ai/api/coding/paas/v4\",  [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"Global (Coding Plan)\"),\n    (\"coding-cn\",     \"https://open.bigmodel.cn/api/coding/paas/v4\", [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"China (Coding Plan)\"),\n]\n\n\ndef detect_zai_endpoint(api_key: str, timeout: float = 8.0) -> Optional[Dict[str, str]]:\n    \"\"\"Probe z.ai endpoints to find one that accepts this API key.\n\n    Returns {\"id\": ..., \"base_url\": ..., \"model\": ..., \"label\": ...} for the\n    first working endpoint, or None if all fail.  For endpoints with multiple\n    candidate models, tries each in order and returns the first that succeeds.\n    \"\"\"\n    for ep_id, base_url, probe_models, label in ZAI_ENDPOINTS:\n        for model in probe_models:\n            try:\n                resp = httpx.post(\n                    f\"{base_url}/chat/completions\",\n                    headers={\n                        \"Authorization\": f\"Bearer {api_key}\",\n                        \"Content-Type\": \"application/json\",\n                    },\n                    json={\n                        \"model\": model,\n                        \"stream\": False,\n                        \"max_tokens\": 1,\n                        \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}],\n                    },\n                    timeout=timeout,\n                )\n                if resp.status_code == 200:\n                    logger.debug(\"Z.AI endpoint probe: %s (%s) model=%s OK\", ep_id, base_url, model)\n                    return {\n                        \"id\": ep_id,\n                        \"base_url\": base_url,\n                        \"model\": model,\n                        \"label\": label,\n                    }\n                logger.debug(\"Z.AI endpoint probe: %s model=%s returned %s\", ep_id, model, resp.status_code)\n            except Exception as exc:\n                logger.debug(\"Z.AI endpoint probe: %s model=%s failed: %s\", ep_id, model, exc)\n    return None\n\n\ndef _resolve_zai_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Z.AI base URL by probing endpoints.\n\n    If the user has explicitly set GLM_BASE_URL, that always wins.\n    Otherwise, probe the candidate endpoints to find one that accepts the\n    key.  The detected endpoint is cached in provider state (auth.json) keyed\n    on a hash of the API key so subsequent starts skip the probe.\n    \"\"\"\n    if env_override:\n        return env_override\n\n    # No API key set → don't probe (would fire N×M HTTPS requests with an\n    # empty Bearer token, all returning 401).  This path is hit during\n    # auxiliary-client auto-detection when the user has no Z.AI credentials\n    # at all — the caller discards the result immediately, so the probe is\n    # pure latency for every AIAgent construction.\n    if not api_key:\n        return default_url\n\n    # Check provider-state cache for a previously-detected endpoint.\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"zai\") or {}\n    cached = state.get(\"detected_endpoint\")\n    if isinstance(cached, dict) and cached.get(\"base_url\"):\n        key_hash = cached.get(\"key_hash\", \"\")\n        if key_hash == hashlib.sha256(api_key.encode()).hexdigest()[:16]:\n            logger.debug(\"Z.AI: using cached endpoint %s\", cached[\"base_url\"])\n            return cached[\"base_url\"]\n\n    # Probe — may take up to ~8s per endpoint.\n    detected = detect_zai_endpoint(api_key)\n    if detected and detected.get(\"base_url\"):\n        # Persist the detection result keyed on the API key hash.\n        key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]\n        state[\"detected_endpoint\"] = {\n            \"base_url\": detected[\"base_url\"],\n            \"endpoint_id\": detected.get(\"id\", \"\"),\n            \"model\": detected.get(\"model\", \"\"),\n            \"label\": detected.get(\"label\", \"\"),\n            \"key_hash\": key_hash,\n        }\n        _save_provider_state(auth_store, \"zai\", state)\n        logger.info(\"Z.AI: auto-detected endpoint %s (%s)\", detected[\"label\"], detected[\"base_url\"])\n        return detected[\"base_url\"]\n\n    logger.debug(\"Z.AI: probe failed, falling back to default %s\", default_url)\n    return default_url\n\n\n# =============================================================================\n# Error Types\n# =============================================================================\n\nclass AuthError(RuntimeError):\n    \"\"\"Structured auth error with UX mapping hints.\"\"\"\n\n    def __init__(\n        self,\n        message: str,\n        *,\n        provider: str = \"\",\n        code: Optional[str] = None,\n        relogin_required: bool = False,\n    ) -> None:\n        super().__init__(message)\n        self.provider = provider\n        self.code = code\n        self.relogin_required = relogin_required\n\n\ndef format_auth_error(error: Exception) -> str:\n    \"\"\"Map auth failures to concise user-facing guidance.\"\"\"\n    if not isinstance(error, AuthError):\n        return str(error)\n\n    if error.relogin_required:\n        return f\"{error} Run `clawbot model` to re-authenticate.\"\n\n    if error.code == \"subscription_required\":\n        return (\n            \"No active paid subscription found on Soam Portal. \"\n            \"Please purchase/activate a subscription, then retry.\"\n        )\n\n    if error.code == \"insufficient_credits\":\n        return (\n            \"Subscription credits are exhausted. \"\n            \"Top up/renew credits in Soam Portal, then retry.\"\n        )\n\n    if error.code == \"temporarily_unavailable\":\n        return f\"{error} Please retry in a few seconds.\"\n\n    return str(error)\n\n\ndef _token_fingerprint(token: Any) -> Optional[str]:\n    \"\"\"Return a short hash fingerprint for telemetry without leaking token bytes.\"\"\"\n    if not isinstance(token, str):\n        return None\n    cleaned = token.strip()\n    if not cleaned:\n        return None\n    return hashlib.sha256(cleaned.encode(\"utf-8\")).hexdigest()[:12]\n\n\ndef _oauth_trace_enabled() -> bool:\n    raw = os.getenv(\"CLAWBOT_OAUTH_TRACE\", \"\").strip().lower()\n    return raw in {\"1\", \"true\", \"yes\", \"on\"}\n\n\ndef _oauth_trace(event: str, *, sequence_id: Optional[str] = None, **fields: Any) -> None:\n    if not _oauth_trace_enabled():\n        return\n    payload: Dict[str, Any] = {\"event\": event}\n    if sequence_id:\n        payload[\"sequence_id\"] = sequence_id\n    payload.update(fields)\n    logger.info(\"oauth_trace %s\", json.dumps(payload, sort_keys=True, ensure_ascii=False))\n\n\n# =============================================================================\n# Auth Store — persistence layer for ~/.clawbot/auth.json\n# =============================================================================\n\ndef _auth_file_path() -> Path:\n    path = get_clawbot_home() / \"auth.json\"\n    # Seat belt: if pytest is running and CLAWBOT_HOME resolves to the real\n    # user's auth store, refuse rather than silently corrupt it. This catches\n    # tests that forgot to monkeypatch CLAWBOT_HOME, tests invoked without the\n    # clawbotic conftest, or sandbox escapes via threads/subprocesses. In\n    # production (no PYTEST_CURRENT_TEST) this is a single dict lookup.\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_auth = (Path.home() / \".clawbot\" / \"auth.json\").resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_auth:\n            raise RuntimeError(\n                f\"Refusing to touch real user auth store during test run: {path}. \"\n                \"Set CLAWBOT_HOME to a tmp_path in your test fixture, or run \"\n                \"via scripts/run_tests.sh for clawbotic CI-parity env.\"\n            )\n    return path\n\n\ndef _global_auth_file_path() -> Optional[Path]:\n    \"\"\"Return the global-root auth.json when the process is in profile mode.\n\n    Returns ``None`` when the profile and global root resolve to the same\n    directory (classic mode, or custom CLAWBOT_HOME that is not a profile).\n    Used by read-only fallback paths so providers authed at the root are\n    visible to profile processes that haven't configured them locally.\n\n    See issue #18594 follow-up (credential_pool shadowing).\n    \"\"\"\n    try:\n        from clawbot_constants import get_default_clawbot_root\n        global_root = get_default_clawbot_root()\n    except Exception:\n        return None\n    profile_home = get_clawbot_home()\n    try:\n        if profile_home.resolve(strict=False) == global_root.resolve(strict=False):\n            return None\n    except Exception:\n        if profile_home == global_root:\n            return None\n    # No pytest seat belt here: this is a pure read-only path, and\n    # ``_load_global_auth_store()`` wraps the read in a try/except so an\n    # unreadable global file can never break the profile process.  The\n    # write-side seat belt still lives on ``_auth_file_path()`` where it\n    # belongs (that's what protects the real user's auth store from being\n    # corrupted by a mis-configured test).\n    return global_root / \"auth.json\"\n\n\ndef _load_global_auth_store() -> Dict[str, Any]:\n    \"\"\"Load the global-root auth store (read-only fallback).\n\n    Returns an empty dict when no global fallback exists (classic mode,\n    or the global auth.json is absent). Never raises on missing file.\n\n    Seat belt: under pytest, refuses to read the real user's\n    ``~/.clawbot/auth.json`` even when CLAWBOT_HOME is set to a profile\n    path. The clawbotic conftest does not redirect ``HOME``, so\n    ``get_default_clawbot_root()`` for a profile-shaped CLAWBOT_HOME can\n    still resolve to the real user's home on a dev machine. That would\n    leak real credentials into tests. This guard uses the unmodified\n    ``HOME`` env var (what ``os.path.expanduser('~')`` would resolve to),\n    not ``Path.home()``, because ``Path.home`` is sometimes monkeypatched\n    by fixtures that want to relocate the global root to a tmp path.\n    \"\"\"\n    global_path = _global_auth_file_path()\n    if global_path is None or not global_path.exists():\n        return {}\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_env = os.environ.get(\"HOME\", \"\")\n        if real_home_env:\n            real_root = Path(real_home_env) / \".clawbot\" / \"auth.json\"\n            try:\n                if global_path.resolve(strict=False) == real_root.resolve(strict=False):\n                    return {}\n            except Exception:\n                pass\n    try:\n        return _load_auth_store(global_path)\n    except Exception:\n        # A malformed global store must not break profile reads. The\n        # profile's own auth store is still authoritative.\n        return {}\n\n\ndef _auth_lock_path() -> Path:\n    return _auth_file_path().with_suffix(\".lock\")\n\n\n_auth_lock_holder = threading.local()\n\n\n@contextmanager\ndef _file_lock(\n    lock_path: Path,\n    holder: threading.local,\n    timeout_seconds: float,\n    timeout_message: str,\n):\n    \"\"\"Cross-process advisory flock helper.\n\n    Reentrant per-thread via ``holder.depth``. Falls back to a depth-only\n    guard when neither ``fcntl`` nor ``msvcrt`` is available (rare).\n    Callers supply their own ``threading.local`` so independent locks\n    (e.g. profile auth.json vs shared Soam store) don't share reentrancy\n    state — that would let one lock's reentrant acquisition silently skip\n    the other's kernel-level flock.\n    \"\"\"\n    if getattr(holder, \"depth\", 0) > 0:\n        holder.depth += 1\n        try:\n            yield\n        finally:\n            holder.depth -= 1\n        return\n\n    lock_path.parent.mkdir(parents=True, exist_ok=True)\n\n    if fcntl is None and msvcrt is None:\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n        return\n\n    # On Windows, msvcrt.locking needs the file to have content and the\n    # file pointer at position 0. Ensure the lock file has at least 1 byte.\n    if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):\n        lock_path.write_text(\" \", encoding=\"utf-8\")\n\n    with lock_path.open(\"r+\" if msvcrt else \"a+\", encoding=\"utf-8\") as lock_file:\n        deadline = time.monotonic() + max(1.0, timeout_seconds)\n        while True:\n            try:\n                if fcntl:\n                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)\n                else:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)\n                break\n            except (BlockingIOError, OSError, PermissionError):\n                if time.monotonic() >= deadline:\n                    raise TimeoutError(timeout_message)\n                time.sleep(0.05)\n\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n            if fcntl:\n                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n            elif msvcrt:\n                try:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)\n                except (OSError, IOError):\n                    pass\n\n\n@contextmanager\ndef _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-process advisory lock for auth.json reads+writes.  Reentrant.\n\n    Lock ordering invariant: when this lock is held together with\n    ``_soam_shared_store_lock``, acquire ``_auth_store_lock`` FIRST\n    (outer) and the shared Soam lock SECOND (inner). All runtime\n    refresh paths follow this order; violating it risks deadlock\n    against a concurrent import on the shared store.\n    \"\"\"\n    with _file_lock(\n        _auth_lock_path(),\n        _auth_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for auth store lock\",\n    ):\n        yield\n\n\ndef _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:\n    auth_file = auth_file or _auth_file_path()\n    if not auth_file.exists():\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    try:\n        raw = json.loads(auth_file.read_text())\n    except Exception as exc:\n        corrupt_path = auth_file.with_suffix(\".json.corrupt\")\n        try:\n            import shutil\n            shutil.copy2(auth_file, corrupt_path)\n        except Exception:\n            pass\n        logger.warning(\n            \"auth: failed to parse %s (%s) — starting with empty store. \"\n            \"Corrupt file preserved at %s\",\n            auth_file, exc, corrupt_path,\n        )\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    if isinstance(raw, dict) and (\n        isinstance(raw.get(\"providers\"), dict)\n        or isinstance(raw.get(\"credential_pool\"), dict)\n    ):\n        raw.setdefault(\"providers\", {})\n        return raw\n\n    # Migrate from PR's \"systems\" format if present\n    if isinstance(raw, dict) and isinstance(raw.get(\"systems\"), dict):\n        systems = raw[\"systems\"]\n        providers = {}\n        if \"soam_portal\" in systems:\n            providers[\"soam\"] = systems[\"soam_portal\"]\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": providers,\n                \"active_provider\": \"soam\" if providers else None}\n\n    return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n\ndef _save_auth_store(auth_store: Dict[str, Any]) -> Path:\n    auth_file = _auth_file_path()\n    auth_file.parent.mkdir(parents=True, exist_ok=True)\n    # Tighten parent dir to 0o700 so siblings can't traverse to creds.\n    # No-op on Windows (POSIX mode bits not enforced); ignore failures.\n    try:\n        os.chmod(auth_file.parent, 0o700)\n    except OSError:\n        pass\n    auth_store[\"version\"] = AUTH_STORE_VERSION\n    auth_store[\"updated_at\"] = datetime.now(timezone.utc).isoformat()\n    payload = json.dumps(auth_store, indent=2) + \"\\n\"\n    tmp_path = auth_file.with_name(f\"{auth_file.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    try:\n        # Create with 0o600 atomically via os.open(O_EXCL) + fdopen to close\n        # the TOCTOU window where default umask (often 0o644) briefly exposed\n        # OAuth tokens to other local users between open() and chmod().\n        # Mirrors agent/google_oauth.py (#19673) and tools/mcp_oauth.py (#21148).\n        fd = os.open(\n            str(tmp_path),\n            os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n            stat.S_IRUSR | stat.S_IWUSR,\n        )\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as handle:\n            handle.write(payload)\n            handle.flush()\n            os.fsync(handle.fileno())\n        atomic_replace(tmp_path, auth_file)\n        try:\n            dir_fd = os.open(str(auth_file.parent), os.O_RDONLY)\n        except OSError:\n            dir_fd = None\n        if dir_fd is not None:\n            try:\n                os.fsync(dir_fd)\n            finally:\n                os.close(dir_fd)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    # Restrict file permissions to owner only\n    try:\n        auth_file.chmod(stat.S_IRUSR | stat.S_IWUSR)\n    except OSError:\n        pass\n    return auth_file\n\n\ndef _load_provider_state(auth_store: Dict[str, Any], provider_id: str) -> Optional[Dict[str, Any]]:\n    providers = auth_store.get(\"providers\")\n    if not isinstance(providers, dict):\n        return None\n    state = providers.get(provider_id)\n    return dict(state) if isinstance(state, dict) else None\n\n\ndef _save_provider_state(auth_store: Dict[str, Any], provider_id: str, state: Dict[str, Any]) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    auth_store[\"active_provider\"] = provider_id\n\n\ndef _store_provider_state(\n    auth_store: Dict[str, Any],\n    provider_id: str,\n    state: Dict[str, Any],\n    *,\n    set_active: bool = True,\n) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    if set_active:\n        auth_store[\"active_provider\"] = provider_id\n\n\ndef is_known_auth_provider(provider_id: str) -> bool:\n    normalized = (provider_id or \"\").strip().lower()\n    return normalized in PROVIDER_REGISTRY or normalized in SERVICE_PROVIDER_NAMES\n\n\ndef get_auth_provider_display_name(provider_id: str) -> str:\n    normalized = (provider_id or \"\").strip().lower()\n    if normalized in PROVIDER_REGISTRY:\n        return PROVIDER_REGISTRY[normalized].name\n    return SERVICE_PROVIDER_NAMES.get(normalized, provider_id)\n\n\ndef read_credential_pool(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Return the persisted credential pool, or one provider slice.\n\n    In profile mode, the profile's credential pool is authoritative. If a\n    provider has no entries in the profile, entries from the global-root\n    ``auth.json`` are used as a read-only fallback — so workers spawned in a\n    profile can see providers that were only authenticated at global scope.\n\n    Profile entries always win: the global fallback only applies per-provider\n    when the profile has zero entries for that provider. Once the user runs\n    ``clawbot auth add <provider>`` inside the profile, profile entries\n    fully shadow global for that provider on the next read.\n\n    Writes always go to the profile (``write_credential_pool`` is unchanged).\n    See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        pool = {}\n\n    global_pool: Dict[str, Any] = {}\n    global_store = _load_global_auth_store()\n    maybe_global_pool = global_store.get(\"credential_pool\") if global_store else None\n    if isinstance(maybe_global_pool, dict):\n        global_pool = maybe_global_pool\n\n    if provider_id is None:\n        merged = dict(pool)\n        for gp_key, gp_entries in global_pool.items():\n            if not isinstance(gp_entries, list) or not gp_entries:\n                continue\n            # Per-provider shadowing: profile wins whenever it has ANY entries.\n            existing = merged.get(gp_key)\n            if isinstance(existing, list) and existing:\n                continue\n            merged[gp_key] = list(gp_entries)\n        return merged\n\n    provider_entries = pool.get(provider_id)\n    if isinstance(provider_entries, list) and provider_entries:\n        return list(provider_entries)\n    # Profile has no entries for this provider — fall back to global.\n    global_entries = global_pool.get(provider_id)\n    return list(global_entries) if isinstance(global_entries, list) else []\n\n\ndef write_credential_pool(provider_id: str, entries: List[Dict[str, Any]]) -> Path:\n    \"\"\"Persist one provider's credential pool under auth.json.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n        pool[provider_id] = list(entries)\n        return _save_auth_store(auth_store)\n\n\ndef suppress_credential_source(provider_id: str, source: str) -> None:\n    \"\"\"Mark a credential source as suppressed so it won't be re-seeded.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.setdefault(\"suppressed_sources\", {})\n        provider_list = suppressed.setdefault(provider_id, [])\n        if source not in provider_list:\n            provider_list.append(source)\n        _save_auth_store(auth_store)\n\n\ndef is_source_suppressed(provider_id: str, source: str) -> bool:\n    \"\"\"Check if a credential source has been suppressed by the user.\"\"\"\n    try:\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\", {})\n        return source in suppressed.get(provider_id, [])\n    except Exception:\n        return False\n\n\ndef unsuppress_credential_source(provider_id: str, source: str) -> bool:\n    \"\"\"Clear a suppression marker so the source will be re-seeded on the next load.\n\n    Returns True if a marker was cleared, False if no marker existed.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\")\n        if not isinstance(suppressed, dict):\n            return False\n        provider_list = suppressed.get(provider_id)\n        if not isinstance(provider_list, list) or source not in provider_list:\n            return False\n        provider_list.remove(source)\n        if not provider_list:\n            suppressed.pop(provider_id, None)\n        if not suppressed:\n            auth_store.pop(\"suppressed_sources\", None)\n        _save_auth_store(auth_store)\n        return True\n\n\ndef get_provider_auth_state(provider_id: str) -> Optional[Dict[str, Any]]:\n    \"\"\"Return persisted auth state for a provider, or None.\n\n    In profile mode, falls back to the global-root ``auth.json`` when the\n    profile has no state for this provider. Profile state always wins when\n    present. Writes (``_save_auth_store`` / ``persist_*_credentials``) are\n    unchanged — they still target the profile only. This mirrors\n    ``read_credential_pool``'s per-provider shadowing semantics so that\n    ``_seed_from_singletons`` can reseed a profile's credential pool from\n    global-scope provider state (e.g. a globally-authenticated Anthropic\n    OAuth or Soam device-code session). See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, provider_id)\n    if state is not None:\n        return state\n    global_store = _load_global_auth_store()\n    if not global_store:\n        return None\n    return _load_provider_state(global_store, provider_id)\n\n\ndef get_active_provider() -> Optional[str]:\n    \"\"\"Return the currently active provider ID from auth store.\"\"\"\n    auth_store = _load_auth_store()\n    return auth_store.get(\"active_provider\")\n\n\ndef is_provider_explicitly_configured(provider_id: str) -> bool:\n    \"\"\"Return True only if the user has explicitly configured this provider.\n\n    Checks:\n      1. active_provider in auth.json matches\n      2. model.provider in config.yaml matches\n      3. Provider-specific env vars are set (e.g. ANTHROPIC_API_KEY)\n\n    This is used to gate auto-discovery of external credentials (e.g.\n    Claude Code's ~/.claude/.credentials.json) so they are never used\n    without the user's explicit choice.  See PR #4210 for the same\n    pattern applied to the setup wizard gate.\n    \"\"\"\n    normalized = (provider_id or \"\").strip().lower()\n\n    # 1. Check auth.json active_provider\n    try:\n        auth_store = _load_auth_store()\n        active = (auth_store.get(\"active_provider\") or \"\").strip().lower()\n        if active and active == normalized:\n            return True\n    except Exception:\n        pass\n\n    # 2. Check config.yaml model.provider\n    try:\n        from clawbot_cli.config import load_config\n        cfg = load_config()\n        model_cfg = cfg.get(\"model\")\n        if isinstance(model_cfg, dict):\n            cfg_provider = (model_cfg.get(\"provider\") or \"\").strip().lower()\n            if cfg_provider == normalized:\n                return True\n    except Exception:\n        pass\n\n    # 3. Check provider-specific env vars\n    # Exclude CLAUDE_CODE_OAUTH_TOKEN — it's set by Claude Code itself,\n    # not by the user explicitly configuring anthropic in Clawbot.\n    _IMPLICIT_ENV_VARS = {\"CLAUDE_CODE_OAUTH_TOKEN\"}\n    pconfig = PROVIDER_REGISTRY.get(normalized)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        for env_var in pconfig.api_key_env_vars:\n            if env_var in _IMPLICIT_ENV_VARS:\n                continue\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return True\n\n    return False\n\n\ndef clear_provider_auth(provider_id: Optional[str] = None) -> bool:\n    \"\"\"\n    Clear auth state for a provider. Used by `clawbot logout`.\n    If provider_id is None, clears the active provider.\n    Returns True if something was cleared.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        target = provider_id or auth_store.get(\"active_provider\")\n        if not target:\n            return False\n\n        providers = auth_store.get(\"providers\", {})\n        if not isinstance(providers, dict):\n            providers = {}\n            auth_store[\"providers\"] = providers\n\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n\n        cleared = False\n        if target in providers:\n            del providers[target]\n            cleared = True\n        if target in pool:\n            del pool[target]\n            cleared = True\n\n        if auth_store.get(\"active_provider\") == target:\n            auth_store[\"active_provider\"] = None\n            cleared = True\n\n        if not cleared:\n            return False\n        _save_auth_store(auth_store)\n    return True\n\n\ndef deactivate_provider() -> None:\n    \"\"\"\n    Clear active_provider in auth.json without deleting credentials.\n    Used when the user switches to a non-OAuth provider (OpenRouter, custom)\n    so auto-resolution doesn't keep picking the OAuth provider.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = None\n        _save_auth_store(auth_store)\n\n\n# =============================================================================\n# Provider Resolution — picks which provider to use\n# =============================================================================\n\n\ndef _get_config_hint_for_unknown_provider(provider_name: str) -> str:\n    \"\"\"Return a helpful hint string when provider resolution fails.\n\n    Checks for common config.yaml mistakes (malformed custom_providers, etc.)\n    and returns a human-readable diagnostic, or empty string if nothing found.\n    \"\"\"\n    try:\n        from clawbot_cli.config import validate_config_structure\n        issues = validate_config_structure()\n        if not issues:\n            return \"\"\n\n        lines = [\"Config issue detected — run 'clawbot doctor' for full diagnostics:\"]\n        for ci in issues:\n            prefix = \"ERROR\" if ci.severity == \"error\" else \"WARNING\"\n            lines.append(f\"  [{prefix}] {ci.message}\")\n            # Show first line of hint\n            first_hint = ci.hint.splitlines()[0] if ci.hint else \"\"\n            if first_hint:\n                lines.append(f\"    → {first_hint}\")\n        return \"\\n\".join(lines)\n    except Exception:\n        return \"\"\n\n\ndef resolve_provider(\n    requested: Optional[str] = None,\n    *,\n    explicit_api_key: Optional[str] = None,\n    explicit_base_url: Optional[str] = None,\n) -> str:\n    \"\"\"\n    Determine which inference provider to use.\n\n    Priority (when requested=\"auto\" or None):\n    1. active_provider in auth.json with valid credentials\n    2. Explicit CLI api_key/base_url -> \"openrouter\"\n    3. OPENAI_API_KEY or OPENROUTER_API_KEY env vars -> \"openrouter\"\n    4. Provider-specific API keys (GLM, Kimi, MiniMax) -> that provider\n    5. Fallback: \"openrouter\"\n    \"\"\"\n    normalized = (requested or \"auto\").strip().lower()\n\n    # Normalize provider aliases\n    _PROVIDER_ALIASES = {\n        \"glm\": \"zai\", \"z-ai\": \"zai\", \"z.ai\": \"zai\", \"zhipu\": \"zai\",\n        \"google\": \"gemini\", \"google-gemini\": \"gemini\", \"google-ai-studio\": \"gemini\",\n        \"x-ai\": \"xai\", \"x.ai\": \"xai\", \"grok\": \"xai\",\n        \"xai-oauth\": \"xai-oauth\", \"x-ai-oauth\": \"xai-oauth\",\n        \"grok-oauth\": \"xai-oauth\", \"xai-grok-oauth\": \"xai-oauth\",\n        \"kimi\": \"kimi-coding\", \"kimi-for-coding\": \"kimi-coding\", \"moonshot\": \"kimi-coding\",\n        \"kimi-cn\": \"kimi-coding-cn\", \"moonshot-cn\": \"kimi-coding-cn\",\n        \"step\": \"stepfun\", \"stepfun-coding-plan\": \"stepfun\",\n        \"arcee-ai\": \"arcee\", \"arceeai\": \"arcee\",\n        \"gmi-cloud\": \"gmi\", \"gmicloud\": \"gmi\",\n        \"minimax-china\": \"minimax-cn\", \"minimax_cn\": \"minimax-cn\",\n        \"minimax-portal\": \"minimax-oauth\", \"minimax-global\": \"minimax-oauth\", \"minimax_oauth\": \"minimax-oauth\",\n        \"alibaba_coding\": \"alibaba-coding-plan\", \"alibaba-coding\": \"alibaba-coding-plan\",\n        \"alibaba_coding_plan\": \"alibaba-coding-plan\",\n        \"claude\": \"anthropic\", \"claude-code\": \"anthropic\",\n        \"github\": \"copilot\", \"github-copilot\": \"copilot\",\n        \"github-models\": \"copilot\", \"github-model\": \"copilot\",\n        \"github-copilot-acp\": \"copilot-acp\", \"copilot-acp-agent\": \"copilot-acp\",\n        \"aigateway\": \"ai-gateway\", \"vercel\": \"ai-gateway\", \"vercel-ai-gateway\": \"ai-gateway\",\n        \"opencode\": \"opencode-zen\", \"zen\": \"opencode-zen\",\n        \"qwen-portal\": \"qwen-oauth\", \"qwen-cli\": \"qwen-oauth\", \"qwen-oauth\": \"qwen-oauth\", \"google-gemini-cli\": \"google-gemini-cli\", \"gemini-cli\": \"google-gemini-cli\", \"gemini-oauth\": \"google-gemini-cli\",\n        \"hf\": \"huggingface\", \"hugging-face\": \"huggingface\", \"huggingface-hub\": \"huggingface\",\n        \"mimo\": \"xiaomi\", \"xiaomi-mimo\": \"xiaomi\",\n        \"tencent\": \"tencent-tokenhub\", \"tokenhub\": \"tencent-tokenhub\",\n        \"tencent-cloud\": \"tencent-tokenhub\", \"tencentmaas\": \"tencent-tokenhub\",\n        \"aws\": \"bedrock\", \"aws-bedrock\": \"bedrock\", \"amazon-bedrock\": \"bedrock\", \"amazon\": \"bedrock\",\n        \"go\": \"opencode-go\", \"opencode-go-sub\": \"opencode-go\",\n        \"kilo\": \"kilocode\", \"kilo-code\": \"kilocode\", \"kilo-gateway\": \"kilocode\",\n        \"lmstudio\": \"lmstudio\", \"lm-studio\": \"lmstudio\", \"lm_studio\": \"lmstudio\",\n        # Local server aliases — route through the generic custom provider\n        \"ollama\": \"custom\", \"ollama_cloud\": \"ollama-cloud\",\n        \"vllm\": \"custom\", \"llamacpp\": \"custom\",\n        \"llama.cpp\": \"custom\", \"llama-cpp\": \"custom\",\n    }\n    # Extend with aliases declared in plugins/model-providers/<name>/ that aren't already mapped.\n    # This keeps providers/ as the single source for new aliases while the\n    # hardcoded dict above remains authoritative for existing ones.\n    try:\n        from providers import list_providers as _lp\n        for _pp in _lp():\n            for _alias in _pp.aliases:\n                if _alias not in _PROVIDER_ALIASES:\n                    _PROVIDER_ALIASES[_alias] = _pp.name\n    except Exception:\n        pass\n    normalized = _PROVIDER_ALIASES.get(normalized, normalized)\n\n    if normalized == \"openrouter\":\n        return \"openrouter\"\n    if normalized == \"custom\":\n        return \"custom\"\n    if normalized in PROVIDER_REGISTRY:\n        return normalized\n    if normalized != \"auto\":\n        # Check for common config.yaml issues that cause this error\n        _config_hint = _get_config_hint_for_unknown_provider(normalized)\n        msg = f\"Unknown provider '{normalized}'.\"\n        if _config_hint:\n            msg += f\"\\n\\n{_config_hint}\"\n        else:\n            msg += \" Check 'clawbot model' for available providers, or run 'clawbot doctor' to diagnose config issues.\"\n        raise AuthError(msg, code=\"invalid_provider\")\n\n    # Explicit one-off CLI creds always mean openrouter/custom\n    if explicit_api_key or explicit_base_url:\n        return \"openrouter\"\n\n    # Check auth store for an active OAuth provider\n    try:\n        auth_store = _load_auth_store()\n        active = auth_store.get(\"active_provider\")\n        if active and active in PROVIDER_REGISTRY:\n            status = get_auth_status(active)\n            if status.get(\"logged_in\"):\n                return active\n    except Exception as e:\n        logger.debug(\"Could not detect active auth provider: %s\", e)\n\n    if has_usable_secret(os.getenv(\"OPENAI_API_KEY\")) or has_usable_secret(os.getenv(\"OPENROUTER_API_KEY\")):\n        return \"openrouter\"\n\n    # Auto-detect API-key providers by checking their env vars\n    for pid, pconfig in PROVIDER_REGISTRY.items():\n        if pconfig.auth_type != \"api_key\":\n            continue\n        # GitHub tokens are commonly present for repo/tool access but should not\n        # hijack inference auto-selection unless the user explicitly chooses\n        # Copilot/GitHub Models as the provider. LM Studio is a local server\n        # whose availability isn't implied by LM_API_KEY presence (it may be\n        # offline, and the no-auth setup uses a placeholder value), so it\n        # also requires explicit selection.\n        if pid in {\"copilot\", \"lmstudio\"}:\n            continue\n        for env_var in pconfig.api_key_env_vars:\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return pid\n\n    # AWS Bedrock — detect via boto3 credential chain (IAM roles, SSO, env vars).\n    # This runs after API-key providers so explicit keys always win.\n    try:\n        from agent.bedrock_adapter import has_aws_credentials\n        if has_aws_credentials():\n            return \"bedrock\"\n    except ImportError:\n        pass  # boto3 not installed — skip Bedrock auto-detection\n\n    raise AuthError(\n        \"No inference provider configured. Run 'clawbot model' to choose a \"\n        \"provider and model, or set an API key (OPENROUTER_API_KEY, \"\n        \"OPENAI_API_KEY, etc.) in ~/.clawbot/.env.\",\n        code=\"no_provider_configured\",\n    )\n\n\n# =============================================================================\n# Timestamp / TTL helpers\n# =============================================================================\n\ndef _parse_iso_timestamp(value: Any) -> Optional[float]:\n    if not isinstance(value, str) or not value:\n        return None\n    text = value.strip()\n    if not text:\n        return None\n    if text.endswith(\"Z\"):\n        text = text[:-1] + \"+00:00\"\n    try:\n        parsed = datetime.fromisoformat(text)\n    except Exception:\n        return None\n    if parsed.tzinfo is None:\n        parsed = parsed.replace(tzinfo=timezone.utc)\n    return parsed.timestamp()\n\n\ndef _is_expiring(expires_at_iso: Any, skew_seconds: int) -> bool:\n    expires_epoch = _parse_iso_timestamp(expires_at_iso)\n    if expires_epoch is None:\n        return True\n    return expires_epoch <= (time.time() + skew_seconds)\n\n\ndef _coerce_ttl_seconds(expires_in: Any) -> int:\n    try:\n        ttl = int(expires_in)\n    except Exception:\n        ttl = 0\n    return max(0, ttl)\n\n\ndef _optional_base_url(value: Any) -> Optional[str]:\n    if not isinstance(value, str):\n        return None\n    cleaned = value.strip().rstrip(\"/\")\n    return cleaned if cleaned else None\n\n\ndef _decode_jwt_claims(token: Any) -> Dict[str, Any]:\n    if not isinstance(token, str) or token.count(\".\") != 2:\n        return {}\n    payload = token.split(\".\")[1]\n    payload += \"=\" * ((4 - len(payload) % 4) % 4)\n    try:\n        raw = base64.urlsafe_b64decode(payload.encode(\"utf-8\"))\n        claims = json.loads(raw.decode(\"utf-8\"))\n    except Exception:\n        return {}\n    return claims if isinstance(claims, dict) else {}\n\n\ndef _scope_values(raw_scope: Any) -> set[str]:\n    # OAuth token responses normally return a space-separated string. Keep\n    # collection support for JWT ``scp`` claims and older stored test fixtures.\n    scopes: set[str] = set()\n    if isinstance(raw_scope, str):\n        for part in raw_scope.replace(\",\", \" \").split():\n            cleaned = part.strip()\n            if cleaned:\n                scopes.add(cleaned)\n    elif isinstance(raw_scope, (list, tuple, set, frozenset)):\n        for item in raw_scope:\n            if isinstance(item, str):\n                scopes.update(_scope_values(item))\n    return scopes\n\n\ndef _soam_legacy_session_keys_forced() -> bool:\n    return is_truthy_value(os.getenv(SOAM_LEGACY_SESSION_KEYS_ENV), default=False)\n\n\ndef _soam_scope_has_invoke(raw_scope: Any) -> bool:\n    return SOAM_INFERENCE_INVOKE_SCOPE in _scope_values(raw_scope)\n\n\ndef _normalize_soam_inference_auth_mode(inference_auth_mode: Optional[str]) -> str:\n    mode = str(inference_auth_mode or SOAM_INFERENCE_AUTH_MODE_AUTO).strip().lower()\n    if mode not in SOAM_INFERENCE_AUTH_MODES:\n        allowed = \", \".join(sorted(SOAM_INFERENCE_AUTH_MODES))\n        raise ValueError(\n            \"Invalid Soam inference auth mode \"\n            f\"{inference_auth_mode!r}; expected one of: {allowed}\"\n        )\n    return mode\n\n\ndef _soam_invoke_jwt_status(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> Optional[str]:\n    \"\"\"Return None when the token can be used for inference, else a reason.\"\"\"\n    claims = _decode_jwt_claims(token)\n    if not claims:\n        return \"access_token_not_jwt\"\n    scopes = (\n        _scope_values(scope)\n        | _scope_values(claims.get(\"scope\"))\n        | _scope_values(claims.get(\"scp\"))\n    )\n    if SOAM_INFERENCE_INVOKE_SCOPE not in scopes:\n        return \"missing_inference_invoke_scope\"\n    exp = claims.get(\"exp\")\n    skew = max(0, int(min_ttl_seconds))\n    if isinstance(exp, (int, float)):\n        if float(exp) <= (time.time() + skew):\n            return \"invoke_jwt_expiring\"\n        return None\n    if _is_expiring(expires_at, skew):\n        return \"invoke_jwt_expiry_unknown_or_expiring\"\n    return None\n\n\ndef _soam_invoke_jwt_is_usable(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> bool:\n    return (\n        _soam_invoke_jwt_status(\n            token,\n            scope=scope,\n            expires_at=expires_at,\n            min_ttl_seconds=min_ttl_seconds,\n        )\n        is None\n    )\n\n\ndef _soam_legacy_session_key_reason(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> str:\n    if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY:\n        return \"forced_legacy_session_key\"\n    if _soam_legacy_session_keys_forced():\n        return \"forced_legacy_session_keys\"\n    return (\n        _soam_invoke_jwt_status(token, scope=scope, expires_at=expires_at)\n        or \"invoke_jwt_unavailable\"\n    )\n\n\ndef _choose_soam_inference_auth_path(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Tuple[str, Optional[str]]:\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    token = state.get(\"access_token\") if access_token is None else access_token\n    if (\n        not _soam_legacy_session_keys_forced()\n        and inference_auth_mode != SOAM_INFERENCE_AUTH_MODE_LEGACY\n        and _soam_invoke_jwt_is_usable(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n        )\n    ):\n        return SOAM_AUTH_PATH_INVOKE_JWT, None\n    if (\n        inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_AUTO\n        and _agent_key_is_usable(\n            state,\n            max(60, int(min_key_ttl_seconds)),\n        )\n    ):\n        return SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE, None\n    return (\n        SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT,\n        _soam_legacy_session_key_reason(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n            inference_auth_mode=inference_auth_mode,\n        ),\n    )\n\n\ndef _log_soam_invoke_jwt_selected(\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\"Soam inference auth: using NAS invoke JWT\")\n    _oauth_trace(\n        \"soam_invoke_jwt_selected\",\n        sequence_id=sequence_id,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _log_soam_legacy_session_key_selected(\n    reason: str,\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\n        \"Soam inference auth: using legacy session key path (%s)\",\n        reason,\n    )\n    _oauth_trace(\n        \"soam_legacy_session_key_selected\",\n        sequence_id=sequence_id,\n        reason=reason,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _soam_jwt_expires_at(token: Any, fallback_expires_at: Any = None) -> Optional[str]:\n    claims = _decode_jwt_claims(token)\n    exp = claims.get(\"exp\")\n    if isinstance(exp, (int, float)):\n        try:\n            return datetime.fromtimestamp(float(exp), tz=timezone.utc).isoformat()\n        except Exception:\n            pass\n    return fallback_expires_at if isinstance(fallback_expires_at, str) else None\n\n\ndef _set_soam_agent_key_from_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    obtained_at: Optional[str] = None,\n) -> None:\n    access_token = state.get(\"access_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        return\n    now = datetime.now(timezone.utc)\n    existing_obtained_at = state.get(\"agent_key_obtained_at\")\n    if obtained_at:\n        effective_obtained_at = obtained_at\n    elif (\n        state.get(\"agent_key\") == access_token\n        and isinstance(existing_obtained_at, str)\n        and existing_obtained_at.strip()\n    ):\n        effective_obtained_at = existing_obtained_at\n    else:\n        effective_obtained_at = now.isoformat()\n    expires_at = _soam_jwt_expires_at(access_token, state.get(\"expires_at\"))\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"expires_in\"))\n    )\n    if expires_at:\n        state[\"expires_at\"] = expires_at\n        state[\"expires_in\"] = expires_in\n    state[\"agent_key\"] = access_token\n    state[\"agent_key_id\"] = None\n    state[\"agent_key_expires_at\"] = expires_at\n    state[\"agent_key_expires_in\"] = expires_in\n    state[\"agent_key_reused\"] = False\n    state[\"agent_key_obtained_at\"] = effective_obtained_at\n\n\ndef _select_soam_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    sequence_id: Optional[str] = None,\n) -> None:\n    if isinstance(access_token, str) and access_token.strip():\n        state[\"access_token\"] = access_token\n    _set_soam_agent_key_from_invoke_jwt(state)\n    _log_soam_invoke_jwt_selected(\n        access_token=state.get(\"access_token\"),\n        sequence_id=sequence_id,\n    )\n\n\n_SOAM_EFFECTIVE_STATE_IGNORED_KEYS = frozenset({\n    # These are derived from expires_at/JWT exp and naturally tick down between\n    # reads. Persisting only these changes makes auth.json noisy and defeats\n    # the mtime-keyed auth-status cache.\n    \"expires_in\",\n    \"agent_key_expires_in\",\n})\n\n\ndef _soam_effective_provider_state(state: Dict[str, Any]) -> Dict[str, Any]:\n    return {\n        key: value\n        for key, value in state.items()\n        if key not in _SOAM_EFFECTIVE_STATE_IGNORED_KEYS\n    }\n\n\ndef _codex_access_token_is_expiring(access_token: Any, skew_seconds: int) -> bool:\n    claims = _decode_jwt_claims(access_token)\n    exp = claims.get(\"exp\")\n    if not isinstance(exp, (int, float)):\n        return False\n    return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n\n\ndef _qwen_cli_auth_path() -> Path:\n    return Path.home() / \".qwen\" / \"oauth_creds.json\"\n\n\ndef _read_qwen_cli_tokens() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    if not auth_path.exists():\n        raise AuthError(\n            \"Qwen CLI credentials not found. Run 'qwen auth qwen-oauth' first.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_missing\",\n        )\n    try:\n        data = json.loads(auth_path.read_text(encoding=\"utf-8\"))\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to read Qwen CLI credentials from {auth_path}: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_read_failed\",\n        ) from exc\n    if not isinstance(data, dict):\n        raise AuthError(\n            f\"Invalid Qwen CLI credentials in {auth_path}.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_invalid\",\n        )\n    return data\n\n\ndef _save_qwen_cli_tokens(tokens: Dict[str, Any]) -> Path:\n    auth_path = _qwen_cli_auth_path()\n    auth_path.parent.mkdir(parents=True, exist_ok=True)\n    try:\n        os.chmod(auth_path.parent, 0o700)\n    except OSError:\n        pass\n    # Per-process random temp suffix avoids collisions between concurrent\n    # writers and stale leftovers from a crashed prior write.\n    tmp_path = auth_path.with_name(f\"{auth_path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n    # window where write_text() + post-write chmod briefly exposed tokens\n    # at process umask (typically 0o644). See #19673, #21148.\n    fd = os.open(\n        str(tmp_path),\n        os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n        stat.S_IRUSR | stat.S_IWUSR,\n    )\n    try:\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n            fh.write(json.dumps(tokens, indent=2, sort_keys=True) + \"\\n\")\n            fh.flush()\n            os.fsync(fh.fileno())\n        atomic_replace(tmp_path, auth_path)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    return auth_path\n\n\ndef _qwen_access_token_is_expiring(expiry_date_ms: Any, skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS) -> bool:\n    try:\n        expiry_ms = int(expiry_date_ms)\n    except Exception:\n        return True\n    return (time.time() + max(0, int(skew_seconds))) * 1000 >= expiry_ms\n\n\ndef _refresh_qwen_cli_tokens(tokens: Dict[str, Any], timeout_seconds: float = 20.0) -> Dict[str, Any]:\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Qwen OAuth refresh token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_token_missing\",\n        )\n\n    try:\n        response = httpx.post(\n            QWEN_OAUTH_TOKEN_URL,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": QWEN_OAUTH_CLIENT_ID,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh failed: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        body = response.text.strip()\n        raise AuthError(\n            \"Qwen OAuth refresh failed. Re-run 'qwen auth qwen-oauth'.\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh returned invalid JSON: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_json\",\n        ) from exc\n\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Qwen OAuth refresh response missing access_token.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_response\",\n        )\n\n    expires_in = payload.get(\"expires_in\")\n    try:\n        expires_in_seconds = int(expires_in)\n    except Exception:\n        expires_in_seconds = 6 * 60 * 60\n\n    refreshed = {\n        \"access_token\": str(payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(payload.get(\"refresh_token\", refresh_token) or refresh_token).strip(),\n        \"token_type\": str(payload.get(\"token_type\", tokens.get(\"token_type\", \"Bearer\")) or \"Bearer\").strip() or \"Bearer\",\n        \"resource_url\": str(payload.get(\"resource_url\", tokens.get(\"resource_url\", \"portal.qwen.ai\")) or \"portal.qwen.ai\").strip(),\n        \"expiry_date\": int(time.time() * 1000) + max(1, expires_in_seconds) * 1000,\n    }\n    _save_qwen_cli_tokens(refreshed)\n    return refreshed\n\n\ndef resolve_qwen_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    tokens = _read_qwen_cli_tokens()\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    should_refresh = bool(force_refresh)\n    if not should_refresh and refresh_if_expiring:\n        should_refresh = _qwen_access_token_is_expiring(tokens.get(\"expiry_date\"), refresh_skew_seconds)\n    if should_refresh:\n        tokens = _refresh_qwen_cli_tokens(tokens)\n        access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Qwen OAuth access token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_access_token_missing\",\n        )\n\n    base_url = os.getenv(\"CLAWBOT_QWEN_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_QWEN_BASE_URL\n    return {\n        \"provider\": \"qwen-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"qwen-cli\",\n        \"expires_at_ms\": tokens.get(\"expiry_date\"),\n        \"auth_file\": str(_qwen_cli_auth_path()),\n    }\n\n\ndef get_qwen_auth_status() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    try:\n        creds = resolve_qwen_runtime_credentials(refresh_if_expiring=False)\n        return {\n            \"logged_in\": True,\n            \"auth_file\": str(auth_path),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n            \"expires_at_ms\": creds.get(\"expires_at_ms\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": str(exc),\n        }\n\n\n# =============================================================================\n# Google Gemini OAuth (google-gemini-cli) — PKCE flow + Cloud Code Assist.\n#\n# Tokens live in ~/.clawbot/auth/google_oauth.json (managed by agent.google_oauth).\n# The `base_url` here is the marker \"cloudcode-pa://google\" that run_agent.py\n# uses to construct a GeminiCloudCodeClient instead of the default OpenAI SDK.\n# Actual HTTP traffic goes to https://cloudcode-pa.googleapis.com/v1internal:*.\n# =============================================================================\n\ndef resolve_gemini_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime OAuth creds for google-gemini-cli.\"\"\"\n    try:\n        from agent.google_oauth import (\n            GoogleOAuthError,\n            _credentials_path,\n            get_valid_access_token,\n            load_credentials,\n        )\n    except ImportError as exc:\n        raise AuthError(\n            f\"agent.google_oauth is not importable: {exc}\",\n            provider=\"google-gemini-cli\",\n            code=\"google_oauth_module_missing\",\n        ) from exc\n\n    try:\n        access_token = get_valid_access_token(force_refresh=force_refresh)\n    except GoogleOAuthError as exc:\n        raise AuthError(\n            str(exc),\n            provider=\"google-gemini-cli\",\n            code=exc.code,\n        ) from exc\n\n    creds = load_credentials()\n    base_url = DEFAULT_GEMINI_CLOUDCODE_BASE_URL\n    return {\n        \"provider\": \"google-gemini-cli\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"google-oauth\",\n        \"expires_at_ms\": (creds.expires_ms if creds else None),\n        \"auth_file\": str(_credentials_path()),\n        \"email\": (creds.email if creds else \"\") or \"\",\n        \"project_id\": (creds.project_id if creds else \"\") or \"\",\n    }\n\n\ndef get_gemini_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return a status dict for `clawbot auth list` / `clawbot status`.\"\"\"\n    try:\n        from agent.google_oauth import _credentials_path, load_credentials\n    except ImportError:\n        return {\"logged_in\": False, \"error\": \"agent.google_oauth unavailable\"}\n    auth_path = _credentials_path()\n    creds = load_credentials()\n    if creds is None or not creds.access_token:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": \"not logged in\",\n        }\n    return {\n        \"logged_in\": True,\n        \"auth_file\": str(auth_path),\n        \"source\": \"google-oauth\",\n        \"api_key\": creds.access_token,\n        \"expires_at_ms\": creds.expires_ms,\n        \"email\": creds.email,\n        \"project_id\": creds.project_id,\n    }\n# Spotify auth — PKCE tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\n\ndef _spotify_scope_list(raw_scope: Optional[str] = None) -> List[str]:\n    scope_text = (raw_scope or DEFAULT_SPOTIFY_SCOPE).strip()\n    scopes = [part for part in scope_text.split() if part]\n    seen: set[str] = set()\n    ordered: List[str] = []\n    for scope in scopes:\n        if scope not in seen:\n            seen.add(scope)\n            ordered.append(scope)\n    return ordered\n\n\ndef _spotify_scope_string(raw_scope: Optional[str] = None) -> str:\n    return \" \".join(_spotify_scope_list(raw_scope))\n\n\ndef _spotify_client_id(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\"),\n        get_env_value(\"SPOTIFY_CLIENT_ID\"),\n        state.get(\"client_id\") if isinstance(state, dict) else None,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    raise AuthError(\n        \"Spotify client_id is required. Set CLAWBOT_SPOTIFY_CLIENT_ID or pass --client-id.\",\n        provider=\"spotify\",\n        code=\"spotify_client_id_missing\",\n    )\n\n\ndef _spotify_redirect_uri(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\"),\n        get_env_value(\"SPOTIFY_REDIRECT_URI\"),\n        state.get(\"redirect_uri\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_REDIRECT_URI,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_REDIRECT_URI\n\n\ndef _spotify_api_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_API_BASE_URL\"),\n        state.get(\"api_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_API_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_API_BASE_URL\n\n\ndef _spotify_accounts_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_ACCOUNTS_BASE_URL\"),\n        state.get(\"accounts_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL\n\n\ndef _spotify_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _spotify_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _oauth_pkce_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _oauth_pkce_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _spotify_build_authorize_url(\n    *,\n    client_id: str,\n    redirect_uri: str,\n    scope: str,\n    state: str,\n    code_challenge: str,\n    accounts_base_url: str,\n) -> str:\n    query = urlencode({\n        \"client_id\": client_id,\n        \"response_type\": \"code\",\n        \"redirect_uri\": redirect_uri,\n        \"scope\": scope,\n        \"state\": state,\n        \"code_challenge_method\": \"S256\",\n        \"code_challenge\": code_challenge,\n    })\n    return f\"{accounts_base_url}/authorize?{query}\"\n\n\ndef _spotify_validate_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must use http://localhost or http://127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host not in {\"127.0.0.1\", \"localhost\"}:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must point to localhost or 127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must include an explicit localhost port.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _make_spotify_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _SpotifyCallbackHandler(BaseHTTPRequestHandler):\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>Spotify authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>Spotify authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _SpotifyCallbackHandler, result\n\n\ndef _spotify_wait_for_callback(\n    redirect_uri: str,\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    host, port, path = _spotify_validate_redirect_uri(redirect_uri)\n    handler_cls, result = _make_spotify_callback_handler(path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    try:\n        server = _ReuseHTTPServer((host, port), handler_cls)\n    except OSError as exc:\n        raise AuthError(\n            f\"Could not bind Spotify callback server on {host}:{port}: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_callback_bind_failed\",\n        ) from exc\n\n    thread = threading.Thread(target=server.serve_forever, kwargs={\"poll_interval\": 0.1}, daemon=True)\n    thread.start()\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"Spotify authorization timed out waiting for the local callback.\",\n        provider=\"spotify\",\n        code=\"spotify_callback_timeout\",\n    )\n\n\ndef _xai_validate_loopback_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"xAI OAuth redirect_uri must use http://127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host != XAI_OAUTH_REDIRECT_HOST:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must point to 127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must include an explicit localhost port.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _xai_callback_cors_origin(origin: Optional[str]) -> str:\n    # CORS allowlist for the loopback callback.  Only xAI's own auth origins\n    # are accepted; the redirect_uri itself is bound to 127.0.0.1 and gated by\n    # PKCE+state, so additional dev/3p origins are not needed here.\n    allowed = {\n        \"https://accounts.x.ai\",\n        \"https://auth.x.ai\",\n    }\n    return origin if origin in allowed else \"\"\n\n\ndef _make_xai_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _XAICallbackHandler(BaseHTTPRequestHandler):\n        def _maybe_write_cors_headers(self) -> None:\n            origin = self.headers.get(\"Origin\")\n            allow_origin = _xai_callback_cors_origin(origin)\n            if allow_origin:\n                self.send_header(\"Access-Control-Allow-Origin\", allow_origin)\n                self.send_header(\"Access-Control-Allow-Methods\", \"GET, OPTIONS\")\n                self.send_header(\"Access-Control-Allow-Headers\", \"Content-Type\")\n                self.send_header(\"Access-Control-Allow-Private-Network\", \"true\")\n                self.send_header(\"Vary\", \"Origin\")\n\n        def do_OPTIONS(self) -> None:  # noqa: N802\n            self.send_response(204)\n            self._maybe_write_cors_headers()\n            self.end_headers()\n\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self._maybe_write_cors_headers()\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>xAI authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _XAICallbackHandler, result\n\n\ndef _xai_start_callback_server(\n    preferred_port: int = XAI_OAUTH_REDIRECT_PORT,\n) -> tuple[HTTPServer, threading.Thread, dict[str, Any], str]:\n    host = XAI_OAUTH_REDIRECT_HOST\n    expected_path = XAI_OAUTH_REDIRECT_PATH\n    handler_cls, result = _make_xai_callback_handler(expected_path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    ports_to_try = [preferred_port]\n    if preferred_port != 0:\n        ports_to_try.append(0)\n    server = None\n    last_error: Optional[OSError] = None\n    for port in ports_to_try:\n        try:\n            server = _ReuseHTTPServer((host, port), handler_cls)\n            break\n        except OSError as exc:\n            last_error = exc\n    if server is None:\n        raise AuthError(\n            f\"Could not bind xAI callback server on {host}:{preferred_port}: {last_error}\",\n            provider=\"xai-oauth\",\n            code=\"xai_callback_bind_failed\",\n        ) from last_error\n\n    actual_port = int(server.server_address[1])\n    redirect_uri = f\"http://{host}:{actual_port}{expected_path}\"\n    thread = threading.Thread(\n        target=server.serve_forever,\n        kwargs={\"poll_interval\": 0.1},\n        daemon=True,\n    )\n    thread.start()\n    return server, thread, result, redirect_uri\n\n\ndef _xai_wait_for_callback(\n    server: HTTPServer,\n    thread: threading.Thread,\n    result: dict[str, Any],\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"xAI authorization timed out waiting for the local callback.\",\n        provider=\"xai-oauth\",\n        code=\"xai_callback_timeout\",\n    )\n\n\ndef _spotify_token_payload_to_state(\n    token_payload: Dict[str, Any],\n    *,\n    client_id: str,\n    redirect_uri: str,\n    requested_scope: str,\n    accounts_base_url: str,\n    api_base_url: str,\n    previous_state: Optional[Dict[str, Any]] = None,\n) -> Dict[str, Any]:\n    now = datetime.now(timezone.utc)\n    expires_in = _coerce_ttl_seconds(token_payload.get(\"expires_in\", 0))\n    expires_at = datetime.fromtimestamp(now.timestamp() + expires_in, tz=timezone.utc)\n    state = dict(previous_state or {})\n    state.update({\n        \"client_id\": client_id,\n        \"redirect_uri\": redirect_uri,\n        \"accounts_base_url\": accounts_base_url,\n        \"api_base_url\": api_base_url,\n        \"scope\": requested_scope,\n        \"granted_scope\": str(token_payload.get(\"scope\") or requested_scope).strip(),\n        \"token_type\": str(token_payload.get(\"token_type\", \"Bearer\") or \"Bearer\").strip() or \"Bearer\",\n        \"access_token\": str(token_payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(\n            token_payload.get(\"refresh_token\")\n            or state.get(\"refresh_token\")\n            or \"\"\n        ).strip(),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": expires_at.isoformat(),\n        \"expires_in\": expires_in,\n        \"auth_type\": \"oauth_pkce\",\n    })\n    return state\n\n\ndef _spotify_exchange_code_for_tokens(\n    *,\n    client_id: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    accounts_base_url: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"client_id\": client_id,\n                \"grant_type\": \"authorization_code\",\n                \"code\": code,\n                \"redirect_uri\": redirect_uri,\n                \"code_verifier\": code_verifier,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token exchange failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token exchange failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        )\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify token response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _refresh_spotify_oauth_state(\n    state: Dict[str, Any],\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Spotify refresh token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_token_missing\",\n            relogin_required=True,\n        )\n\n    client_id = _spotify_client_id(state=state)\n    accounts_base_url = _spotify_accounts_base_url(state)\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": client_id,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token refresh failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token refresh failed. Run `clawbot auth spotify` again.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n            relogin_required=True,\n        )\n\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify refresh response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_invalid\",\n            relogin_required=True,\n        )\n\n    return _spotify_token_payload_to_state(\n        payload,\n        client_id=client_id,\n        redirect_uri=_spotify_redirect_uri(state=state),\n        requested_scope=str(state.get(\"scope\") or DEFAULT_SPOTIFY_SCOPE),\n        accounts_base_url=accounts_base_url,\n        api_base_url=_spotify_api_base_url(state),\n        previous_state=state,\n    )\n\n\ndef resolve_spotify_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = SPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"spotify\")\n        if not state:\n            raise AuthError(\n                \"Spotify is not authenticated. Run `clawbot auth spotify` first.\",\n                provider=\"spotify\",\n                code=\"spotify_auth_missing\",\n                relogin_required=True,\n            )\n\n        should_refresh = bool(force_refresh)\n        if not should_refresh and refresh_if_expiring:\n            should_refresh = _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds)\n        if should_refresh:\n            state = _refresh_spotify_oauth_state(state)\n            _store_provider_state(auth_store, \"spotify\", state, set_active=False)\n            _save_auth_store(auth_store)\n\n    access_token = str(state.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Spotify access token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_access_token_missing\",\n            relogin_required=True,\n        )\n\n    return {\n        \"provider\": \"spotify\",\n        \"access_token\": access_token,\n        \"api_key\": access_token,\n        \"token_type\": str(state.get(\"token_type\", \"Bearer\") or \"Bearer\"),\n        \"base_url\": _spotify_api_base_url(state),\n        \"scope\": str(state.get(\"granted_scope\") or state.get(\"scope\") or \"\").strip(),\n        \"client_id\": _spotify_client_id(state=state),\n        \"redirect_uri\": _spotify_redirect_uri(state=state),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"refresh_token\": str(state.get(\"refresh_token\", \"\") or \"\").strip(),\n    }\n\n\ndef get_spotify_auth_status() -> Dict[str, Any]:\n    state = get_provider_auth_state(\"spotify\")\n    if not state:\n        return {\"logged_in\": False}\n\n    expires_at = state.get(\"expires_at\")\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    return {\n        \"logged_in\": bool(refresh_token or not _is_expiring(expires_at, 0)),\n        \"auth_type\": state.get(\"auth_type\", \"oauth_pkce\"),\n        \"client_id\": state.get(\"client_id\"),\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n        \"scope\": state.get(\"granted_scope\") or state.get(\"scope\"),\n        \"expires_at\": expires_at,\n        \"api_base_url\": state.get(\"api_base_url\"),\n        \"has_refresh_token\": bool(refresh_token),\n    }\n\n\ndef _spotify_interactive_setup(redirect_uri_hint: str) -> str:\n    \"\"\"Walk the user through creating a Spotify developer app, persist the\n    resulting client_id to ~/.clawbot/.env, and return it.\n\n    Raises SystemExit if the user aborts or submits an empty value.\n    \"\"\"\n    from clawbot_cli.config import save_env_value\n\n    print()\n    print(\"=\" * 70)\n    print(\"Spotify first-time setup\")\n    print(\"=\" * 70)\n    print()\n    print(\"Spotify requires every user to register their own lightweight\")\n    print(\"developer app. This takes about two minutes and only has to be\")\n    print(\"done once per machine.\")\n    print()\n    print(f\"Full guide: {SPOTIFY_DOCS_URL}\")\n    print()\n    print(\"Steps:\")\n    print(f\"  1. Opening {SPOTIFY_DASHBOARD_URL} in your browser...\")\n    print(\"  2. Click 'Create app' and fill in:\")\n    print(\"       App name:     anything (e.g. clawbot-agent)\")\n    print(\"       Description:  anything\")\n    print(f\"       Redirect URI: {redirect_uri_hint}\")\n    print(\"       API/SDK:      Web API\")\n    print(\"  3. Agree to the terms, click Save.\")\n    print(\"  4. Open the app's Settings page and copy the Client ID.\")\n    print(\"  5. Paste it below.\")\n    print()\n\n    if not _is_remote_session():\n        try:\n            webbrowser.open(SPOTIFY_DASHBOARD_URL)\n        except Exception:\n            pass\n\n    try:\n        raw = input(\"Spotify Client ID: \").strip()\n    except (EOFError, KeyboardInterrupt):\n        print()\n        raise SystemExit(\"Spotify setup cancelled.\")\n\n    if not raw:\n        print()\n        print(f\"No Client ID entered. See {SPOTIFY_DOCS_URL} for the full guide.\")\n        raise SystemExit(\"Spotify setup cancelled: empty Client ID.\")\n\n    # Persist so subsequent `clawbot auth spotify` runs skip the wizard.\n    save_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\", raw)\n    # Only persist the redirect URI if it's non-default, to avoid pinning\n    # users to a value the default might later change to.\n    if redirect_uri_hint and redirect_uri_hint != DEFAULT_SPOTIFY_REDIRECT_URI:\n        save_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\", redirect_uri_hint)\n\n    print()\n    print(\"Saved CLAWBOT_SPOTIFY_CLIENT_ID to ~/.clawbot/.env\")\n    print()\n    return raw\n\n\ndef login_spotify_command(args) -> None:\n    existing_state = get_provider_auth_state(\"spotify\") or {}\n\n    # Interactive wizard: if no client_id is configured anywhere, walk the\n    # user through creating the Spotify developer app instead of crashing\n    # with \"CLAWBOT_SPOTIFY_CLIENT_ID is required\".\n    explicit_client_id = getattr(args, \"client_id\", None)\n    try:\n        client_id = _spotify_client_id(explicit_client_id, existing_state)\n    except AuthError as exc:\n        if getattr(exc, \"code\", \"\") != \"spotify_client_id_missing\":\n            raise\n        client_id = _spotify_interactive_setup(\n            redirect_uri_hint=getattr(args, \"redirect_uri\", None) or DEFAULT_SPOTIFY_REDIRECT_URI,\n        )\n\n    redirect_uri = _spotify_redirect_uri(getattr(args, \"redirect_uri\", None), existing_state)\n    scope = _spotify_scope_string(getattr(args, \"scope\", None) or existing_state.get(\"scope\"))\n    accounts_base_url = _spotify_accounts_base_url(existing_state)\n    api_base_url = _spotify_api_base_url(existing_state)\n    open_browser = not getattr(args, \"no_browser\", False)\n\n    code_verifier = _spotify_code_verifier()\n    code_challenge = _spotify_code_challenge(code_verifier)\n    state_nonce = uuid.uuid4().hex\n    authorize_url = _spotify_build_authorize_url(\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        scope=scope,\n        state=state_nonce,\n        code_challenge=code_challenge,\n        accounts_base_url=accounts_base_url,\n    )\n\n    print(\"Starting Spotify PKCE login...\")\n    print(f\"Client ID: {client_id}\")\n    print(f\"Redirect URI: {redirect_uri}\")\n    print(\"Make sure this redirect URI is allow-listed in your Spotify app settings.\")\n    print()\n    print(\"Open this URL to authorize Clawbot:\")\n    print(authorize_url)\n    print()\n    print(f\"Full setup guide: {SPOTIFY_DOCS_URL}\")\n    print()\n\n    _print_loopback_ssh_hint(redirect_uri, docs_url=SPOTIFY_DOCS_URL)\n\n    if open_browser and not _is_remote_session():\n        try:\n            opened = webbrowser.open(authorize_url)\n        except Exception:\n            opened = False\n        if opened:\n            print(\"Browser opened for Spotify authorization.\")\n        else:\n            print(\"Could not open the browser automatically; use the URL above.\")\n\n    callback = _spotify_wait_for_callback(\n        redirect_uri,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 180.0),\n    )\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise SystemExit(f\"Spotify authorization failed: {detail}\")\n    if callback.get(\"state\") != state_nonce:\n        raise SystemExit(\"Spotify authorization failed: state mismatch.\")\n\n    token_payload = _spotify_exchange_code_for_tokens(\n        client_id=client_id,\n        code=str(callback.get(\"code\") or \"\"),\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        accounts_base_url=accounts_base_url,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 20.0),\n    )\n    spotify_state = _spotify_token_payload_to_state(\n        token_payload,\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        requested_scope=scope,\n        accounts_base_url=accounts_base_url,\n        api_base_url=api_base_url,\n    )\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _store_provider_state(auth_store, \"spotify\", spotify_state, set_active=False)\n        saved_to = _save_auth_store(auth_store)\n\n    print(\"Spotify login successful!\")\n    print(f\"  Auth state: {saved_to}\")\n    print(\"  Provider state saved under providers.spotify\")\n    print(f\"  Docs: {SPOTIFY_DOCS_URL}\")\n\n# =============================================================================\n# SSH / remote session detection\n# =============================================================================\n\ndef _is_remote_session() -> bool:\n    \"\"\"Detect if running in an SSH session where webbrowser.open() won't work.\"\"\"\n    return bool(os.getenv(\"SSH_CLIENT\") or os.getenv(\"SSH_TTY\"))\n\n\ndef _print_loopback_ssh_hint(redirect_uri: str, *, docs_url: str | None = None) -> None:\n    \"\"\"Print an SSH tunnel hint when running a loopback-redirect OAuth flow on a\n    remote host. The auth server (xAI, Spotify, ...) will redirect the user's\n    browser to ``127.0.0.1:<port>/callback``. If the browser is on a different\n    machine than the loopback listener (the usual SSH case), the redirect can't\n    reach the listener without a local port forward.\n\n    The hint is best-effort: silent if we don't think we're remote, or if we\n    can't parse a host/port out of the redirect URI.\n\n    Pass ``docs_url`` for a provider-specific guide (e.g. the xAI Grok OAuth\n    page); the generic OAuth-over-SSH guide is always shown after it.\n    \"\"\"\n    if not _is_remote_session():\n        return\n    try:\n        parsed = urlparse(redirect_uri)\n    except Exception:\n        return\n    host = parsed.hostname or \"\"\n    port = parsed.port\n    if host not in {\"127.0.0.1\", \"::1\", \"localhost\"} or not port:\n        return\n    print()\n    print(\"Remote session detected. Your browser will redirect to\")\n    print(f\"  {redirect_uri}\")\n    print(\"which the loopback listener on THIS machine is waiting on. If your\")\n    print(\"browser is on a different machine, forward the port first from your\")\n    print(\"local machine in a separate terminal:\")\n    print()\n    print(f\"  ssh -N -L {port}:127.0.0.1:{port} <user>@<this-host>\")\n    print()\n    print(\"Then open the authorize URL above in your local browser.\")\n    if docs_url:\n        print(f\"Provider docs:      {docs_url}\")\n    print(f\"SSH/jump-box guide: {OAUTH_OVER_SSH_DOCS_URL}\")\n    print()\n\n\n# =============================================================================\n# OpenAI Codex auth — tokens stored in ~/.clawbot/auth.json (not ~/.codex/)\n#\n# Clawbot maintains its own Codex OAuth session separate from the Codex CLI\n# and VS Code extension. This prevents refresh token rotation conflicts\n# where one app's refresh invalidates the other's session.\n# =============================================================================\n\ndef _read_codex_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    \"\"\"Read Codex OAuth tokens from Clawbot auth store (~/.clawbot/auth.json).\n    \n    Returns dict with 'tokens' (access_token, refresh_token) and 'last_refresh'.\n    Raises AuthError if no Codex tokens are stored.\n    \"\"\"\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"openai-codex\")\n    if not state:\n        raise AuthError(\n            \"No Codex credentials stored. Run `clawbot auth` to authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"Codex auth state is missing tokens. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = tokens.get(\"access_token\")\n    refresh_token = tokens.get(\"refresh_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        raise AuthError(\n            \"Codex auth is missing access_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n    }\n\n\ndef _save_codex_tokens(tokens: Dict[str, str], last_refresh: str = None) -> None:\n    \"\"\"Save Codex OAuth tokens to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"openai-codex\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"chatgpt\"\n        _save_provider_state(auth_store, \"openai-codex\", state)\n        _save_auth_store(auth_store)\n\n\ndef refresh_codex_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Codex OAuth tokens without mutating Clawbot auth state.\"\"\"\n    del access_token  # Access token is only used by callers to decide whether to refresh.\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            CODEX_OAUTH_TOKEN_URL,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": CODEX_OAUTH_CLIENT_ID,\n            },\n        )\n\n    if response.status_code != 200:\n        code = \"codex_refresh_failed\"\n        message = f\"Codex token refresh failed with status {response.status_code}.\"\n        relogin_required = False\n        try:\n            err = response.json()\n            if isinstance(err, dict):\n                err_obj = err.get(\"error\")\n                # OpenAI shape: {\"error\": {\"code\": \"...\", \"message\": \"...\", \"type\": \"...\"}}\n                if isinstance(err_obj, dict):\n                    nested_code = err_obj.get(\"code\") or err_obj.get(\"type\")\n                    if isinstance(nested_code, str) and nested_code.strip():\n                        code = nested_code.strip()\n                    nested_msg = err_obj.get(\"message\")\n                    if isinstance(nested_msg, str) and nested_msg.strip():\n                        message = f\"Codex token refresh failed: {nested_msg.strip()}\"\n                # OAuth spec shape: {\"error\": \"code_str\", \"error_description\": \"...\"}\n                elif isinstance(err_obj, str) and err_obj.strip():\n                    code = err_obj.strip()\n                    err_desc = err.get(\"error_description\") or err.get(\"message\")\n                    if isinstance(err_desc, str) and err_desc.strip():\n                        message = f\"Codex token refresh failed: {err_desc.strip()}\"\n        except Exception:\n            pass\n        if code in {\"invalid_grant\", \"invalid_token\", \"invalid_request\"}:\n            relogin_required = True\n        if code == \"refresh_token_reused\":\n            message = (\n                \"Codex refresh token was already consumed by another client \"\n                \"(e.g. Codex CLI or VS Code extension). \"\n                \"Run `codex` in your terminal to generate fresh tokens, \"\n                \"then run `clawbot auth` to re-authenticate.\"\n            )\n            relogin_required = True\n        # A 401/403 from the token endpoint always means the refresh token\n        # is invalid/expired — force relogin even if the body error code\n        # wasn't one of the known strings above.\n        if response.status_code in {401, 403} and not relogin_required:\n            relogin_required = True\n        raise AuthError(\n            message,\n            provider=\"openai-codex\",\n            code=code,\n            relogin_required=relogin_required,\n        )\n\n    try:\n        refresh_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            \"Codex token refresh returned invalid JSON.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_invalid_json\",\n            relogin_required=True,\n        ) from exc\n\n    refreshed_access = refresh_payload.get(\"access_token\")\n    if not isinstance(refreshed_access, str) or not refreshed_access.strip():\n        raise AuthError(\n            \"Codex token refresh response was missing access_token.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n\n    updated = {\n        \"access_token\": refreshed_access.strip(),\n        \"refresh_token\": refresh_token.strip(),\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    next_refresh = refresh_payload.get(\"refresh_token\")\n    if isinstance(next_refresh, str) and next_refresh.strip():\n        updated[\"refresh_token\"] = next_refresh.strip()\n    return updated\n\n\ndef _refresh_codex_auth_tokens(\n    tokens: Dict[str, str],\n    timeout_seconds: float,\n) -> Dict[str, str]:\n    \"\"\"Refresh Codex access token using the refresh token.\n    \n    Saves the new tokens to Clawbot auth store automatically.\n    \"\"\"\n    refreshed = refresh_codex_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n\n    _save_codex_tokens(updated_tokens)\n    return updated_tokens\n\n\ndef _import_codex_cli_tokens() -> Optional[Dict[str, str]]:\n    \"\"\"Try to read tokens from ~/.codex/auth.json (Codex CLI shared file).\n    \n    Returns tokens dict if valid and not expired, None otherwise.\n    Does NOT write to the shared file.\n    \"\"\"\n    codex_home = os.getenv(\"CODEX_HOME\", \"\").strip()\n    if not codex_home:\n        codex_home = str(Path.home() / \".codex\")\n    auth_path = Path(codex_home).expanduser() / \"auth.json\"\n    if not auth_path.is_file():\n        return None\n    try:\n        payload = json.loads(auth_path.read_text())\n        tokens = payload.get(\"tokens\")\n        if not isinstance(tokens, dict):\n            return None\n        access_token = tokens.get(\"access_token\")\n        refresh_token = tokens.get(\"refresh_token\")\n        if not access_token or not refresh_token:\n            return None\n        # Reject expired tokens — importing stale tokens from ~/.codex/\n        # that can't be refreshed leaves the user stuck with \"Login successful!\"\n        # but no working credentials.\n        if _codex_access_token_is_expiring(access_token, 0):\n            logger.debug(\n                \"Codex CLI tokens at %s are expired — skipping import.\", auth_path,\n            )\n            return None\n        return dict(tokens)\n    except Exception:\n        return None\n\n\ndef resolve_codex_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime credentials from Clawbot's own Codex token store.\"\"\"\n    data = _read_codex_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_CODEX_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        # Re-read under lock to avoid racing with other Clawbot processes\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_codex_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n\n            if should_refresh:\n                tokens = _refresh_codex_auth_tokens(tokens, refresh_timeout_seconds)\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"provider\": \"openai-codex\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"chatgpt\",\n    }\n\n\n# =============================================================================\n# xAI Grok OAuth — tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\ndef _read_xai_oauth_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"xai-oauth\")\n    if not state:\n        raise AuthError(\n            \"No xAI OAuth credentials stored. Select xAI Grok OAuth (SuperGrok Subscription) in `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"xAI OAuth state is missing tokens. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI OAuth state is missing access_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI OAuth state is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n        \"discovery\": state.get(\"discovery\") or {},\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n    }\n\n\ndef _save_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    discovery: Optional[Dict[str, Any]] = None,\n    redirect_uri: str = \"\",\n    last_refresh: Optional[str] = None,\n) -> None:\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"xai-oauth\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"oauth_pkce\"\n        if discovery:\n            state[\"discovery\"] = discovery\n        if redirect_uri:\n            state[\"redirect_uri\"] = redirect_uri\n        _save_provider_state(auth_store, \"xai-oauth\", state)\n        _save_auth_store(auth_store)\n\n\ndef _xai_access_token_is_expiring(access_token: str, skew_seconds: int = 0) -> bool:\n    if not isinstance(access_token, str) or \".\" not in access_token:\n        return False\n    try:\n        parts = access_token.split(\".\")\n        if len(parts) < 2:\n            return False\n        payload_b64 = parts[1]\n        payload_b64 += \"=\" * (-len(payload_b64) % 4)\n        payload = json.loads(base64.urlsafe_b64decode(payload_b64.encode(\"ascii\")).decode(\"utf-8\"))\n        exp = payload.get(\"exp\")\n        if not isinstance(exp, (int, float)):\n            return False\n        return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n    except Exception:\n        return False\n\n\ndef _xai_validate_oauth_endpoint(url: str, *, field: str) -> str:\n    \"\"\"Refuse any OIDC discovery endpoint that isn't HTTPS on the xAI origin.\n\n    The OIDC discovery response is a long-lived, low-frequency request whose\n    output is cached in ``~/.clawbot/auth.json``. A single MITM during initial\n    login could substitute a malicious ``token_endpoint``; that URL would\n    then receive the refresh_token on every subsequent refresh — a permanent\n    credential leak from a one-time MITM. Validating scheme + host pins the\n    cached endpoint to the xAI auth origin (or a future ``*.x.ai`` subdomain\n    if xAI migrates) so the cache poisoning loses its persistence guarantee.\n\n    RFC 8414 §2 requires the issuer to be ``https://`` and SHOULD-keeps the\n    token_endpoint on the same origin; we enforce both. ``x.ai`` is the\n    bare apex, so we accept either exact host match or any ``.x.ai`` suffix.\n    \"\"\"\n    parsed = urlparse(url)\n    if parsed.scheme != \"https\":\n        raise AuthError(\n            f\"xAI OIDC discovery returned a non-HTTPS {field}: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    host = (parsed.hostname or \"\").lower()\n    if not host:\n        raise AuthError(\n            f\"xAI OIDC discovery {field} is missing a hostname: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    if host != \"x.ai\" and not host.endswith(\".x.ai\"):\n        raise AuthError(\n            f\"xAI OIDC discovery {field} host {host!r} is not on the xAI origin \"\n            f\"(expected x.ai or a *.x.ai subdomain). Refusing to use a cached \"\n            f\"endpoint that may have been substituted by a MITM during initial \"\n            f\"discovery; re-authenticate with `clawbot model` to re-fetch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    return url\n\n\ndef _xai_oauth_discovery(timeout_seconds: float = 15.0) -> Dict[str, str]:\n    try:\n        response = httpx.get(\n            XAI_OAUTH_DISCOVERY_URL,\n            headers={\"Accept\": \"application/json\"},\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        ) from exc\n    if response.status_code != 200:\n        raise AuthError(\n            f\"xAI OIDC discovery returned status {response.status_code}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI OIDC discovery response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    authorization_endpoint = str(payload.get(\"authorization_endpoint\", \"\") or \"\").strip()\n    token_endpoint = str(payload.get(\"token_endpoint\", \"\") or \"\").strip()\n    if not authorization_endpoint or not token_endpoint:\n        raise AuthError(\n            \"xAI OIDC discovery response was missing required endpoints.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    _xai_validate_oauth_endpoint(authorization_endpoint, field=\"authorization_endpoint\")\n    _xai_validate_oauth_endpoint(token_endpoint, field=\"token_endpoint\")\n    return {\n        \"authorization_endpoint\": authorization_endpoint,\n        \"token_endpoint\": token_endpoint,\n    }\n\n\ndef refresh_xai_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    token_endpoint: str = \"\",\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    del access_token\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"xAI OAuth is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    endpoint = token_endpoint.strip() or _xai_oauth_discovery(timeout_seconds)[\"token_endpoint\"]\n    # Re-validate cached endpoints on the refresh hot path: an auth.json\n    # written by an older Clawbot (or hand-edited) may carry a non-xAI\n    # token_endpoint that would receive every future refresh_token in\n    # plaintext if we trusted it blindly. Cheap suffix check; fast-fail\n    # with a clear error so the user can re-run `clawbot model` to refetch.\n    _xai_validate_oauth_endpoint(endpoint, field=\"token_endpoint\")\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            endpoint,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": XAI_OAUTH_CLIENT_ID,\n                \"refresh_token\": refresh_token,\n            },\n        )\n    if response.status_code != 200:\n        detail = response.text.strip()\n        raise AuthError(\n            \"xAI token refresh failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_failed\",\n            relogin_required=(response.status_code in {400, 401, 403}),\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token refresh returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token refresh response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_response\",\n            relogin_required=True,\n        )\n    refreshed_access = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    if not refreshed_access:\n        raise AuthError(\n            \"xAI token refresh response was missing access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n    updated = {\n        \"access_token\": refreshed_access,\n        \"refresh_token\": str(payload.get(\"refresh_token\") or refresh_token).strip(),\n        \"id_token\": str(payload.get(\"id_token\") or \"\").strip(),\n        \"expires_in\": payload.get(\"expires_in\"),\n        \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    return updated\n\n\ndef _refresh_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    token_endpoint: str,\n    redirect_uri: str = \"\",\n    timeout_seconds: float,\n) -> Dict[str, Any]:\n    refreshed = refresh_xai_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        token_endpoint=token_endpoint,\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n    if refreshed.get(\"id_token\"):\n        updated_tokens[\"id_token\"] = refreshed[\"id_token\"]\n    if refreshed.get(\"expires_in\") is not None:\n        updated_tokens[\"expires_in\"] = refreshed[\"expires_in\"]\n    if refreshed.get(\"token_type\"):\n        updated_tokens[\"token_type\"] = refreshed[\"token_type\"]\n    _save_xai_oauth_tokens(\n        updated_tokens,\n        discovery={\"token_endpoint\": token_endpoint},\n        redirect_uri=redirect_uri,\n        last_refresh=refreshed[\"last_refresh\"],\n    )\n    return updated_tokens\n\n\ndef resolve_xai_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = XAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    data = _read_xai_oauth_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_XAI_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n    discovery = dict(data.get(\"discovery\") or {})\n    token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n    redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_xai_oauth_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n            discovery = dict(data.get(\"discovery\") or {})\n            token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n            redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n            if should_refresh:\n                if not token_endpoint:\n                    token_endpoint = _xai_oauth_discovery(refresh_timeout_seconds)[\"token_endpoint\"]\n                tokens = _refresh_xai_oauth_tokens(\n                    tokens,\n                    token_endpoint=token_endpoint,\n                    redirect_uri=redirect_uri,\n                    timeout_seconds=refresh_timeout_seconds,\n                )\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"provider\": \"xai-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"oauth_pkce\",\n    }\n\n\n# =============================================================================\n# TLS verification helper\n# =============================================================================\n\ndef _default_verify() -> bool | ssl.SSLContext:\n    \"\"\"Platform-aware default SSL verify for httpx clients.\n\n    On macOS with Homebrew Python, the system OpenSSL cannot locate the\n    system trust store and valid public certs fail verification. When\n    certifi is importable we pin its bundle explicitly; elsewhere we\n    defer to httpx's built-in default (certifi via its own dependency).\n    Mirrors the weixin fix in 3a0ec1d93.\n    \"\"\"\n    if sys.platform == \"darwin\":\n        try:\n            import certifi\n            return ssl.create_default_context(cafile=certifi.where())\n        except ImportError:\n            pass\n    return True\n\n\ndef _resolve_verify(\n    *,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    auth_state: Optional[Dict[str, Any]] = None,\n) -> bool | ssl.SSLContext:\n    tls_state = auth_state.get(\"tls\") if isinstance(auth_state, dict) else {}\n    tls_state = tls_state if isinstance(tls_state, dict) else {}\n\n    effective_insecure = (\n        is_truthy_value(insecure, default=False) if insecure is not None\n        else is_truthy_value(tls_state.get(\"insecure\", False), default=False)\n    )\n    effective_ca = (\n        ca_bundle\n        or tls_state.get(\"ca_bundle\")\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n        or os.getenv(\"REQUESTS_CA_BUNDLE\")\n    )\n\n    if effective_insecure:\n        return False\n    if effective_ca:\n        ca_path = str(effective_ca)\n        if not os.path.isfile(ca_path):\n            logger.warning(\n                \"CA bundle path does not exist: %s — falling back to default certificates\",\n                ca_path,\n            )\n            return _default_verify()\n        return ssl.create_default_context(cafile=ca_path)\n    return _default_verify()\n\n\n# =============================================================================\n# OAuth Device Code Flow — generic, parameterized by provider\n# =============================================================================\n\ndef _request_device_code(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: Optional[str],\n) -> Dict[str, Any]:\n    \"\"\"POST to the device code endpoint. Returns device_code, user_code, etc.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/device/code\",\n        data={\n            \"client_id\": client_id,\n            **({\"scope\": scope} if scope else {}),\n        },\n    )\n    response.raise_for_status()\n    data = response.json()\n\n    required_fields = [\n        \"device_code\", \"user_code\", \"verification_uri\",\n        \"verification_uri_complete\", \"expires_in\", \"interval\",\n    ]\n    missing = [f for f in required_fields if f not in data]\n    if missing:\n        raise ValueError(f\"Device code response missing fields: {', '.join(missing)}\")\n    return data\n\n\ndef _is_soam_invoke_scope_refusal(exc: Exception) -> bool:\n    if not isinstance(exc, httpx.HTTPStatusError):\n        return False\n    response = exc.response\n    if response.status_code not in {400, 401, 403}:\n        return False\n    try:\n        payload = response.json()\n    except Exception:\n        payload = {}\n    text = \" \".join(\n        str(value)\n        for value in (\n            payload.get(\"error\") if isinstance(payload, dict) else None,\n            payload.get(\"error_description\") if isinstance(payload, dict) else None,\n            response.text,\n        )\n        if value\n    ).lower()\n    if not text:\n        return False\n    return (\n        \"invalid_scope\" in text\n        or \"unsupported_scope\" in text\n        or \"scope\" in text and SOAM_INFERENCE_INVOKE_SCOPE in text\n    )\n\n\ndef _soam_device_scope_with_env_override(\n    requested_scope: Optional[str],\n    *,\n    default_scope: str = DEFAULT_SOAM_SCOPE,\n) -> Tuple[str, bool]:\n    explicit_scope = requested_scope is not None\n    scope = requested_scope or default_scope\n    if _soam_legacy_session_keys_forced():\n        scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n    return scope, explicit_scope\n\n\ndef _request_soam_device_code_with_scope_fallback(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: str,\n    allow_legacy_fallback: bool,\n) -> Tuple[Dict[str, Any], str]:\n    try:\n        return (\n            _request_device_code(\n                client=client,\n                portal_base_url=portal_base_url,\n                client_id=client_id,\n                scope=scope,\n            ),\n            scope,\n        )\n    except Exception as exc:\n        if (\n            allow_legacy_fallback\n            and _soam_scope_has_invoke(scope)\n            and _is_soam_invoke_scope_refusal(exc)\n        ):\n            logger.info(\"Soam inference auth: NAS refused invoke scope, retrying legacy scope\")\n            _oauth_trace(\"soam_device_code_invoke_scope_refused\")\n            retry_scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n            return (\n                _request_device_code(\n                    client=client,\n                    portal_base_url=portal_base_url,\n                    client_id=client_id,\n                    scope=retry_scope,\n                ),\n                retry_scope,\n            )\n        raise\n\n\ndef _poll_for_token(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    device_code: str,\n    expires_in: int,\n    poll_interval: int,\n) -> Dict[str, Any]:\n    \"\"\"Poll the token endpoint until the user approves or the code expires.\"\"\"\n    deadline = time.monotonic() + max(1, expires_in)\n    current_interval = max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n\n    while time.monotonic() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/api/oauth/token\",\n            data={\n                \"grant_type\": \"urn:ietf:params:oauth:grant-type:device_code\",\n                \"client_id\": client_id,\n                \"device_code\": device_code,\n            },\n        )\n\n        if response.status_code == 200:\n            payload = response.json()\n            if \"access_token\" not in payload:\n                raise ValueError(\"Token response did not include access_token\")\n            return payload\n\n        try:\n            error_payload = response.json()\n        except Exception:\n            response.raise_for_status()\n            raise RuntimeError(\"Token endpoint returned a non-JSON error response\")\n\n        error_code = error_payload.get(\"error\", \"\")\n        if error_code == \"authorization_pending\":\n            time.sleep(current_interval)\n            continue\n        if error_code == \"slow_down\":\n            current_interval = min(current_interval + 1, 30)\n            time.sleep(current_interval)\n            continue\n\n        description = error_payload.get(\"error_description\") or \"Unknown authentication error\"\n        raise RuntimeError(f\"{error_code}: {description}\")\n\n    raise TimeoutError(\"Timed out waiting for device authorization\")\n\n\n# =============================================================================\n# Soam Portal — token refresh, agent key minting, model discovery\n# =============================================================================\n\n# -----------------------------------------------------------------------------\n# Shared Soam token store — lets OAuth credentials persist across profiles\n# so a new `clawbot --profile <name> auth add soam --type oauth` can one-tap\n# import instead of running the full device-code flow every time.\n#\n# File lives at ${CLAWBOT_SHARED_AUTH_DIR}/soam_auth.json, defaulting to\n# ``<clawbot-root>/shared/soam_auth.json`` where ``<clawbot-root>`` is what\n# ``get_default_clawbot_root()`` returns — ``~/.clawbot`` on Linux/macOS,\n# ``%LOCALAPPDATA%\\clawbot`` on native Windows, or the Docker/custom root.\n# It is OUTSIDE any named profile's CLAWBOT_HOME so named profiles (which\n# typically live under ``<clawbot-root>/profiles/<name>/``) all see the\n# same file.\n#\n# Written on successful login and on every runtime refresh so the stored\n# refresh_token stays current even if one profile refreshes and rotates it.\n# If ever the stored refresh_token does go stale server-side, import fails\n# gracefully and the user falls back to the normal device-code flow.\n# -----------------------------------------------------------------------------\n\nSOAM_SHARED_STORE_FILENAME = \"soam_auth.json\"\n_soam_shared_lock_holder = threading.local()\n\n\ndef _soam_shared_auth_dir() -> Path:\n    \"\"\"Resolve the directory that holds the shared Soam token store.\n\n    Honors ``CLAWBOT_SHARED_AUTH_DIR`` so tests can redirect it to a tmp\n    path without touching the real user's home. Defaults to\n    ``<clawbot-root>/shared/``, where ``<clawbot-root>`` is what\n    :func:`clawbot_constants.get_default_clawbot_root` returns — so\n    Linux/macOS classic installs land at ``~/.clawbot/shared/``, native\n    Windows installs at ``%LOCALAPPDATA%\\\\clawbot\\\\shared\\\\``, and\n    Docker / custom ``CLAWBOT_HOME`` deployments at\n    ``<CLAWBOT_HOME>/shared/``. Sits outside any named profile so all\n    profiles under the same root share the store.\n    \"\"\"\n    override = os.getenv(\"CLAWBOT_SHARED_AUTH_DIR\", \"\").strip()\n    if override:\n        return Path(override).expanduser()\n    from clawbot_constants import get_default_clawbot_root\n    return get_default_clawbot_root() / \"shared\"\n\n\ndef _soam_shared_store_path() -> Path:\n    path = _soam_shared_auth_dir() / SOAM_SHARED_STORE_FILENAME\n    # Seat belt: if pytest is running and this resolves to a path under the\n    # real user's Clawbot root, refuse rather than silently corrupt cross-profile\n    # state. Tests must set CLAWBOT_SHARED_AUTH_DIR to a tmp_path (conftest\n    # does not do this automatically — mirror the _auth_file_path() guard\n    # so forgetting to set it fails loudly instead of writing to the real\n    # shared store).\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        from clawbot_constants import get_default_clawbot_root\n        real_home_shared = (\n            get_default_clawbot_root() / \"shared\" / SOAM_SHARED_STORE_FILENAME\n        ).resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_shared:\n            raise RuntimeError(\n                f\"Refusing to touch real user shared Soam auth store during test run: \"\n                f\"{path}. Set CLAWBOT_SHARED_AUTH_DIR to a tmp_path in your test fixture.\"\n            )\n    return path\n\n\n@contextmanager\ndef _soam_shared_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-profile lock for the shared Soam OAuth store.\n\n    Lock ordering invariant: if both this and ``_auth_store_lock`` need\n    to be held, acquire ``_auth_store_lock`` FIRST. All runtime refresh\n    paths follow this order. The one exception is\n    ``_try_import_shared_soam_state``, which holds this lock alone for\n    the entire refresh+mint cycle so concurrent imports on sibling\n    profiles can't race on the single-use shared refresh token; that\n    helper must NOT be called with ``_auth_store_lock`` already held.\n    \"\"\"\n    try:\n        lock_path = _soam_shared_store_path().with_suffix(\".lock\")\n    except RuntimeError:\n        # No CLAWBOT_HOME yet (pre-setup): fall through without locking.\n        yield\n        return\n\n    with _file_lock(\n        lock_path,\n        _soam_shared_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for shared Soam auth lock\",\n    ):\n        yield\n\n\ndef _merge_shared_soam_oauth_state(state: Dict[str, Any]) -> bool:\n    \"\"\"Copy fresher shared OAuth tokens into a profile-local Soam state.\"\"\"\n    shared = _read_shared_soam_state()\n    if not shared:\n        return False\n\n    shared_refresh = shared.get(\"refresh_token\")\n    if not isinstance(shared_refresh, str) or not shared_refresh.strip():\n        return False\n\n    local_refresh = state.get(\"refresh_token\")\n    shared_access_exp = _parse_iso_timestamp(shared.get(\"expires_at\")) or 0.0\n    local_access_exp = _parse_iso_timestamp(state.get(\"expires_at\")) or 0.0\n    refresh_changed = shared_refresh.strip() != str(local_refresh or \"\").strip()\n    fresher_access = shared_access_exp > local_access_exp\n    if not refresh_changed and not fresher_access:\n        return False\n\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"token_type\",\n        \"scope\",\n        \"client_id\",\n        \"portal_base_url\",\n        \"inference_base_url\",\n        \"obtained_at\",\n        \"expires_at\",\n    ):\n        value = shared.get(key)\n        if value not in {None, \"\"}:\n            state[key] = value\n    return True\n\n\ndef _write_shared_soam_state(state: Dict[str, Any]) -> None:\n    \"\"\"Persist a minimal copy of the Soam OAuth state to the shared store.\n\n    Best-effort: any failure is swallowed after logging. The shared store\n    is a convenience layer; the per-profile auth.json remains the source\n    of truth.\n\n    We deliberately omit the runtime ``agent_key`` compatibility field\n    (either an invoke JWT or legacy opaque session key) — only OAuth tokens\n    are cross-profile useful.\n    \"\"\"\n    refresh_token = state.get(\"refresh_token\")\n    access_token = state.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        # No refresh_token = nothing worth sharing across profiles\n        return\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return\n\n    shared = {\n        \"_schema\": 1,\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"token_type\": state.get(\"token_type\") or \"Bearer\",\n        \"scope\": state.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n        \"client_id\": state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": state.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n        \"inference_base_url\": state.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n        \"obtained_at\": state.get(\"obtained_at\"),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"updated_at\": datetime.now(timezone.utc).isoformat(),\n    }\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            path.parent.mkdir(parents=True, exist_ok=True)\n            try:\n                os.chmod(path.parent, 0o700)\n            except OSError:\n                pass\n            tmp = path.with_name(f\"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n            # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n            # window where write_text() + post-write chmod briefly exposed Soam\n            # refresh_token at process umask. See #19673, #21148.\n            fd = os.open(\n                str(tmp),\n                os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n                stat.S_IRUSR | stat.S_IWUSR,\n            )\n            try:\n                with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n                    fh.write(json.dumps(shared, indent=2, sort_keys=True))\n                    fh.flush()\n                    os.fsync(fh.fileno())\n                os.replace(tmp, path)\n            finally:\n                try:\n                    if tmp.exists():\n                        tmp.unlink()\n                except OSError:\n                    pass\n        _oauth_trace(\n            \"soam_shared_store_written\",\n            path=str(path),\n            refresh_token_fp=_token_fingerprint(refresh_token),\n        )\n    except Exception as exc:\n        logger.debug(\"Failed to write shared Soam auth store: %s\", exc)\n\n\ndef _read_shared_soam_state() -> Optional[Dict[str, Any]]:\n    \"\"\"Return the shared Soam OAuth state if present and well-formed.\n\n    Returns ``None`` when the file is missing, unreadable, malformed, or\n    lacks required fields. Callers should treat ``None`` as \"no shared\n    credentials available — fall through to device-code\".\n    \"\"\"\n    try:\n        path = _soam_shared_store_path()\n    except RuntimeError:\n        # Test seat belt tripped — treat as missing\n        return None\n    if not path.is_file():\n        return None\n    try:\n        payload = json.loads(path.read_text())\n    except (OSError, ValueError) as exc:\n        logger.debug(\"Shared Soam auth store at %s is unreadable: %s\", path, exc)\n        return None\n    if not isinstance(payload, dict):\n        return None\n    refresh_token = payload.get(\"refresh_token\")\n    access_token = payload.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        return None\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return None\n    return payload\n\n\ndef _clear_shared_soam_state(reason: str) -> None:\n    \"\"\"Remove the shared Soam OAuth store after a terminal token failure.\"\"\"\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            try:\n                path.unlink()\n            except FileNotFoundError:\n                pass\n        _oauth_trace(\"soam_shared_store_cleared\", reason=reason)\n    except Exception as exc:\n        logger.debug(\"Failed to clear shared Soam auth store: %s\", exc)\n\n\ndef _is_terminal_soam_refresh_error(exc: Exception) -> bool:\n    \"\"\"True when retrying the same Soam refresh token cannot succeed.\"\"\"\n    return (\n        isinstance(exc, AuthError)\n        and exc.provider == \"soam\"\n        and exc.code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n        and bool(exc.relogin_required)\n    )\n\n\ndef _quarantine_soam_oauth_state(\n    state: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> None:\n    \"\"\"Keep routing metadata but remove dead OAuth material so it is not replayed.\"\"\"\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"expires_at\",\n        \"expires_in\",\n        \"obtained_at\",\n        \"agent_key\",\n        \"agent_key_id\",\n        \"agent_key_expires_at\",\n        \"agent_key_expires_in\",\n        \"agent_key_reused\",\n        \"agent_key_obtained_at\",\n    ):\n        state.pop(key, None)\n    state[\"last_auth_error\"] = {\n        \"provider\": \"soam\",\n        \"code\": error.code,\n        \"message\": str(error),\n        \"reason\": reason,\n        \"relogin_required\": True,\n        \"at\": datetime.now(timezone.utc).isoformat(),\n    }\n    _clear_shared_soam_state(reason)\n    invalidate_soam_auth_status_cache()\n\n\ndef _quarantine_soam_pool_entries(\n    auth_store: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> bool:\n    \"\"\"Remove singleton-seeded Soam pool entries that contain dead OAuth state.\"\"\"\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        return False\n    entries = pool.get(\"soam\")\n    if not isinstance(entries, list):\n        return False\n\n    retained = []\n    removed = False\n    singleton_sources = {SOAM_DEVICE_CODE_SOURCE, f\"manual:{SOAM_DEVICE_CODE_SOURCE}\"}\n    for entry in entries:\n        if isinstance(entry, dict) and entry.get(\"source\") in singleton_sources:\n            removed = True\n            continue\n        retained.append(entry)\n\n    if removed:\n        pool[\"soam\"] = retained\n        _oauth_trace(\n            \"soam_pool_device_code_quarantined\",\n            reason=reason,\n            error_code=error.code,\n        )\n    return removed\n\n\ndef _try_import_shared_soam_state(\n    *,\n    timeout_seconds: float = 15.0,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Optional[Dict[str, Any]]:\n    \"\"\"Attempt to rehydrate Soam OAuth state from the shared store.\n\n    Reads the shared file (if present), runs a forced refresh+mint using\n    the stored refresh_token to produce a fresh access_token + agent_key\n    scoped to this profile, and returns the full auth_state dict ready\n    for ``persist_soam_credentials()``.\n\n    Returns ``None`` when no shared state is available or the rehydrate\n    fails for any reason (expired refresh_token, portal unreachable,\n    etc.) — caller should then fall through to the normal device-code\n    flow.\n    \"\"\"\n    try:\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            shared = _read_shared_soam_state()\n            if not shared:\n                return None\n\n            # Build a full state dict so refresh_soam_oauth_from_state has every\n            # field it needs. force_refresh=True gets us a fresh access_token\n            # for this profile; fresh auth mode avoids stale cached legacy keys.\n            state: Dict[str, Any] = {\n                \"access_token\": shared.get(\"access_token\"),\n                \"refresh_token\": shared.get(\"refresh_token\"),\n                \"client_id\": shared.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n                \"portal_base_url\": shared.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n                \"inference_base_url\": shared.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n                \"token_type\": shared.get(\"token_type\") or \"Bearer\",\n                \"scope\": shared.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n                \"obtained_at\": shared.get(\"obtained_at\"),\n                \"expires_at\": shared.get(\"expires_at\"),\n                \"agent_key\": None,\n                \"agent_key_expires_at\": None,\n                \"tls\": {\"insecure\": False, \"ca_bundle\": None},\n            }\n\n            def _persist_shared_refresh(updated_state: Dict[str, Any], _reason: str) -> None:\n                _write_shared_soam_state(updated_state)\n\n            refreshed = refresh_soam_oauth_from_state(\n                state,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                timeout_seconds=timeout_seconds,\n                force_refresh=True,\n                inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n                on_state_update=_persist_shared_refresh,\n            )\n            _write_shared_soam_state(refreshed)\n    except AuthError as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n            error_code=getattr(exc, \"code\", None),\n        )\n        if _is_terminal_soam_refresh_error(exc):\n            _clear_shared_soam_state(\"shared_import_terminal_refresh_failure\")\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n    except Exception as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n        )\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n\n    return refreshed\n\n\ndef _refresh_access_token(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    refresh_token: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/token\",\n        headers={\"x-soam-refresh-token\": refresh_token},\n        data={\n            \"grant_type\": \"refresh_token\",\n            \"client_id\": client_id,\n        },\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"access_token\" not in payload:\n            raise AuthError(\"Refresh response missing access_token\",\n                            provider=\"soam\", code=\"invalid_token\", relogin_required=True)\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Refresh token exchange failed\",\n                        provider=\"soam\", relogin_required=True) from exc\n\n    code = str(error_payload.get(\"error\", \"invalid_grant\"))\n    description = str(error_payload.get(\"error_description\") or \"Refresh token exchange failed\")\n    relogin = code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n\n    # Detect the OAuth 2.1 \"refresh token reuse\" signal from the Soam portal\n    # server and surface an actionable message.  This fires when an external\n    # process (health-check script, monitoring tool, custom self-heal hook)\n    # called POST /api/oauth/token with Clawbot's refresh_token without\n    # persisting the rotated token back to auth.json — the server then\n    # retires the original RT, Clawbot's next refresh uses it, and the whole\n    # session chain gets revoked as a token-theft signal (#15099).\n    lowered = description.lower()\n    if code == \"refresh_token_reused\" or \"reuse\" in lowered or \"reuse detected\" in lowered:\n        description = (\n            \"Soam Portal detected refresh-token reuse and revoked this session.\\n\"\n            \"This usually means an external process (monitoring script, \"\n            \"custom self-heal hook, or another Clawbot install sharing \"\n            \"~/.clawbot/auth.json) called POST /api/oauth/token with Clawbot's \"\n            \"refresh token without persisting the rotated token back.\\n\"\n            \"Soam refresh tokens are single-use — only Clawbot may call the \"\n            \"refresh endpoint. For health checks, use `clawbot auth status` \"\n            \"instead.\\n\"\n            \"Re-authenticate with: clawbot auth add soam\"\n        )\n        relogin = True\n\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef _mint_agent_key(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    access_token: str,\n    min_ttl_seconds: int,\n) -> Dict[str, Any]:\n    \"\"\"Mint (or reuse) a short-lived inference API key.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/agent-key\",\n        headers={\"Authorization\": f\"Bearer {access_token}\"},\n        json={\"min_ttl_seconds\": max(60, int(min_ttl_seconds))},\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"api_key\" not in payload:\n            raise AuthError(\"Mint response missing api_key\",\n                            provider=\"soam\", code=\"server_error\")\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Agent key mint request failed\",\n                        provider=\"soam\", code=\"server_error\") from exc\n\n    code = str(error_payload.get(\"error\", \"server_error\"))\n    description = str(error_payload.get(\"error_description\") or \"Agent key mint request failed\")\n    relogin = code in {\"invalid_token\", \"invalid_grant\"}\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef fetch_soam_models(\n    *,\n    inference_base_url: str,\n    api_key: str,\n    timeout_seconds: float = 15.0,\n    verify: bool | str = True,\n) -> List[str]:\n    \"\"\"Fetch available model IDs from the Soam inference API.\"\"\"\n    timeout = httpx.Timeout(timeout_seconds)\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        response = client.get(\n            f\"{inference_base_url.rstrip('/')}/models\",\n            headers={\"Authorization\": f\"Bearer {api_key}\"},\n        )\n\n    if response.status_code != 200:\n        description = f\"/models request failed with status {response.status_code}\"\n        try:\n            err = response.json()\n            description = str(err.get(\"error_description\") or err.get(\"error\") or description)\n        except Exception as e:\n            logger.debug(\"Could not parse error response JSON: %s\", e)\n        raise AuthError(description, provider=\"soam\", code=\"models_fetch_failed\")\n\n    payload = response.json()\n    data = payload.get(\"data\")\n    if not isinstance(data, list):\n        return []\n\n    model_ids: List[str] = []\n    for item in data:\n        if not isinstance(item, dict):\n            continue\n        model_id = item.get(\"id\")\n        if isinstance(model_id, str) and model_id.strip():\n            mid = model_id.strip()\n            # Skip Clawbot models — they're not reliable for agentic tool-calling\n            if \"clawbot\" in mid.lower():\n                continue\n            model_ids.append(mid)\n\n    # Sort: prefer opus > pro > haiku/flash > sonnet (sonnet is cheap/fast,\n    # users who want the best model should see opus first).\n    def _model_priority(mid: str) -> tuple:\n        low = mid.lower()\n        if \"opus\" in low:\n            return (0, mid)\n        if \"pro\" in low and \"sonnet\" not in low:\n            return (1, mid)\n        if \"sonnet\" in low:\n            return (3, mid)\n        return (2, mid)\n\n    model_ids.sort(key=_model_priority)\n    return list(dict.fromkeys(model_ids))\n\n\ndef _agent_key_is_usable(state: Dict[str, Any], min_ttl_seconds: int) -> bool:\n    key = state.get(\"agent_key\")\n    if not isinstance(key, str) or not key.strip():\n        return False\n    if _decode_jwt_claims(key):\n        if _soam_legacy_session_keys_forced():\n            return False\n        return _soam_invoke_jwt_is_usable(\n            key,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"agent_key_expires_at\"),\n        )\n    return not _is_expiring(state.get(\"agent_key_expires_at\"), min_ttl_seconds)\n\n\ndef resolve_soam_access_token(\n    *,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    refresh_skew_seconds: int = ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> str:\n    \"\"\"Resolve a refresh-aware Soam Portal access token for managed tool gateways.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\n                \"Clawbot is not logged into Soam Portal.\",\n                provider=\"soam\",\n                relogin_required=True,\n            )\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            merged_shared = _merge_shared_soam_oauth_state(state)\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\n                    \"No access token found for Soam Portal login.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            if not _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds):\n                if merged_shared:\n                    _save_provider_state(auth_store, \"soam\", state)\n                    _save_auth_store(auth_store)\n                return access_token\n\n            if not isinstance(refresh_token, str) or not refresh_token:\n                raise AuthError(\n                    \"Session expired and no refresh token is available.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n            with httpx.Client(\n                timeout=timeout,\n                headers={\"Accept\": \"application/json\"},\n                verify=verify,\n            ) as client:\n                try:\n                    refreshed = _refresh_access_token(\n                        client=client,\n                        portal_base_url=portal_base_url,\n                        client_id=client_id,\n                        refresh_token=refresh_token,\n                    )\n                except AuthError as exc:\n                    if _is_terminal_soam_refresh_error(exc):\n                        _quarantine_soam_oauth_state(\n                            state,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _quarantine_soam_pool_entries(\n                            auth_store,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _save_provider_state(auth_store, \"soam\", state)\n                        _save_auth_store(auth_store)\n                    raise\n\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl,\n                tz=timezone.utc,\n            ).isoformat()\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n            _save_provider_state(auth_store, \"soam\", state)\n            _save_auth_store(auth_store)\n            _write_shared_soam_state(state)\n            return state[\"access_token\"]\n\n\ndef refresh_soam_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    client_id: str,\n    portal_base_url: str,\n    inference_base_url: str,\n    *,\n    token_type: str = \"Bearer\",\n    scope: str = DEFAULT_SOAM_SCOPE,\n    obtained_at: Optional[str] = None,\n    expires_at: Optional[str] = None,\n    agent_key: Optional[str] = None,\n    agent_key_expires_at: Optional[str] = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth state without mutating auth.json directly.\n\n    ``on_state_update`` is called after a successful access-token refresh and\n    before any subsequent agent-key mint. Callers that own persistent state can\n    use it to save the newly rotated refresh token before later work can fail.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    state: Dict[str, Any] = {\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"client_id\": client_id or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": (portal_base_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\"),\n        \"inference_base_url\": (inference_base_url or DEFAULT_SOAM_INFERENCE_URL).rstrip(\"/\"),\n        \"token_type\": token_type or \"Bearer\",\n        \"scope\": scope or DEFAULT_SOAM_SCOPE,\n        \"obtained_at\": obtained_at,\n        \"expires_at\": expires_at,\n        \"agent_key\": agent_key,\n        \"agent_key_expires_at\": agent_key_expires_at,\n        \"tls\": {\n            \"insecure\": bool(insecure),\n            \"ca_bundle\": ca_bundle,\n        },\n    }\n    verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n    timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        min_agent_key_ttl = max(60, int(min_key_ttl_seconds))\n        legacy_session_keys = _soam_legacy_session_keys_forced()\n        current_invoke_jwt_usable = (\n            not legacy_session_keys\n            and _soam_invoke_jwt_is_usable(\n                state.get(\"access_token\"),\n                scope=state.get(\"scope\"),\n                expires_at=state.get(\"expires_at\"),\n            )\n        )\n        if (\n            force_refresh\n            or (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            )\n        ):\n            refreshed = _refresh_access_token(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                client_id=state[\"client_id\"],\n                refresh_token=state[\"refresh_token\"],\n            )\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or state[\"refresh_token\"]\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n            if refreshed_url:\n                state[\"inference_base_url\"] = refreshed_url\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl, tz=timezone.utc\n            ).isoformat()\n            if on_state_update is not None:\n                on_state_update(dict(state), \"post_refresh_access_token\")\n\n        selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n            state,\n            min_key_ttl_seconds=min_agent_key_ttl,\n            inference_auth_mode=inference_auth_mode,\n        )\n        if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n            _select_soam_invoke_jwt(state)\n        elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT:\n            _log_soam_legacy_session_key_selected(\n                fallback_reason or \"legacy_session_key_required\",\n                access_token=state.get(\"access_token\"),\n            )\n            mint_payload = _mint_agent_key(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                access_token=state[\"access_token\"],\n                min_ttl_seconds=min_key_ttl_seconds,\n            )\n            now = datetime.now(timezone.utc)\n            state[\"agent_key\"] = mint_payload.get(\"api_key\")\n            state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n            state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n            state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n            state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n            state[\"agent_key_obtained_at\"] = now.isoformat()\n            minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n            if minted_url:\n                state[\"inference_base_url\"] = minted_url\n\n    return state\n\n\ndef refresh_soam_oauth_from_state(\n    state: Dict[str, Any],\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth from a state dict. Thin wrapper around refresh_soam_oauth_pure.\"\"\"\n    tls = state.get(\"tls\") or {}\n    return refresh_soam_oauth_pure(\n        state.get(\"access_token\", \"\"),\n        state.get(\"refresh_token\", \"\"),\n        state.get(\"client_id\", \"clawbot-cli\"),\n        state.get(\"portal_base_url\", DEFAULT_SOAM_PORTAL_URL),\n        state.get(\"inference_base_url\", DEFAULT_SOAM_INFERENCE_URL),\n        token_type=state.get(\"token_type\", \"Bearer\"),\n        scope=state.get(\"scope\", DEFAULT_SOAM_SCOPE),\n        obtained_at=state.get(\"obtained_at\"),\n        expires_at=state.get(\"expires_at\"),\n        agent_key=state.get(\"agent_key\"),\n        agent_key_expires_at=state.get(\"agent_key_expires_at\"),\n        min_key_ttl_seconds=min_key_ttl_seconds,\n        timeout_seconds=timeout_seconds,\n        insecure=tls.get(\"insecure\"),\n        ca_bundle=tls.get(\"ca_bundle\"),\n        force_refresh=force_refresh,\n        inference_auth_mode=inference_auth_mode,\n        on_state_update=on_state_update,\n    )\n\n\ndef persist_soam_credentials(\n    creds: Dict[str, Any],\n    *,\n    label: Optional[str] = None,\n):\n    \"\"\"Persist minted Soam OAuth credentials as the singleton provider state\n    and ensure the credential pool is in sync.\n\n    Soam credentials are read at runtime from two independent locations:\n\n    - ``providers.soam``: singleton state read by\n      ``resolve_soam_runtime_credentials()`` during 401 recovery and by\n      ``_seed_from_singletons()`` during pool load.\n    - ``credential_pool.soam``: used by the runtime ``pool.select()`` path.\n\n    Historically ``clawbot auth add soam`` wrote a ``manual:device_code`` pool\n    entry only, skipping ``providers.soam``.  When the 24h agent_key TTL\n    expired, the recovery path read the empty singleton state and raised\n    ``AuthError`` silently (``logger.debug`` at INFO level).\n\n    This helper writes ``providers.soam`` then calls ``load_pool(\"soam\")`` so\n    ``_seed_from_singletons`` materialises the canonical ``device_code`` pool\n    entry from the singleton.  Re-running login upserts the same entry in\n    place; the pool never accumulates duplicate device_code rows.\n\n    ``label`` is an optional user-chosen display name (from\n    ``clawbot auth add soam --label <name>``).  It gets embedded in the\n    singleton state so that ``_seed_from_singletons`` uses it as the pool\n    entry's label on every subsequent ``load_pool(\"soam\")`` instead of the\n    auto-derived token fingerprint.  When ``None``, the auto-derived label\n    via ``label_from_token`` is used (unchanged default behaviour).\n\n    Returns the upserted :class:`PooledCredential` entry (or ``None`` if\n    seeding somehow produced no match — shouldn't happen).\n    \"\"\"\n    from agent.credential_pool import load_pool\n\n    state = dict(creds)\n    if label and str(label).strip():\n        state[\"label\"] = str(label).strip()\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"soam\", state)\n        _save_auth_store(auth_store)\n\n    # Mirror to the shared store so a new profile can one-tap import\n    # these credentials via `clawbot auth add soam --type oauth`. Best-\n    # effort: any I/O failure is logged and swallowed (the per-profile\n    # auth.json is still the source of truth).\n    _write_shared_soam_state(state)\n\n    pool = load_pool(\"soam\")\n    return next(\n        (e for e in pool.entries() if e.source == SOAM_DEVICE_CODE_SOURCE),\n        None,\n    )\n\n\ndef _sync_soam_pool_from_auth_store() -> None:\n    \"\"\"Best-effort pool reseed after providers.soam changes; never fail login.\"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        load_pool(\"soam\")\n    except Exception as exc:\n        logger.debug(\"Failed to sync Soam credential pool from auth store: %s\", exc)\n\n\ndef resolve_soam_runtime_credentials(\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Dict[str, Any]:\n    \"\"\"\n    Resolve Soam inference credentials for runtime use.\n\n    Ensures access_token is valid (refreshes if needed) and a short-lived\n    inference key is present with minimum TTL (mints/reuses as needed).\n    Concurrent processes coordinate through the auth store file lock.\n\n    Returns dict with: provider, base_url, api_key, key_id, expires_at,\n    expires_in, source (\"invoke_jwt\", \"cache\", or \"portal\"), and auth_path.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    min_key_ttl_seconds = max(60, int(min_key_ttl_seconds))\n    sequence_id = uuid.uuid4().hex[:12]\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\"Clawbot is not logged into Soam Portal.\",\n                            provider=\"soam\", relogin_required=True)\n\n        persisted_state = dict(state)\n        state_persisted = False\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        inference_base_url = (\n            _optional_base_url(state.get(\"inference_base_url\"))\n            or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n            or DEFAULT_SOAM_INFERENCE_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n\n        def _persist_state(reason: str) -> None:\n            nonlocal persisted_state, state_persisted\n            # Skip writes where only derived TTL countdowns changed; this keeps\n            # the mtime-keyed Soam auth-status cache warm during read paths.\n            if (\n                _soam_effective_provider_state(state)\n                == _soam_effective_provider_state(persisted_state)\n            ):\n                _oauth_trace(\n                    \"soam_state_persist_skipped\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                )\n                return\n            try:\n                _save_provider_state(auth_store, \"soam\", state)\n                _save_auth_store(auth_store)\n            except Exception as exc:\n                _oauth_trace(\n                    \"soam_state_persist_failed\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                    error_type=type(exc).__name__,\n                )\n                raise\n            _oauth_trace(\n                \"soam_state_persisted\",\n                sequence_id=sequence_id,\n                reason=reason,\n                refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n                access_token_fp=_token_fingerprint(state.get(\"access_token\")),\n            )\n            persisted_state = dict(state)\n            state_persisted = True\n            # Mirror post-refresh state to the shared store so sibling\n            # profiles don't hold stale refresh_tokens after rotation.\n            # Best-effort — any failure is logged and swallowed inside\n            # _write_shared_soam_state.\n            _write_shared_soam_state(state)\n\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n        timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n        _oauth_trace(\n            \"soam_runtime_credentials_start\",\n            sequence_id=sequence_id,\n            inference_auth_mode=inference_auth_mode,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n        )\n\n        with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\"No access token found for Soam Portal login.\",\n                                provider=\"soam\", relogin_required=True)\n\n            # Step 1: refresh access token if expiring. If the access token\n            # is already a valid invoke JWT, trust its own exp claim even when\n            # older auth.json metadata has a stale/missing expires_at.\n            current_invoke_jwt_usable = (\n                not _soam_legacy_session_keys_forced()\n                and _soam_invoke_jwt_is_usable(\n                    access_token,\n                    scope=state.get(\"scope\"),\n                    expires_at=state.get(\"expires_at\"),\n                )\n            )\n            if (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            ):\n                with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                    if _merge_shared_soam_oauth_state(state):\n                        access_token = state.get(\"access_token\")\n                        refresh_token = state.get(\"refresh_token\")\n                        _persist_state(\"post_shared_merge_access_expiring\")\n\n                    if (\n                        _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                        and not _soam_invoke_jwt_is_usable(\n                            access_token,\n                            scope=state.get(\"scope\"),\n                            expires_at=state.get(\"expires_at\"),\n                        )\n                    ):\n                        if not isinstance(refresh_token, str) or not refresh_token:\n                            raise AuthError(\"Session expired and no refresh token is available.\",\n                                            provider=\"soam\", relogin_required=True)\n\n                        _oauth_trace(\n                            \"refresh_start\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        try:\n                            refreshed = _refresh_access_token(\n                                client=client, portal_base_url=portal_base_url,\n                                client_id=client_id, refresh_token=refresh_token,\n                            )\n                        except AuthError as exc:\n                            if _is_terminal_soam_refresh_error(exc):\n                                _quarantine_soam_oauth_state(\n                                    state,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _quarantine_soam_pool_entries(\n                                    auth_store,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _persist_state(\"terminal_runtime_access_refresh_failure\")\n                            raise\n                        now = datetime.now(timezone.utc)\n                        access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                        previous_refresh_token = refresh_token\n                        state[\"access_token\"] = refreshed[\"access_token\"]\n                        state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n                        state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                        state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                        refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                        if refreshed_url:\n                            inference_base_url = refreshed_url\n                        state[\"obtained_at\"] = now.isoformat()\n                        state[\"expires_in\"] = access_ttl\n                        state[\"expires_at\"] = datetime.fromtimestamp(\n                            now.timestamp() + access_ttl, tz=timezone.utc\n                        ).isoformat()\n                        access_token = state[\"access_token\"]\n                        refresh_token = state[\"refresh_token\"]\n                        _oauth_trace(\n                            \"refresh_success\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            previous_refresh_token_fp=_token_fingerprint(previous_refresh_token),\n                            new_refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        # Persist immediately so downstream mint failures cannot drop rotated refresh tokens.\n                        _persist_state(\"post_refresh_access_expiring\")\n\n            # Step 2: resolve the compatibility ``agent_key`` field. Preferred\n            # path stores the NAS invoke JWT there; legacy path mints/reuses\n            # the opaque session key.\n            used_cached_key = False\n            mint_payload: Optional[Dict[str, Any]] = None\n            selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n                state,\n                access_token=access_token,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                inference_auth_mode=inference_auth_mode,\n            )\n\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                _select_soam_invoke_jwt(\n                    state,\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n            elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE:\n                used_cached_key = True\n                logger.info(\"Soam inference auth: using cached agent_key\")\n                _oauth_trace(\"agent_key_reuse\", sequence_id=sequence_id)\n            else:\n                _log_soam_legacy_session_key_selected(\n                    fallback_reason or \"legacy_session_key_required\",\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n                try:\n                    _oauth_trace(\n                        \"mint_start\",\n                        sequence_id=sequence_id,\n                        access_token_fp=_token_fingerprint(access_token),\n                    )\n                    mint_payload = _mint_agent_key(\n                        client=client, portal_base_url=portal_base_url,\n                        access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                    )\n                except AuthError as exc:\n                    _oauth_trace(\n                        \"mint_error\",\n                        sequence_id=sequence_id,\n                        code=exc.code,\n                    )\n                    # Retry path: access token may be stale server-side despite local checks\n                    latest_refresh_token = state.get(\"refresh_token\")\n                    if (\n                        exc.code in {\"invalid_token\", \"invalid_grant\"}\n                        and isinstance(latest_refresh_token, str)\n                        and latest_refresh_token\n                    ):\n                        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                            if _merge_shared_soam_oauth_state(state):\n                                access_token = state.get(\"access_token\")\n                                latest_refresh_token = state.get(\"refresh_token\")\n                                _persist_state(\"post_shared_merge_mint_retry\")\n                            else:\n                                _oauth_trace(\n                                    \"refresh_start\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                )\n                                try:\n                                    refreshed = _refresh_access_token(\n                                        client=client, portal_base_url=portal_base_url,\n                                        client_id=client_id, refresh_token=latest_refresh_token,\n                                    )\n                                except AuthError as exc:\n                                    if _is_terminal_soam_refresh_error(exc):\n                                        _quarantine_soam_oauth_state(\n                                            state,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _quarantine_soam_pool_entries(\n                                            auth_store,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _persist_state(\"terminal_runtime_mint_retry_refresh_failure\")\n                                    raise\n                                now = datetime.now(timezone.utc)\n                                access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                                state[\"access_token\"] = refreshed[\"access_token\"]\n                                state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or latest_refresh_token\n                                state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                                state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                                refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                                if refreshed_url:\n                                    inference_base_url = refreshed_url\n                                state[\"obtained_at\"] = now.isoformat()\n                                state[\"expires_in\"] = access_ttl\n                                state[\"expires_at\"] = datetime.fromtimestamp(\n                                    now.timestamp() + access_ttl, tz=timezone.utc\n                                ).isoformat()\n                                access_token = state[\"access_token\"]\n                                refresh_token = state[\"refresh_token\"]\n                                _oauth_trace(\n                                    \"refresh_success\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    previous_refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                    new_refresh_token_fp=_token_fingerprint(refresh_token),\n                                )\n                                # Persist retry refresh immediately for crash safety and cross-process visibility.\n                                _persist_state(\"post_refresh_mint_retry\")\n\n                        retry_inference_auth_mode = (\n                            SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            else SOAM_INFERENCE_AUTH_MODE_FRESH\n                        )\n                        retry_auth_path, _ = _choose_soam_inference_auth_path(\n                            state,\n                            access_token=access_token,\n                            min_key_ttl_seconds=min_key_ttl_seconds,\n                            inference_auth_mode=retry_inference_auth_mode,\n                        )\n                        if retry_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                            mint_payload = None\n                            selected_auth_path = SOAM_AUTH_PATH_INVOKE_JWT\n                            _select_soam_invoke_jwt(\n                                state,\n                                access_token=access_token,\n                                sequence_id=sequence_id,\n                            )\n                        else:\n                            mint_payload = _mint_agent_key(\n                                client=client, portal_base_url=portal_base_url,\n                                access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                            )\n                    else:\n                        raise\n\n            if mint_payload is not None:\n                now = datetime.now(timezone.utc)\n                state[\"agent_key\"] = mint_payload.get(\"api_key\")\n                state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n                state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n                state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n                state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n                state[\"agent_key_obtained_at\"] = now.isoformat()\n                minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n                if minted_url:\n                    inference_base_url = minted_url\n                _oauth_trace(\n                    \"mint_success\",\n                    sequence_id=sequence_id,\n                    reused=bool(mint_payload.get(\"reused\", False)),\n                )\n\n            # Persist routing and TLS metadata for non-interactive refresh/mint\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"inference_base_url\"] = inference_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n\n        _persist_state(\"resolve_soam_runtime_credentials_final\")\n\n    if state_persisted:\n        _sync_soam_pool_from_auth_store()\n\n    api_key = state.get(\"agent_key\")\n    if not isinstance(api_key, str) or not api_key:\n        raise AuthError(\"Failed to resolve a Soam inference API key\",\n                        provider=\"soam\", code=\"server_error\")\n\n    expires_at = state.get(\"agent_key_expires_at\")\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"agent_key_expires_in\"))\n    )\n\n    return {\n        \"provider\": \"soam\",\n        \"base_url\": inference_base_url,\n        \"api_key\": api_key,\n        \"key_id\": state.get(\"agent_key_id\"),\n        \"expires_at\": expires_at,\n        \"expires_in\": expires_in,\n        \"source\": (\n            SOAM_AUTH_PATH_INVOKE_JWT\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT\n            else (\"cache\" if used_cached_key else \"portal\")\n        ),\n        \"auth_path\": selected_auth_path,\n    }\n\n\n# =============================================================================\n# Status helpers\n# =============================================================================\n\ndef _empty_soam_auth_status() -> Dict[str, Any]:\n    return {\n        \"logged_in\": False,\n        \"portal_base_url\": None,\n        \"inference_base_url\": None,\n        \"access_expires_at\": None,\n        \"agent_key_expires_at\": None,\n        \"has_refresh_token\": False,\n    }\n\n\ndef _snapshot_soam_pool_status() -> Dict[str, Any]:\n    \"\"\"Best-effort status from the credential pool.\n\n    This is a fallback only. The auth-store provider state is the runtime source\n    of truth because it is what ``resolve_soam_runtime_credentials()`` refreshes\n    and mints against.\n    \"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"soam\")\n        if not pool or not pool.has_credentials():\n            return _empty_soam_auth_status()\n\n        entries = list(pool.entries())\n        if not entries:\n            return _empty_soam_auth_status()\n\n        def _entry_sort_key(entry: Any) -> tuple[float, float, int]:\n            agent_exp = _parse_iso_timestamp(getattr(entry, \"agent_key_expires_at\", None)) or 0.0\n            access_exp = _parse_iso_timestamp(getattr(entry, \"expires_at\", None)) or 0.0\n            priority = int(getattr(entry, \"priority\", 0) or 0)\n            return (agent_exp, access_exp, -priority)\n\n        entry = max(entries, key=_entry_sort_key)\n        access_token = (\n            getattr(entry, \"access_token\", None)\n            or getattr(entry, \"runtime_api_key\", \"\")\n        )\n        if not access_token:\n            return _empty_soam_auth_status()\n\n        return {\n            \"logged_in\": True,\n            \"portal_base_url\": getattr(entry, \"portal_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"inference_base_url\": getattr(entry, \"inference_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"access_token\": access_token,\n            \"access_expires_at\": getattr(entry, \"expires_at\", None),\n            \"agent_key_expires_at\": getattr(entry, \"agent_key_expires_at\", None),\n            \"has_refresh_token\": bool(getattr(entry, \"refresh_token\", None)),\n            \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n        }\n    except Exception:\n        return _empty_soam_auth_status()\n\n\n# ── Process-level memo for get_soam_auth_status() ──\n# get_soam_auth_status() validates state by calling resolve_soam_runtime_credentials(),\n# which does a synchrosoam OAuth refresh POST to portal.aayushsoam.com. That can take\n# ~350ms even on the failure path, and read-only UI surfaces (`clawbot tools`, status panels,\n# subscription-feature checks) call it many times per render — `clawbot tools` → \"All Platforms\"\n# was firing the refresh ~31× during one menu paint, racking up >13s of HTTP and burning\n# single-use refresh tokens. Cache the snapshot for a few seconds, keyed on the auth.json\n# mtime so that `clawbot auth login/logout/add/remove` invalidate naturally on the next call.\n_SOAM_AUTH_STATUS_CACHE_TTL = 15.0  # seconds\n_soam_auth_status_cache: Optional[Tuple[float, Optional[float], Dict[str, Any]]] = None\n\n\ndef _auth_file_mtime() -> Optional[float]:\n    try:\n        return _auth_file_path().stat().st_mtime\n    except FileNotFoundError:\n        return None\n    except Exception:\n        return None\n\n\ndef invalidate_soam_auth_status_cache() -> None:\n    \"\"\"Clear the get_soam_auth_status() process-level memo.\n\n    Call this from any code path that mutates Soam auth state without going\n    through resolve_soam_runtime_credentials() (e.g. tests). Login/logout\n    flows touch auth.json, so the mtime check below invalidates them\n    automatically — explicit invalidation is the belt-and-braces option.\n    \"\"\"\n    global _soam_auth_status_cache\n    _soam_auth_status_cache = None\n\n\ndef get_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Soam auth.\n\n    Prefer the auth-store provider state, because that is the live source of\n    truth for refresh + mint operations. When provider state exists, validate it\n    by resolving runtime credentials so revoked refresh sessions do not show up\n    as a healthy login. If provider state is absent, fall back to the credential\n    pool for the just-logged-in / not-yet-promoted case.\n\n    The returned snapshot is memoised for ~15s keyed on the auth.json mtime,\n    so menu/status surfaces that ask repeatedly don't trigger one refresh POST\n    per call. Login/logout flows write to auth.json and therefore invalidate\n    the cache automatically; tests can also call\n    ``invalidate_soam_auth_status_cache()`` explicitly.\n    \"\"\"\n    global _soam_auth_status_cache\n    now = time.monotonic()\n    mtime = _auth_file_mtime()\n    cached = _soam_auth_status_cache\n    if cached is not None:\n        cached_at, cached_mtime, cached_status = cached\n        if (\n            cached_mtime == mtime\n            and (now - cached_at) < _SOAM_AUTH_STATUS_CACHE_TTL\n        ):\n            return dict(cached_status)\n\n    status = _compute_soam_auth_status()\n    _soam_auth_status_cache = (now, mtime, dict(status))\n    return status\n\n\ndef _compute_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Uncached implementation of get_soam_auth_status(). See that function.\"\"\"\n    state = get_provider_auth_state(\"soam\")\n    if state:\n        base_status = {\n            \"logged_in\": bool(state.get(\"access_token\")),\n            \"portal_base_url\": state.get(\"portal_base_url\"),\n            \"inference_base_url\": state.get(\"inference_base_url\"),\n            \"access_expires_at\": state.get(\"expires_at\"),\n            \"agent_key_expires_at\": state.get(\"agent_key_expires_at\"),\n            \"has_refresh_token\": bool(state.get(\"refresh_token\")),\n            \"access_token\": state.get(\"access_token\"),\n            \"source\": \"auth_store\",\n        }\n        try:\n            creds = resolve_soam_runtime_credentials(min_key_ttl_seconds=60)\n            refreshed_state = get_provider_auth_state(\"soam\") or state\n            base_status.update(\n                {\n                    \"logged_in\": True,\n                    \"portal_base_url\": refreshed_state.get(\"portal_base_url\") or base_status.get(\"portal_base_url\"),\n                    \"inference_base_url\": creds.get(\"base_url\")\n                    or refreshed_state.get(\"inference_base_url\")\n                    or base_status.get(\"inference_base_url\"),\n                    \"access_expires_at\": refreshed_state.get(\"expires_at\") or base_status.get(\"access_expires_at\"),\n                    \"agent_key_expires_at\": creds.get(\"expires_at\")\n                    or refreshed_state.get(\"agent_key_expires_at\")\n                    or base_status.get(\"agent_key_expires_at\"),\n                    \"has_refresh_token\": bool(refreshed_state.get(\"refresh_token\")),\n                    \"source\": f\"runtime:{creds.get('source', 'portal')}\",\n                    \"key_id\": creds.get(\"key_id\"),\n                }\n            )\n            return base_status\n        except AuthError as exc:\n            base_status.update({\n                \"logged_in\": False,\n                \"error\": str(exc),\n                \"relogin_required\": bool(getattr(exc, \"relogin_required\", False)),\n                \"error_code\": getattr(exc, \"code\", None),\n            })\n            return base_status\n\n    return _snapshot_soam_pool_status()\n\n\ndef get_codex_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Codex auth.\n    \n    Checks the credential pool first (where `clawbot auth` stores credentials),\n    then falls back to the legacy provider state.\n    \"\"\"\n    # Check credential pool first — this is where `clawbot auth` and\n    # `clawbot model` store device_code tokens.\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(\"openai-codex\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _codex_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"chatgpt\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    # Fall back to legacy provider state\n    try:\n        creds = resolve_codex_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_xai_oauth_auth_status() -> Dict[str, Any]:\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"xai-oauth\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _xai_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"oauth_pkce\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    try:\n        creds = resolve_xai_oauth_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_api_key_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for API-key providers (z.ai, Kimi, MiniMax).\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        return {\"configured\": False}\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"configured\": bool(api_key),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"key_source\": key_source,\n        \"base_url\": base_url,\n        \"logged_in\": bool(api_key),  # compat with OAuth status shape\n    }\n\n\ndef get_external_process_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for providers that run a local subprocess.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        return {\"configured\": False}\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    resolved_command = shutil.which(command) if command else None\n    return {\n        \"configured\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"command\": command,\n        \"args\": args,\n        \"resolved_command\": resolved_command,\n        \"base_url\": base_url,\n        \"logged_in\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n    }\n\n\ndef get_auth_status(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Generic auth status dispatcher.\"\"\"\n    target = provider_id or get_active_provider()\n    if target == \"spotify\":\n        return get_spotify_auth_status()\n    if target == \"soam\":\n        return get_soam_auth_status()\n    if target == \"openai-codex\":\n        return get_codex_auth_status()\n    if target == \"xai-oauth\":\n        return get_xai_oauth_auth_status()\n    if target == \"qwen-oauth\":\n        return get_qwen_auth_status()\n    if target == \"google-gemini-cli\":\n        return get_gemini_oauth_auth_status()\n    if target == \"minimax-oauth\":\n        return get_minimax_oauth_auth_status()\n    if target == \"copilot-acp\":\n        return get_external_process_provider_status(target)\n    # API-key providers\n    pconfig = PROVIDER_REGISTRY.get(target)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        return get_api_key_provider_status(target)\n    # AWS SDK providers (Bedrock) — check via boto3 credential chain\n    if pconfig and pconfig.auth_type == \"aws_sdk\":\n        try:\n            from agent.bedrock_adapter import has_aws_credentials\n            return {\"logged_in\": has_aws_credentials(), \"provider\": target}\n        except ImportError:\n            return {\"logged_in\": False, \"provider\": target, \"error\": \"boto3 not installed\"}\n    return {\"logged_in\": False}\n\n\ndef resolve_api_key_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve API key and base URL for an API-key provider.\n\n    Returns dict with: provider, api_key, base_url, source.\n    \"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an API-key provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    # No-auth LM Studio: substitute a placeholder so runtime / auxiliary_client\n    # see the local server as configured. doctor still reports unconfigured\n    # because get_api_key_provider_status uses the raw secret resolver.\n    if not api_key and provider_id == \"lmstudio\":\n        api_key = LMSTUDIO_NOAUTH_PLACEHOLDER\n        key_source = key_source or \"default\"\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif provider_id == \"zai\":\n        base_url = _resolve_zai_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url.rstrip(\"/\")\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": api_key,\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"source\": key_source or \"default\",\n    }\n\n\ndef resolve_external_process_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve runtime details for local subprocess-backed providers.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an external-process provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    resolved_command = shutil.which(command) if command else None\n    if not resolved_command and not base_url.startswith(\"acp+tcp://\"):\n        raise AuthError(\n            f\"Could not find the Copilot CLI command '{command}'. \"\n            \"Install GitHub Copilot CLI or set CLAWBOT_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH.\",\n            provider=provider_id,\n            code=\"missing_copilot_cli\",\n        )\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": \"copilot-acp\",\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"command\": resolved_command or command,\n        \"args\": args,\n        \"source\": \"process\",\n    }\n\n\n# =============================================================================\n# CLI Commands — login / logout\n# =============================================================================\n\ndef _update_config_for_provider(\n    provider_id: str,\n    inference_base_url: str,\n    default_model: Optional[str] = None,\n) -> Path:\n    \"\"\"Update config.yaml and auth.json to reflect the active provider.\n\n    When *default_model* is provided the function also writes it as the\n    ``model.default`` value.  This prevents a race condition where the\n    gateway (which re-reads config per-message) picks up the new provider\n    before the caller has finished model selection, resulting in a\n    mismatched model/provider (e.g. ``anthropic/claude-opus-4.6`` sent to\n    MiniMax's API).\n    \"\"\"\n    # Set active_provider in auth.json so auto-resolution picks this provider\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = provider_id\n        _save_auth_store(auth_store)\n\n    # Update config.yaml model section\n    config_path = get_config_path()\n    config_path.parent.mkdir(parents=True, exist_ok=True)\n\n    config = read_raw_config()\n\n    current_model = config.get(\"model\")\n    if isinstance(current_model, dict):\n        model_cfg = dict(current_model)\n    elif isinstance(current_model, str) and current_model.strip():\n        model_cfg = {\"default\": current_model.strip()}\n    else:\n        model_cfg = {}\n\n    model_cfg[\"provider\"] = provider_id\n    if inference_base_url and inference_base_url.strip():\n        model_cfg[\"base_url\"] = inference_base_url.rstrip(\"/\")\n    else:\n        # Clear stale base_url to prevent contamination when switching providers\n        model_cfg.pop(\"base_url\", None)\n\n    # Clear stale api_key/api_mode left over from a previous custom provider.\n    # When the user switches from e.g. a MiniMax custom endpoint\n    # (api_mode=anthropic_messages, api_key=mxp-...) to a built-in provider\n    # (e.g. OpenRouter), the stale api_key/api_mode would override the new\n    # provider's credentials and transport choice.  Built-in providers that\n    # need a specific api_mode (copilot, xai) set it at request-resolution\n    # time via `_copilot_runtime_api_mode` / `_detect_api_mode_for_url`, so\n    # removing the persisted value here is safe.\n    model_cfg.pop(\"api_key\", None)\n    model_cfg.pop(\"api_mode\", None)\n\n    # When switching to a non-OpenRouter provider, ensure model.default is\n    # valid for the new provider.  An OpenRouter-formatted name like\n    # \"anthropic/claude-opus-4.6\" will fail on direct-API providers.\n    if default_model:\n        cur_default = model_cfg.get(\"default\", \"\")\n        if not cur_default or \"/\" in cur_default:\n            model_cfg[\"default\"] = default_model\n\n    config[\"model\"] = model_cfg\n\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _get_config_provider() -> Optional[str]:\n    \"\"\"Return model.provider from config.yaml, normalized, if present.\"\"\"\n    try:\n        config = read_raw_config()\n    except Exception:\n        return None\n    if not config:\n        return None\n    model = config.get(\"model\")\n    if not isinstance(model, dict):\n        return None\n    provider = model.get(\"provider\")\n    if not isinstance(provider, str):\n        return None\n    provider = provider.strip().lower()\n    return provider or None\n\n\ndef _config_provider_matches(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when config.yaml currently selects *provider_id*.\"\"\"\n    if not provider_id:\n        return False\n    return _get_config_provider() == provider_id.strip().lower()\n\n\ndef _should_reset_config_provider_on_logout(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when logout should reset the model provider config.\"\"\"\n    if not provider_id:\n        return False\n    normalized = provider_id.strip().lower()\n    return normalized in PROVIDER_REGISTRY and _config_provider_matches(normalized)\n\n\ndef _logout_default_provider_from_config() -> Optional[str]:\n    \"\"\"Fallback logout target when auth.json has no active provider.\n\n    `clawbot logout` historically keyed off auth.json.active_provider only.\n    That left users stuck when auth state had already been cleared but\n    config.yaml still selected an OAuth provider such as openai-codex for the\n    agent model: there was no active auth provider to target, so logout printed\n    \"No provider is currently logged in\" and never reset model.provider.\n    \"\"\"\n    provider = _get_config_provider()\n    if provider in {\"soam\", \"openai-codex\", \"xai-oauth\"}:\n        return provider\n    return None\n\n\ndef _reset_config_provider() -> Path:\n    \"\"\"Reset config.yaml provider back to auto after logout.\"\"\"\n    config_path = get_config_path()\n    if not config_path.exists():\n        return config_path\n\n    config = read_raw_config()\n    if not config:\n        return config_path\n\n    model = config.get(\"model\")\n    if isinstance(model, dict):\n        model[\"provider\"] = \"auto\"\n        if \"base_url\" in model:\n            model[\"base_url\"] = OPENROUTER_BASE_URL\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _prompt_model_selection(\n    model_ids: List[str],\n    current_model: str = \"\",\n    pricing: Optional[Dict[str, Dict[str, str]]] = None,\n    unavailable_models: Optional[List[str]] = None,\n    portal_url: str = \"\",\n) -> Optional[str]:\n    \"\"\"Interactive model selection. Puts current_model first with a marker. Returns chosen model ID or None.\n\n    If *pricing* is provided (``{model_id: {prompt, completion}}``), a compact\n    price indicator is shown next to each model in aligned columns.\n\n    If *unavailable_models* is provided, those models are shown grayed out\n    and unselectable, with an upgrade link to *portal_url*.\n    \"\"\"\n    from clawbot_cli.models import _format_price_per_mtok\n\n    _unavailable = unavailable_models or []\n\n    # Reorder: current model first, then the rest (deduplicated)\n    ordered = []\n    if current_model and current_model in model_ids:\n        ordered.append(current_model)\n    for mid in model_ids:\n        if mid not in ordered:\n            ordered.append(mid)\n\n    # All models for column-width computation (selectable + unavailable)\n    all_models = list(ordered) + list(_unavailable)\n\n    # Column-aligned labels when pricing is available\n    has_pricing = bool(pricing and any(pricing.get(m) for m in all_models))\n    name_col = max((len(m) for m in all_models), default=0) + 2 if has_pricing else 0\n\n    # Pre-compute formatted prices and dynamic column widths\n    _price_cache: dict[str, tuple[str, str, str]] = {}\n    price_col = 3  # minimum width\n    cache_col = 0  # only set if any model has cache pricing\n    has_cache = False\n    if has_pricing:\n        for mid in all_models:\n            p = pricing.get(mid)  # type: ignore[union-attr]\n            if p:\n                inp = _format_price_per_mtok(p.get(\"prompt\", \"\"))\n                out = _format_price_per_mtok(p.get(\"completion\", \"\"))\n                cache_read = p.get(\"input_cache_read\", \"\")\n                cache = _format_price_per_mtok(cache_read) if cache_read else \"\"\n                if cache:\n                    has_cache = True\n            else:\n                inp, out, cache = \"\", \"\", \"\"\n            _price_cache[mid] = (inp, out, cache)\n            price_col = max(price_col, len(inp), len(out))\n            cache_col = max(cache_col, len(cache))\n        if has_cache:\n            cache_col = max(cache_col, 5)  # minimum: \"Cache\" header\n\n    def _label(mid):\n        if has_pricing:\n            inp, out, cache = _price_cache.get(mid, (\"\", \"\", \"\"))\n            price_part = f\" {inp:>{price_col}}  {out:>{price_col}}\"\n            if has_cache:\n                price_part += f\"  {cache:>{cache_col}}\"\n            base = f\"{mid:<{name_col}}{price_part}\"\n        else:\n            base = mid\n        if mid == current_model:\n            base += \"  ← currently in use\"\n        return base\n\n    # Default cursor on the current model (index 0 if it was reordered to top)\n    default_idx = 0\n\n    # Build a pricing header hint for the menu title\n    menu_title = \"Select default model:\"\n    if has_pricing:\n        # Align the header with the model column.\n        # Each choice is \"  {label}\" (2 spaces) and simple_term_menu prepends\n        # a 3-char cursor region (\"-> \" or \"   \"), so content starts at col 5.\n        pad = \" \" * 5\n        header = f\"\\n{pad}{'':>{name_col}} {'In':>{price_col}}  {'Out':>{price_col}}\"\n        if has_cache:\n            header += f\"  {'Cache':>{cache_col}}\"\n        menu_title += header + \"  /Mtok\"\n\n    # ANSI escape for dim text\n    _DIM = \"\\033[2m\"\n    _RESET = \"\\033[0m\"\n\n    # Try arrow-key menu first, fall back to number input\n    try:\n        from simple_term_menu import TerminalMenu\n\n        choices = [f\"  {_label(mid)}\" for mid in ordered]\n        choices.append(\"  Enter custom model name\")\n        choices.append(\"  Skip (keep current)\")\n\n        # Print the unavailable block BEFORE the menu via regular print().\n        # simple_term_menu pads title lines to terminal width (causes wrapping),\n        # so we keep the title minimal and use stdout for the static block.\n        # clear_screen=False means our printed output stays visible above.\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        if _unavailable:\n            print(menu_title)\n            print()\n            for mid in _unavailable:\n                print(f\"{_DIM}     {_label(mid)}{_RESET}\")\n            print()\n            print(f\"{_DIM}  ── Upgrade at {_upgrade_url} for paid models ──{_RESET}\")\n            print()\n            effective_title = \"Available free models:\"\n        else:\n            effective_title = menu_title\n\n        menu = TerminalMenu(\n            choices,\n            cursor_index=default_idx,\n            menu_cursor=\"-> \",\n            menu_cursor_style=(\"fg_green\", \"bold\"),\n            menu_highlight_style=(\"fg_green\",),\n            cycle_cursor=True,\n            clear_screen=False,\n            title=effective_title,\n        )\n        idx = menu.show()\n        from clawbot_cli.curses_ui import flush_stdin\n        flush_stdin()\n        if idx is None:\n            return None\n        print()\n        if idx < len(ordered):\n            return ordered[idx]\n        elif idx == len(ordered):\n            custom = input(\"Enter model name: \").strip()\n            return custom if custom else None\n        return None\n    except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError):\n        pass\n\n    # Fallback: numbered list\n    print(menu_title)\n    num_width = len(str(len(ordered) + 2))\n    for i, mid in enumerate(ordered, 1):\n        print(f\"  {i:>{num_width}}. {_label(mid)}\")\n    n = len(ordered)\n    print(f\"  {n + 1:>{num_width}}. Enter custom model name\")\n    print(f\"  {n + 2:>{num_width}}. Skip (keep current)\")\n\n    if _unavailable:\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        print()\n        print(f\"  {_DIM}── Unavailable models (requires paid tier — upgrade at {_upgrade_url}) ──{_RESET}\")\n        for mid in _unavailable:\n            print(f\"  {'':>{num_width}}  {_DIM}{_label(mid)}{_RESET}\")\n    print()\n\n    while True:\n        try:\n            choice = input(f\"Choice [1-{n + 2}] (default: skip): \").strip()\n            if not choice:\n                return None\n            idx = int(choice)\n            if 1 <= idx <= n:\n                return ordered[idx - 1]\n            elif idx == n + 1:\n                custom = input(\"Enter model name: \").strip()\n                return custom if custom else None\n            elif idx == n + 2:\n                return None\n            print(f\"Please enter 1-{n + 2}\")\n        except ValueError:\n            print(\"Please enter a number\")\n        except (KeyboardInterrupt, EOFError):\n            return None\n\n\ndef _save_model_choice(model_id: str) -> None:\n    \"\"\"Save the selected model to config.yaml (single source of truth).\n\n    The model is stored in config.yaml only — NOT in .env.  This avoids\n    conflicts in multi-agent setups where env vars would stomp each other.\n    \"\"\"\n    from clawbot_cli.config import save_config, load_config\n\n    config = load_config()\n    # Always use dict format so provider/base_url can be stored alongside\n    if isinstance(config.get(\"model\"), dict):\n        config[\"model\"][\"default\"] = model_id\n    else:\n        config[\"model\"] = {\"default\": model_id}\n    save_config(config)\n\n\ndef login_command(args) -> None:\n    \"\"\"Deprecated: use 'clawbot model' or 'clawbot setup' instead.\"\"\"\n    print(\"The 'clawbot login' command has been removed.\")\n    print(\"Use 'clawbot auth' to manage credentials,\")\n    print(\"'clawbot model' to select a provider, or 'clawbot setup' for full setup.\")\n    raise SystemExit(0)\n\n\ndef _login_openai_codex(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    \"\"\"OpenAI Codex login via device code flow. Tokens stored in ~/.clawbot/auth.json.\"\"\"\n\n    del args, pconfig  # kept for parity with other provider login helpers\n\n    # Check for existing Clawbot-owned credentials\n    if not force_new_login:\n        try:\n            existing = resolve_codex_runtime_credentials()\n            # Verify the resolved token is actually usable (not expired).\n            # resolve_codex_runtime_credentials attempts refresh, so if we get\n            # here the token should be valid — but double-check before telling\n            # the user \"Login successful!\".\n            _resolved_key = existing.get(\"api_key\", \"\")\n            if isinstance(_resolved_key, str) and _resolved_key and not _codex_access_token_is_expiring(_resolved_key, 60):\n                print(\"Existing Codex credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\"openai-codex\", existing.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                    return\n            else:\n                print(\"Existing Codex credentials are expired. Starting fresh login...\")\n        except AuthError:\n            pass\n\n    # Check for existing Codex CLI tokens we can import\n    if not force_new_login:\n        cli_tokens = _import_codex_cli_tokens()\n        if cli_tokens:\n            print(\"Found existing Codex CLI credentials at ~/.codex/auth.json\")\n            print(\"Clawbot will create its own session to avoid conflicts with Codex CLI / VS Code.\")\n            try:\n                do_import = input(\"Import these credentials? (a separate login is recommended) [y/N]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"n\"\n            if do_import in {\"y\", \"yes\"}:\n                _save_codex_tokens(cli_tokens)\n                base_url = os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_CODEX_BASE_URL\n                config_path = _update_config_for_provider(\"openai-codex\", base_url)\n                print()\n                print(\"Credentials imported. Note: if Codex CLI refreshes its token,\")\n                print(\"Clawbot will keep working independently with its own session.\")\n                print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                return\n\n    # Run a fresh device code flow — Clawbot gets its own OAuth session\n    print()\n    print(\"Signing in to OpenAI Codex...\")\n    print(\"(Clawbot creates its own session — won't affect Codex CLI or VS Code)\")\n    print()\n\n    creds = _codex_device_code_login()\n\n    # Save tokens to Clawbot auth store\n    _save_codex_tokens(creds[\"tokens\"], creds.get(\"last_refresh\"))\n    config_path = _update_config_for_provider(\"openai-codex\", creds.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n\n\ndef _login_xai_oauth(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    del pconfig\n\n    if not force_new_login:\n        try:\n            existing = resolve_xai_oauth_runtime_credentials()\n            api_key = existing.get(\"api_key\", \"\")\n            if isinstance(api_key, str) and api_key and not _xai_access_token_is_expiring(api_key, 60):\n                print(\"Existing xAI OAuth credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\n                        \"xai-oauth\",\n                        existing.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL),\n                    )\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n                    return\n        except AuthError:\n            pass\n\n    print()\n    print(\"Signing in to xAI Grok OAuth (SuperGrok Subscription)...\")\n    print(\"(Clawbot creates its own local OAuth session)\")\n    print()\n\n    timeout_seconds = float(getattr(args, \"timeout\", None) or 20.0)\n    open_browser = not getattr(args, \"no_browser\", False)\n    if _is_remote_session():\n        open_browser = False\n\n    creds = _xai_oauth_loopback_login(timeout_seconds=timeout_seconds, open_browser=open_browser)\n    _save_xai_oauth_tokens(\n        creds[\"tokens\"],\n        discovery=creds.get(\"discovery\"),\n        redirect_uri=creds.get(\"redirect_uri\", \"\"),\n        last_refresh=creds.get(\"last_refresh\"),\n    )\n    config_path = _update_config_for_provider(\"xai-oauth\", creds.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n\n\ndef _xai_oauth_build_authorize_url(\n    *,\n    authorization_endpoint: str,\n    redirect_uri: str,\n    code_challenge: str,\n    state: str,\n    nonce: str,\n) -> str:\n    # `plan=generic` opts the consent screen into xAI's generic OAuth plan\n    # tier instead of falling back to the per-account default. Without it,\n    # accounts.x.ai rejects loopback OAuth from non-allowlisted clients.\n    # `referrer=clawbot-agent` lets xAI attribute Clawbot-originated logins\n    # in their OAuth server logs (we still impersonate the upstream Grok-CLI\n    # client_id; this is best-effort attribution until xAI mints us our own).\n    authorize_params = {\n        \"response_type\": \"code\",\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"redirect_uri\": redirect_uri,\n        \"scope\": XAI_OAUTH_SCOPE,\n        \"code_challenge\": code_challenge,\n        \"code_challenge_method\": \"S256\",\n        \"state\": state,\n        \"nonce\": nonce,\n        \"plan\": \"generic\",\n        \"referrer\": \"clawbot-agent\",\n    }\n    return f\"{authorization_endpoint}?{urlencode(authorize_params)}\"\n\n\ndef _xai_oauth_exchange_code_for_tokens(\n    *,\n    token_endpoint: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    code_challenge: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"POST the authorization code to xAI's token endpoint and return\n    the parsed JSON payload.\n\n    Sends ``code_verifier`` as required by RFC 7636 §4.5.  Also echoes\n    ``code_challenge`` + ``code_challenge_method`` in the request body\n    as a defense-in-depth measure for OAuth servers (xAI's among them,\n    per #26990) that re-validate the challenge at the token step\n    instead of relying solely on server-side session state captured\n    during the authorize step.  Echoing the challenge is harmless for\n    strict RFC-compliant servers — RFC 7636 doesn't forbid additional\n    parameters at the token endpoint — and decisively fixes the\n    ``code_challenge is required`` failure mode users hit on the\n    loopback flow.\n\n    Raises :class:`AuthError` on any non-2xx response or transport\n    failure; the error message embeds the HTTP status code and the\n    full response body so users can disambiguate cause at a glance.\n    \"\"\"\n    # Paranoia: if upstream call sites ever drop ``code_verifier`` we\n    # want to surface a precise, local error rather than send a\n    # missing-PKCE request to xAI and receive their generic \"code\n    # challenge required\" message back.\n    if not code_verifier:\n        raise AuthError(\n            \"xAI token exchange refused locally: PKCE code_verifier is empty. \"\n            \"This is a bug in Clawbot — please report at \"\n            \"https://github.com/aayushsoam/clawbot-agent/issues/26990.\",\n            provider=\"xai-oauth\",\n            code=\"xai_pkce_verifier_missing\",\n        )\n\n    data = {\n        \"grant_type\": \"authorization_code\",\n        \"code\": code,\n        \"redirect_uri\": redirect_uri,\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"code_verifier\": code_verifier,\n    }\n    # Defense-in-depth: include the original ``code_challenge`` and\n    # ``code_challenge_method``.  Some OAuth servers (including xAI's\n    # auth.x.ai implementation, per the symptom reported in #26990)\n    # validate these at the token endpoint instead of relying purely on\n    # state captured during the authorize step — without them, xAI\n    # rejects the exchange with ``code_challenge is required`` even\n    # though we sent a valid ``code_verifier``.\n    if code_challenge:\n        data[\"code_challenge\"] = code_challenge\n        data[\"code_challenge_method\"] = \"S256\"\n\n    try:\n        response = httpx.post(\n            token_endpoint,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data=data,\n            timeout=max(20.0, timeout_seconds),\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code != 200:\n        body = response.text.strip()\n        raise AuthError(\n            f\"xAI token exchange failed (HTTP {response.status_code}).\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token exchange response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _xai_oauth_loopback_login(\n    *,\n    timeout_seconds: float = 20.0,\n    open_browser: bool = True,\n) -> Dict[str, Any]:\n    discovery = _xai_oauth_discovery(timeout_seconds)\n    authorization_endpoint = discovery[\"authorization_endpoint\"]\n    token_endpoint = discovery[\"token_endpoint\"]\n\n    server, thread, callback_result, redirect_uri = _xai_start_callback_server()\n    try:\n        _xai_validate_loopback_redirect_uri(redirect_uri)\n        code_verifier = _oauth_pkce_code_verifier()\n        code_challenge = _oauth_pkce_code_challenge(code_verifier)\n        state = uuid.uuid4().hex\n        nonce = uuid.uuid4().hex\n        authorize_url = _xai_oauth_build_authorize_url(\n            authorization_endpoint=authorization_endpoint,\n            redirect_uri=redirect_uri,\n            code_challenge=code_challenge,\n            state=state,\n            nonce=nonce,\n        )\n\n        print(\"Open this URL to authorize Clawbot with xAI:\")\n        print(authorize_url)\n        print()\n        print(f\"Waiting for callback on {redirect_uri}\")\n\n        _print_loopback_ssh_hint(redirect_uri, docs_url=XAI_OAUTH_DOCS_URL)\n\n        if open_browser and not _is_remote_session():\n            try:\n                opened = webbrowser.open(authorize_url)\n            except Exception:\n                opened = False\n            if opened:\n                print(\"Browser opened for xAI authorization.\")\n            else:\n                print(\"Could not open the browser automatically; use the URL above.\")\n\n        callback = _xai_wait_for_callback(\n            server,\n            thread,\n            callback_result,\n            timeout_seconds=max(30.0, timeout_seconds * 9),\n        )\n    except Exception:\n        try:\n            server.shutdown()\n            server.server_close()\n        except Exception:\n            pass\n        try:\n            thread.join(timeout=1.0)\n        except Exception:\n            pass\n        raise\n\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise AuthError(\n            f\"xAI authorization failed: {detail}\",\n            provider=\"xai-oauth\",\n            code=\"xai_authorization_failed\",\n        )\n    if callback.get(\"state\") != state:\n        raise AuthError(\n            \"xAI authorization failed: state mismatch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_state_mismatch\",\n        )\n    code = str(callback.get(\"code\") or \"\").strip()\n    if not code:\n        raise AuthError(\n            \"xAI authorization failed: missing authorization code.\",\n            provider=\"xai-oauth\",\n            code=\"xai_code_missing\",\n        )\n\n    payload = _xai_oauth_exchange_code_for_tokens(\n        token_endpoint=token_endpoint,\n        code=code,\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        code_challenge=code_challenge,\n        timeout_seconds=timeout_seconds,\n    )\n    access_token = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(payload.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI token exchange did not return an access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI token exchange did not return a refresh_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n            \"id_token\": str(payload.get(\"id_token\", \"\") or \"\").strip(),\n            \"expires_in\": payload.get(\"expires_in\"),\n            \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        },\n        \"discovery\": discovery,\n        \"redirect_uri\": redirect_uri,\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"source\": \"oauth-loopback\",\n    }\n\n\ndef _codex_device_code_login() -> Dict[str, Any]:\n    \"\"\"Run the OpenAI device code login flow and return credentials dict.\"\"\"\n    import time as _time\n\n    issuer = \"https://auth.openai.com\"\n    client_id = CODEX_OAUTH_CLIENT_ID\n\n    # Step 1: Request device code\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            resp = client.post(\n                f\"{issuer}/api/accounts/deviceauth/usercode\",\n                json={\"client_id\": client_id},\n                headers={\"Content-Type\": \"application/json\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to request device code: {exc}\",\n            provider=\"openai-codex\", code=\"device_code_request_failed\",\n        )\n\n    if resp.status_code != 200:\n        raise AuthError(\n            f\"Device code request returned status {resp.status_code}.\",\n            provider=\"openai-codex\", code=\"device_code_request_error\",\n        )\n\n    device_data = resp.json()\n    user_code = device_data.get(\"user_code\", \"\")\n    device_auth_id = device_data.get(\"device_auth_id\", \"\")\n    poll_interval = max(3, int(device_data.get(\"interval\", \"5\")))\n\n    if not user_code or not device_auth_id:\n        raise AuthError(\n            \"Device code response missing required fields.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete\",\n        )\n\n    # Step 2: Show user the code\n    print(\"To continue, follow these steps:\\n\")\n    print(\"  1. Open this URL in your browser:\")\n    print(f\"     \\033[94m{issuer}/codex/device\\033[0m\\n\")\n    print(\"  2. Enter this code:\")\n    print(f\"     \\033[94m{user_code}\\033[0m\\n\")\n    print(\"Waiting for sign-in... (press Ctrl+C to cancel)\")\n\n    # Step 3: Poll for authorization code\n    max_wait = 15 * 60  # 15 minutes\n    start = _time.monotonic()\n    code_resp = None\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            while _time.monotonic() - start < max_wait:\n                _time.sleep(poll_interval)\n                poll_resp = client.post(\n                    f\"{issuer}/api/accounts/deviceauth/token\",\n                    json={\"device_auth_id\": device_auth_id, \"user_code\": user_code},\n                    headers={\"Content-Type\": \"application/json\"},\n                )\n\n                if poll_resp.status_code == 200:\n                    code_resp = poll_resp.json()\n                    break\n                elif poll_resp.status_code in {403, 404}:\n                    continue  # User hasn't completed login yet\n                else:\n                    raise AuthError(\n                        f\"Device auth polling returned status {poll_resp.status_code}.\",\n                        provider=\"openai-codex\", code=\"device_code_poll_error\",\n                    )\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n\n    if code_resp is None:\n        raise AuthError(\n            \"Login timed out after 15 minutes.\",\n            provider=\"openai-codex\", code=\"device_code_timeout\",\n        )\n\n    # Step 4: Exchange authorization code for tokens\n    authorization_code = code_resp.get(\"authorization_code\", \"\")\n    code_verifier = code_resp.get(\"code_verifier\", \"\")\n    redirect_uri = f\"{issuer}/deviceauth/callback\"\n\n    if not authorization_code or not code_verifier:\n        raise AuthError(\n            \"Device auth response missing authorization_code or code_verifier.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete_exchange\",\n        )\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            token_resp = client.post(\n                CODEX_OAUTH_TOKEN_URL,\n                data={\n                    \"grant_type\": \"authorization_code\",\n                    \"code\": authorization_code,\n                    \"redirect_uri\": redirect_uri,\n                    \"client_id\": client_id,\n                    \"code_verifier\": code_verifier,\n                },\n                headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Token exchange failed: {exc}\",\n            provider=\"openai-codex\", code=\"token_exchange_failed\",\n        )\n\n    if token_resp.status_code != 200:\n        raise AuthError(\n            f\"Token exchange returned status {token_resp.status_code}.\",\n            provider=\"openai-codex\", code=\"token_exchange_error\",\n        )\n\n    tokens = token_resp.json()\n    access_token = tokens.get(\"access_token\", \"\")\n    refresh_token = tokens.get(\"refresh_token\", \"\")\n\n    if not access_token:\n        raise AuthError(\n            \"Token exchange did not return an access_token.\",\n            provider=\"openai-codex\", code=\"token_exchange_no_access_token\",\n        )\n\n    # Return tokens for the caller to persist (no longer writes to ~/.codex/)\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n        },\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"auth_mode\": \"chatgpt\",\n        \"source\": \"device-code\",\n    }\n\n\n# ==================== MiniMax Portal OAuth ====================\n\ndef _minimax_pkce_pair() -> tuple:\n    \"\"\"Generate (code_verifier, code_challenge_S256, state) for MiniMax OAuth.\"\"\"\n    import secrets\n    verifier = secrets.token_urlsafe(64)[:96]\n    challenge = base64.urlsafe_b64encode(\n        hashlib.sha256(verifier.encode()).digest()\n    ).decode().rstrip(\"=\")\n    state = secrets.token_urlsafe(16)\n    return verifier, challenge, state\n\n\ndef _minimax_request_user_code(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    code_challenge: str, state: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/oauth/code\",\n        data={\n            \"response_type\": \"code\",\n            \"client_id\": client_id,\n            \"scope\": MINIMAX_OAUTH_SCOPE,\n            \"code_challenge\": code_challenge,\n            \"code_challenge_method\": \"S256\",\n            \"state\": state,\n        },\n        headers={\n            \"Content-Type\": \"application/x-www-form-urlencoded\",\n            \"Accept\": \"application/json\",\n            \"x-request-id\": str(uuid.uuid4()),\n        },\n    )\n    if response.status_code != 200:\n        raise AuthError(\n            f\"MiniMax OAuth authorization failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"authorization_failed\",\n        )\n    payload = response.json()\n    for field in (\"user_code\", \"verification_uri\", \"expired_in\"):\n        if field not in payload:\n            raise AuthError(\n                f\"MiniMax OAuth response missing field: {field}\",\n                provider=\"minimax-oauth\", code=\"authorization_incomplete\",\n            )\n    if payload.get(\"state\") != state:\n        raise AuthError(\n            \"MiniMax OAuth state mismatch (possible CSRF).\",\n            provider=\"minimax-oauth\", code=\"state_mismatch\",\n        )\n    return payload\n\n\ndef _minimax_expired_in_looks_like_unix_ms(expired_in: int, *, now_ms: int) -> bool:\n    \"\"\"True if ``expired_in`` is plausibly a unix-ms absolute time (vs TTL seconds).\"\"\"\n    return int(expired_in) > (now_ms // 2)\n\n\ndef _minimax_resolve_token_expiry_unix(expired_in: int, *, now: datetime) -> float:\n    \"\"\"Return access-token expiry as unix seconds (MiniMax uses ms epoch or TTL seconds).\"\"\"\n    raw = int(expired_in)\n    now_ms = int(now.timestamp() * 1000)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        return raw / 1000.0\n    return now.timestamp() + max(1, raw)\n\n\ndef _minimax_poll_token(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    user_code: str, code_verifier: str, expired_in: int, interval_ms: Optional[int],\n) -> Dict[str, Any]:\n    # OpenClaw treats expired_in as a unix-ms timestamp (Date.now() < expireTimeMs).\n    # Defensive parsing: if it's small enough to be a duration, treat as seconds.\n    import time as _time\n    now_ms = int(_time.time() * 1000)\n    raw = int(expired_in)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        deadline = raw / 1000.0\n    else:\n        deadline = _time.time() + max(1, raw)\n    interval = max(2.0, (interval_ms or 2000) / 1000.0)\n\n    while _time.time() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": MINIMAX_OAUTH_GRANT_TYPE,\n                \"client_id\": client_id,\n                \"user_code\": user_code,\n                \"code_verifier\": code_verifier,\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n        try:\n            payload = response.json() if response.text else {}\n        except Exception:\n            payload = {}\n\n        if response.status_code != 200:\n            msg = (payload.get(\"base_resp\", {}) or {}).get(\"status_msg\") or response.text\n            raise AuthError(\n                f\"MiniMax OAuth error: {msg or 'unknown'}\",\n                provider=\"minimax-oauth\", code=\"token_exchange_failed\",\n            )\n\n        status = payload.get(\"status\")\n        if status == \"error\":\n            raise AuthError(\n                \"MiniMax OAuth reported an error. Please try again later.\",\n                provider=\"minimax-oauth\", code=\"authorization_denied\",\n            )\n        if status == \"success\":\n            if not all(payload.get(k) for k in (\"access_token\", \"refresh_token\", \"expired_in\")):\n                raise AuthError(\n                    \"MiniMax OAuth success payload missing required token fields.\",\n                    provider=\"minimax-oauth\", code=\"token_incomplete\",\n                )\n            return payload\n        # \"pending\" or any other status -> keep polling\n        _time.sleep(interval)\n\n    raise AuthError(\n        \"MiniMax OAuth timed out before authorization completed.\",\n        provider=\"minimax-oauth\", code=\"timeout\",\n    )\n\n\ndef _minimax_save_auth_state(auth_state: Dict[str, Any]) -> None:\n    \"\"\"Persist MiniMax OAuth state to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"minimax-oauth\", auth_state)\n        _save_auth_store(auth_store)\n\n\ndef _minimax_oauth_login(\n    *, region: str = \"global\", open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n) -> Dict[str, Any]:\n    \"\"\"Run MiniMax OAuth flow, persist tokens, return auth state dict.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"minimax-oauth\"]\n    if region == \"cn\":\n        portal_base_url = pconfig.extra[\"cn_portal_base_url\"]\n        inference_base_url = pconfig.extra[\"cn_inference_base_url\"]\n    else:\n        portal_base_url = pconfig.portal_base_url\n        inference_base_url = pconfig.inference_base_url\n\n    verifier, challenge, state = _minimax_pkce_pair()\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via MiniMax ({region}) OAuth...\")\n    print(f\"Portal: {portal_base_url}\")\n\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      headers={\"Accept\": \"application/json\"},\n                      follow_redirects=True) as client:\n        code_data = _minimax_request_user_code(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            code_challenge=challenge, state=state,\n        )\n        verification_url = str(code_data[\"verification_uri\"])\n        user_code = str(code_data[\"user_code\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n        if open_browser:\n            if webbrowser.open(verification_url):\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically -- use the URL above.\")\n\n        interval_raw = code_data.get(\"interval\")\n        interval_ms = int(interval_raw) if interval_raw is not None else None\n        print(\"Waiting for approval...\")\n\n        token_data = _minimax_poll_token(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            user_code=user_code, code_verifier=verifier,\n            expired_in=int(code_data[\"expired_in\"]),\n            interval_ms=interval_ms,\n        )\n\n    now = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(token_data[\"expired_in\"]), now=now,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now.timestamp()))\n\n    auth_state = {\n        \"provider\": \"minimax-oauth\",\n        \"region\": region,\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": inference_base_url,\n        \"client_id\": pconfig.client_id,\n        \"scope\": MINIMAX_OAUTH_SCOPE,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data[\"refresh_token\"],\n        \"resource_url\": token_data.get(\"resource_url\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    }\n\n    _minimax_save_auth_state(auth_state)\n    print(\"\\u2713 MiniMax OAuth login successful.\")\n    if msg := token_data.get(\"notification_message\"):\n        print(f\"Note from MiniMax: {msg}\")\n    return auth_state\n\n\ndef _refresh_minimax_oauth_state(\n    state: Dict[str, Any], *, timeout_seconds: float = 15.0,\n    force: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Refresh MiniMax OAuth access token if close to expiry (or forced).\"\"\"\n    if not state.get(\"refresh_token\"):\n        raise AuthError(\n            \"MiniMax OAuth state has no refresh_token; please re-login.\",\n            provider=\"minimax-oauth\", code=\"no_refresh_token\", relogin_required=True,\n        )\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n    except Exception:\n        expires_at = 0.0\n    now = time.time()\n    if not force and (expires_at - now) > MINIMAX_OAUTH_REFRESH_SKEW_SECONDS:\n        return state\n\n    portal_base_url = state[\"portal_base_url\"]\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      follow_redirects=True) as client:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": state[\"client_id\"],\n                \"refresh_token\": state[\"refresh_token\"],\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n    if response.status_code != 200:\n        body = response.text.lower()\n        relogin = any(m in body for m in\n                      (\"invalid_grant\", \"refresh_token_reused\", \"invalid_refresh_token\"))\n        raise AuthError(\n            f\"MiniMax OAuth refresh failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=relogin,\n        )\n    payload = response.json()\n    if payload.get(\"status\") != \"success\":\n        raise AuthError(\n            \"MiniMax OAuth refresh did not return success.\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=True,\n        )\n    now_dt = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(payload[\"expired_in\"]), now=now_dt,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now_dt.timestamp()))\n    new_state = dict(state)\n    new_state.update({\n        \"access_token\": payload[\"access_token\"],\n        \"refresh_token\": payload.get(\"refresh_token\", state[\"refresh_token\"]),\n        \"obtained_at\": now_dt.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    })\n    _minimax_save_auth_state(new_state)\n    return new_state\n\n\ndef resolve_minimax_oauth_runtime_credentials(\n    *, min_token_ttl_seconds: int = MINIMAX_OAUTH_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Return {provider, api_key, base_url, source} for minimax-oauth.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        raise AuthError(\n            \"Not logged into MiniMax OAuth. Run `clawbot model` and select \"\n            \"MiniMax (OAuth).\",\n            provider=\"minimax-oauth\", code=\"not_logged_in\", relogin_required=True,\n        )\n    state = _refresh_minimax_oauth_state(state)\n    return {\n        \"provider\": \"minimax-oauth\",\n        \"api_key\": state[\"access_token\"],\n        \"base_url\": state[\"inference_base_url\"].rstrip(\"/\"),\n        \"source\": \"oauth\",\n    }\n\n\ndef get_minimax_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return auth status dict for MiniMax OAuth provider.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        return {\"logged_in\": False, \"provider\": \"minimax-oauth\"}\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n        token_valid = (expires_at - time.time()) > 0\n    except Exception:\n        token_valid = bool(state.get(\"access_token\"))\n    return {\n        \"logged_in\": token_valid,\n        \"provider\": \"minimax-oauth\",\n        \"region\": state.get(\"region\", \"global\"),\n        \"expires_at\": state.get(\"expires_at\"),\n    }\n\n\ndef _login_minimax_oauth(args, pconfig: ProviderConfig) -> None:\n    \"\"\"CLI entry for MiniMax OAuth login.\"\"\"\n    region = getattr(args, \"region\", None) or \"global\"\n    open_browser = not getattr(args, \"no_browser\", False)\n    timeout = getattr(args, \"timeout\", None) or 15.0\n    try:\n        _minimax_oauth_login(\n            region=region, open_browser=open_browser, timeout_seconds=timeout,\n        )\n    except AuthError as exc:\n        print(format_auth_error(exc))\n        raise SystemExit(1)\n\n\ndef _soam_device_code_login(\n    *,\n    portal_base_url: Optional[str] = None,\n    inference_base_url: Optional[str] = None,\n    client_id: Optional[str] = None,\n    scope: Optional[str] = None,\n    open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n    insecure: bool = False,\n    ca_bundle: Optional[str] = None,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Dict[str, Any]:\n    \"\"\"Run the Soam device-code flow and return full OAuth state without persisting.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"soam\"]\n    portal_base_url = (\n        portal_base_url\n        or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n        or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n        or pconfig.portal_base_url\n    ).rstrip(\"/\")\n    requested_inference_url = (\n        inference_base_url\n        or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n        or pconfig.inference_base_url\n    ).rstrip(\"/\")\n    client_id = client_id or pconfig.client_id\n    scope, explicit_scope = _soam_device_scope_with_env_override(\n        scope,\n        default_scope=pconfig.scope,\n    )\n    timeout = httpx.Timeout(timeout_seconds)\n    verify: bool | str = False if insecure else (ca_bundle if ca_bundle else True)\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via {pconfig.name}...\")\n    print(f\"Portal: {portal_base_url}\")\n    if insecure:\n        print(\"TLS verification: disabled (--insecure)\")\n    elif ca_bundle:\n        print(f\"TLS verification: custom CA bundle ({ca_bundle})\")\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        device_data, scope = _request_soam_device_code_with_scope_fallback(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            scope=scope,\n            allow_legacy_fallback=not explicit_scope,\n        )\n\n        verification_url = str(device_data[\"verification_uri_complete\"])\n        user_code = str(device_data[\"user_code\"])\n        expires_in = int(device_data[\"expires_in\"])\n        interval = int(device_data[\"interval\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n\n        if open_browser:\n            opened = webbrowser.open(verification_url)\n            if opened:\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically — use the URL above.\")\n\n        effective_interval = max(1, min(interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n        print(f\"Waiting for approval (polling every {effective_interval}s)...\")\n\n        token_data = _poll_for_token(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            device_code=str(device_data[\"device_code\"]),\n            expires_in=expires_in,\n            poll_interval=interval,\n        )\n\n    now = datetime.now(timezone.utc)\n    token_expires_in = _coerce_ttl_seconds(token_data.get(\"expires_in\", 0))\n    expires_at = now.timestamp() + token_expires_in\n    resolved_inference_url = (\n        _optional_base_url(token_data.get(\"inference_base_url\"))\n        or requested_inference_url\n    )\n    if resolved_inference_url != requested_inference_url:\n        print(f\"Using portal-provided inference URL: {resolved_inference_url}\")\n\n    auth_state = {\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": resolved_inference_url,\n        \"client_id\": client_id,\n        \"scope\": token_data.get(\"scope\") or scope,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data.get(\"refresh_token\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(),\n        \"expires_in\": token_expires_in,\n        \"tls\": {\n            \"insecure\": verify is False,\n            \"ca_bundle\": verify if isinstance(verify, str) else None,\n        },\n        \"agent_key\": None,\n        \"agent_key_id\": None,\n        \"agent_key_expires_at\": None,\n        \"agent_key_expires_in\": None,\n        \"agent_key_reused\": None,\n        \"agent_key_obtained_at\": None,\n    }\n    try:\n        return refresh_soam_oauth_from_state(\n            auth_state,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            timeout_seconds=timeout_seconds,\n            force_refresh=False,\n            inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n        )\n    except AuthError as exc:\n        if exc.code == \"subscription_required\":\n            portal_url = auth_state.get(\n                \"portal_base_url\", DEFAULT_SOAM_PORTAL_URL\n            ).rstrip(\"/\")\n            print()\n            print(\"Your Soam Portal account does not have an active subscription.\")\n            print(f\"  Subscribe here: {portal_url}/billing\")\n            print()\n            print(\"After subscribing, run `clawbot model` again to finish setup.\")\n            raise SystemExit(1)\n        raise\n\n\ndef _login_soam(args, pconfig: ProviderConfig) -> None:\n    \"\"\"Soam Portal device authorization flow.\"\"\"\n    timeout_seconds = getattr(args, \"timeout\", None) or 15.0\n    insecure = bool(getattr(args, \"insecure\", False))\n    ca_bundle = (\n        getattr(args, \"ca_bundle\", None)\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n    )\n\n    try:\n        auth_state = None\n\n        # Codex-style auto-import: before launching a fresh device-code\n        # flow, check the shared store for an existing Soam credential\n        # from any other profile. If present, offer to rehydrate it.\n        shared = _read_shared_soam_state()\n        if shared:\n            try:\n                shared_path = _soam_shared_store_path()\n            except RuntimeError:\n                shared_path = None\n            print()\n            if shared_path:\n                print(f\"Found existing Soam OAuth credentials at {shared_path}\")\n            else:\n                print(\"Found existing shared Soam OAuth credentials\")\n            try:\n                do_import = input(\"Import these credentials? [Y/n]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"y\"\n            if do_import in {\"\", \"y\", \"yes\"}:\n                print(\"Rehydrating Soam session from shared credentials...\")\n                auth_state = _try_import_shared_soam_state(\n                    timeout_seconds=timeout_seconds,\n                    min_key_ttl_seconds=5 * 60,\n                )\n                if auth_state is None:\n                    print(\"Could not refresh shared credentials — falling back to device-code login.\")\n\n        if auth_state is None:\n            auth_state = _soam_device_code_login(\n                portal_base_url=getattr(args, \"portal_url\", None),\n                inference_base_url=getattr(args, \"inference_url\", None),\n                client_id=getattr(args, \"client_id\", None) or pconfig.client_id,\n                scope=getattr(args, \"scope\", None),\n                open_browser=not getattr(args, \"no_browser\", False),\n                timeout_seconds=timeout_seconds,\n                insecure=insecure,\n                ca_bundle=ca_bundle,\n                min_key_ttl_seconds=5 * 60,\n            )\n\n        inference_base_url = auth_state[\"inference_base_url\"]\n\n        # Snapshot the prior active_provider BEFORE _save_provider_state\n        # overwrites it to \"soam\".  If the user picks \"Skip (keep current)\"\n        # during model selection below, we restore this so the user's previous\n        # provider (e.g. openrouter) is preserved.\n        with _auth_store_lock():\n            _prior_store = _load_auth_store()\n            prior_active_provider = _prior_store.get(\"active_provider\")\n\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n            _save_provider_state(auth_store, \"soam\", auth_state)\n            saved_to = _save_auth_store(auth_store)\n\n        # Mirror to the shared store so other profiles can one-tap import\n        # these credentials. Best-effort: any I/O failure is logged and\n        # swallowed inside the helper.\n        _write_shared_soam_state(auth_state)\n        _sync_soam_pool_from_auth_store()\n\n        print()\n        print(\"Login successful!\")\n        print(f\"  Auth state: {saved_to}\")\n\n        # Resolve model BEFORE writing provider to config.yaml so we never\n        # leave the config in a half-updated state (provider=soam but model\n        # still set to the previous provider's model, e.g. opus from\n        # OpenRouter).  The auth.json active_provider was already set above.\n        selected_model = None\n        try:\n            runtime_key = auth_state.get(\"agent_key\") or auth_state.get(\"access_token\")\n            if not isinstance(runtime_key, str) or not runtime_key:\n                raise AuthError(\n                    \"No runtime API key available to fetch models\",\n                    provider=\"soam\",\n                    code=\"invalid_token\",\n                )\n\n            from clawbot_cli.models import (\n                get_curated_soam_model_ids, get_pricing_for_provider,\n                check_soam_free_tier, partition_soam_models_by_tier,\n                union_with_portal_free_recommendations,\n                union_with_portal_paid_recommendations,\n            )\n            model_ids = get_curated_soam_model_ids()\n\n            print()\n            unavailable_models: list = []\n            if model_ids:\n                pricing = get_pricing_for_provider(\"soam\")\n                free_tier = check_soam_free_tier()\n                _portal_for_recs = auth_state.get(\"portal_base_url\", \"\")\n                if free_tier:\n                    # The Portal's freeRecommendedModels endpoint is the\n                    # source of truth for what's free *right now*. Augment\n                    # the curated list with anything new the Portal flags\n                    # as free so users on older Clawbot builds still see\n                    # newly-launched free models without a CLI release.\n                    model_ids, pricing = union_with_portal_free_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n                    model_ids, unavailable_models = partition_soam_models_by_tier(\n                        model_ids, pricing, free_tier=True,\n                    )\n                else:\n                    # Paid-tier mirror: pull paidRecommendedModels so newly\n                    # launched paid models surface in the picker even if\n                    # the in-repo curated list and docs-hosted manifest\n                    # haven't caught up yet.\n                    model_ids, pricing = union_with_portal_paid_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n            _portal = auth_state.get(\"portal_base_url\", \"\")\n            if model_ids:\n                print(f\"Showing {len(model_ids)} curated models — use \\\"Enter custom model name\\\" for others.\")\n                selected_model = _prompt_model_selection(\n                    model_ids, pricing=pricing,\n                    unavailable_models=unavailable_models,\n                    portal_url=_portal,\n                )\n            elif unavailable_models:\n                _url = (_portal or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n                print(\"No free models currently available.\")\n                print(f\"Upgrade at {_url} to access paid models.\")\n            else:\n                print(\"No curated models available for Soam Portal.\")\n        except Exception as exc:\n            message = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc)\n            print()\n            print(f\"Login succeeded, but could not fetch available models. Reason: {message}\")\n\n        # Write provider + model atomically so config is never mismatched.\n        # If no model was selected (user picked \"Skip (keep current)\",\n        # model list fetch failed, or no curated models were available),\n        # preserve the user's previous provider — don't silently switch\n        # them to Soam with a mismatched model.  The Soam OAuth tokens\n        # stay saved for future use.\n        if not selected_model:\n            # Restore the prior active_provider that _save_provider_state\n            # overwrote to \"soam\".  config.yaml model.provider is left\n            # untouched, so the user's previous provider is fully preserved.\n            with _auth_store_lock():\n                auth_store = _load_auth_store()\n                if prior_active_provider:\n                    auth_store[\"active_provider\"] = prior_active_provider\n                else:\n                    auth_store.pop(\"active_provider\", None)\n                _save_auth_store(auth_store)\n            print()\n            print(\"No provider change. Soam credentials saved for future use.\")\n            print(\"  Run `clawbot model` again to switch to Soam Portal.\")\n            return\n\n        config_path = _update_config_for_provider(\n            \"soam\", inference_base_url, default_model=selected_model,\n        )\n        if selected_model:\n            _save_model_choice(selected_model)\n            print(f\"Default model set to: {selected_model}\")\n        print(f\"  Config updated: {config_path} (model.provider=soam)\")\n\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n    except Exception as exc:\n        print(f\"Login failed: {exc}\")\n        raise SystemExit(1)\n\n\ndef logout_command(args) -> None:\n    \"\"\"Clear auth state for a provider.\"\"\"\n    provider_id = getattr(args, \"provider\", None)\n\n    if provider_id and not is_known_auth_provider(provider_id):\n        print(f\"Unknown provider: {provider_id}\")\n        raise SystemExit(1)\n\n    active = get_active_provider()\n    target = provider_id or active or _logout_default_provider_from_config()\n\n    if not target:\n        print(\"No provider is currently logged in.\")\n        return\n\n    should_reset_config = _should_reset_config_provider_on_logout(target)\n    provider_name = get_auth_provider_display_name(target)\n\n    if clear_provider_auth(target) or should_reset_config:\n        if should_reset_config:\n            _reset_config_provider()\n        print(f\"Logged out of {provider_name}.\")\n        if should_reset_config and os.getenv(\"OPENROUTER_API_KEY\"):\n            print(\"Clawbot will use OpenRouter for inference.\")\n        elif should_reset_config:\n            print(\"Run `clawbot model` or configure an API key to use Clawbot.\")\n        else:\n            print(\"Model provider configuration was unchanged.\")\n    else:\n        print(f\"No auth state found for {provider_name}.\")\n"}, "943d359fcb6bebea2bca199486cda78d28f1d836": {"t": 1785763617.2021842, "n": 273583, "h": "d07b919dc8b2acb8", "c": "\"\"\"\nMulti-provider authentication system for Clawbot Agent.\n\nSupports OAuth device code flows (Soam Portal, future: OpenAI Codex) and\ntraditional API key providers (OpenRouter, custom endpoints). Auth state\nis persisted in ~/.clawbot/auth.json with cross-process file locking.\n\nArchitecture:\n- ProviderConfig registry defines known OAuth providers\n- Auth store (auth.json) holds per-provider credential state\n- resolve_provider() picks the active provider via priority chain\n- resolve_*_runtime_credentials() handles token refresh and key minting\n- logout_command() is the CLI entry point for clearing auth\n\nSoam authentication paths:\n- Invoke JWT (preferred): use a scoped access_token directly for inference.\n- Legacy session key (fallback): mint an opaque 24h key when JWT auth is\n  unavailable, or when CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS is set for\n  debugging or rollback.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport shutil\nimport shlex\nimport ssl\nimport stat\nimport sys\nimport base64\nimport hashlib\nimport subprocess\nimport threading\nimport time\nimport uuid\nimport webbrowser\nfrom contextlib import contextmanager\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\nfrom pathlib import Path\nfrom typing import Any, Callable, Dict, List, Optional, Tuple\nfrom urllib.parse import parse_qs, urlencode, urlparse\n\nimport httpx\nimport yaml\n\nfrom clawbot_cli.config import get_clawbot_home, get_config_path, read_raw_config\nfrom clawbot_constants import OPENROUTER_BASE_URL\nfrom utils import atomic_replace, atomic_yaml_write, is_truthy_value\n\nlogger = logging.getLogger(__name__)\n\ntry:\n    import fcntl\nexcept Exception:\n    fcntl = None\ntry:\n    import msvcrt\nexcept Exception:\n    msvcrt = None\n\n# =============================================================================\n# Constants\n# =============================================================================\n\nAUTH_STORE_VERSION = 1\nAUTH_LOCK_TIMEOUT_SECONDS = 15.0\n\n# Soam Portal defaults\nDEFAULT_SOAM_PORTAL_URL = \"https://portal.aayushsoam.com\"\nDEFAULT_SOAM_INFERENCE_URL = \"https://inference-api.aayushsoam.com/v1\"\nDEFAULT_SOAM_CLIENT_ID = \"clawbot-cli\"\nSOAM_LEGACY_AGENT_KEY_SCOPE = \"inference:mint_agent_key\"\nSOAM_INFERENCE_INVOKE_SCOPE = \"inference:invoke\"\nDEFAULT_SOAM_SCOPE = f\"{SOAM_INFERENCE_INVOKE_SCOPE} {SOAM_LEGACY_AGENT_KEY_SCOPE}\"\nSOAM_LEGACY_SESSION_KEYS_ENV = \"CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS\"\nSOAM_DEVICE_CODE_SOURCE = \"device_code\"\nSOAM_INFERENCE_AUTH_MODE_AUTO = \"auto\"\nSOAM_INFERENCE_AUTH_MODE_FRESH = \"fresh\"\nSOAM_INFERENCE_AUTH_MODE_LEGACY = \"legacy\"\nSOAM_INFERENCE_AUTH_MODES = frozenset({\n    SOAM_INFERENCE_AUTH_MODE_AUTO,\n    SOAM_INFERENCE_AUTH_MODE_FRESH,\n    SOAM_INFERENCE_AUTH_MODE_LEGACY,\n})\nSOAM_AUTH_PATH_INVOKE_JWT = \"\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE = \"legacy_session_key_cache\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT = \"legacy_session_key_mint\"\nDEFAULT_AGENT_KEY_MIN_TTL_SECONDS = 30 * 60  # 30 minutes\nACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120       # refresh 2 min before expiry\nSOAM_INVOKE_JWT_MIN_TTL_SECONDS = ACCESS_TOKEN_REFRESH_SKEW_SECONDS\nDEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS = 1     # poll at most every 1s\nDEFAULT_CODEX_BASE_URL = \"https://chatgpt.com/backend-api/codex\"\nDEFAULT_XAI_OAUTH_BASE_URL = \"https://api.x.ai/v1\"\nMINIMAX_OAUTH_CLIENT_ID = \"\"\nMINIMAX_OAUTH_SCOPE = \"group_id profile model.completion\"\nMINIMAX_OAUTH_GRANT_TYPE = \"urn:ietf:params:oauth:grant-type:user_code\"\nMINIMAX_OAUTH_GLOBAL_BASE = \"https://api.minimax.io\"\nMINIMAX_OAUTH_CN_BASE = \"https://api.minimaxi.com\"\nMINIMAX_OAUTH_GLOBAL_INFERENCE = \"https://api.minimax.io/anthropic\"\nMINIMAX_OAUTH_CN_INFERENCE = \"https://api.minimaxi.com/anthropic\"\nMINIMAX_OAUTH_REFRESH_SKEW_SECONDS = 60\nDEFAULT_QWEN_BASE_URL = \"https://portal.qwen.ai/v1\"\nDEFAULT_GITHUB_MODELS_BASE_URL = \"https://api.githubcopilot.com\"\nDEFAULT_COPILOT_ACP_BASE_URL = \"acp://copilot\"\nDEFAULT_OLLAMA_CLOUD_BASE_URL = \"https://ollama.com/v1\"\nSTEPFUN_STEP_PLAN_INTL_BASE_URL = \"https://api.stepfun.ai/step_plan/v1\"\nSTEPFUN_STEP_PLAN_CN_BASE_URL = \"https://api.stepfun.com/step_plan/v1\"\nCODEX_OAUTH_CLIENT_ID = \"\"\nCODEX_OAUTH_TOKEN_URL = \"https://auth.openai.com/oauth/token\"\nCODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nXAI_OAUTH_ISSUER = \"https://auth.x.ai\"\nXAI_OAUTH_DISCOVERY_URL = f\"{XAI_OAUTH_ISSUER}/.well-known/openid-configuration\"\nXAI_OAUTH_CLIENT_ID = \"\"\nXAI_OAUTH_SCOPE = \"openid profile email offline_access grok-cli:access api:access\"\nXAI_OAUTH_REDIRECT_HOST = \"127.0.0.1\"\nXAI_OAUTH_REDIRECT_PORT = 56121\nXAI_OAUTH_REDIRECT_PATH = \"/callback\"\nXAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nQWEN_OAUTH_CLIENT_ID = \"\"\nQWEN_OAUTH_TOKEN_URL = \"https://chat.qwen.ai/api/v1/oauth2/token\"\nQWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nDEFAULT_SPOTIFY_ACCOUNTS_BASE_URL = \"https://accounts.spotify.com\"\nDEFAULT_SPOTIFY_API_BASE_URL = \"https://api.spotify.com/v1\"\nDEFAULT_SPOTIFY_REDIRECT_URI = \"http://127.0.0.1:43827/spotify/callback\"\nSPOTIFY_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/user-guide/features/spotify\"\nSPOTIFY_DASHBOARD_URL = \"https://developer.spotify.com/dashboard\"\nSPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\n\nXAI_OAUTH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/xai-grok-oauth\"\nOAUTH_OVER_SSH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/oauth-over-ssh\"\nDEFAULT_SPOTIFY_SCOPE = \" \".join((\n    \"user-modify-playback-state\",\n    \"user-read-playback-state\",\n    \"user-read-currently-playing\",\n    \"user-read-recently-played\",\n    \"playlist-read-private\",\n    \"playlist-read-collaborative\",\n    \"playlist-modify-public\",\n    \"playlist-modify-private\",\n    \"user-library-read\",\n    \"user-library-modify\",\n))\nSERVICE_PROVIDER_NAMES: Dict[str, str] = {\n    \"spotify\": \"Spotify\",\n}\n\n# Google Gemini OAuth (google-gemini-cli provider, Cloud Code Assist backend)\nDEFAULT_GEMINI_CLOUDCODE_BASE_URL = \"cloudcode-pa://google\"\nGEMINI_OAUTH_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 60  # refresh 60s before expiry\n\n# LM Studio's default no-auth mode still requires *some* non-empty bearer for\n# the API-key code paths (auxiliary_client, runtime resolver) to treat the\n# provider as configured. This sentinel is sent only to LM Studio, never to\n# any remote service.\nLMSTUDIO_NOAUTH_PLACEHOLDER = \"dummy-lm-api-key\"\n\n\n# =============================================================================\n# Provider Registry\n# =============================================================================\n\n@dataclass\nclass ProviderConfig:\n    \"\"\"Describes a known inference provider.\"\"\"\n    id: str\n    name: str\n    auth_type: str  # \"oauth_device_code\", \"oauth_external\", \"oauth_minimax\", or \"api_key\"\n    portal_base_url: str = \"\"\n    inference_base_url: str = \"\"\n    client_id: str = \"\"\n    scope: str = \"\"\n    extra: Dict[str, Any] = field(default_factory=dict)\n    # For API-key providers: env vars to check (in priority order)\n    api_key_env_vars: tuple = ()\n    # Optional env var for base URL override\n    base_url_env_var: str = \"\"\n\n\nPROVIDER_REGISTRY: Dict[str, ProviderConfig] = {\n    \"soam\": ProviderConfig(\n        id=\"soam\",\n        name=\"Soam Portal\",\n        auth_type=\"oauth_device_code\",\n        portal_base_url=DEFAULT_SOAM_PORTAL_URL,\n        inference_base_url=DEFAULT_SOAM_INFERENCE_URL,\n        client_id=DEFAULT_SOAM_CLIENT_ID,\n        scope=DEFAULT_SOAM_SCOPE,\n    ),\n    \"openai-codex\": ProviderConfig(\n        id=\"openai-codex\",\n        name=\"OpenAI Codex\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_CODEX_BASE_URL,\n    ),\n    \"xai-oauth\": ProviderConfig(\n        id=\"xai-oauth\",\n        name=\"xAI Grok OAuth (SuperGrok Subscription)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_XAI_OAUTH_BASE_URL,\n    ),\n    \"qwen-oauth\": ProviderConfig(\n        id=\"qwen-oauth\",\n        name=\"Qwen OAuth\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_QWEN_BASE_URL,\n    ),\n    \"google-gemini-cli\": ProviderConfig(\n        id=\"google-gemini-cli\",\n        name=\"Google Gemini (OAuth)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_GEMINI_CLOUDCODE_BASE_URL,\n    ),\n    \"lmstudio\": ProviderConfig(\n        id=\"lmstudio\",\n        name=\"LM Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"http://127.0.0.1:1234/v1\",\n        api_key_env_vars=(\"LM_API_KEY\",),\n        base_url_env_var=\"LM_BASE_URL\",\n    ),\n    \"copilot\": ProviderConfig(\n        id=\"copilot\",\n        name=\"GitHub Copilot\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_GITHUB_MODELS_BASE_URL,\n        api_key_env_vars=(\"COPILOT_GITHUB_TOKEN\", \"GH_TOKEN\", \"GITHUB_TOKEN\"),\n        base_url_env_var=\"COPILOT_API_BASE_URL\",\n    ),\n    \"copilot-acp\": ProviderConfig(\n        id=\"copilot-acp\",\n        name=\"GitHub Copilot ACP\",\n        auth_type=\"external_process\",\n        inference_base_url=DEFAULT_COPILOT_ACP_BASE_URL,\n        base_url_env_var=\"COPILOT_ACP_BASE_URL\",\n    ),\n    \"gemini\": ProviderConfig(\n        id=\"gemini\",\n        name=\"Google AI Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://generativelanguage.googleapis.com/v1beta\",\n        api_key_env_vars=(\"GOOGLE_API_KEY\", \"GEMINI_API_KEY\"),\n        base_url_env_var=\"GEMINI_BASE_URL\",\n    ),\n    \"zai\": ProviderConfig(\n        id=\"zai\",\n        name=\"Z.AI / GLM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.z.ai/api/paas/v4\",\n        api_key_env_vars=(\"GLM_API_KEY\", \"ZAI_API_KEY\", \"Z_AI_API_KEY\"),\n        base_url_env_var=\"GLM_BASE_URL\",\n    ),\n    \"kimi-coding\": ProviderConfig(\n        id=\"kimi-coding\",\n        name=\"Kimi / Moonshot\",\n        auth_type=\"api_key\",\n        # Legacy platform.moonshot.ai keys use this endpoint (OpenAI-compat).\n        # sk-kimi- (Kimi Code) keys are auto-redirected to api.kimi.com/coding\n        # by _resolve_kimi_base_url() below.\n        inference_base_url=\"https://api.moonshot.ai/v1\",\n        api_key_env_vars=(\"KIMI_API_KEY\", \"KIMI_CODING_API_KEY\"),\n        base_url_env_var=\"KIMI_BASE_URL\",\n    ),\n    \"kimi-coding-cn\": ProviderConfig(\n        id=\"kimi-coding-cn\",\n        name=\"Kimi / Moonshot (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.moonshot.cn/v1\",\n        api_key_env_vars=(\"KIMI_CN_API_KEY\",),\n    ),\n    \"stepfun\": ProviderConfig(\n        id=\"stepfun\",\n        name=\"StepFun Step Plan\",\n        auth_type=\"api_key\",\n        inference_base_url=STEPFUN_STEP_PLAN_INTL_BASE_URL,\n        api_key_env_vars=(\"STEPFUN_API_KEY\",),\n        base_url_env_var=\"STEPFUN_BASE_URL\",\n    ),\n    \"arcee\": ProviderConfig(\n        id=\"arcee\",\n        name=\"Arcee AI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.arcee.ai/api/v1\",\n        api_key_env_vars=(\"ARCEEAI_API_KEY\",),\n        base_url_env_var=\"ARCEE_BASE_URL\",\n    ),\n    \"gmi\": ProviderConfig(\n        id=\"gmi\",\n        name=\"GMI Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.gmi-serving.com/v1\",\n        api_key_env_vars=(\"GMI_API_KEY\",),\n        base_url_env_var=\"GMI_BASE_URL\",\n    ),\n    \"minimax\": ProviderConfig(\n        id=\"minimax\",\n        name=\"MiniMax\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimax.io/anthropic\",\n        api_key_env_vars=(\"MINIMAX_API_KEY\",),\n        base_url_env_var=\"MINIMAX_BASE_URL\",\n    ),\n    \"minimax-oauth\": ProviderConfig(\n        id=\"minimax-oauth\",\n        name=\"MiniMax (OAuth \\u00b7 minimax.io)\",\n        auth_type=\"oauth_minimax\",\n        portal_base_url=MINIMAX_OAUTH_GLOBAL_BASE,\n        inference_base_url=MINIMAX_OAUTH_GLOBAL_INFERENCE,\n        client_id=MINIMAX_OAUTH_CLIENT_ID,\n        scope=MINIMAX_OAUTH_SCOPE,\n        extra={\"region\": \"global\", \"cn_portal_base_url\": MINIMAX_OAUTH_CN_BASE,\n               \"cn_inference_base_url\": MINIMAX_OAUTH_CN_INFERENCE},\n    ),\n    \"anthropic\": ProviderConfig(\n        id=\"anthropic\",\n        name=\"Anthropic\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.anthropic.com\",\n        api_key_env_vars=(\"ANTHROPIC_API_KEY\", \"ANTHROPIC_TOKEN\", \"CLAUDE_CODE_OAUTH_TOKEN\"),\n        base_url_env_var=\"ANTHROPIC_BASE_URL\",\n    ),\n    \"alibaba\": ProviderConfig(\n        id=\"alibaba\",\n        name=\"Qwen Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://dashscope-intl.aliyuncs.com/compatible-mode/v1\",\n        api_key_env_vars=(\"DASHSCOPE_API_KEY\",),\n        base_url_env_var=\"DASHSCOPE_BASE_URL\",\n    ),\n    \"alibaba-coding-plan\": ProviderConfig(\n        id=\"alibaba-coding-plan\",\n        name=\"Alibaba Cloud (Coding Plan)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://coding-intl.dashscope.aliyuncs.com/v1\",\n        api_key_env_vars=(\"ALIBABA_CODING_PLAN_API_KEY\", \"DASHSCOPE_API_KEY\"),\n        base_url_env_var=\"ALIBABA_CODING_PLAN_BASE_URL\",\n    ),\n    \"minimax-cn\": ProviderConfig(\n        id=\"minimax-cn\",\n        name=\"MiniMax (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimaxi.com/anthropic\",\n        api_key_env_vars=(\"MINIMAX_CN_API_KEY\",),\n        base_url_env_var=\"MINIMAX_CN_BASE_URL\",\n    ),\n    \"deepseek\": ProviderConfig(\n        id=\"deepseek\",\n        name=\"DeepSeek\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.deepseek.com/v1\",\n        api_key_env_vars=(\"DEEPSEEK_API_KEY\",),\n        base_url_env_var=\"DEEPSEEK_BASE_URL\",\n    ),\n    \"xai\": ProviderConfig(\n        id=\"xai\",\n        name=\"xAI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.x.ai/v1\",\n        api_key_env_vars=(\"XAI_API_KEY\",),\n        base_url_env_var=\"XAI_BASE_URL\",\n    ),\n    \"nvidia\": ProviderConfig(\n        id=\"nvidia\",\n        name=\"NVIDIA NIM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://integrate.api.nvidia.com/v1\",\n        api_key_env_vars=(\"NVIDIA_API_KEY\",),\n        base_url_env_var=\"NVIDIA_BASE_URL\",\n    ),\n    \"ai-gateway\": ProviderConfig(\n        id=\"ai-gateway\",\n        name=\"Vercel AI Gateway\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://ai-gateway.vercel.sh/v1\",\n        api_key_env_vars=(\"AI_GATEWAY_API_KEY\",),\n        base_url_env_var=\"AI_GATEWAY_BASE_URL\",\n    ),\n    \"opencode-zen\": ProviderConfig(\n        id=\"opencode-zen\",\n        name=\"OpenCode Zen\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://opencode.ai/zen/v1\",\n        api_key_env_vars=(\"OPENCODE_ZEN_API_KEY\",),\n        base_url_env_var=\"OPENCODE_ZEN_BASE_URL\",\n    ),\n    \"opencode-go\": ProviderConfig(\n        id=\"opencode-go\",\n        name=\"OpenCode Go\",\n        auth_type=\"api_key\",\n        # OpenCode Go mixes API surfaces by model:\n        # - GLM / Kimi use OpenAI-compatible chat completions under /v1\n        # - MiniMax models use Anthropic Messages under /v1/messages\n        # Keep the provider base at /v1 and select api_mode per-model.\n        inference_base_url=\"https://opencode.ai/zen/go/v1\",\n        api_key_env_vars=(\"OPENCODE_GO_API_KEY\",),\n        base_url_env_var=\"OPENCODE_GO_BASE_URL\",\n    ),\n    \"kilocode\": ProviderConfig(\n        id=\"kilocode\",\n        name=\"Kilo Code\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.kilo.ai/api/gateway\",\n        api_key_env_vars=(\"KILOCODE_API_KEY\",),\n        base_url_env_var=\"KILOCODE_BASE_URL\",\n    ),\n    \"huggingface\": ProviderConfig(\n        id=\"huggingface\",\n        name=\"Hugging Face\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://router.huggingface.co/v1\",\n        api_key_env_vars=(\"HF_TOKEN\",),\n        base_url_env_var=\"HF_BASE_URL\",\n    ),\n    \"xiaomi\": ProviderConfig(\n        id=\"xiaomi\",\n        name=\"Xiaomi MiMo\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.xiaomimimo.com/v1\",\n        api_key_env_vars=(\"XIAOMI_API_KEY\",),\n        base_url_env_var=\"XIAOMI_BASE_URL\",\n    ),\n    \"tencent-tokenhub\": ProviderConfig(\n        id=\"tencent-tokenhub\",\n        name=\"Tencent TokenHub\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://tokenhub.tencentmaas.com/v1\",\n        api_key_env_vars=(\"TOKENHUB_API_KEY\",),\n        base_url_env_var=\"TOKENHUB_BASE_URL\",\n    ),\n    \"ollama-cloud\": ProviderConfig(\n        id=\"ollama-cloud\",\n        name=\"Ollama Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_OLLAMA_CLOUD_BASE_URL,\n        api_key_env_vars=(\"OLLAMA_API_KEY\",),\n        base_url_env_var=\"OLLAMA_BASE_URL\",\n    ),\n    \"bedrock\": ProviderConfig(\n        id=\"bedrock\",\n        name=\"AWS Bedrock\",\n        auth_type=\"aws_sdk\",\n        inference_base_url=\"https://bedrock-runtime.us-east-1.amazonaws.com\",\n        api_key_env_vars=(),\n        base_url_env_var=\"BEDROCK_BASE_URL\",\n    ),\n    \"azure-foundry\": ProviderConfig(\n        id=\"azure-foundry\",\n        name=\"Azure Foundry\",\n        auth_type=\"api_key\",\n        inference_base_url=\"\",  # User-provided endpoint\n        api_key_env_vars=(\"AZURE_FOUNDRY_API_KEY\",),\n        base_url_env_var=\"AZURE_FOUNDRY_BASE_URL\",\n    ),\n}\n\n# Auto-extend PROVIDER_REGISTRY with any api-key provider registered in\n# providers/ that is not already declared above.  New providers only need a\n# plugins/model-providers/<name>/ plugin — no edits to this file required.\ntry:\n    from providers import list_providers as _list_providers_for_registry\n    for _pp in _list_providers_for_registry():\n        if _pp.name in PROVIDER_REGISTRY:\n            continue\n        if _pp.auth_type != \"api_key\" or not _pp.env_vars:\n            continue\n        # Skip providers that need custom token resolution or are special-cased\n        # in resolve_provider() (copilot/kimi/zai have bespoke token refresh;\n        # openrouter/custom are aggregator/user-supplied and handled outside\n        # the registry — adding them here breaks runtime_provider resolution\n        # that relies on `openrouter not in PROVIDER_REGISTRY`).\n        if _pp.name in {\"copilot\", \"kimi-coding\", \"kimi-coding-cn\", \"zai\", \"openrouter\", \"custom\"}:\n            continue\n        _api_key_vars = tuple(v for v in _pp.env_vars if not v.endswith(\"_BASE_URL\") and not v.endswith(\"_URL\"))\n        _base_url_var = next((v for v in _pp.env_vars if v.endswith(\"_BASE_URL\") or v.endswith(\"_URL\")), None)\n        PROVIDER_REGISTRY[_pp.name] = ProviderConfig(\n            id=_pp.name,\n            name=_pp.display_name or _pp.name,\n            auth_type=\"api_key\",\n            inference_base_url=_pp.base_url,\n            api_key_env_vars=_api_key_vars or _pp.env_vars,\n            base_url_env_var=_base_url_var or \"\",\n        )\n        # Also register aliases so resolve_provider() resolves them\n        for _alias in _pp.aliases:\n            if _alias not in PROVIDER_REGISTRY:\n                PROVIDER_REGISTRY[_alias] = PROVIDER_REGISTRY[_pp.name]\nexcept Exception:\n    pass\n\n\n# =============================================================================\n# Anthropic Key Helper\n# =============================================================================\n\ndef get_anthropic_key() -> str:\n    \"\"\"Return the first usable Anthropic credential, or ``\"\"``.\n\n    Checks both the ``.env`` file (via ``get_env_value``) and the process\n    environment (``os.getenv``).  The fallback order mirrors the\n    ``PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars`` tuple:\n\n        ANTHROPIC_API_KEY -> ANTHROPIC_TOKEN -> CLAUDE_CODE_OAUTH_TOKEN\n    \"\"\"\n    from clawbot_cli.config import get_env_value\n\n    for var in PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars:\n        value = get_env_value(var) or os.getenv(var, \"\")\n        if value:\n            return value\n    return \"\"\n\n\n# =============================================================================\n# Kimi Code Endpoint Detection\n# =============================================================================\n\n# Kimi Code (kimi.com/code) issues keys prefixed \"sk-kimi-\" that only work\n# on api.kimi.com/coding.  Legacy keys from platform.moonshot.ai work on\n# api.moonshot.ai/v1 (the old default).  Auto-detect when user hasn't set\n# KIMI_BASE_URL explicitly.\n#\n# Note: the base URL intentionally has NO /v1 suffix.  The /coding endpoint\n# speaks the Anthropic Messages protocol, and the anthropic SDK appends\n# \"/v1/messages\" internally — so \"/coding\" + SDK suffix → \"/coding/v1/messages\"\n# (the correct target). Using \"/coding/v1\" here would produce\n# \"/coding/v1/v1/messages\" (a 404).\nKIMI_CODE_BASE_URL = \"https://api.kimi.com/coding\"\n\n\ndef _resolve_kimi_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Kimi base URL based on the API key prefix.\n\n    If the user has explicitly set KIMI_BASE_URL, that always wins.\n    Otherwise, sk-kimi- prefixed keys route to api.kimi.com/coding/v1.\n    \"\"\"\n    if env_override:\n        return env_override\n    # No key → nothing to infer from.  Return default without inspecting.\n    if not api_key:\n        return default_url\n    if api_key.startswith(\"sk-kimi-\"):\n        return KIMI_CODE_BASE_URL\n    return default_url\n\n\n\n_PLACEHOLDER_SECRET_VALUES = {\n    \"*\",\n    \"**\",\n    \"***\",\n    \"changeme\",\n    \"your_api_key\",\n    \"your-api-key\",\n    \"placeholder\",\n    \"example\",\n    \"dummy\",\n    \"null\",\n    \"none\",\n}\n\n\ndef has_usable_secret(value: Any, *, min_length: int = 4) -> bool:\n    \"\"\"Return True when a configured secret looks usable, not empty/placeholder.\"\"\"\n    if not isinstance(value, str):\n        return False\n    cleaned = value.strip()\n    if len(cleaned) < min_length:\n        return False\n    if cleaned.lower() in _PLACEHOLDER_SECRET_VALUES:\n        return False\n    return True\n\n\ndef _resolve_api_key_provider_secret(\n    provider_id: str, pconfig: ProviderConfig\n) -> tuple[str, str]:\n    \"\"\"Resolve an API-key provider's token and indicate where it came from.\"\"\"\n    if provider_id == \"copilot\":\n        # Use the dedicated copilot auth module for proper token validation\n        try:\n            from clawbot_cli.copilot_auth import resolve_copilot_token, get_copilot_api_token\n            token, source = resolve_copilot_token()\n            if token:\n                return get_copilot_api_token(token), source\n        except ValueError as exc:\n            logger.warning(\"Copilot token validation failed: %s\", exc)\n        except Exception:\n            pass\n        return \"\", \"\"\n\n    from clawbot_cli.config import get_env_value\n    for env_var in pconfig.api_key_env_vars:\n        # Check both os.environ and ~/.clawbot/.env file\n        val = (get_env_value(env_var) or \"\").strip()\n        if has_usable_secret(val):\n            return val, env_var\n\n    # Fallback: try credential pool (e.g. zai key stored via auth.json)\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(provider_id)\n        if pool and pool.has_credentials():\n            entry = pool.peek()\n            if entry:\n                key = getattr(entry, \"access_token\", \"\") or getattr(entry, \"runtime_api_key\", \"\")\n                key = str(key).strip()\n                if has_usable_secret(key):\n                    return key, f\"credential_pool:{provider_id}\"\n    except Exception:\n        pass\n\n    return \"\", \"\"\n\n\n# =============================================================================\n# Z.AI Endpoint Detection\n# =============================================================================\n\n# Z.AI has separate billing for general vs coding plans, and global vs China\n# endpoints.  A key that works on one may return \"Insufficient balance\" on\n# another.  We probe at setup time and store the working endpoint.\n# Each entry lists candidate models to try in order — newer coding plan accounts\n# may only have access to recent models (glm-5.1, glm-5v-turbo) while older\n# ones still use glm-4.7.\n\nZAI_ENDPOINTS = [\n    # (id, base_url, probe_models, label)\n    (\"global\",        \"https://api.z.ai/api/paas/v4\",        [\"glm-5\"],   \"Global\"),\n    (\"cn\",            \"https://open.bigmodel.cn/api/paas/v4\", [\"glm-5\"],   \"China\"),\n    (\"coding-global\", \"https://api.z.ai/api/coding/paas/v4\",  [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"Global (Coding Plan)\"),\n    (\"coding-cn\",     \"https://open.bigmodel.cn/api/coding/paas/v4\", [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"China (Coding Plan)\"),\n]\n\n\ndef detect_zai_endpoint(api_key: str, timeout: float = 8.0) -> Optional[Dict[str, str]]:\n    \"\"\"Probe z.ai endpoints to find one that accepts this API key.\n\n    Returns {\"id\": ..., \"base_url\": ..., \"model\": ..., \"label\": ...} for the\n    first working endpoint, or None if all fail.  For endpoints with multiple\n    candidate models, tries each in order and returns the first that succeeds.\n    \"\"\"\n    for ep_id, base_url, probe_models, label in ZAI_ENDPOINTS:\n        for model in probe_models:\n            try:\n                resp = httpx.post(\n                    f\"{base_url}/chat/completions\",\n                    headers={\n                        \"Authorization\": f\"Bearer {api_key}\",\n                        \"Content-Type\": \"application/json\",\n                    },\n                    json={\n                        \"model\": model,\n                        \"stream\": False,\n                        \"max_tokens\": 1,\n                        \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}],\n                    },\n                    timeout=timeout,\n                )\n                if resp.status_code == 200:\n                    logger.debug(\"Z.AI endpoint probe: %s (%s) model=%s OK\", ep_id, base_url, model)\n                    return {\n                        \"id\": ep_id,\n                        \"base_url\": base_url,\n                        \"model\": model,\n                        \"label\": label,\n                    }\n                logger.debug(\"Z.AI endpoint probe: %s model=%s returned %s\", ep_id, model, resp.status_code)\n            except Exception as exc:\n                logger.debug(\"Z.AI endpoint probe: %s model=%s failed: %s\", ep_id, model, exc)\n    return None\n\n\ndef _resolve_zai_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Z.AI base URL by probing endpoints.\n\n    If the user has explicitly set GLM_BASE_URL, that always wins.\n    Otherwise, probe the candidate endpoints to find one that accepts the\n    key.  The detected endpoint is cached in provider state (auth.json) keyed\n    on a hash of the API key so subsequent starts skip the probe.\n    \"\"\"\n    if env_override:\n        return env_override\n\n    # No API key set → don't probe (would fire N×M HTTPS requests with an\n    # empty Bearer token, all returning 401).  This path is hit during\n    # auxiliary-client auto-detection when the user has no Z.AI credentials\n    # at all — the caller discards the result immediately, so the probe is\n    # pure latency for every AIAgent construction.\n    if not api_key:\n        return default_url\n\n    # Check provider-state cache for a previously-detected endpoint.\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"zai\") or {}\n    cached = state.get(\"detected_endpoint\")\n    if isinstance(cached, dict) and cached.get(\"base_url\"):\n        key_hash = cached.get(\"key_hash\", \"\")\n        if key_hash == hashlib.sha256(api_key.encode()).hexdigest()[:16]:\n            logger.debug(\"Z.AI: using cached endpoint %s\", cached[\"base_url\"])\n            return cached[\"base_url\"]\n\n    # Probe — may take up to ~8s per endpoint.\n    detected = detect_zai_endpoint(api_key)\n    if detected and detected.get(\"base_url\"):\n        # Persist the detection result keyed on the API key hash.\n        key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]\n        state[\"detected_endpoint\"] = {\n            \"base_url\": detected[\"base_url\"],\n            \"endpoint_id\": detected.get(\"id\", \"\"),\n            \"model\": detected.get(\"model\", \"\"),\n            \"label\": detected.get(\"label\", \"\"),\n            \"key_hash\": key_hash,\n        }\n        _save_provider_state(auth_store, \"zai\", state)\n        logger.info(\"Z.AI: auto-detected endpoint %s (%s)\", detected[\"label\"], detected[\"base_url\"])\n        return detected[\"base_url\"]\n\n    logger.debug(\"Z.AI: probe failed, falling back to default %s\", default_url)\n    return default_url\n\n\n# =============================================================================\n# Error Types\n# =============================================================================\n\nclass AuthError(RuntimeError):\n    \"\"\"Structured auth error with UX mapping hints.\"\"\"\n\n    def __init__(\n        self,\n        message: str,\n        *,\n        provider: str = \"\",\n        code: Optional[str] = None,\n        relogin_required: bool = False,\n    ) -> None:\n        super().__init__(message)\n        self.provider = provider\n        self.code = code\n        self.relogin_required = relogin_required\n\n\ndef format_auth_error(error: Exception) -> str:\n    \"\"\"Map auth failures to concise user-facing guidance.\"\"\"\n    if not isinstance(error, AuthError):\n        return str(error)\n\n    if error.relogin_required:\n        return f\"{error} Run `clawbot model` to re-authenticate.\"\n\n    if error.code == \"subscription_required\":\n        return (\n            \"No active paid subscription found on Soam Portal. \"\n            \"Please purchase/activate a subscription, then retry.\"\n        )\n\n    if error.code == \"insufficient_credits\":\n        return (\n            \"Subscription credits are exhausted. \"\n            \"Top up/renew credits in Soam Portal, then retry.\"\n        )\n\n    if error.code == \"temporarily_unavailable\":\n        return f\"{error} Please retry in a few seconds.\"\n\n    return str(error)\n\n\ndef _token_fingerprint(token: Any) -> Optional[str]:\n    \"\"\"Return a short hash fingerprint for telemetry without leaking token bytes.\"\"\"\n    if not isinstance(token, str):\n        return None\n    cleaned = token.strip()\n    if not cleaned:\n        return None\n    return hashlib.sha256(cleaned.encode(\"utf-8\")).hexdigest()[:12]\n\n\ndef _oauth_trace_enabled() -> bool:\n    raw = os.getenv(\"CLAWBOT_OAUTH_TRACE\", \"\").strip().lower()\n    return raw in {\"1\", \"true\", \"yes\", \"on\"}\n\n\ndef _oauth_trace(event: str, *, sequence_id: Optional[str] = None, **fields: Any) -> None:\n    if not _oauth_trace_enabled():\n        return\n    payload: Dict[str, Any] = {\"event\": event}\n    if sequence_id:\n        payload[\"sequence_id\"] = sequence_id\n    payload.update(fields)\n    logger.info(\"oauth_trace %s\", json.dumps(payload, sort_keys=True, ensure_ascii=False))\n\n\n# =============================================================================\n# Auth Store — persistence layer for ~/.clawbot/auth.json\n# =============================================================================\n\ndef _auth_file_path() -> Path:\n    path = get_clawbot_home() / \"auth.json\"\n    # Seat belt: if pytest is running and CLAWBOT_HOME resolves to the real\n    # user's auth store, refuse rather than silently corrupt it. This catches\n    # tests that forgot to monkeypatch CLAWBOT_HOME, tests invoked without the\n    # clawbotic conftest, or sandbox escapes via threads/subprocesses. In\n    # production (no PYTEST_CURRENT_TEST) this is a single dict lookup.\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_auth = (Path.home() / \".clawbot\" / \"auth.json\").resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_auth:\n            raise RuntimeError(\n                f\"Refusing to touch real user auth store during test run: {path}. \"\n                \"Set CLAWBOT_HOME to a tmp_path in your test fixture, or run \"\n                \"via scripts/run_tests.sh for clawbotic CI-parity env.\"\n            )\n    return path\n\n\ndef _global_auth_file_path() -> Optional[Path]:\n    \"\"\"Return the global-root auth.json when the process is in profile mode.\n\n    Returns ``None`` when the profile and global root resolve to the same\n    directory (classic mode, or custom CLAWBOT_HOME that is not a profile).\n    Used by read-only fallback paths so providers authed at the root are\n    visible to profile processes that haven't configured them locally.\n\n    See issue #18594 follow-up (credential_pool shadowing).\n    \"\"\"\n    try:\n        from clawbot_constants import get_default_clawbot_root\n        global_root = get_default_clawbot_root()\n    except Exception:\n        return None\n    profile_home = get_clawbot_home()\n    try:\n        if profile_home.resolve(strict=False) == global_root.resolve(strict=False):\n            return None\n    except Exception:\n        if profile_home == global_root:\n            return None\n    # No pytest seat belt here: this is a pure read-only path, and\n    # ``_load_global_auth_store()`` wraps the read in a try/except so an\n    # unreadable global file can never break the profile process.  The\n    # write-side seat belt still lives on ``_auth_file_path()`` where it\n    # belongs (that's what protects the real user's auth store from being\n    # corrupted by a mis-configured test).\n    return global_root / \"auth.json\"\n\n\ndef _load_global_auth_store() -> Dict[str, Any]:\n    \"\"\"Load the global-root auth store (read-only fallback).\n\n    Returns an empty dict when no global fallback exists (classic mode,\n    or the global auth.json is absent). Never raises on missing file.\n\n    Seat belt: under pytest, refuses to read the real user's\n    ``~/.clawbot/auth.json`` even when CLAWBOT_HOME is set to a profile\n    path. The clawbotic conftest does not redirect ``HOME``, so\n    ``get_default_clawbot_root()`` for a profile-shaped CLAWBOT_HOME can\n    still resolve to the real user's home on a dev machine. That would\n    leak real credentials into tests. This guard uses the unmodified\n    ``HOME`` env var (what ``os.path.expanduser('~')`` would resolve to),\n    not ``Path.home()``, because ``Path.home`` is sometimes monkeypatched\n    by fixtures that want to relocate the global root to a tmp path.\n    \"\"\"\n    global_path = _global_auth_file_path()\n    if global_path is None or not global_path.exists():\n        return {}\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_env = os.environ.get(\"HOME\", \"\")\n        if real_home_env:\n            real_root = Path(real_home_env) / \".clawbot\" / \"auth.json\"\n            try:\n                if global_path.resolve(strict=False) == real_root.resolve(strict=False):\n                    return {}\n            except Exception:\n                pass\n    try:\n        return _load_auth_store(global_path)\n    except Exception:\n        # A malformed global store must not break profile reads. The\n        # profile's own auth store is still authoritative.\n        return {}\n\n\ndef _auth_lock_path() -> Path:\n    return _auth_file_path().with_suffix(\".lock\")\n\n\n_auth_lock_holder = threading.local()\n\n\n@contextmanager\ndef _file_lock(\n    lock_path: Path,\n    holder: threading.local,\n    timeout_seconds: float,\n    timeout_message: str,\n):\n    \"\"\"Cross-process advisory flock helper.\n\n    Reentrant per-thread via ``holder.depth``. Falls back to a depth-only\n    guard when neither ``fcntl`` nor ``msvcrt`` is available (rare).\n    Callers supply their own ``threading.local`` so independent locks\n    (e.g. profile auth.json vs shared Soam store) don't share reentrancy\n    state — that would let one lock's reentrant acquisition silently skip\n    the other's kernel-level flock.\n    \"\"\"\n    if getattr(holder, \"depth\", 0) > 0:\n        holder.depth += 1\n        try:\n            yield\n        finally:\n            holder.depth -= 1\n        return\n\n    lock_path.parent.mkdir(parents=True, exist_ok=True)\n\n    if fcntl is None and msvcrt is None:\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n        return\n\n    # On Windows, msvcrt.locking needs the file to have content and the\n    # file pointer at position 0. Ensure the lock file has at least 1 byte.\n    if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):\n        lock_path.write_text(\" \", encoding=\"utf-8\")\n\n    with lock_path.open(\"r+\" if msvcrt else \"a+\", encoding=\"utf-8\") as lock_file:\n        deadline = time.monotonic() + max(1.0, timeout_seconds)\n        while True:\n            try:\n                if fcntl:\n                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)\n                else:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)\n                break\n            except (BlockingIOError, OSError, PermissionError):\n                if time.monotonic() >= deadline:\n                    raise TimeoutError(timeout_message)\n                time.sleep(0.05)\n\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n            if fcntl:\n                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n            elif msvcrt:\n                try:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)\n                except (OSError, IOError):\n                    pass\n\n\n@contextmanager\ndef _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-process advisory lock for auth.json reads+writes.  Reentrant.\n\n    Lock ordering invariant: when this lock is held together with\n    ``_soam_shared_store_lock``, acquire ``_auth_store_lock`` FIRST\n    (outer) and the shared Soam lock SECOND (inner). All runtime\n    refresh paths follow this order; violating it risks deadlock\n    against a concurrent import on the shared store.\n    \"\"\"\n    with _file_lock(\n        _auth_lock_path(),\n        _auth_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for auth store lock\",\n    ):\n        yield\n\n\ndef _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:\n    auth_file = auth_file or _auth_file_path()\n    if not auth_file.exists():\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    try:\n        raw = json.loads(auth_file.read_text())\n    except Exception as exc:\n        corrupt_path = auth_file.with_suffix(\".json.corrupt\")\n        try:\n            import shutil\n            shutil.copy2(auth_file, corrupt_path)\n        except Exception:\n            pass\n        logger.warning(\n            \"auth: failed to parse %s (%s) — starting with empty store. \"\n            \"Corrupt file preserved at %s\",\n            auth_file, exc, corrupt_path,\n        )\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    if isinstance(raw, dict) and (\n        isinstance(raw.get(\"providers\"), dict)\n        or isinstance(raw.get(\"credential_pool\"), dict)\n    ):\n        raw.setdefault(\"providers\", {})\n        return raw\n\n    # Migrate from PR's \"systems\" format if present\n    if isinstance(raw, dict) and isinstance(raw.get(\"systems\"), dict):\n        systems = raw[\"systems\"]\n        providers = {}\n        if \"soam_portal\" in systems:\n            providers[\"soam\"] = systems[\"soam_portal\"]\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": providers,\n                \"active_provider\": \"soam\" if providers else None}\n\n    return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n\ndef _save_auth_store(auth_store: Dict[str, Any]) -> Path:\n    auth_file = _auth_file_path()\n    auth_file.parent.mkdir(parents=True, exist_ok=True)\n    # Tighten parent dir to 0o700 so siblings can't traverse to creds.\n    # No-op on Windows (POSIX mode bits not enforced); ignore failures.\n    try:\n        os.chmod(auth_file.parent, 0o700)\n    except OSError:\n        pass\n    auth_store[\"version\"] = AUTH_STORE_VERSION\n    auth_store[\"updated_at\"] = datetime.now(timezone.utc).isoformat()\n    payload = json.dumps(auth_store, indent=2) + \"\\n\"\n    tmp_path = auth_file.with_name(f\"{auth_file.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    try:\n        # Create with 0o600 atomically via os.open(O_EXCL) + fdopen to close\n        # the TOCTOU window where default umask (often 0o644) briefly exposed\n        # OAuth tokens to other local users between open() and chmod().\n        # Mirrors agent/google_oauth.py (#19673) and tools/mcp_oauth.py (#21148).\n        fd = os.open(\n            str(tmp_path),\n            os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n            stat.S_IRUSR | stat.S_IWUSR,\n        )\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as handle:\n            handle.write(payload)\n            handle.flush()\n            os.fsync(handle.fileno())\n        atomic_replace(tmp_path, auth_file)\n        try:\n            dir_fd = os.open(str(auth_file.parent), os.O_RDONLY)\n        except OSError:\n            dir_fd = None\n        if dir_fd is not None:\n            try:\n                os.fsync(dir_fd)\n            finally:\n                os.close(dir_fd)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    # Restrict file permissions to owner only\n    try:\n        auth_file.chmod(stat.S_IRUSR | stat.S_IWUSR)\n    except OSError:\n        pass\n    return auth_file\n\n\ndef _load_provider_state(auth_store: Dict[str, Any], provider_id: str) -> Optional[Dict[str, Any]]:\n    providers = auth_store.get(\"providers\")\n    if not isinstance(providers, dict):\n        return None\n    state = providers.get(provider_id)\n    return dict(state) if isinstance(state, dict) else None\n\n\ndef _save_provider_state(auth_store: Dict[str, Any], provider_id: str, state: Dict[str, Any]) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    auth_store[\"active_provider\"] = provider_id\n\n\ndef _store_provider_state(\n    auth_store: Dict[str, Any],\n    provider_id: str,\n    state: Dict[str, Any],\n    *,\n    set_active: bool = True,\n) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    if set_active:\n        auth_store[\"active_provider\"] = provider_id\n\n\ndef is_known_auth_provider(provider_id: str) -> bool:\n    normalized = (provider_id or \"\").strip().lower()\n    return normalized in PROVIDER_REGISTRY or normalized in SERVICE_PROVIDER_NAMES\n\n\ndef get_auth_provider_display_name(provider_id: str) -> str:\n    normalized = (provider_id or \"\").strip().lower()\n    if normalized in PROVIDER_REGISTRY:\n        return PROVIDER_REGISTRY[normalized].name\n    return SERVICE_PROVIDER_NAMES.get(normalized, provider_id)\n\n\ndef read_credential_pool(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Return the persisted credential pool, or one provider slice.\n\n    In profile mode, the profile's credential pool is authoritative. If a\n    provider has no entries in the profile, entries from the global-root\n    ``auth.json`` are used as a read-only fallback — so workers spawned in a\n    profile can see providers that were only authenticated at global scope.\n\n    Profile entries always win: the global fallback only applies per-provider\n    when the profile has zero entries for that provider. Once the user runs\n    ``clawbot auth add <provider>`` inside the profile, profile entries\n    fully shadow global for that provider on the next read.\n\n    Writes always go to the profile (``write_credential_pool`` is unchanged).\n    See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        pool = {}\n\n    global_pool: Dict[str, Any] = {}\n    global_store = _load_global_auth_store()\n    maybe_global_pool = global_store.get(\"credential_pool\") if global_store else None\n    if isinstance(maybe_global_pool, dict):\n        global_pool = maybe_global_pool\n\n    if provider_id is None:\n        merged = dict(pool)\n        for gp_key, gp_entries in global_pool.items():\n            if not isinstance(gp_entries, list) or not gp_entries:\n                continue\n            # Per-provider shadowing: profile wins whenever it has ANY entries.\n            existing = merged.get(gp_key)\n            if isinstance(existing, list) and existing:\n                continue\n            merged[gp_key] = list(gp_entries)\n        return merged\n\n    provider_entries = pool.get(provider_id)\n    if isinstance(provider_entries, list) and provider_entries:\n        return list(provider_entries)\n    # Profile has no entries for this provider — fall back to global.\n    global_entries = global_pool.get(provider_id)\n    return list(global_entries) if isinstance(global_entries, list) else []\n\n\ndef write_credential_pool(provider_id: str, entries: List[Dict[str, Any]]) -> Path:\n    \"\"\"Persist one provider's credential pool under auth.json.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n        pool[provider_id] = list(entries)\n        return _save_auth_store(auth_store)\n\n\ndef suppress_credential_source(provider_id: str, source: str) -> None:\n    \"\"\"Mark a credential source as suppressed so it won't be re-seeded.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.setdefault(\"suppressed_sources\", {})\n        provider_list = suppressed.setdefault(provider_id, [])\n        if source not in provider_list:\n            provider_list.append(source)\n        _save_auth_store(auth_store)\n\n\ndef is_source_suppressed(provider_id: str, source: str) -> bool:\n    \"\"\"Check if a credential source has been suppressed by the user.\"\"\"\n    try:\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\", {})\n        return source in suppressed.get(provider_id, [])\n    except Exception:\n        return False\n\n\ndef unsuppress_credential_source(provider_id: str, source: str) -> bool:\n    \"\"\"Clear a suppression marker so the source will be re-seeded on the next load.\n\n    Returns True if a marker was cleared, False if no marker existed.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\")\n        if not isinstance(suppressed, dict):\n            return False\n        provider_list = suppressed.get(provider_id)\n        if not isinstance(provider_list, list) or source not in provider_list:\n            return False\n        provider_list.remove(source)\n        if not provider_list:\n            suppressed.pop(provider_id, None)\n        if not suppressed:\n            auth_store.pop(\"suppressed_sources\", None)\n        _save_auth_store(auth_store)\n        return True\n\n\ndef get_provider_auth_state(provider_id: str) -> Optional[Dict[str, Any]]:\n    \"\"\"Return persisted auth state for a provider, or None.\n\n    In profile mode, falls back to the global-root ``auth.json`` when the\n    profile has no state for this provider. Profile state always wins when\n    present. Writes (``_save_auth_store`` / ``persist_*_credentials``) are\n    unchanged — they still target the profile only. This mirrors\n    ``read_credential_pool``'s per-provider shadowing semantics so that\n    ``_seed_from_singletons`` can reseed a profile's credential pool from\n    global-scope provider state (e.g. a globally-authenticated Anthropic\n    OAuth or Soam device-code session). See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, provider_id)\n    if state is not None:\n        return state\n    global_store = _load_global_auth_store()\n    if not global_store:\n        return None\n    return _load_provider_state(global_store, provider_id)\n\n\ndef get_active_provider() -> Optional[str]:\n    \"\"\"Return the currently active provider ID from auth store.\"\"\"\n    auth_store = _load_auth_store()\n    return auth_store.get(\"active_provider\")\n\n\ndef is_provider_explicitly_configured(provider_id: str) -> bool:\n    \"\"\"Return True only if the user has explicitly configured this provider.\n\n    Checks:\n      1. active_provider in auth.json matches\n      2. model.provider in config.yaml matches\n      3. Provider-specific env vars are set (e.g. ANTHROPIC_API_KEY)\n\n    This is used to gate auto-discovery of external credentials (e.g.\n    Claude Code's ~/.claude/.credentials.json) so they are never used\n    without the user's explicit choice.  See PR #4210 for the same\n    pattern applied to the setup wizard gate.\n    \"\"\"\n    normalized = (provider_id or \"\").strip().lower()\n\n    # 1. Check auth.json active_provider\n    try:\n        auth_store = _load_auth_store()\n        active = (auth_store.get(\"active_provider\") or \"\").strip().lower()\n        if active and active == normalized:\n            return True\n    except Exception:\n        pass\n\n    # 2. Check config.yaml model.provider\n    try:\n        from clawbot_cli.config import load_config\n        cfg = load_config()\n        model_cfg = cfg.get(\"model\")\n        if isinstance(model_cfg, dict):\n            cfg_provider = (model_cfg.get(\"provider\") or \"\").strip().lower()\n            if cfg_provider == normalized:\n                return True\n    except Exception:\n        pass\n\n    # 3. Check provider-specific env vars\n    # Exclude CLAUDE_CODE_OAUTH_TOKEN — it's set by Claude Code itself,\n    # not by the user explicitly configuring anthropic in Clawbot.\n    _IMPLICIT_ENV_VARS = {\"CLAUDE_CODE_OAUTH_TOKEN\"}\n    pconfig = PROVIDER_REGISTRY.get(normalized)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        for env_var in pconfig.api_key_env_vars:\n            if env_var in _IMPLICIT_ENV_VARS:\n                continue\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return True\n\n    return False\n\n\ndef clear_provider_auth(provider_id: Optional[str] = None) -> bool:\n    \"\"\"\n    Clear auth state for a provider. Used by `clawbot logout`.\n    If provider_id is None, clears the active provider.\n    Returns True if something was cleared.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        target = provider_id or auth_store.get(\"active_provider\")\n        if not target:\n            return False\n\n        providers = auth_store.get(\"providers\", {})\n        if not isinstance(providers, dict):\n            providers = {}\n            auth_store[\"providers\"] = providers\n\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n\n        cleared = False\n        if target in providers:\n            del providers[target]\n            cleared = True\n        if target in pool:\n            del pool[target]\n            cleared = True\n\n        if auth_store.get(\"active_provider\") == target:\n            auth_store[\"active_provider\"] = None\n            cleared = True\n\n        if not cleared:\n            return False\n        _save_auth_store(auth_store)\n    return True\n\n\ndef deactivate_provider() -> None:\n    \"\"\"\n    Clear active_provider in auth.json without deleting credentials.\n    Used when the user switches to a non-OAuth provider (OpenRouter, custom)\n    so auto-resolution doesn't keep picking the OAuth provider.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = None\n        _save_auth_store(auth_store)\n\n\n# =============================================================================\n# Provider Resolution — picks which provider to use\n# =============================================================================\n\n\ndef _get_config_hint_for_unknown_provider(provider_name: str) -> str:\n    \"\"\"Return a helpful hint string when provider resolution fails.\n\n    Checks for common config.yaml mistakes (malformed custom_providers, etc.)\n    and returns a human-readable diagnostic, or empty string if nothing found.\n    \"\"\"\n    try:\n        from clawbot_cli.config import validate_config_structure\n        issues = validate_config_structure()\n        if not issues:\n            return \"\"\n\n        lines = [\"Config issue detected — run 'clawbot doctor' for full diagnostics:\"]\n        for ci in issues:\n            prefix = \"ERROR\" if ci.severity == \"error\" else \"WARNING\"\n            lines.append(f\"  [{prefix}] {ci.message}\")\n            # Show first line of hint\n            first_hint = ci.hint.splitlines()[0] if ci.hint else \"\"\n            if first_hint:\n                lines.append(f\"    → {first_hint}\")\n        return \"\\n\".join(lines)\n    except Exception:\n        return \"\"\n\n\ndef resolve_provider(\n    requested: Optional[str] = None,\n    *,\n    explicit_api_key: Optional[str] = None,\n    explicit_base_url: Optional[str] = None,\n) -> str:\n    \"\"\"\n    Determine which inference provider to use.\n\n    Priority (when requested=\"auto\" or None):\n    1. active_provider in auth.json with valid credentials\n    2. Explicit CLI api_key/base_url -> \"openrouter\"\n    3. OPENAI_API_KEY or OPENROUTER_API_KEY env vars -> \"openrouter\"\n    4. Provider-specific API keys (GLM, Kimi, MiniMax) -> that provider\n    5. Fallback: \"openrouter\"\n    \"\"\"\n    normalized = (requested or \"auto\").strip().lower()\n\n    # Normalize provider aliases\n    _PROVIDER_ALIASES = {\n        \"glm\": \"zai\", \"z-ai\": \"zai\", \"z.ai\": \"zai\", \"zhipu\": \"zai\",\n        \"google\": \"gemini\", \"google-gemini\": \"gemini\", \"google-ai-studio\": \"gemini\",\n        \"x-ai\": \"xai\", \"x.ai\": \"xai\", \"grok\": \"xai\",\n        \"xai-oauth\": \"xai-oauth\", \"x-ai-oauth\": \"xai-oauth\",\n        \"grok-oauth\": \"xai-oauth\", \"xai-grok-oauth\": \"xai-oauth\",\n        \"kimi\": \"kimi-coding\", \"kimi-for-coding\": \"kimi-coding\", \"moonshot\": \"kimi-coding\",\n        \"kimi-cn\": \"kimi-coding-cn\", \"moonshot-cn\": \"kimi-coding-cn\",\n        \"step\": \"stepfun\", \"stepfun-coding-plan\": \"stepfun\",\n        \"arcee-ai\": \"arcee\", \"arceeai\": \"arcee\",\n        \"gmi-cloud\": \"gmi\", \"gmicloud\": \"gmi\",\n        \"minimax-china\": \"minimax-cn\", \"minimax_cn\": \"minimax-cn\",\n        \"minimax-portal\": \"minimax-oauth\", \"minimax-global\": \"minimax-oauth\", \"minimax_oauth\": \"minimax-oauth\",\n        \"alibaba_coding\": \"alibaba-coding-plan\", \"alibaba-coding\": \"alibaba-coding-plan\",\n        \"alibaba_coding_plan\": \"alibaba-coding-plan\",\n        \"claude\": \"anthropic\", \"claude-code\": \"anthropic\",\n        \"github\": \"copilot\", \"github-copilot\": \"copilot\",\n        \"github-models\": \"copilot\", \"github-model\": \"copilot\",\n        \"github-copilot-acp\": \"copilot-acp\", \"copilot-acp-agent\": \"copilot-acp\",\n        \"aigateway\": \"ai-gateway\", \"vercel\": \"ai-gateway\", \"vercel-ai-gateway\": \"ai-gateway\",\n        \"opencode\": \"opencode-zen\", \"zen\": \"opencode-zen\",\n        \"qwen-portal\": \"qwen-oauth\", \"qwen-cli\": \"qwen-oauth\", \"qwen-oauth\": \"qwen-oauth\", \"google-gemini-cli\": \"google-gemini-cli\", \"gemini-cli\": \"google-gemini-cli\", \"gemini-oauth\": \"google-gemini-cli\",\n        \"hf\": \"huggingface\", \"hugging-face\": \"huggingface\", \"huggingface-hub\": \"huggingface\",\n        \"mimo\": \"xiaomi\", \"xiaomi-mimo\": \"xiaomi\",\n        \"tencent\": \"tencent-tokenhub\", \"tokenhub\": \"tencent-tokenhub\",\n        \"tencent-cloud\": \"tencent-tokenhub\", \"tencentmaas\": \"tencent-tokenhub\",\n        \"aws\": \"bedrock\", \"aws-bedrock\": \"bedrock\", \"amazon-bedrock\": \"bedrock\", \"amazon\": \"bedrock\",\n        \"go\": \"opencode-go\", \"opencode-go-sub\": \"opencode-go\",\n        \"kilo\": \"kilocode\", \"kilo-code\": \"kilocode\", \"kilo-gateway\": \"kilocode\",\n        \"lmstudio\": \"lmstudio\", \"lm-studio\": \"lmstudio\", \"lm_studio\": \"lmstudio\",\n        # Local server aliases — route through the generic custom provider\n        \"ollama\": \"custom\", \"ollama_cloud\": \"ollama-cloud\",\n        \"vllm\": \"custom\", \"llamacpp\": \"custom\",\n        \"llama.cpp\": \"custom\", \"llama-cpp\": \"custom\",\n    }\n    # Extend with aliases declared in plugins/model-providers/<name>/ that aren't already mapped.\n    # This keeps providers/ as the single source for new aliases while the\n    # hardcoded dict above remains authoritative for existing ones.\n    try:\n        from providers import list_providers as _lp\n        for _pp in _lp():\n            for _alias in _pp.aliases:\n                if _alias not in _PROVIDER_ALIASES:\n                    _PROVIDER_ALIASES[_alias] = _pp.name\n    except Exception:\n        pass\n    normalized = _PROVIDER_ALIASES.get(normalized, normalized)\n\n    if normalized == \"openrouter\":\n        return \"openrouter\"\n    if normalized == \"custom\":\n        return \"custom\"\n    if normalized in PROVIDER_REGISTRY:\n        return normalized\n    if normalized != \"auto\":\n        # Check for common config.yaml issues that cause this error\n        _config_hint = _get_config_hint_for_unknown_provider(normalized)\n        msg = f\"Unknown provider '{normalized}'.\"\n        if _config_hint:\n            msg += f\"\\n\\n{_config_hint}\"\n        else:\n            msg += \" Check 'clawbot model' for available providers, or run 'clawbot doctor' to diagnose config issues.\"\n        raise AuthError(msg, code=\"invalid_provider\")\n\n    # Explicit one-off CLI creds always mean openrouter/custom\n    if explicit_api_key or explicit_base_url:\n        return \"openrouter\"\n\n    # Check auth store for an active OAuth provider\n    try:\n        auth_store = _load_auth_store()\n        active = auth_store.get(\"active_provider\")\n        if active and active in PROVIDER_REGISTRY:\n            status = get_auth_status(active)\n            if status.get(\"logged_in\"):\n                return active\n    except Exception as e:\n        logger.debug(\"Could not detect active auth provider: %s\", e)\n\n    if has_usable_secret(os.getenv(\"OPENAI_API_KEY\")) or has_usable_secret(os.getenv(\"OPENROUTER_API_KEY\")):\n        return \"openrouter\"\n\n    # Auto-detect API-key providers by checking their env vars\n    for pid, pconfig in PROVIDER_REGISTRY.items():\n        if pconfig.auth_type != \"api_key\":\n            continue\n        # GitHub tokens are commonly present for repo/tool access but should not\n        # hijack inference auto-selection unless the user explicitly chooses\n        # Copilot/GitHub Models as the provider. LM Studio is a local server\n        # whose availability isn't implied by LM_API_KEY presence (it may be\n        # offline, and the no-auth setup uses a placeholder value), so it\n        # also requires explicit selection.\n        if pid in {\"copilot\", \"lmstudio\"}:\n            continue\n        for env_var in pconfig.api_key_env_vars:\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return pid\n\n    # AWS Bedrock — detect via boto3 credential chain (IAM roles, SSO, env vars).\n    # This runs after API-key providers so explicit keys always win.\n    try:\n        from agent.bedrock_adapter import has_aws_credentials\n        if has_aws_credentials():\n            return \"bedrock\"\n    except ImportError:\n        pass  # boto3 not installed — skip Bedrock auto-detection\n\n    raise AuthError(\n        \"No inference provider configured. Run 'clawbot model' to choose a \"\n        \"provider and model, or set an API key (OPENROUTER_API_KEY, \"\n        \"OPENAI_API_KEY, etc.) in ~/.clawbot/.env.\",\n        code=\"no_provider_configured\",\n    )\n\n\n# =============================================================================\n# Timestamp / TTL helpers\n# =============================================================================\n\ndef _parse_iso_timestamp(value: Any) -> Optional[float]:\n    if not isinstance(value, str) or not value:\n        return None\n    text = value.strip()\n    if not text:\n        return None\n    if text.endswith(\"Z\"):\n        text = text[:-1] + \"+00:00\"\n    try:\n        parsed = datetime.fromisoformat(text)\n    except Exception:\n        return None\n    if parsed.tzinfo is None:\n        parsed = parsed.replace(tzinfo=timezone.utc)\n    return parsed.timestamp()\n\n\ndef _is_expiring(expires_at_iso: Any, skew_seconds: int) -> bool:\n    expires_epoch = _parse_iso_timestamp(expires_at_iso)\n    if expires_epoch is None:\n        return True\n    return expires_epoch <= (time.time() + skew_seconds)\n\n\ndef _coerce_ttl_seconds(expires_in: Any) -> int:\n    try:\n        ttl = int(expires_in)\n    except Exception:\n        ttl = 0\n    return max(0, ttl)\n\n\ndef _optional_base_url(value: Any) -> Optional[str]:\n    if not isinstance(value, str):\n        return None\n    cleaned = value.strip().rstrip(\"/\")\n    return cleaned if cleaned else None\n\n\ndef _decode_jwt_claims(token: Any) -> Dict[str, Any]:\n    if not isinstance(token, str) or token.count(\".\") != 2:\n        return {}\n    payload = token.split(\".\")[1]\n    payload += \"=\" * ((4 - len(payload) % 4) % 4)\n    try:\n        raw = base64.urlsafe_b64decode(payload.encode(\"utf-8\"))\n        claims = json.loads(raw.decode(\"utf-8\"))\n    except Exception:\n        return {}\n    return claims if isinstance(claims, dict) else {}\n\n\ndef _scope_values(raw_scope: Any) -> set[str]:\n    # OAuth token responses normally return a space-separated string. Keep\n    # collection support for JWT ``scp`` claims and older stored test fixtures.\n    scopes: set[str] = set()\n    if isinstance(raw_scope, str):\n        for part in raw_scope.replace(\",\", \" \").split():\n            cleaned = part.strip()\n            if cleaned:\n                scopes.add(cleaned)\n    elif isinstance(raw_scope, (list, tuple, set, frozenset)):\n        for item in raw_scope:\n            if isinstance(item, str):\n                scopes.update(_scope_values(item))\n    return scopes\n\n\ndef _soam_legacy_session_keys_forced() -> bool:\n    return is_truthy_value(os.getenv(SOAM_LEGACY_SESSION_KEYS_ENV), default=False)\n\n\ndef _soam_scope_has_invoke(raw_scope: Any) -> bool:\n    return SOAM_INFERENCE_INVOKE_SCOPE in _scope_values(raw_scope)\n\n\ndef _normalize_soam_inference_auth_mode(inference_auth_mode: Optional[str]) -> str:\n    mode = str(inference_auth_mode or SOAM_INFERENCE_AUTH_MODE_AUTO).strip().lower()\n    if mode not in SOAM_INFERENCE_AUTH_MODES:\n        allowed = \", \".join(sorted(SOAM_INFERENCE_AUTH_MODES))\n        raise ValueError(\n            \"Invalid Soam inference auth mode \"\n            f\"{inference_auth_mode!r}; expected one of: {allowed}\"\n        )\n    return mode\n\n\ndef _soam_invoke_jwt_status(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> Optional[str]:\n    \"\"\"Return None when the token can be used for inference, else a reason.\"\"\"\n    claims = _decode_jwt_claims(token)\n    if not claims:\n        return \"access_token_not_jwt\"\n    scopes = (\n        _scope_values(scope)\n        | _scope_values(claims.get(\"scope\"))\n        | _scope_values(claims.get(\"scp\"))\n    )\n    if SOAM_INFERENCE_INVOKE_SCOPE not in scopes:\n        return \"missing_inference_invoke_scope\"\n    exp = claims.get(\"exp\")\n    skew = max(0, int(min_ttl_seconds))\n    if isinstance(exp, (int, float)):\n        if float(exp) <= (time.time() + skew):\n            return \"invoke_jwt_expiring\"\n        return None\n    if _is_expiring(expires_at, skew):\n        return \"invoke_jwt_expiry_unknown_or_expiring\"\n    return None\n\n\ndef _soam_invoke_jwt_is_usable(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> bool:\n    return (\n        _soam_invoke_jwt_status(\n            token,\n            scope=scope,\n            expires_at=expires_at,\n            min_ttl_seconds=min_ttl_seconds,\n        )\n        is None\n    )\n\n\ndef _soam_legacy_session_key_reason(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> str:\n    if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY:\n        return \"forced_legacy_session_key\"\n    if _soam_legacy_session_keys_forced():\n        return \"forced_legacy_session_keys\"\n    return (\n        _soam_invoke_jwt_status(token, scope=scope, expires_at=expires_at)\n        or \"invoke_jwt_unavailable\"\n    )\n\n\ndef _choose_soam_inference_auth_path(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Tuple[str, Optional[str]]:\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    token = state.get(\"access_token\") if access_token is None else access_token\n    if (\n        not _soam_legacy_session_keys_forced()\n        and inference_auth_mode != SOAM_INFERENCE_AUTH_MODE_LEGACY\n        and _soam_invoke_jwt_is_usable(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n        )\n    ):\n        return SOAM_AUTH_PATH_INVOKE_JWT, None\n    if (\n        inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_AUTO\n        and _agent_key_is_usable(\n            state,\n            max(60, int(min_key_ttl_seconds)),\n        )\n    ):\n        return SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE, None\n    return (\n        SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT,\n        _soam_legacy_session_key_reason(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n            inference_auth_mode=inference_auth_mode,\n        ),\n    )\n\n\ndef _log_soam_invoke_jwt_selected(\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\"Soam inference auth: using NAS invoke JWT\")\n    _oauth_trace(\n        \"soam_invoke_jwt_selected\",\n        sequence_id=sequence_id,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _log_soam_legacy_session_key_selected(\n    reason: str,\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\n        \"Soam inference auth: using legacy session key path (%s)\",\n        reason,\n    )\n    _oauth_trace(\n        \"soam_legacy_session_key_selected\",\n        sequence_id=sequence_id,\n        reason=reason,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _soam_jwt_expires_at(token: Any, fallback_expires_at: Any = None) -> Optional[str]:\n    claims = _decode_jwt_claims(token)\n    exp = claims.get(\"exp\")\n    if isinstance(exp, (int, float)):\n        try:\n            return datetime.fromtimestamp(float(exp), tz=timezone.utc).isoformat()\n        except Exception:\n            pass\n    return fallback_expires_at if isinstance(fallback_expires_at, str) else None\n\n\ndef _set_soam_agent_key_from_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    obtained_at: Optional[str] = None,\n) -> None:\n    access_token = state.get(\"access_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        return\n    now = datetime.now(timezone.utc)\n    existing_obtained_at = state.get(\"agent_key_obtained_at\")\n    if obtained_at:\n        effective_obtained_at = obtained_at\n    elif (\n        state.get(\"agent_key\") == access_token\n        and isinstance(existing_obtained_at, str)\n        and existing_obtained_at.strip()\n    ):\n        effective_obtained_at = existing_obtained_at\n    else:\n        effective_obtained_at = now.isoformat()\n    expires_at = _soam_jwt_expires_at(access_token, state.get(\"expires_at\"))\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"expires_in\"))\n    )\n    if expires_at:\n        state[\"expires_at\"] = expires_at\n        state[\"expires_in\"] = expires_in\n    state[\"agent_key\"] = access_token\n    state[\"agent_key_id\"] = None\n    state[\"agent_key_expires_at\"] = expires_at\n    state[\"agent_key_expires_in\"] = expires_in\n    state[\"agent_key_reused\"] = False\n    state[\"agent_key_obtained_at\"] = effective_obtained_at\n\n\ndef _select_soam_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    sequence_id: Optional[str] = None,\n) -> None:\n    if isinstance(access_token, str) and access_token.strip():\n        state[\"access_token\"] = access_token\n    _set_soam_agent_key_from_invoke_jwt(state)\n    _log_soam_invoke_jwt_selected(\n        access_token=state.get(\"access_token\"),\n        sequence_id=sequence_id,\n    )\n\n\n_SOAM_EFFECTIVE_STATE_IGNORED_KEYS = frozenset({\n    # These are derived from expires_at/JWT exp and naturally tick down between\n    # reads. Persisting only these changes makes auth.json noisy and defeats\n    # the mtime-keyed auth-status cache.\n    \"expires_in\",\n    \"agent_key_expires_in\",\n})\n\n\ndef _soam_effective_provider_state(state: Dict[str, Any]) -> Dict[str, Any]:\n    return {\n        key: value\n        for key, value in state.items()\n        if key not in _SOAM_EFFECTIVE_STATE_IGNORED_KEYS\n    }\n\n\ndef _codex_access_token_is_expiring(access_token: Any, skew_seconds: int) -> bool:\n    claims = _decode_jwt_claims(access_token)\n    exp = claims.get(\"exp\")\n    if not isinstance(exp, (int, float)):\n        return False\n    return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n\n\ndef _qwen_cli_auth_path() -> Path:\n    return Path.home() / \".qwen\" / \"oauth_creds.json\"\n\n\ndef _read_qwen_cli_tokens() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    if not auth_path.exists():\n        raise AuthError(\n            \"Qwen CLI credentials not found. Run 'qwen auth qwen-oauth' first.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_missing\",\n        )\n    try:\n        data = json.loads(auth_path.read_text(encoding=\"utf-8\"))\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to read Qwen CLI credentials from {auth_path}: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_read_failed\",\n        ) from exc\n    if not isinstance(data, dict):\n        raise AuthError(\n            f\"Invalid Qwen CLI credentials in {auth_path}.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_invalid\",\n        )\n    return data\n\n\ndef _save_qwen_cli_tokens(tokens: Dict[str, Any]) -> Path:\n    auth_path = _qwen_cli_auth_path()\n    auth_path.parent.mkdir(parents=True, exist_ok=True)\n    try:\n        os.chmod(auth_path.parent, 0o700)\n    except OSError:\n        pass\n    # Per-process random temp suffix avoids collisions between concurrent\n    # writers and stale leftovers from a crashed prior write.\n    tmp_path = auth_path.with_name(f\"{auth_path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n    # window where write_text() + post-write chmod briefly exposed tokens\n    # at process umask (typically 0o644). See #19673, #21148.\n    fd = os.open(\n        str(tmp_path),\n        os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n        stat.S_IRUSR | stat.S_IWUSR,\n    )\n    try:\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n            fh.write(json.dumps(tokens, indent=2, sort_keys=True) + \"\\n\")\n            fh.flush()\n            os.fsync(fh.fileno())\n        atomic_replace(tmp_path, auth_path)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    return auth_path\n\n\ndef _qwen_access_token_is_expiring(expiry_date_ms: Any, skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS) -> bool:\n    try:\n        expiry_ms = int(expiry_date_ms)\n    except Exception:\n        return True\n    return (time.time() + max(0, int(skew_seconds))) * 1000 >= expiry_ms\n\n\ndef _refresh_qwen_cli_tokens(tokens: Dict[str, Any], timeout_seconds: float = 20.0) -> Dict[str, Any]:\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Qwen OAuth refresh token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_token_missing\",\n        )\n\n    try:\n        response = httpx.post(\n            QWEN_OAUTH_TOKEN_URL,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": QWEN_OAUTH_CLIENT_ID,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh failed: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        body = response.text.strip()\n        raise AuthError(\n            \"Qwen OAuth refresh failed. Re-run 'qwen auth qwen-oauth'.\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh returned invalid JSON: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_json\",\n        ) from exc\n\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Qwen OAuth refresh response missing access_token.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_response\",\n        )\n\n    expires_in = payload.get(\"expires_in\")\n    try:\n        expires_in_seconds = int(expires_in)\n    except Exception:\n        expires_in_seconds = 6 * 60 * 60\n\n    refreshed = {\n        \"access_token\": str(payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(payload.get(\"refresh_token\", refresh_token) or refresh_token).strip(),\n        \"token_type\": str(payload.get(\"token_type\", tokens.get(\"token_type\", \"Bearer\")) or \"Bearer\").strip() or \"Bearer\",\n        \"resource_url\": str(payload.get(\"resource_url\", tokens.get(\"resource_url\", \"portal.qwen.ai\")) or \"portal.qwen.ai\").strip(),\n        \"expiry_date\": int(time.time() * 1000) + max(1, expires_in_seconds) * 1000,\n    }\n    _save_qwen_cli_tokens(refreshed)\n    return refreshed\n\n\ndef resolve_qwen_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    tokens = _read_qwen_cli_tokens()\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    should_refresh = bool(force_refresh)\n    if not should_refresh and refresh_if_expiring:\n        should_refresh = _qwen_access_token_is_expiring(tokens.get(\"expiry_date\"), refresh_skew_seconds)\n    if should_refresh:\n        tokens = _refresh_qwen_cli_tokens(tokens)\n        access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Qwen OAuth access token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_access_token_missing\",\n        )\n\n    base_url = os.getenv(\"CLAWBOT_QWEN_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_QWEN_BASE_URL\n    return {\n        \"provider\": \"qwen-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"qwen-cli\",\n        \"expires_at_ms\": tokens.get(\"expiry_date\"),\n        \"auth_file\": str(_qwen_cli_auth_path()),\n    }\n\n\ndef get_qwen_auth_status() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    try:\n        creds = resolve_qwen_runtime_credentials(refresh_if_expiring=False)\n        return {\n            \"logged_in\": True,\n            \"auth_file\": str(auth_path),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n            \"expires_at_ms\": creds.get(\"expires_at_ms\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": str(exc),\n        }\n\n\n# =============================================================================\n# Google Gemini OAuth (google-gemini-cli) — PKCE flow + Cloud Code Assist.\n#\n# Tokens live in ~/.clawbot/auth/google_oauth.json (managed by agent.google_oauth).\n# The `base_url` here is the marker \"cloudcode-pa://google\" that run_agent.py\n# uses to construct a GeminiCloudCodeClient instead of the default OpenAI SDK.\n# Actual HTTP traffic goes to https://cloudcode-pa.googleapis.com/v1internal:*.\n# =============================================================================\n\ndef resolve_gemini_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime OAuth creds for google-gemini-cli.\"\"\"\n    try:\n        from agent.google_oauth import (\n            GoogleOAuthError,\n            _credentials_path,\n            get_valid_access_token,\n            load_credentials,\n        )\n    except ImportError as exc:\n        raise AuthError(\n            f\"agent.google_oauth is not importable: {exc}\",\n            provider=\"google-gemini-cli\",\n            code=\"google_oauth_module_missing\",\n        ) from exc\n\n    try:\n        access_token = get_valid_access_token(force_refresh=force_refresh)\n    except GoogleOAuthError as exc:\n        raise AuthError(\n            str(exc),\n            provider=\"google-gemini-cli\",\n            code=exc.code,\n        ) from exc\n\n    creds = load_credentials()\n    base_url = DEFAULT_GEMINI_CLOUDCODE_BASE_URL\n    return {\n        \"provider\": \"google-gemini-cli\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"google-oauth\",\n        \"expires_at_ms\": (creds.expires_ms if creds else None),\n        \"auth_file\": str(_credentials_path()),\n        \"email\": (creds.email if creds else \"\") or \"\",\n        \"project_id\": (creds.project_id if creds else \"\") or \"\",\n    }\n\n\ndef get_gemini_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return a status dict for `clawbot auth list` / `clawbot status`.\"\"\"\n    try:\n        from agent.google_oauth import _credentials_path, load_credentials\n    except ImportError:\n        return {\"logged_in\": False, \"error\": \"agent.google_oauth unavailable\"}\n    auth_path = _credentials_path()\n    creds = load_credentials()\n    if creds is None or not creds.access_token:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": \"not logged in\",\n        }\n    return {\n        \"logged_in\": True,\n        \"auth_file\": str(auth_path),\n        \"source\": \"google-oauth\",\n        \"api_key\": creds.access_token,\n        \"expires_at_ms\": creds.expires_ms,\n        \"email\": creds.email,\n        \"project_id\": creds.project_id,\n    }\n# Spotify auth — PKCE tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\n\ndef _spotify_scope_list(raw_scope: Optional[str] = None) -> List[str]:\n    scope_text = (raw_scope or DEFAULT_SPOTIFY_SCOPE).strip()\n    scopes = [part for part in scope_text.split() if part]\n    seen: set[str] = set()\n    ordered: List[str] = []\n    for scope in scopes:\n        if scope not in seen:\n            seen.add(scope)\n            ordered.append(scope)\n    return ordered\n\n\ndef _spotify_scope_string(raw_scope: Optional[str] = None) -> str:\n    return \" \".join(_spotify_scope_list(raw_scope))\n\n\ndef _spotify_client_id(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\"),\n        get_env_value(\"SPOTIFY_CLIENT_ID\"),\n        state.get(\"client_id\") if isinstance(state, dict) else None,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    raise AuthError(\n        \"Spotify client_id is required. Set CLAWBOT_SPOTIFY_CLIENT_ID or pass --client-id.\",\n        provider=\"spotify\",\n        code=\"spotify_client_id_missing\",\n    )\n\n\ndef _spotify_redirect_uri(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\"),\n        get_env_value(\"SPOTIFY_REDIRECT_URI\"),\n        state.get(\"redirect_uri\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_REDIRECT_URI,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_REDIRECT_URI\n\n\ndef _spotify_api_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_API_BASE_URL\"),\n        state.get(\"api_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_API_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_API_BASE_URL\n\n\ndef _spotify_accounts_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_ACCOUNTS_BASE_URL\"),\n        state.get(\"accounts_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL\n\n\ndef _spotify_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _spotify_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _oauth_pkce_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _oauth_pkce_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _spotify_build_authorize_url(\n    *,\n    client_id: str,\n    redirect_uri: str,\n    scope: str,\n    state: str,\n    code_challenge: str,\n    accounts_base_url: str,\n) -> str:\n    query = urlencode({\n        \"client_id\": client_id,\n        \"response_type\": \"code\",\n        \"redirect_uri\": redirect_uri,\n        \"scope\": scope,\n        \"state\": state,\n        \"code_challenge_method\": \"S256\",\n        \"code_challenge\": code_challenge,\n    })\n    return f\"{accounts_base_url}/authorize?{query}\"\n\n\ndef _spotify_validate_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must use http://localhost or http://127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host not in {\"127.0.0.1\", \"localhost\"}:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must point to localhost or 127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must include an explicit localhost port.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _make_spotify_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _SpotifyCallbackHandler(BaseHTTPRequestHandler):\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>Spotify authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>Spotify authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _SpotifyCallbackHandler, result\n\n\ndef _spotify_wait_for_callback(\n    redirect_uri: str,\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    host, port, path = _spotify_validate_redirect_uri(redirect_uri)\n    handler_cls, result = _make_spotify_callback_handler(path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    try:\n        server = _ReuseHTTPServer((host, port), handler_cls)\n    except OSError as exc:\n        raise AuthError(\n            f\"Could not bind Spotify callback server on {host}:{port}: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_callback_bind_failed\",\n        ) from exc\n\n    thread = threading.Thread(target=server.serve_forever, kwargs={\"poll_interval\": 0.1}, daemon=True)\n    thread.start()\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"Spotify authorization timed out waiting for the local callback.\",\n        provider=\"spotify\",\n        code=\"spotify_callback_timeout\",\n    )\n\n\ndef _xai_validate_loopback_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"xAI OAuth redirect_uri must use http://127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host != XAI_OAUTH_REDIRECT_HOST:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must point to 127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must include an explicit localhost port.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _xai_callback_cors_origin(origin: Optional[str]) -> str:\n    # CORS allowlist for the loopback callback.  Only xAI's own auth origins\n    # are accepted; the redirect_uri itself is bound to 127.0.0.1 and gated by\n    # PKCE+state, so additional dev/3p origins are not needed here.\n    allowed = {\n        \"https://accounts.x.ai\",\n        \"https://auth.x.ai\",\n    }\n    return origin if origin in allowed else \"\"\n\n\ndef _make_xai_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _XAICallbackHandler(BaseHTTPRequestHandler):\n        def _maybe_write_cors_headers(self) -> None:\n            origin = self.headers.get(\"Origin\")\n            allow_origin = _xai_callback_cors_origin(origin)\n            if allow_origin:\n                self.send_header(\"Access-Control-Allow-Origin\", allow_origin)\n                self.send_header(\"Access-Control-Allow-Methods\", \"GET, OPTIONS\")\n                self.send_header(\"Access-Control-Allow-Headers\", \"Content-Type\")\n                self.send_header(\"Access-Control-Allow-Private-Network\", \"true\")\n                self.send_header(\"Vary\", \"Origin\")\n\n        def do_OPTIONS(self) -> None:  # noqa: N802\n            self.send_response(204)\n            self._maybe_write_cors_headers()\n            self.end_headers()\n\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self._maybe_write_cors_headers()\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>xAI authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _XAICallbackHandler, result\n\n\ndef _xai_start_callback_server(\n    preferred_port: int = XAI_OAUTH_REDIRECT_PORT,\n) -> tuple[HTTPServer, threading.Thread, dict[str, Any], str]:\n    host = XAI_OAUTH_REDIRECT_HOST\n    expected_path = XAI_OAUTH_REDIRECT_PATH\n    handler_cls, result = _make_xai_callback_handler(expected_path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    ports_to_try = [preferred_port]\n    if preferred_port != 0:\n        ports_to_try.append(0)\n    server = None\n    last_error: Optional[OSError] = None\n    for port in ports_to_try:\n        try:\n            server = _ReuseHTTPServer((host, port), handler_cls)\n            break\n        except OSError as exc:\n            last_error = exc\n    if server is None:\n        raise AuthError(\n            f\"Could not bind xAI callback server on {host}:{preferred_port}: {last_error}\",\n            provider=\"xai-oauth\",\n            code=\"xai_callback_bind_failed\",\n        ) from last_error\n\n    actual_port = int(server.server_address[1])\n    redirect_uri = f\"http://{host}:{actual_port}{expected_path}\"\n    thread = threading.Thread(\n        target=server.serve_forever,\n        kwargs={\"poll_interval\": 0.1},\n        daemon=True,\n    )\n    thread.start()\n    return server, thread, result, redirect_uri\n\n\ndef _xai_wait_for_callback(\n    server: HTTPServer,\n    thread: threading.Thread,\n    result: dict[str, Any],\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"xAI authorization timed out waiting for the local callback.\",\n        provider=\"xai-oauth\",\n        code=\"xai_callback_timeout\",\n    )\n\n\ndef _spotify_token_payload_to_state(\n    token_payload: Dict[str, Any],\n    *,\n    client_id: str,\n    redirect_uri: str,\n    requested_scope: str,\n    accounts_base_url: str,\n    api_base_url: str,\n    previous_state: Optional[Dict[str, Any]] = None,\n) -> Dict[str, Any]:\n    now = datetime.now(timezone.utc)\n    expires_in = _coerce_ttl_seconds(token_payload.get(\"expires_in\", 0))\n    expires_at = datetime.fromtimestamp(now.timestamp() + expires_in, tz=timezone.utc)\n    state = dict(previous_state or {})\n    state.update({\n        \"client_id\": client_id,\n        \"redirect_uri\": redirect_uri,\n        \"accounts_base_url\": accounts_base_url,\n        \"api_base_url\": api_base_url,\n        \"scope\": requested_scope,\n        \"granted_scope\": str(token_payload.get(\"scope\") or requested_scope).strip(),\n        \"token_type\": str(token_payload.get(\"token_type\", \"Bearer\") or \"Bearer\").strip() or \"Bearer\",\n        \"access_token\": str(token_payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(\n            token_payload.get(\"refresh_token\")\n            or state.get(\"refresh_token\")\n            or \"\"\n        ).strip(),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": expires_at.isoformat(),\n        \"expires_in\": expires_in,\n        \"auth_type\": \"oauth_pkce\",\n    })\n    return state\n\n\ndef _spotify_exchange_code_for_tokens(\n    *,\n    client_id: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    accounts_base_url: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"client_id\": client_id,\n                \"grant_type\": \"authorization_code\",\n                \"code\": code,\n                \"redirect_uri\": redirect_uri,\n                \"code_verifier\": code_verifier,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token exchange failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token exchange failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        )\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify token response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _refresh_spotify_oauth_state(\n    state: Dict[str, Any],\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Spotify refresh token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_token_missing\",\n            relogin_required=True,\n        )\n\n    client_id = _spotify_client_id(state=state)\n    accounts_base_url = _spotify_accounts_base_url(state)\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": client_id,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token refresh failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token refresh failed. Run `clawbot auth spotify` again.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n            relogin_required=True,\n        )\n\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify refresh response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_invalid\",\n            relogin_required=True,\n        )\n\n    return _spotify_token_payload_to_state(\n        payload,\n        client_id=client_id,\n        redirect_uri=_spotify_redirect_uri(state=state),\n        requested_scope=str(state.get(\"scope\") or DEFAULT_SPOTIFY_SCOPE),\n        accounts_base_url=accounts_base_url,\n        api_base_url=_spotify_api_base_url(state),\n        previous_state=state,\n    )\n\n\ndef resolve_spotify_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = SPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"spotify\")\n        if not state:\n            raise AuthError(\n                \"Spotify is not authenticated. Run `clawbot auth spotify` first.\",\n                provider=\"spotify\",\n                code=\"spotify_auth_missing\",\n                relogin_required=True,\n            )\n\n        should_refresh = bool(force_refresh)\n        if not should_refresh and refresh_if_expiring:\n            should_refresh = _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds)\n        if should_refresh:\n            state = _refresh_spotify_oauth_state(state)\n            _store_provider_state(auth_store, \"spotify\", state, set_active=False)\n            _save_auth_store(auth_store)\n\n    access_token = str(state.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Spotify access token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_access_token_missing\",\n            relogin_required=True,\n        )\n\n    return {\n        \"provider\": \"spotify\",\n        \"access_token\": access_token,\n        \"api_key\": access_token,\n        \"token_type\": str(state.get(\"token_type\", \"Bearer\") or \"Bearer\"),\n        \"base_url\": _spotify_api_base_url(state),\n        \"scope\": str(state.get(\"granted_scope\") or state.get(\"scope\") or \"\").strip(),\n        \"client_id\": _spotify_client_id(state=state),\n        \"redirect_uri\": _spotify_redirect_uri(state=state),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"refresh_token\": str(state.get(\"refresh_token\", \"\") or \"\").strip(),\n    }\n\n\ndef get_spotify_auth_status() -> Dict[str, Any]:\n    state = get_provider_auth_state(\"spotify\")\n    if not state:\n        return {\"logged_in\": False}\n\n    expires_at = state.get(\"expires_at\")\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    return {\n        \"logged_in\": bool(refresh_token or not _is_expiring(expires_at, 0)),\n        \"auth_type\": state.get(\"auth_type\", \"oauth_pkce\"),\n        \"client_id\": state.get(\"client_id\"),\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n        \"scope\": state.get(\"granted_scope\") or state.get(\"scope\"),\n        \"expires_at\": expires_at,\n        \"api_base_url\": state.get(\"api_base_url\"),\n        \"has_refresh_token\": bool(refresh_token),\n    }\n\n\ndef _spotify_interactive_setup(redirect_uri_hint: str) -> str:\n    \"\"\"Walk the user through creating a Spotify developer app, persist the\n    resulting client_id to ~/.clawbot/.env, and return it.\n\n    Raises SystemExit if the user aborts or submits an empty value.\n    \"\"\"\n    from clawbot_cli.config import save_env_value\n\n    print()\n    print(\"=\" * 70)\n    print(\"Spotify first-time setup\")\n    print(\"=\" * 70)\n    print()\n    print(\"Spotify requires every user to register their own lightweight\")\n    print(\"developer app. This takes about two minutes and only has to be\")\n    print(\"done once per machine.\")\n    print()\n    print(f\"Full guide: {SPOTIFY_DOCS_URL}\")\n    print()\n    print(\"Steps:\")\n    print(f\"  1. Opening {SPOTIFY_DASHBOARD_URL} in your browser...\")\n    print(\"  2. Click 'Create app' and fill in:\")\n    print(\"       App name:     anything (e.g. clawbot-agent)\")\n    print(\"       Description:  anything\")\n    print(f\"       Redirect URI: {redirect_uri_hint}\")\n    print(\"       API/SDK:      Web API\")\n    print(\"  3. Agree to the terms, click Save.\")\n    print(\"  4. Open the app's Settings page and copy the Client ID.\")\n    print(\"  5. Paste it below.\")\n    print()\n\n    if not _is_remote_session():\n        try:\n            webbrowser.open(SPOTIFY_DASHBOARD_URL)\n        except Exception:\n            pass\n\n    try:\n        raw = input(\"Spotify Client ID: \").strip()\n    except (EOFError, KeyboardInterrupt):\n        print()\n        raise SystemExit(\"Spotify setup cancelled.\")\n\n    if not raw:\n        print()\n        print(f\"No Client ID entered. See {SPOTIFY_DOCS_URL} for the full guide.\")\n        raise SystemExit(\"Spotify setup cancelled: empty Client ID.\")\n\n    # Persist so subsequent `clawbot auth spotify` runs skip the wizard.\n    save_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\", raw)\n    # Only persist the redirect URI if it's non-default, to avoid pinning\n    # users to a value the default might later change to.\n    if redirect_uri_hint and redirect_uri_hint != DEFAULT_SPOTIFY_REDIRECT_URI:\n        save_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\", redirect_uri_hint)\n\n    print()\n    print(\"Saved CLAWBOT_SPOTIFY_CLIENT_ID to ~/.clawbot/.env\")\n    print()\n    return raw\n\n\ndef login_spotify_command(args) -> None:\n    existing_state = get_provider_auth_state(\"spotify\") or {}\n\n    # Interactive wizard: if no client_id is configured anywhere, walk the\n    # user through creating the Spotify developer app instead of crashing\n    # with \"CLAWBOT_SPOTIFY_CLIENT_ID is required\".\n    explicit_client_id = getattr(args, \"client_id\", None)\n    try:\n        client_id = _spotify_client_id(explicit_client_id, existing_state)\n    except AuthError as exc:\n        if getattr(exc, \"code\", \"\") != \"spotify_client_id_missing\":\n            raise\n        client_id = _spotify_interactive_setup(\n            redirect_uri_hint=getattr(args, \"redirect_uri\", None) or DEFAULT_SPOTIFY_REDIRECT_URI,\n        )\n\n    redirect_uri = _spotify_redirect_uri(getattr(args, \"redirect_uri\", None), existing_state)\n    scope = _spotify_scope_string(getattr(args, \"scope\", None) or existing_state.get(\"scope\"))\n    accounts_base_url = _spotify_accounts_base_url(existing_state)\n    api_base_url = _spotify_api_base_url(existing_state)\n    open_browser = not getattr(args, \"no_browser\", False)\n\n    code_verifier = _spotify_code_verifier()\n    code_challenge = _spotify_code_challenge(code_verifier)\n    state_nonce = uuid.uuid4().hex\n    authorize_url = _spotify_build_authorize_url(\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        scope=scope,\n        state=state_nonce,\n        code_challenge=code_challenge,\n        accounts_base_url=accounts_base_url,\n    )\n\n    print(\"Starting Spotify PKCE login...\")\n    print(f\"Client ID: {client_id}\")\n    print(f\"Redirect URI: {redirect_uri}\")\n    print(\"Make sure this redirect URI is allow-listed in your Spotify app settings.\")\n    print()\n    print(\"Open this URL to authorize Clawbot:\")\n    print(authorize_url)\n    print()\n    print(f\"Full setup guide: {SPOTIFY_DOCS_URL}\")\n    print()\n\n    _print_loopback_ssh_hint(redirect_uri, docs_url=SPOTIFY_DOCS_URL)\n\n    if open_browser and not _is_remote_session():\n        try:\n            opened = webbrowser.open(authorize_url)\n        except Exception:\n            opened = False\n        if opened:\n            print(\"Browser opened for Spotify authorization.\")\n        else:\n            print(\"Could not open the browser automatically; use the URL above.\")\n\n    callback = _spotify_wait_for_callback(\n        redirect_uri,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 180.0),\n    )\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise SystemExit(f\"Spotify authorization failed: {detail}\")\n    if callback.get(\"state\") != state_nonce:\n        raise SystemExit(\"Spotify authorization failed: state mismatch.\")\n\n    token_payload = _spotify_exchange_code_for_tokens(\n        client_id=client_id,\n        code=str(callback.get(\"code\") or \"\"),\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        accounts_base_url=accounts_base_url,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 20.0),\n    )\n    spotify_state = _spotify_token_payload_to_state(\n        token_payload,\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        requested_scope=scope,\n        accounts_base_url=accounts_base_url,\n        api_base_url=api_base_url,\n    )\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _store_provider_state(auth_store, \"spotify\", spotify_state, set_active=False)\n        saved_to = _save_auth_store(auth_store)\n\n    print(\"Spotify login successful!\")\n    print(f\"  Auth state: {saved_to}\")\n    print(\"  Provider state saved under providers.spotify\")\n    print(f\"  Docs: {SPOTIFY_DOCS_URL}\")\n\n# =============================================================================\n# SSH / remote session detection\n# =============================================================================\n\ndef _is_remote_session() -> bool:\n    \"\"\"Detect if running in an SSH session where webbrowser.open() won't work.\"\"\"\n    return bool(os.getenv(\"SSH_CLIENT\") or os.getenv(\"SSH_TTY\"))\n\n\ndef _print_loopback_ssh_hint(redirect_uri: str, *, docs_url: str | None = None) -> None:\n    \"\"\"Print an SSH tunnel hint when running a loopback-redirect OAuth flow on a\n    remote host. The auth server (xAI, Spotify, ...) will redirect the user's\n    browser to ``127.0.0.1:<port>/callback``. If the browser is on a different\n    machine than the loopback listener (the usual SSH case), the redirect can't\n    reach the listener without a local port forward.\n\n    The hint is best-effort: silent if we don't think we're remote, or if we\n    can't parse a host/port out of the redirect URI.\n\n    Pass ``docs_url`` for a provider-specific guide (e.g. the xAI Grok OAuth\n    page); the generic OAuth-over-SSH guide is always shown after it.\n    \"\"\"\n    if not _is_remote_session():\n        return\n    try:\n        parsed = urlparse(redirect_uri)\n    except Exception:\n        return\n    host = parsed.hostname or \"\"\n    port = parsed.port\n    if host not in {\"127.0.0.1\", \"::1\", \"localhost\"} or not port:\n        return\n    print()\n    print(\"Remote session detected. Your browser will redirect to\")\n    print(f\"  {redirect_uri}\")\n    print(\"which the loopback listener on THIS machine is waiting on. If your\")\n    print(\"browser is on a different machine, forward the port first from your\")\n    print(\"local machine in a separate terminal:\")\n    print()\n    print(f\"  ssh -N -L {port}:127.0.0.1:{port} <user>@<this-host>\")\n    print()\n    print(\"Then open the authorize URL above in your local browser.\")\n    if docs_url:\n        print(f\"Provider docs:      {docs_url}\")\n    print(f\"SSH/jump-box guide: {OAUTH_OVER_SSH_DOCS_URL}\")\n    print()\n\n\n# =============================================================================\n# OpenAI Codex auth — tokens stored in ~/.clawbot/auth.json (not ~/.codex/)\n#\n# Clawbot maintains its own Codex OAuth session separate from the Codex CLI\n# and VS Code extension. This prevents refresh token rotation conflicts\n# where one app's refresh invalidates the other's session.\n# =============================================================================\n\ndef _read_codex_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    \"\"\"Read Codex OAuth tokens from Clawbot auth store (~/.clawbot/auth.json).\n    \n    Returns dict with 'tokens' (access_token, refresh_token) and 'last_refresh'.\n    Raises AuthError if no Codex tokens are stored.\n    \"\"\"\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"openai-codex\")\n    if not state:\n        raise AuthError(\n            \"No Codex credentials stored. Run `clawbot auth` to authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"Codex auth state is missing tokens. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = tokens.get(\"access_token\")\n    refresh_token = tokens.get(\"refresh_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        raise AuthError(\n            \"Codex auth is missing access_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n    }\n\n\ndef _save_codex_tokens(tokens: Dict[str, str], last_refresh: str = None) -> None:\n    \"\"\"Save Codex OAuth tokens to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"openai-codex\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"chatgpt\"\n        _save_provider_state(auth_store, \"openai-codex\", state)\n        _save_auth_store(auth_store)\n\n\ndef refresh_codex_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Codex OAuth tokens without mutating Clawbot auth state.\"\"\"\n    del access_token  # Access token is only used by callers to decide whether to refresh.\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            CODEX_OAUTH_TOKEN_URL,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": CODEX_OAUTH_CLIENT_ID,\n            },\n        )\n\n    if response.status_code != 200:\n        code = \"codex_refresh_failed\"\n        message = f\"Codex token refresh failed with status {response.status_code}.\"\n        relogin_required = False\n        try:\n            err = response.json()\n            if isinstance(err, dict):\n                err_obj = err.get(\"error\")\n                # OpenAI shape: {\"error\": {\"code\": \"...\", \"message\": \"...\", \"type\": \"...\"}}\n                if isinstance(err_obj, dict):\n                    nested_code = err_obj.get(\"code\") or err_obj.get(\"type\")\n                    if isinstance(nested_code, str) and nested_code.strip():\n                        code = nested_code.strip()\n                    nested_msg = err_obj.get(\"message\")\n                    if isinstance(nested_msg, str) and nested_msg.strip():\n                        message = f\"Codex token refresh failed: {nested_msg.strip()}\"\n                # OAuth spec shape: {\"error\": \"code_str\", \"error_description\": \"...\"}\n                elif isinstance(err_obj, str) and err_obj.strip():\n                    code = err_obj.strip()\n                    err_desc = err.get(\"error_description\") or err.get(\"message\")\n                    if isinstance(err_desc, str) and err_desc.strip():\n                        message = f\"Codex token refresh failed: {err_desc.strip()}\"\n        except Exception:\n            pass\n        if code in {\"invalid_grant\", \"invalid_token\", \"invalid_request\"}:\n            relogin_required = True\n        if code == \"refresh_token_reused\":\n            message = (\n                \"Codex refresh token was already consumed by another client \"\n                \"(e.g. Codex CLI or VS Code extension). \"\n                \"Run `codex` in your terminal to generate fresh tokens, \"\n                \"then run `clawbot auth` to re-authenticate.\"\n            )\n            relogin_required = True\n        # A 401/403 from the token endpoint always means the refresh token\n        # is invalid/expired — force relogin even if the body error code\n        # wasn't one of the known strings above.\n        if response.status_code in {401, 403} and not relogin_required:\n            relogin_required = True\n        raise AuthError(\n            message,\n            provider=\"openai-codex\",\n            code=code,\n            relogin_required=relogin_required,\n        )\n\n    try:\n        refresh_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            \"Codex token refresh returned invalid JSON.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_invalid_json\",\n            relogin_required=True,\n        ) from exc\n\n    refreshed_access = refresh_payload.get(\"access_token\")\n    if not isinstance(refreshed_access, str) or not refreshed_access.strip():\n        raise AuthError(\n            \"Codex token refresh response was missing access_token.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n\n    updated = {\n        \"access_token\": refreshed_access.strip(),\n        \"refresh_token\": refresh_token.strip(),\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    next_refresh = refresh_payload.get(\"refresh_token\")\n    if isinstance(next_refresh, str) and next_refresh.strip():\n        updated[\"refresh_token\"] = next_refresh.strip()\n    return updated\n\n\ndef _refresh_codex_auth_tokens(\n    tokens: Dict[str, str],\n    timeout_seconds: float,\n) -> Dict[str, str]:\n    \"\"\"Refresh Codex access token using the refresh token.\n    \n    Saves the new tokens to Clawbot auth store automatically.\n    \"\"\"\n    refreshed = refresh_codex_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n\n    _save_codex_tokens(updated_tokens)\n    return updated_tokens\n\n\ndef _import_codex_cli_tokens() -> Optional[Dict[str, str]]:\n    \"\"\"Try to read tokens from ~/.codex/auth.json (Codex CLI shared file).\n    \n    Returns tokens dict if valid and not expired, None otherwise.\n    Does NOT write to the shared file.\n    \"\"\"\n    codex_home = os.getenv(\"CODEX_HOME\", \"\").strip()\n    if not codex_home:\n        codex_home = str(Path.home() / \".codex\")\n    auth_path = Path(codex_home).expanduser() / \"auth.json\"\n    if not auth_path.is_file():\n        return None\n    try:\n        payload = json.loads(auth_path.read_text())\n        tokens = payload.get(\"tokens\")\n        if not isinstance(tokens, dict):\n            return None\n        access_token = tokens.get(\"access_token\")\n        refresh_token = tokens.get(\"refresh_token\")\n        if not access_token or not refresh_token:\n            return None\n        # Reject expired tokens — importing stale tokens from ~/.codex/\n        # that can't be refreshed leaves the user stuck with \"Login successful!\"\n        # but no working credentials.\n        if _codex_access_token_is_expiring(access_token, 0):\n            logger.debug(\n                \"Codex CLI tokens at %s are expired — skipping import.\", auth_path,\n            )\n            return None\n        return dict(tokens)\n    except Exception:\n        return None\n\n\ndef resolve_codex_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime credentials from Clawbot's own Codex token store.\"\"\"\n    data = _read_codex_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_CODEX_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        # Re-read under lock to avoid racing with other Clawbot processes\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_codex_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n\n            if should_refresh:\n                tokens = _refresh_codex_auth_tokens(tokens, refresh_timeout_seconds)\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"provider\": \"openai-codex\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"chatgpt\",\n    }\n\n\n# =============================================================================\n# xAI Grok OAuth — tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\ndef _read_xai_oauth_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"xai-oauth\")\n    if not state:\n        raise AuthError(\n            \"No xAI OAuth credentials stored. Select xAI Grok OAuth (SuperGrok Subscription) in `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"xAI OAuth state is missing tokens. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI OAuth state is missing access_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI OAuth state is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n        \"discovery\": state.get(\"discovery\") or {},\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n    }\n\n\ndef _save_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    discovery: Optional[Dict[str, Any]] = None,\n    redirect_uri: str = \"\",\n    last_refresh: Optional[str] = None,\n) -> None:\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"xai-oauth\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"oauth_pkce\"\n        if discovery:\n            state[\"discovery\"] = discovery\n        if redirect_uri:\n            state[\"redirect_uri\"] = redirect_uri\n        _save_provider_state(auth_store, \"xai-oauth\", state)\n        _save_auth_store(auth_store)\n\n\ndef _xai_access_token_is_expiring(access_token: str, skew_seconds: int = 0) -> bool:\n    if not isinstance(access_token, str) or \".\" not in access_token:\n        return False\n    try:\n        parts = access_token.split(\".\")\n        if len(parts) < 2:\n            return False\n        payload_b64 = parts[1]\n        payload_b64 += \"=\" * (-len(payload_b64) % 4)\n        payload = json.loads(base64.urlsafe_b64decode(payload_b64.encode(\"ascii\")).decode(\"utf-8\"))\n        exp = payload.get(\"exp\")\n        if not isinstance(exp, (int, float)):\n            return False\n        return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n    except Exception:\n        return False\n\n\ndef _xai_validate_oauth_endpoint(url: str, *, field: str) -> str:\n    \"\"\"Refuse any OIDC discovery endpoint that isn't HTTPS on the xAI origin.\n\n    The OIDC discovery response is a long-lived, low-frequency request whose\n    output is cached in ``~/.clawbot/auth.json``. A single MITM during initial\n    login could substitute a malicious ``token_endpoint``; that URL would\n    then receive the refresh_token on every subsequent refresh — a permanent\n    credential leak from a one-time MITM. Validating scheme + host pins the\n    cached endpoint to the xAI auth origin (or a future ``*.x.ai`` subdomain\n    if xAI migrates) so the cache poisoning loses its persistence guarantee.\n\n    RFC 8414 §2 requires the issuer to be ``https://`` and SHOULD-keeps the\n    token_endpoint on the same origin; we enforce both. ``x.ai`` is the\n    bare apex, so we accept either exact host match or any ``.x.ai`` suffix.\n    \"\"\"\n    parsed = urlparse(url)\n    if parsed.scheme != \"https\":\n        raise AuthError(\n            f\"xAI OIDC discovery returned a non-HTTPS {field}: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    host = (parsed.hostname or \"\").lower()\n    if not host:\n        raise AuthError(\n            f\"xAI OIDC discovery {field} is missing a hostname: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    if host != \"x.ai\" and not host.endswith(\".x.ai\"):\n        raise AuthError(\n            f\"xAI OIDC discovery {field} host {host!r} is not on the xAI origin \"\n            f\"(expected x.ai or a *.x.ai subdomain). Refusing to use a cached \"\n            f\"endpoint that may have been substituted by a MITM during initial \"\n            f\"discovery; re-authenticate with `clawbot model` to re-fetch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    return url\n\n\ndef _xai_oauth_discovery(timeout_seconds: float = 15.0) -> Dict[str, str]:\n    try:\n        response = httpx.get(\n            XAI_OAUTH_DISCOVERY_URL,\n            headers={\"Accept\": \"application/json\"},\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        ) from exc\n    if response.status_code != 200:\n        raise AuthError(\n            f\"xAI OIDC discovery returned status {response.status_code}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI OIDC discovery response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    authorization_endpoint = str(payload.get(\"authorization_endpoint\", \"\") or \"\").strip()\n    token_endpoint = str(payload.get(\"token_endpoint\", \"\") or \"\").strip()\n    if not authorization_endpoint or not token_endpoint:\n        raise AuthError(\n            \"xAI OIDC discovery response was missing required endpoints.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    _xai_validate_oauth_endpoint(authorization_endpoint, field=\"authorization_endpoint\")\n    _xai_validate_oauth_endpoint(token_endpoint, field=\"token_endpoint\")\n    return {\n        \"authorization_endpoint\": authorization_endpoint,\n        \"token_endpoint\": token_endpoint,\n    }\n\n\ndef refresh_xai_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    token_endpoint: str = \"\",\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    del access_token\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"xAI OAuth is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    endpoint = token_endpoint.strip() or _xai_oauth_discovery(timeout_seconds)[\"token_endpoint\"]\n    # Re-validate cached endpoints on the refresh hot path: an auth.json\n    # written by an older Clawbot (or hand-edited) may carry a non-xAI\n    # token_endpoint that would receive every future refresh_token in\n    # plaintext if we trusted it blindly. Cheap suffix check; fast-fail\n    # with a clear error so the user can re-run `clawbot model` to refetch.\n    _xai_validate_oauth_endpoint(endpoint, field=\"token_endpoint\")\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            endpoint,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": XAI_OAUTH_CLIENT_ID,\n                \"refresh_token\": refresh_token,\n            },\n        )\n    if response.status_code != 200:\n        detail = response.text.strip()\n        raise AuthError(\n            \"xAI token refresh failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_failed\",\n            relogin_required=(response.status_code in {400, 401, 403}),\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token refresh returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token refresh response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_response\",\n            relogin_required=True,\n        )\n    refreshed_access = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    if not refreshed_access:\n        raise AuthError(\n            \"xAI token refresh response was missing access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n    updated = {\n        \"access_token\": refreshed_access,\n        \"refresh_token\": str(payload.get(\"refresh_token\") or refresh_token).strip(),\n        \"id_token\": str(payload.get(\"id_token\") or \"\").strip(),\n        \"expires_in\": payload.get(\"expires_in\"),\n        \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    return updated\n\n\ndef _refresh_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    token_endpoint: str,\n    redirect_uri: str = \"\",\n    timeout_seconds: float,\n) -> Dict[str, Any]:\n    refreshed = refresh_xai_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        token_endpoint=token_endpoint,\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n    if refreshed.get(\"id_token\"):\n        updated_tokens[\"id_token\"] = refreshed[\"id_token\"]\n    if refreshed.get(\"expires_in\") is not None:\n        updated_tokens[\"expires_in\"] = refreshed[\"expires_in\"]\n    if refreshed.get(\"token_type\"):\n        updated_tokens[\"token_type\"] = refreshed[\"token_type\"]\n    _save_xai_oauth_tokens(\n        updated_tokens,\n        discovery={\"token_endpoint\": token_endpoint},\n        redirect_uri=redirect_uri,\n        last_refresh=refreshed[\"last_refresh\"],\n    )\n    return updated_tokens\n\n\ndef resolve_xai_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = XAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    data = _read_xai_oauth_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_XAI_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n    discovery = dict(data.get(\"discovery\") or {})\n    token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n    redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_xai_oauth_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n            discovery = dict(data.get(\"discovery\") or {})\n            token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n            redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n            if should_refresh:\n                if not token_endpoint:\n                    token_endpoint = _xai_oauth_discovery(refresh_timeout_seconds)[\"token_endpoint\"]\n                tokens = _refresh_xai_oauth_tokens(\n                    tokens,\n                    token_endpoint=token_endpoint,\n                    redirect_uri=redirect_uri,\n                    timeout_seconds=refresh_timeout_seconds,\n                )\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"provider\": \"xai-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"oauth_pkce\",\n    }\n\n\n# =============================================================================\n# TLS verification helper\n# =============================================================================\n\ndef _default_verify() -> bool | ssl.SSLContext:\n    \"\"\"Platform-aware default SSL verify for httpx clients.\n\n    On macOS with Homebrew Python, the system OpenSSL cannot locate the\n    system trust store and valid public certs fail verification. When\n    certifi is importable we pin its bundle explicitly; elsewhere we\n    defer to httpx's built-in default (certifi via its own dependency).\n    Mirrors the weixin fix in 3a0ec1d93.\n    \"\"\"\n    if sys.platform == \"darwin\":\n        try:\n            import certifi\n            return ssl.create_default_context(cafile=certifi.where())\n        except ImportError:\n            pass\n    return True\n\n\ndef _resolve_verify(\n    *,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    auth_state: Optional[Dict[str, Any]] = None,\n) -> bool | ssl.SSLContext:\n    tls_state = auth_state.get(\"tls\") if isinstance(auth_state, dict) else {}\n    tls_state = tls_state if isinstance(tls_state, dict) else {}\n\n    effective_insecure = (\n        is_truthy_value(insecure, default=False) if insecure is not None\n        else is_truthy_value(tls_state.get(\"insecure\", False), default=False)\n    )\n    effective_ca = (\n        ca_bundle\n        or tls_state.get(\"ca_bundle\")\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n        or os.getenv(\"REQUESTS_CA_BUNDLE\")\n    )\n\n    if effective_insecure:\n        return False\n    if effective_ca:\n        ca_path = str(effective_ca)\n        if not os.path.isfile(ca_path):\n            logger.warning(\n                \"CA bundle path does not exist: %s — falling back to default certificates\",\n                ca_path,\n            )\n            return _default_verify()\n        return ssl.create_default_context(cafile=ca_path)\n    return _default_verify()\n\n\n# =============================================================================\n# OAuth Device Code Flow — generic, parameterized by provider\n# =============================================================================\n\ndef _request_device_code(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: Optional[str],\n) -> Dict[str, Any]:\n    \"\"\"POST to the device code endpoint. Returns device_code, user_code, etc.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/device/code\",\n        data={\n            \"client_id\": client_id,\n            **({\"scope\": scope} if scope else {}),\n        },\n    )\n    response.raise_for_status()\n    data = response.json()\n\n    required_fields = [\n        \"device_code\", \"user_code\", \"verification_uri\",\n        \"verification_uri_complete\", \"expires_in\", \"interval\",\n    ]\n    missing = [f for f in required_fields if f not in data]\n    if missing:\n        raise ValueError(f\"Device code response missing fields: {', '.join(missing)}\")\n    return data\n\n\ndef _is_soam_invoke_scope_refusal(exc: Exception) -> bool:\n    if not isinstance(exc, httpx.HTTPStatusError):\n        return False\n    response = exc.response\n    if response.status_code not in {400, 401, 403}:\n        return False\n    try:\n        payload = response.json()\n    except Exception:\n        payload = {}\n    text = \" \".join(\n        str(value)\n        for value in (\n            payload.get(\"error\") if isinstance(payload, dict) else None,\n            payload.get(\"error_description\") if isinstance(payload, dict) else None,\n            response.text,\n        )\n        if value\n    ).lower()\n    if not text:\n        return False\n    return (\n        \"invalid_scope\" in text\n        or \"unsupported_scope\" in text\n        or \"scope\" in text and SOAM_INFERENCE_INVOKE_SCOPE in text\n    )\n\n\ndef _soam_device_scope_with_env_override(\n    requested_scope: Optional[str],\n    *,\n    default_scope: str = DEFAULT_SOAM_SCOPE,\n) -> Tuple[str, bool]:\n    explicit_scope = requested_scope is not None\n    scope = requested_scope or default_scope\n    if _soam_legacy_session_keys_forced():\n        scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n    return scope, explicit_scope\n\n\ndef _request_soam_device_code_with_scope_fallback(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: str,\n    allow_legacy_fallback: bool,\n) -> Tuple[Dict[str, Any], str]:\n    try:\n        return (\n            _request_device_code(\n                client=client,\n                portal_base_url=portal_base_url,\n                client_id=client_id,\n                scope=scope,\n            ),\n            scope,\n        )\n    except Exception as exc:\n        if (\n            allow_legacy_fallback\n            and _soam_scope_has_invoke(scope)\n            and _is_soam_invoke_scope_refusal(exc)\n        ):\n            logger.info(\"Soam inference auth: NAS refused invoke scope, retrying legacy scope\")\n            _oauth_trace(\"soam_device_code_invoke_scope_refused\")\n            retry_scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n            return (\n                _request_device_code(\n                    client=client,\n                    portal_base_url=portal_base_url,\n                    client_id=client_id,\n                    scope=retry_scope,\n                ),\n                retry_scope,\n            )\n        raise\n\n\ndef _poll_for_token(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    device_code: str,\n    expires_in: int,\n    poll_interval: int,\n) -> Dict[str, Any]:\n    \"\"\"Poll the token endpoint until the user approves or the code expires.\"\"\"\n    deadline = time.monotonic() + max(1, expires_in)\n    current_interval = max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n\n    while time.monotonic() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/api/oauth/token\",\n            data={\n                \"grant_type\": \"urn:ietf:params:oauth:grant-type:device_code\",\n                \"client_id\": client_id,\n                \"device_code\": device_code,\n            },\n        )\n\n        if response.status_code == 200:\n            payload = response.json()\n            if \"access_token\" not in payload:\n                raise ValueError(\"Token response did not include access_token\")\n            return payload\n\n        try:\n            error_payload = response.json()\n        except Exception:\n            response.raise_for_status()\n            raise RuntimeError(\"Token endpoint returned a non-JSON error response\")\n\n        error_code = error_payload.get(\"error\", \"\")\n        if error_code == \"authorization_pending\":\n            time.sleep(current_interval)\n            continue\n        if error_code == \"slow_down\":\n            current_interval = min(current_interval + 1, 30)\n            time.sleep(current_interval)\n            continue\n\n        description = error_payload.get(\"error_description\") or \"Unknown authentication error\"\n        raise RuntimeError(f\"{error_code}: {description}\")\n\n    raise TimeoutError(\"Timed out waiting for device authorization\")\n\n\n# =============================================================================\n# Soam Portal — token refresh, agent key minting, model discovery\n# =============================================================================\n\n# -----------------------------------------------------------------------------\n# Shared Soam token store — lets OAuth credentials persist across profiles\n# so a new `clawbot --profile <name> auth add soam --type oauth` can one-tap\n# import instead of running the full device-code flow every time.\n#\n# File lives at ${CLAWBOT_SHARED_AUTH_DIR}/soam_auth.json, defaulting to\n# ``<clawbot-root>/shared/soam_auth.json`` where ``<clawbot-root>`` is what\n# ``get_default_clawbot_root()`` returns — ``~/.clawbot`` on Linux/macOS,\n# ``%LOCALAPPDATA%\\clawbot`` on native Windows, or the Docker/custom root.\n# It is OUTSIDE any named profile's CLAWBOT_HOME so named profiles (which\n# typically live under ``<clawbot-root>/profiles/<name>/``) all see the\n# same file.\n#\n# Written on successful login and on every runtime refresh so the stored\n# refresh_token stays current even if one profile refreshes and rotates it.\n# If ever the stored refresh_token does go stale server-side, import fails\n# gracefully and the user falls back to the normal device-code flow.\n# -----------------------------------------------------------------------------\n\nSOAM_SHARED_STORE_FILENAME = \"soam_auth.json\"\n_soam_shared_lock_holder = threading.local()\n\n\ndef _soam_shared_auth_dir() -> Path:\n    \"\"\"Resolve the directory that holds the shared Soam token store.\n\n    Honors ``CLAWBOT_SHARED_AUTH_DIR`` so tests can redirect it to a tmp\n    path without touching the real user's home. Defaults to\n    ``<clawbot-root>/shared/``, where ``<clawbot-root>`` is what\n    :func:`clawbot_constants.get_default_clawbot_root` returns — so\n    Linux/macOS classic installs land at ``~/.clawbot/shared/``, native\n    Windows installs at ``%LOCALAPPDATA%\\\\clawbot\\\\shared\\\\``, and\n    Docker / custom ``CLAWBOT_HOME`` deployments at\n    ``<CLAWBOT_HOME>/shared/``. Sits outside any named profile so all\n    profiles under the same root share the store.\n    \"\"\"\n    override = os.getenv(\"CLAWBOT_SHARED_AUTH_DIR\", \"\").strip()\n    if override:\n        return Path(override).expanduser()\n    from clawbot_constants import get_default_clawbot_root\n    return get_default_clawbot_root() / \"shared\"\n\n\ndef _soam_shared_store_path() -> Path:\n    path = _soam_shared_auth_dir() / SOAM_SHARED_STORE_FILENAME\n    # Seat belt: if pytest is running and this resolves to a path under the\n    # real user's Clawbot root, refuse rather than silently corrupt cross-profile\n    # state. Tests must set CLAWBOT_SHARED_AUTH_DIR to a tmp_path (conftest\n    # does not do this automatically — mirror the _auth_file_path() guard\n    # so forgetting to set it fails loudly instead of writing to the real\n    # shared store).\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        from clawbot_constants import get_default_clawbot_root\n        real_home_shared = (\n            get_default_clawbot_root() / \"shared\" / SOAM_SHARED_STORE_FILENAME\n        ).resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_shared:\n            raise RuntimeError(\n                f\"Refusing to touch real user shared Soam auth store during test run: \"\n                f\"{path}. Set CLAWBOT_SHARED_AUTH_DIR to a tmp_path in your test fixture.\"\n            )\n    return path\n\n\n@contextmanager\ndef _soam_shared_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-profile lock for the shared Soam OAuth store.\n\n    Lock ordering invariant: if both this and ``_auth_store_lock`` need\n    to be held, acquire ``_auth_store_lock`` FIRST. All runtime refresh\n    paths follow this order. The one exception is\n    ``_try_import_shared_soam_state``, which holds this lock alone for\n    the entire refresh+mint cycle so concurrent imports on sibling\n    profiles can't race on the single-use shared refresh token; that\n    helper must NOT be called with ``_auth_store_lock`` already held.\n    \"\"\"\n    try:\n        lock_path = _soam_shared_store_path().with_suffix(\".lock\")\n    except RuntimeError:\n        # No CLAWBOT_HOME yet (pre-setup): fall through without locking.\n        yield\n        return\n\n    with _file_lock(\n        lock_path,\n        _soam_shared_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for shared Soam auth lock\",\n    ):\n        yield\n\n\ndef _merge_shared_soam_oauth_state(state: Dict[str, Any]) -> bool:\n    \"\"\"Copy fresher shared OAuth tokens into a profile-local Soam state.\"\"\"\n    shared = _read_shared_soam_state()\n    if not shared:\n        return False\n\n    shared_refresh = shared.get(\"refresh_token\")\n    if not isinstance(shared_refresh, str) or not shared_refresh.strip():\n        return False\n\n    local_refresh = state.get(\"refresh_token\")\n    shared_access_exp = _parse_iso_timestamp(shared.get(\"expires_at\")) or 0.0\n    local_access_exp = _parse_iso_timestamp(state.get(\"expires_at\")) or 0.0\n    refresh_changed = shared_refresh.strip() != str(local_refresh or \"\").strip()\n    fresher_access = shared_access_exp > local_access_exp\n    if not refresh_changed and not fresher_access:\n        return False\n\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"token_type\",\n        \"scope\",\n        \"client_id\",\n        \"portal_base_url\",\n        \"inference_base_url\",\n        \"obtained_at\",\n        \"expires_at\",\n    ):\n        value = shared.get(key)\n        if value not in {None, \"\"}:\n            state[key] = value\n    return True\n\n\ndef _write_shared_soam_state(state: Dict[str, Any]) -> None:\n    \"\"\"Persist a minimal copy of the Soam OAuth state to the shared store.\n\n    Best-effort: any failure is swallowed after logging. The shared store\n    is a convenience layer; the per-profile auth.json remains the source\n    of truth.\n\n    We deliberately omit the runtime ``agent_key`` compatibility field\n    (either an invoke JWT or legacy opaque session key) — only OAuth tokens\n    are cross-profile useful.\n    \"\"\"\n    refresh_token = state.get(\"refresh_token\")\n    access_token = state.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        # No refresh_token = nothing worth sharing across profiles\n        return\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return\n\n    shared = {\n        \"_schema\": 1,\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"token_type\": state.get(\"token_type\") or \"Bearer\",\n        \"scope\": state.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n        \"client_id\": state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": state.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n        \"inference_base_url\": state.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n        \"obtained_at\": state.get(\"obtained_at\"),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"updated_at\": datetime.now(timezone.utc).isoformat(),\n    }\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            path.parent.mkdir(parents=True, exist_ok=True)\n            try:\n                os.chmod(path.parent, 0o700)\n            except OSError:\n                pass\n            tmp = path.with_name(f\"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n            # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n            # window where write_text() + post-write chmod briefly exposed Soam\n            # refresh_token at process umask. See #19673, #21148.\n            fd = os.open(\n                str(tmp),\n                os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n                stat.S_IRUSR | stat.S_IWUSR,\n            )\n            try:\n                with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n                    fh.write(json.dumps(shared, indent=2, sort_keys=True))\n                    fh.flush()\n                    os.fsync(fh.fileno())\n                os.replace(tmp, path)\n            finally:\n                try:\n                    if tmp.exists():\n                        tmp.unlink()\n                except OSError:\n                    pass\n        _oauth_trace(\n            \"soam_shared_store_written\",\n            path=str(path),\n            refresh_token_fp=_token_fingerprint(refresh_token),\n        )\n    except Exception as exc:\n        logger.debug(\"Failed to write shared Soam auth store: %s\", exc)\n\n\ndef _read_shared_soam_state() -> Optional[Dict[str, Any]]:\n    \"\"\"Return the shared Soam OAuth state if present and well-formed.\n\n    Returns ``None`` when the file is missing, unreadable, malformed, or\n    lacks required fields. Callers should treat ``None`` as \"no shared\n    credentials available — fall through to device-code\".\n    \"\"\"\n    try:\n        path = _soam_shared_store_path()\n    except RuntimeError:\n        # Test seat belt tripped — treat as missing\n        return None\n    if not path.is_file():\n        return None\n    try:\n        payload = json.loads(path.read_text())\n    except (OSError, ValueError) as exc:\n        logger.debug(\"Shared Soam auth store at %s is unreadable: %s\", path, exc)\n        return None\n    if not isinstance(payload, dict):\n        return None\n    refresh_token = payload.get(\"refresh_token\")\n    access_token = payload.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        return None\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return None\n    return payload\n\n\ndef _clear_shared_soam_state(reason: str) -> None:\n    \"\"\"Remove the shared Soam OAuth store after a terminal token failure.\"\"\"\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            try:\n                path.unlink()\n            except FileNotFoundError:\n                pass\n        _oauth_trace(\"soam_shared_store_cleared\", reason=reason)\n    except Exception as exc:\n        logger.debug(\"Failed to clear shared Soam auth store: %s\", exc)\n\n\ndef _is_terminal_soam_refresh_error(exc: Exception) -> bool:\n    \"\"\"True when retrying the same Soam refresh token cannot succeed.\"\"\"\n    return (\n        isinstance(exc, AuthError)\n        and exc.provider == \"soam\"\n        and exc.code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n        and bool(exc.relogin_required)\n    )\n\n\ndef _quarantine_soam_oauth_state(\n    state: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> None:\n    \"\"\"Keep routing metadata but remove dead OAuth material so it is not replayed.\"\"\"\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"expires_at\",\n        \"expires_in\",\n        \"obtained_at\",\n        \"agent_key\",\n        \"agent_key_id\",\n        \"agent_key_expires_at\",\n        \"agent_key_expires_in\",\n        \"agent_key_reused\",\n        \"agent_key_obtained_at\",\n    ):\n        state.pop(key, None)\n    state[\"last_auth_error\"] = {\n        \"provider\": \"soam\",\n        \"code\": error.code,\n        \"message\": str(error),\n        \"reason\": reason,\n        \"relogin_required\": True,\n        \"at\": datetime.now(timezone.utc).isoformat(),\n    }\n    _clear_shared_soam_state(reason)\n    invalidate_soam_auth_status_cache()\n\n\ndef _quarantine_soam_pool_entries(\n    auth_store: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> bool:\n    \"\"\"Remove singleton-seeded Soam pool entries that contain dead OAuth state.\"\"\"\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        return False\n    entries = pool.get(\"soam\")\n    if not isinstance(entries, list):\n        return False\n\n    retained = []\n    removed = False\n    singleton_sources = {SOAM_DEVICE_CODE_SOURCE, f\"manual:{SOAM_DEVICE_CODE_SOURCE}\"}\n    for entry in entries:\n        if isinstance(entry, dict) and entry.get(\"source\") in singleton_sources:\n            removed = True\n            continue\n        retained.append(entry)\n\n    if removed:\n        pool[\"soam\"] = retained\n        _oauth_trace(\n            \"soam_pool_device_code_quarantined\",\n            reason=reason,\n            error_code=error.code,\n        )\n    return removed\n\n\ndef _try_import_shared_soam_state(\n    *,\n    timeout_seconds: float = 15.0,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Optional[Dict[str, Any]]:\n    \"\"\"Attempt to rehydrate Soam OAuth state from the shared store.\n\n    Reads the shared file (if present), runs a forced refresh+mint using\n    the stored refresh_token to produce a fresh access_token + agent_key\n    scoped to this profile, and returns the full auth_state dict ready\n    for ``persist_soam_credentials()``.\n\n    Returns ``None`` when no shared state is available or the rehydrate\n    fails for any reason (expired refresh_token, portal unreachable,\n    etc.) — caller should then fall through to the normal device-code\n    flow.\n    \"\"\"\n    try:\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            shared = _read_shared_soam_state()\n            if not shared:\n                return None\n\n            # Build a full state dict so refresh_soam_oauth_from_state has every\n            # field it needs. force_refresh=True gets us a fresh access_token\n            # for this profile; fresh auth mode avoids stale cached legacy keys.\n            state: Dict[str, Any] = {\n                \"access_token\": shared.get(\"access_token\"),\n                \"refresh_token\": shared.get(\"refresh_token\"),\n                \"client_id\": shared.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n                \"portal_base_url\": shared.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n                \"inference_base_url\": shared.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n                \"token_type\": shared.get(\"token_type\") or \"Bearer\",\n                \"scope\": shared.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n                \"obtained_at\": shared.get(\"obtained_at\"),\n                \"expires_at\": shared.get(\"expires_at\"),\n                \"agent_key\": None,\n                \"agent_key_expires_at\": None,\n                \"tls\": {\"insecure\": False, \"ca_bundle\": None},\n            }\n\n            def _persist_shared_refresh(updated_state: Dict[str, Any], _reason: str) -> None:\n                _write_shared_soam_state(updated_state)\n\n            refreshed = refresh_soam_oauth_from_state(\n                state,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                timeout_seconds=timeout_seconds,\n                force_refresh=True,\n                inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n                on_state_update=_persist_shared_refresh,\n            )\n            _write_shared_soam_state(refreshed)\n    except AuthError as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n            error_code=getattr(exc, \"code\", None),\n        )\n        if _is_terminal_soam_refresh_error(exc):\n            _clear_shared_soam_state(\"shared_import_terminal_refresh_failure\")\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n    except Exception as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n        )\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n\n    return refreshed\n\n\ndef _refresh_access_token(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    refresh_token: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/token\",\n        headers={\"x-soam-refresh-token\": refresh_token},\n        data={\n            \"grant_type\": \"refresh_token\",\n            \"client_id\": client_id,\n        },\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"access_token\" not in payload:\n            raise AuthError(\"Refresh response missing access_token\",\n                            provider=\"soam\", code=\"invalid_token\", relogin_required=True)\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Refresh token exchange failed\",\n                        provider=\"soam\", relogin_required=True) from exc\n\n    code = str(error_payload.get(\"error\", \"invalid_grant\"))\n    description = str(error_payload.get(\"error_description\") or \"Refresh token exchange failed\")\n    relogin = code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n\n    # Detect the OAuth 2.1 \"refresh token reuse\" signal from the Soam portal\n    # server and surface an actionable message.  This fires when an external\n    # process (health-check script, monitoring tool, custom self-heal hook)\n    # called POST /api/oauth/token with Clawbot's refresh_token without\n    # persisting the rotated token back to auth.json — the server then\n    # retires the original RT, Clawbot's next refresh uses it, and the whole\n    # session chain gets revoked as a token-theft signal (#15099).\n    lowered = description.lower()\n    if code == \"refresh_token_reused\" or \"reuse\" in lowered or \"reuse detected\" in lowered:\n        description = (\n            \"Soam Portal detected refresh-token reuse and revoked this session.\\n\"\n            \"This usually means an external process (monitoring script, \"\n            \"custom self-heal hook, or another Clawbot install sharing \"\n            \"~/.clawbot/auth.json) called POST /api/oauth/token with Clawbot's \"\n            \"refresh token without persisting the rotated token back.\\n\"\n            \"Soam refresh tokens are single-use — only Clawbot may call the \"\n            \"refresh endpoint. For health checks, use `clawbot auth status` \"\n            \"instead.\\n\"\n            \"Re-authenticate with: clawbot auth add soam\"\n        )\n        relogin = True\n\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef _mint_agent_key(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    access_token: str,\n    min_ttl_seconds: int,\n) -> Dict[str, Any]:\n    \"\"\"Mint (or reuse) a short-lived inference API key.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/agent-key\",\n        headers={\"Authorization\": f\"Bearer {access_token}\"},\n        json={\"min_ttl_seconds\": max(60, int(min_ttl_seconds))},\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"api_key\" not in payload:\n            raise AuthError(\"Mint response missing api_key\",\n                            provider=\"soam\", code=\"server_error\")\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Agent key mint request failed\",\n                        provider=\"soam\", code=\"server_error\") from exc\n\n    code = str(error_payload.get(\"error\", \"server_error\"))\n    description = str(error_payload.get(\"error_description\") or \"Agent key mint request failed\")\n    relogin = code in {\"invalid_token\", \"invalid_grant\"}\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef fetch_soam_models(\n    *,\n    inference_base_url: str,\n    api_key: str,\n    timeout_seconds: float = 15.0,\n    verify: bool | str = True,\n) -> List[str]:\n    \"\"\"Fetch available model IDs from the Soam inference API.\"\"\"\n    timeout = httpx.Timeout(timeout_seconds)\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        response = client.get(\n            f\"{inference_base_url.rstrip('/')}/models\",\n            headers={\"Authorization\": f\"Bearer {api_key}\"},\n        )\n\n    if response.status_code != 200:\n        description = f\"/models request failed with status {response.status_code}\"\n        try:\n            err = response.json()\n            description = str(err.get(\"error_description\") or err.get(\"error\") or description)\n        except Exception as e:\n            logger.debug(\"Could not parse error response JSON: %s\", e)\n        raise AuthError(description, provider=\"soam\", code=\"models_fetch_failed\")\n\n    payload = response.json()\n    data = payload.get(\"data\")\n    if not isinstance(data, list):\n        return []\n\n    model_ids: List[str] = []\n    for item in data:\n        if not isinstance(item, dict):\n            continue\n        model_id = item.get(\"id\")\n        if isinstance(model_id, str) and model_id.strip():\n            mid = model_id.strip()\n            # Skip Clawbot models — they're not reliable for agentic tool-calling\n            if \"clawbot\" in mid.lower():\n                continue\n            model_ids.append(mid)\n\n    # Sort: prefer opus > pro > haiku/flash > sonnet (sonnet is cheap/fast,\n    # users who want the best model should see opus first).\n    def _model_priority(mid: str) -> tuple:\n        low = mid.lower()\n        if \"opus\" in low:\n            return (0, mid)\n        if \"pro\" in low and \"sonnet\" not in low:\n            return (1, mid)\n        if \"sonnet\" in low:\n            return (3, mid)\n        return (2, mid)\n\n    model_ids.sort(key=_model_priority)\n    return list(dict.fromkeys(model_ids))\n\n\ndef _agent_key_is_usable(state: Dict[str, Any], min_ttl_seconds: int) -> bool:\n    key = state.get(\"agent_key\")\n    if not isinstance(key, str) or not key.strip():\n        return False\n    if _decode_jwt_claims(key):\n        if _soam_legacy_session_keys_forced():\n            return False\n        return _soam_invoke_jwt_is_usable(\n            key,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"agent_key_expires_at\"),\n        )\n    return not _is_expiring(state.get(\"agent_key_expires_at\"), min_ttl_seconds)\n\n\ndef resolve_soam_access_token(\n    *,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    refresh_skew_seconds: int = ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> str:\n    \"\"\"Resolve a refresh-aware Soam Portal access token for managed tool gateways.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\n                \"Clawbot is not logged into Soam Portal.\",\n                provider=\"soam\",\n                relogin_required=True,\n            )\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            merged_shared = _merge_shared_soam_oauth_state(state)\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\n                    \"No access token found for Soam Portal login.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            if not _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds):\n                if merged_shared:\n                    _save_provider_state(auth_store, \"soam\", state)\n                    _save_auth_store(auth_store)\n                return access_token\n\n            if not isinstance(refresh_token, str) or not refresh_token:\n                raise AuthError(\n                    \"Session expired and no refresh token is available.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n            with httpx.Client(\n                timeout=timeout,\n                headers={\"Accept\": \"application/json\"},\n                verify=verify,\n            ) as client:\n                try:\n                    refreshed = _refresh_access_token(\n                        client=client,\n                        portal_base_url=portal_base_url,\n                        client_id=client_id,\n                        refresh_token=refresh_token,\n                    )\n                except AuthError as exc:\n                    if _is_terminal_soam_refresh_error(exc):\n                        _quarantine_soam_oauth_state(\n                            state,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _quarantine_soam_pool_entries(\n                            auth_store,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _save_provider_state(auth_store, \"soam\", state)\n                        _save_auth_store(auth_store)\n                    raise\n\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl,\n                tz=timezone.utc,\n            ).isoformat()\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n            _save_provider_state(auth_store, \"soam\", state)\n            _save_auth_store(auth_store)\n            _write_shared_soam_state(state)\n            return state[\"access_token\"]\n\n\ndef refresh_soam_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    client_id: str,\n    portal_base_url: str,\n    inference_base_url: str,\n    *,\n    token_type: str = \"Bearer\",\n    scope: str = DEFAULT_SOAM_SCOPE,\n    obtained_at: Optional[str] = None,\n    expires_at: Optional[str] = None,\n    agent_key: Optional[str] = None,\n    agent_key_expires_at: Optional[str] = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth state without mutating auth.json directly.\n\n    ``on_state_update`` is called after a successful access-token refresh and\n    before any subsequent agent-key mint. Callers that own persistent state can\n    use it to save the newly rotated refresh token before later work can fail.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    state: Dict[str, Any] = {\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"client_id\": client_id or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": (portal_base_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\"),\n        \"inference_base_url\": (inference_base_url or DEFAULT_SOAM_INFERENCE_URL).rstrip(\"/\"),\n        \"token_type\": token_type or \"Bearer\",\n        \"scope\": scope or DEFAULT_SOAM_SCOPE,\n        \"obtained_at\": obtained_at,\n        \"expires_at\": expires_at,\n        \"agent_key\": agent_key,\n        \"agent_key_expires_at\": agent_key_expires_at,\n        \"tls\": {\n            \"insecure\": bool(insecure),\n            \"ca_bundle\": ca_bundle,\n        },\n    }\n    verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n    timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        min_agent_key_ttl = max(60, int(min_key_ttl_seconds))\n        legacy_session_keys = _soam_legacy_session_keys_forced()\n        current_invoke_jwt_usable = (\n            not legacy_session_keys\n            and _soam_invoke_jwt_is_usable(\n                state.get(\"access_token\"),\n                scope=state.get(\"scope\"),\n                expires_at=state.get(\"expires_at\"),\n            )\n        )\n        if (\n            force_refresh\n            or (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            )\n        ):\n            refreshed = _refresh_access_token(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                client_id=state[\"client_id\"],\n                refresh_token=state[\"refresh_token\"],\n            )\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or state[\"refresh_token\"]\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n            if refreshed_url:\n                state[\"inference_base_url\"] = refreshed_url\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl, tz=timezone.utc\n            ).isoformat()\n            if on_state_update is not None:\n                on_state_update(dict(state), \"post_refresh_access_token\")\n\n        selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n            state,\n            min_key_ttl_seconds=min_agent_key_ttl,\n            inference_auth_mode=inference_auth_mode,\n        )\n        if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n            _select_soam_invoke_jwt(state)\n        elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT:\n            _log_soam_legacy_session_key_selected(\n                fallback_reason or \"legacy_session_key_required\",\n                access_token=state.get(\"access_token\"),\n            )\n            mint_payload = _mint_agent_key(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                access_token=state[\"access_token\"],\n                min_ttl_seconds=min_key_ttl_seconds,\n            )\n            now = datetime.now(timezone.utc)\n            state[\"agent_key\"] = mint_payload.get(\"api_key\")\n            state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n            state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n            state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n            state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n            state[\"agent_key_obtained_at\"] = now.isoformat()\n            minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n            if minted_url:\n                state[\"inference_base_url\"] = minted_url\n\n    return state\n\n\ndef refresh_soam_oauth_from_state(\n    state: Dict[str, Any],\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth from a state dict. Thin wrapper around refresh_soam_oauth_pure.\"\"\"\n    tls = state.get(\"tls\") or {}\n    return refresh_soam_oauth_pure(\n        state.get(\"access_token\", \"\"),\n        state.get(\"refresh_token\", \"\"),\n        state.get(\"client_id\", \"clawbot-cli\"),\n        state.get(\"portal_base_url\", DEFAULT_SOAM_PORTAL_URL),\n        state.get(\"inference_base_url\", DEFAULT_SOAM_INFERENCE_URL),\n        token_type=state.get(\"token_type\", \"Bearer\"),\n        scope=state.get(\"scope\", DEFAULT_SOAM_SCOPE),\n        obtained_at=state.get(\"obtained_at\"),\n        expires_at=state.get(\"expires_at\"),\n        agent_key=state.get(\"agent_key\"),\n        agent_key_expires_at=state.get(\"agent_key_expires_at\"),\n        min_key_ttl_seconds=min_key_ttl_seconds,\n        timeout_seconds=timeout_seconds,\n        insecure=tls.get(\"insecure\"),\n        ca_bundle=tls.get(\"ca_bundle\"),\n        force_refresh=force_refresh,\n        inference_auth_mode=inference_auth_mode,\n        on_state_update=on_state_update,\n    )\n\n\ndef persist_soam_credentials(\n    creds: Dict[str, Any],\n    *,\n    label: Optional[str] = None,\n):\n    \"\"\"Persist minted Soam OAuth credentials as the singleton provider state\n    and ensure the credential pool is in sync.\n\n    Soam credentials are read at runtime from two independent locations:\n\n    - ``providers.soam``: singleton state read by\n      ``resolve_soam_runtime_credentials()`` during 401 recovery and by\n      ``_seed_from_singletons()`` during pool load.\n    - ``credential_pool.soam``: used by the runtime ``pool.select()`` path.\n\n    Historically ``clawbot auth add soam`` wrote a ``manual:device_code`` pool\n    entry only, skipping ``providers.soam``.  When the 24h agent_key TTL\n    expired, the recovery path read the empty singleton state and raised\n    ``AuthError`` silently (``logger.debug`` at INFO level).\n\n    This helper writes ``providers.soam`` then calls ``load_pool(\"soam\")`` so\n    ``_seed_from_singletons`` materialises the canonical ``device_code`` pool\n    entry from the singleton.  Re-running login upserts the same entry in\n    place; the pool never accumulates duplicate device_code rows.\n\n    ``label`` is an optional user-chosen display name (from\n    ``clawbot auth add soam --label <name>``).  It gets embedded in the\n    singleton state so that ``_seed_from_singletons`` uses it as the pool\n    entry's label on every subsequent ``load_pool(\"soam\")`` instead of the\n    auto-derived token fingerprint.  When ``None``, the auto-derived label\n    via ``label_from_token`` is used (unchanged default behaviour).\n\n    Returns the upserted :class:`PooledCredential` entry (or ``None`` if\n    seeding somehow produced no match — shouldn't happen).\n    \"\"\"\n    from agent.credential_pool import load_pool\n\n    state = dict(creds)\n    if label and str(label).strip():\n        state[\"label\"] = str(label).strip()\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"soam\", state)\n        _save_auth_store(auth_store)\n\n    # Mirror to the shared store so a new profile can one-tap import\n    # these credentials via `clawbot auth add soam --type oauth`. Best-\n    # effort: any I/O failure is logged and swallowed (the per-profile\n    # auth.json is still the source of truth).\n    _write_shared_soam_state(state)\n\n    pool = load_pool(\"soam\")\n    return next(\n        (e for e in pool.entries() if e.source == SOAM_DEVICE_CODE_SOURCE),\n        None,\n    )\n\n\ndef _sync_soam_pool_from_auth_store() -> None:\n    \"\"\"Best-effort pool reseed after providers.soam changes; never fail login.\"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        load_pool(\"soam\")\n    except Exception as exc:\n        logger.debug(\"Failed to sync Soam credential pool from auth store: %s\", exc)\n\n\ndef resolve_soam_runtime_credentials(\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Dict[str, Any]:\n    \"\"\"\n    Resolve Soam inference credentials for runtime use.\n\n    Ensures access_token is valid (refreshes if needed) and a short-lived\n    inference key is present with minimum TTL (mints/reuses as needed).\n    Concurrent processes coordinate through the auth store file lock.\n\n    Returns dict with: provider, base_url, api_key, key_id, expires_at,\n    expires_in, source (\"invoke_jwt\", \"cache\", or \"portal\"), and auth_path.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    min_key_ttl_seconds = max(60, int(min_key_ttl_seconds))\n    sequence_id = uuid.uuid4().hex[:12]\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\"Clawbot is not logged into Soam Portal.\",\n                            provider=\"soam\", relogin_required=True)\n\n        persisted_state = dict(state)\n        state_persisted = False\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        inference_base_url = (\n            _optional_base_url(state.get(\"inference_base_url\"))\n            or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n            or DEFAULT_SOAM_INFERENCE_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n\n        def _persist_state(reason: str) -> None:\n            nonlocal persisted_state, state_persisted\n            # Skip writes where only derived TTL countdowns changed; this keeps\n            # the mtime-keyed Soam auth-status cache warm during read paths.\n            if (\n                _soam_effective_provider_state(state)\n                == _soam_effective_provider_state(persisted_state)\n            ):\n                _oauth_trace(\n                    \"soam_state_persist_skipped\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                )\n                return\n            try:\n                _save_provider_state(auth_store, \"soam\", state)\n                _save_auth_store(auth_store)\n            except Exception as exc:\n                _oauth_trace(\n                    \"soam_state_persist_failed\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                    error_type=type(exc).__name__,\n                )\n                raise\n            _oauth_trace(\n                \"soam_state_persisted\",\n                sequence_id=sequence_id,\n                reason=reason,\n                refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n                access_token_fp=_token_fingerprint(state.get(\"access_token\")),\n            )\n            persisted_state = dict(state)\n            state_persisted = True\n            # Mirror post-refresh state to the shared store so sibling\n            # profiles don't hold stale refresh_tokens after rotation.\n            # Best-effort — any failure is logged and swallowed inside\n            # _write_shared_soam_state.\n            _write_shared_soam_state(state)\n\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n        timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n        _oauth_trace(\n            \"soam_runtime_credentials_start\",\n            sequence_id=sequence_id,\n            inference_auth_mode=inference_auth_mode,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n        )\n\n        with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\"No access token found for Soam Portal login.\",\n                                provider=\"soam\", relogin_required=True)\n\n            # Step 1: refresh access token if expiring. If the access token\n            # is already a valid invoke JWT, trust its own exp claim even when\n            # older auth.json metadata has a stale/missing expires_at.\n            current_invoke_jwt_usable = (\n                not _soam_legacy_session_keys_forced()\n                and _soam_invoke_jwt_is_usable(\n                    access_token,\n                    scope=state.get(\"scope\"),\n                    expires_at=state.get(\"expires_at\"),\n                )\n            )\n            if (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            ):\n                with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                    if _merge_shared_soam_oauth_state(state):\n                        access_token = state.get(\"access_token\")\n                        refresh_token = state.get(\"refresh_token\")\n                        _persist_state(\"post_shared_merge_access_expiring\")\n\n                    if (\n                        _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                        and not _soam_invoke_jwt_is_usable(\n                            access_token,\n                            scope=state.get(\"scope\"),\n                            expires_at=state.get(\"expires_at\"),\n                        )\n                    ):\n                        if not isinstance(refresh_token, str) or not refresh_token:\n                            raise AuthError(\"Session expired and no refresh token is available.\",\n                                            provider=\"soam\", relogin_required=True)\n\n                        _oauth_trace(\n                            \"refresh_start\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        try:\n                            refreshed = _refresh_access_token(\n                                client=client, portal_base_url=portal_base_url,\n                                client_id=client_id, refresh_token=refresh_token,\n                            )\n                        except AuthError as exc:\n                            if _is_terminal_soam_refresh_error(exc):\n                                _quarantine_soam_oauth_state(\n                                    state,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _quarantine_soam_pool_entries(\n                                    auth_store,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _persist_state(\"terminal_runtime_access_refresh_failure\")\n                            raise\n                        now = datetime.now(timezone.utc)\n                        access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                        previous_refresh_token = refresh_token\n                        state[\"access_token\"] = refreshed[\"access_token\"]\n                        state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n                        state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                        state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                        refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                        if refreshed_url:\n                            inference_base_url = refreshed_url\n                        state[\"obtained_at\"] = now.isoformat()\n                        state[\"expires_in\"] = access_ttl\n                        state[\"expires_at\"] = datetime.fromtimestamp(\n                            now.timestamp() + access_ttl, tz=timezone.utc\n                        ).isoformat()\n                        access_token = state[\"access_token\"]\n                        refresh_token = state[\"refresh_token\"]\n                        _oauth_trace(\n                            \"refresh_success\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            previous_refresh_token_fp=_token_fingerprint(previous_refresh_token),\n                            new_refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        # Persist immediately so downstream mint failures cannot drop rotated refresh tokens.\n                        _persist_state(\"post_refresh_access_expiring\")\n\n            # Step 2: resolve the compatibility ``agent_key`` field. Preferred\n            # path stores the NAS invoke JWT there; legacy path mints/reuses\n            # the opaque session key.\n            used_cached_key = False\n            mint_payload: Optional[Dict[str, Any]] = None\n            selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n                state,\n                access_token=access_token,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                inference_auth_mode=inference_auth_mode,\n            )\n\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                _select_soam_invoke_jwt(\n                    state,\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n            elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE:\n                used_cached_key = True\n                logger.info(\"Soam inference auth: using cached agent_key\")\n                _oauth_trace(\"agent_key_reuse\", sequence_id=sequence_id)\n            else:\n                _log_soam_legacy_session_key_selected(\n                    fallback_reason or \"legacy_session_key_required\",\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n                try:\n                    _oauth_trace(\n                        \"mint_start\",\n                        sequence_id=sequence_id,\n                        access_token_fp=_token_fingerprint(access_token),\n                    )\n                    mint_payload = _mint_agent_key(\n                        client=client, portal_base_url=portal_base_url,\n                        access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                    )\n                except AuthError as exc:\n                    _oauth_trace(\n                        \"mint_error\",\n                        sequence_id=sequence_id,\n                        code=exc.code,\n                    )\n                    # Retry path: access token may be stale server-side despite local checks\n                    latest_refresh_token = state.get(\"refresh_token\")\n                    if (\n                        exc.code in {\"invalid_token\", \"invalid_grant\"}\n                        and isinstance(latest_refresh_token, str)\n                        and latest_refresh_token\n                    ):\n                        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                            if _merge_shared_soam_oauth_state(state):\n                                access_token = state.get(\"access_token\")\n                                latest_refresh_token = state.get(\"refresh_token\")\n                                _persist_state(\"post_shared_merge_mint_retry\")\n                            else:\n                                _oauth_trace(\n                                    \"refresh_start\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                )\n                                try:\n                                    refreshed = _refresh_access_token(\n                                        client=client, portal_base_url=portal_base_url,\n                                        client_id=client_id, refresh_token=latest_refresh_token,\n                                    )\n                                except AuthError as exc:\n                                    if _is_terminal_soam_refresh_error(exc):\n                                        _quarantine_soam_oauth_state(\n                                            state,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _quarantine_soam_pool_entries(\n                                            auth_store,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _persist_state(\"terminal_runtime_mint_retry_refresh_failure\")\n                                    raise\n                                now = datetime.now(timezone.utc)\n                                access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                                state[\"access_token\"] = refreshed[\"access_token\"]\n                                state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or latest_refresh_token\n                                state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                                state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                                refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                                if refreshed_url:\n                                    inference_base_url = refreshed_url\n                                state[\"obtained_at\"] = now.isoformat()\n                                state[\"expires_in\"] = access_ttl\n                                state[\"expires_at\"] = datetime.fromtimestamp(\n                                    now.timestamp() + access_ttl, tz=timezone.utc\n                                ).isoformat()\n                                access_token = state[\"access_token\"]\n                                refresh_token = state[\"refresh_token\"]\n                                _oauth_trace(\n                                    \"refresh_success\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    previous_refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                    new_refresh_token_fp=_token_fingerprint(refresh_token),\n                                )\n                                # Persist retry refresh immediately for crash safety and cross-process visibility.\n                                _persist_state(\"post_refresh_mint_retry\")\n\n                        retry_inference_auth_mode = (\n                            SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            else SOAM_INFERENCE_AUTH_MODE_FRESH\n                        )\n                        retry_auth_path, _ = _choose_soam_inference_auth_path(\n                            state,\n                            access_token=access_token,\n                            min_key_ttl_seconds=min_key_ttl_seconds,\n                            inference_auth_mode=retry_inference_auth_mode,\n                        )\n                        if retry_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                            mint_payload = None\n                            selected_auth_path = SOAM_AUTH_PATH_INVOKE_JWT\n                            _select_soam_invoke_jwt(\n                                state,\n                                access_token=access_token,\n                                sequence_id=sequence_id,\n                            )\n                        else:\n                            mint_payload = _mint_agent_key(\n                                client=client, portal_base_url=portal_base_url,\n                                access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                            )\n                    else:\n                        raise\n\n            if mint_payload is not None:\n                now = datetime.now(timezone.utc)\n                state[\"agent_key\"] = mint_payload.get(\"api_key\")\n                state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n                state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n                state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n                state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n                state[\"agent_key_obtained_at\"] = now.isoformat()\n                minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n                if minted_url:\n                    inference_base_url = minted_url\n                _oauth_trace(\n                    \"mint_success\",\n                    sequence_id=sequence_id,\n                    reused=bool(mint_payload.get(\"reused\", False)),\n                )\n\n            # Persist routing and TLS metadata for non-interactive refresh/mint\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"inference_base_url\"] = inference_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n\n        _persist_state(\"resolve_soam_runtime_credentials_final\")\n\n    if state_persisted:\n        _sync_soam_pool_from_auth_store()\n\n    api_key = state.get(\"agent_key\")\n    if not isinstance(api_key, str) or not api_key:\n        raise AuthError(\"Failed to resolve a Soam inference API key\",\n                        provider=\"soam\", code=\"server_error\")\n\n    expires_at = state.get(\"agent_key_expires_at\")\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"agent_key_expires_in\"))\n    )\n\n    return {\n        \"provider\": \"soam\",\n        \"base_url\": inference_base_url,\n        \"api_key\": api_key,\n        \"key_id\": state.get(\"agent_key_id\"),\n        \"expires_at\": expires_at,\n        \"expires_in\": expires_in,\n        \"source\": (\n            SOAM_AUTH_PATH_INVOKE_JWT\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT\n            else (\"cache\" if used_cached_key else \"portal\")\n        ),\n        \"auth_path\": selected_auth_path,\n    }\n\n\n# =============================================================================\n# Status helpers\n# =============================================================================\n\ndef _empty_soam_auth_status() -> Dict[str, Any]:\n    return {\n        \"logged_in\": False,\n        \"portal_base_url\": None,\n        \"inference_base_url\": None,\n        \"access_expires_at\": None,\n        \"agent_key_expires_at\": None,\n        \"has_refresh_token\": False,\n    }\n\n\ndef _snapshot_soam_pool_status() -> Dict[str, Any]:\n    \"\"\"Best-effort status from the credential pool.\n\n    This is a fallback only. The auth-store provider state is the runtime source\n    of truth because it is what ``resolve_soam_runtime_credentials()`` refreshes\n    and mints against.\n    \"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"soam\")\n        if not pool or not pool.has_credentials():\n            return _empty_soam_auth_status()\n\n        entries = list(pool.entries())\n        if not entries:\n            return _empty_soam_auth_status()\n\n        def _entry_sort_key(entry: Any) -> tuple[float, float, int]:\n            agent_exp = _parse_iso_timestamp(getattr(entry, \"agent_key_expires_at\", None)) or 0.0\n            access_exp = _parse_iso_timestamp(getattr(entry, \"expires_at\", None)) or 0.0\n            priority = int(getattr(entry, \"priority\", 0) or 0)\n            return (agent_exp, access_exp, -priority)\n\n        entry = max(entries, key=_entry_sort_key)\n        access_token = (\n            getattr(entry, \"access_token\", None)\n            or getattr(entry, \"runtime_api_key\", \"\")\n        )\n        if not access_token:\n            return _empty_soam_auth_status()\n\n        return {\n            \"logged_in\": True,\n            \"portal_base_url\": getattr(entry, \"portal_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"inference_base_url\": getattr(entry, \"inference_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"access_token\": access_token,\n            \"access_expires_at\": getattr(entry, \"expires_at\", None),\n            \"agent_key_expires_at\": getattr(entry, \"agent_key_expires_at\", None),\n            \"has_refresh_token\": bool(getattr(entry, \"refresh_token\", None)),\n            \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n        }\n    except Exception:\n        return _empty_soam_auth_status()\n\n\n# ── Process-level memo for get_soam_auth_status() ──\n# get_soam_auth_status() validates state by calling resolve_soam_runtime_credentials(),\n# which does a synchrosoam OAuth refresh POST to portal.aayushsoam.com. That can take\n# ~350ms even on the failure path, and read-only UI surfaces (`clawbot tools`, status panels,\n# subscription-feature checks) call it many times per render — `clawbot tools` → \"All Platforms\"\n# was firing the refresh ~31× during one menu paint, racking up >13s of HTTP and burning\n# single-use refresh tokens. Cache the snapshot for a few seconds, keyed on the auth.json\n# mtime so that `clawbot auth login/logout/add/remove` invalidate naturally on the next call.\n_SOAM_AUTH_STATUS_CACHE_TTL = 15.0  # seconds\n_soam_auth_status_cache: Optional[Tuple[float, Optional[float], Dict[str, Any]]] = None\n\n\ndef _auth_file_mtime() -> Optional[float]:\n    try:\n        return _auth_file_path().stat().st_mtime\n    except FileNotFoundError:\n        return None\n    except Exception:\n        return None\n\n\ndef invalidate_soam_auth_status_cache() -> None:\n    \"\"\"Clear the get_soam_auth_status() process-level memo.\n\n    Call this from any code path that mutates Soam auth state without going\n    through resolve_soam_runtime_credentials() (e.g. tests). Login/logout\n    flows touch auth.json, so the mtime check below invalidates them\n    automatically — explicit invalidation is the belt-and-braces option.\n    \"\"\"\n    global _soam_auth_status_cache\n    _soam_auth_status_cache = None\n\n\ndef get_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Soam auth.\n\n    Prefer the auth-store provider state, because that is the live source of\n    truth for refresh + mint operations. When provider state exists, validate it\n    by resolving runtime credentials so revoked refresh sessions do not show up\n    as a healthy login. If provider state is absent, fall back to the credential\n    pool for the just-logged-in / not-yet-promoted case.\n\n    The returned snapshot is memoised for ~15s keyed on the auth.json mtime,\n    so menu/status surfaces that ask repeatedly don't trigger one refresh POST\n    per call. Login/logout flows write to auth.json and therefore invalidate\n    the cache automatically; tests can also call\n    ``invalidate_soam_auth_status_cache()`` explicitly.\n    \"\"\"\n    global _soam_auth_status_cache\n    now = time.monotonic()\n    mtime = _auth_file_mtime()\n    cached = _soam_auth_status_cache\n    if cached is not None:\n        cached_at, cached_mtime, cached_status = cached\n        if (\n            cached_mtime == mtime\n            and (now - cached_at) < _SOAM_AUTH_STATUS_CACHE_TTL\n        ):\n            return dict(cached_status)\n\n    status = _compute_soam_auth_status()\n    _soam_auth_status_cache = (now, mtime, dict(status))\n    return status\n\n\ndef _compute_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Uncached implementation of get_soam_auth_status(). See that function.\"\"\"\n    state = get_provider_auth_state(\"soam\")\n    if state:\n        base_status = {\n            \"logged_in\": bool(state.get(\"access_token\")),\n            \"portal_base_url\": state.get(\"portal_base_url\"),\n            \"inference_base_url\": state.get(\"inference_base_url\"),\n            \"access_expires_at\": state.get(\"expires_at\"),\n            \"agent_key_expires_at\": state.get(\"agent_key_expires_at\"),\n            \"has_refresh_token\": bool(state.get(\"refresh_token\")),\n            \"access_token\": state.get(\"access_token\"),\n            \"source\": \"auth_store\",\n        }\n        try:\n            creds = resolve_soam_runtime_credentials(min_key_ttl_seconds=60)\n            refreshed_state = get_provider_auth_state(\"soam\") or state\n            base_status.update(\n                {\n                    \"logged_in\": True,\n                    \"portal_base_url\": refreshed_state.get(\"portal_base_url\") or base_status.get(\"portal_base_url\"),\n                    \"inference_base_url\": creds.get(\"base_url\")\n                    or refreshed_state.get(\"inference_base_url\")\n                    or base_status.get(\"inference_base_url\"),\n                    \"access_expires_at\": refreshed_state.get(\"expires_at\") or base_status.get(\"access_expires_at\"),\n                    \"agent_key_expires_at\": creds.get(\"expires_at\")\n                    or refreshed_state.get(\"agent_key_expires_at\")\n                    or base_status.get(\"agent_key_expires_at\"),\n                    \"has_refresh_token\": bool(refreshed_state.get(\"refresh_token\")),\n                    \"source\": f\"runtime:{creds.get('source', 'portal')}\",\n                    \"key_id\": creds.get(\"key_id\"),\n                }\n            )\n            return base_status\n        except AuthError as exc:\n            base_status.update({\n                \"logged_in\": False,\n                \"error\": str(exc),\n                \"relogin_required\": bool(getattr(exc, \"relogin_required\", False)),\n                \"error_code\": getattr(exc, \"code\", None),\n            })\n            return base_status\n\n    return _snapshot_soam_pool_status()\n\n\ndef get_codex_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Codex auth.\n    \n    Checks the credential pool first (where `clawbot auth` stores credentials),\n    then falls back to the legacy provider state.\n    \"\"\"\n    # Check credential pool first — this is where `clawbot auth` and\n    # `clawbot model` store device_code tokens.\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(\"openai-codex\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _codex_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"chatgpt\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    # Fall back to legacy provider state\n    try:\n        creds = resolve_codex_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_xai_oauth_auth_status() -> Dict[str, Any]:\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"xai-oauth\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _xai_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"oauth_pkce\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    try:\n        creds = resolve_xai_oauth_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_api_key_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for API-key providers (z.ai, Kimi, MiniMax).\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        return {\"configured\": False}\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"configured\": bool(api_key),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"key_source\": key_source,\n        \"base_url\": base_url,\n        \"logged_in\": bool(api_key),  # compat with OAuth status shape\n    }\n\n\ndef get_external_process_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for providers that run a local subprocess.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        return {\"configured\": False}\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    resolved_command = shutil.which(command) if command else None\n    return {\n        \"configured\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"command\": command,\n        \"args\": args,\n        \"resolved_command\": resolved_command,\n        \"base_url\": base_url,\n        \"logged_in\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n    }\n\n\ndef get_auth_status(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Generic auth status dispatcher.\"\"\"\n    target = provider_id or get_active_provider()\n    if target == \"spotify\":\n        return get_spotify_auth_status()\n    if target == \"soam\":\n        return get_soam_auth_status()\n    if target == \"openai-codex\":\n        return get_codex_auth_status()\n    if target == \"xai-oauth\":\n        return get_xai_oauth_auth_status()\n    if target == \"qwen-oauth\":\n        return get_qwen_auth_status()\n    if target == \"google-gemini-cli\":\n        return get_gemini_oauth_auth_status()\n    if target == \"minimax-oauth\":\n        return get_minimax_oauth_auth_status()\n    if target == \"copilot-acp\":\n        return get_external_process_provider_status(target)\n    # API-key providers\n    pconfig = PROVIDER_REGISTRY.get(target)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        return get_api_key_provider_status(target)\n    # AWS SDK providers (Bedrock) — check via boto3 credential chain\n    if pconfig and pconfig.auth_type == \"aws_sdk\":\n        try:\n            from agent.bedrock_adapter import has_aws_credentials\n            return {\"logged_in\": has_aws_credentials(), \"provider\": target}\n        except ImportError:\n            return {\"logged_in\": False, \"provider\": target, \"error\": \"boto3 not installed\"}\n    return {\"logged_in\": False}\n\n\ndef resolve_api_key_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve API key and base URL for an API-key provider.\n\n    Returns dict with: provider, api_key, base_url, source.\n    \"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an API-key provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    # No-auth LM Studio: substitute a placeholder so runtime / auxiliary_client\n    # see the local server as configured. doctor still reports unconfigured\n    # because get_api_key_provider_status uses the raw secret resolver.\n    if not api_key and provider_id == \"lmstudio\":\n        api_key = LMSTUDIO_NOAUTH_PLACEHOLDER\n        key_source = key_source or \"default\"\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif provider_id == \"zai\":\n        base_url = _resolve_zai_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url.rstrip(\"/\")\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": api_key,\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"source\": key_source or \"default\",\n    }\n\n\ndef resolve_external_process_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve runtime details for local subprocess-backed providers.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an external-process provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    resolved_command = shutil.which(command) if command else None\n    if not resolved_command and not base_url.startswith(\"acp+tcp://\"):\n        raise AuthError(\n            f\"Could not find the Copilot CLI command '{command}'. \"\n            \"Install GitHub Copilot CLI or set CLAWBOT_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH.\",\n            provider=provider_id,\n            code=\"missing_copilot_cli\",\n        )\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": \"copilot-acp\",\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"command\": resolved_command or command,\n        \"args\": args,\n        \"source\": \"process\",\n    }\n\n\n# =============================================================================\n# CLI Commands — login / logout\n# =============================================================================\n\ndef _update_config_for_provider(\n    provider_id: str,\n    inference_base_url: str,\n    default_model: Optional[str] = None,\n) -> Path:\n    \"\"\"Update config.yaml and auth.json to reflect the active provider.\n\n    When *default_model* is provided the function also writes it as the\n    ``model.default`` value.  This prevents a race condition where the\n    gateway (which re-reads config per-message) picks up the new provider\n    before the caller has finished model selection, resulting in a\n    mismatched model/provider (e.g. ``anthropic/claude-opus-4.6`` sent to\n    MiniMax's API).\n    \"\"\"\n    # Set active_provider in auth.json so auto-resolution picks this provider\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = provider_id\n        _save_auth_store(auth_store)\n\n    # Update config.yaml model section\n    config_path = get_config_path()\n    config_path.parent.mkdir(parents=True, exist_ok=True)\n\n    config = read_raw_config()\n\n    current_model = config.get(\"model\")\n    if isinstance(current_model, dict):\n        model_cfg = dict(current_model)\n    elif isinstance(current_model, str) and current_model.strip():\n        model_cfg = {\"default\": current_model.strip()}\n    else:\n        model_cfg = {}\n\n    model_cfg[\"provider\"] = provider_id\n    if inference_base_url and inference_base_url.strip():\n        model_cfg[\"base_url\"] = inference_base_url.rstrip(\"/\")\n    else:\n        # Clear stale base_url to prevent contamination when switching providers\n        model_cfg.pop(\"base_url\", None)\n\n    # Clear stale api_key/api_mode left over from a previous custom provider.\n    # When the user switches from e.g. a MiniMax custom endpoint\n    # (api_mode=anthropic_messages, api_key=mxp-...) to a built-in provider\n    # (e.g. OpenRouter), the stale api_key/api_mode would override the new\n    # provider's credentials and transport choice.  Built-in providers that\n    # need a specific api_mode (copilot, xai) set it at request-resolution\n    # time via `_copilot_runtime_api_mode` / `_detect_api_mode_for_url`, so\n    # removing the persisted value here is safe.\n    model_cfg.pop(\"api_key\", None)\n    model_cfg.pop(\"api_mode\", None)\n\n    # When switching to a non-OpenRouter provider, ensure model.default is\n    # valid for the new provider.  An OpenRouter-formatted name like\n    # \"anthropic/claude-opus-4.6\" will fail on direct-API providers.\n    if default_model:\n        cur_default = model_cfg.get(\"default\", \"\")\n        if not cur_default or \"/\" in cur_default:\n            model_cfg[\"default\"] = default_model\n\n    config[\"model\"] = model_cfg\n\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _get_config_provider() -> Optional[str]:\n    \"\"\"Return model.provider from config.yaml, normalized, if present.\"\"\"\n    try:\n        config = read_raw_config()\n    except Exception:\n        return None\n    if not config:\n        return None\n    model = config.get(\"model\")\n    if not isinstance(model, dict):\n        return None\n    provider = model.get(\"provider\")\n    if not isinstance(provider, str):\n        return None\n    provider = provider.strip().lower()\n    return provider or None\n\n\ndef _config_provider_matches(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when config.yaml currently selects *provider_id*.\"\"\"\n    if not provider_id:\n        return False\n    return _get_config_provider() == provider_id.strip().lower()\n\n\ndef _should_reset_config_provider_on_logout(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when logout should reset the model provider config.\"\"\"\n    if not provider_id:\n        return False\n    normalized = provider_id.strip().lower()\n    return normalized in PROVIDER_REGISTRY and _config_provider_matches(normalized)\n\n\ndef _logout_default_provider_from_config() -> Optional[str]:\n    \"\"\"Fallback logout target when auth.json has no active provider.\n\n    `clawbot logout` historically keyed off auth.json.active_provider only.\n    That left users stuck when auth state had already been cleared but\n    config.yaml still selected an OAuth provider such as openai-codex for the\n    agent model: there was no active auth provider to target, so logout printed\n    \"No provider is currently logged in\" and never reset model.provider.\n    \"\"\"\n    provider = _get_config_provider()\n    if provider in {\"soam\", \"openai-codex\", \"xai-oauth\"}:\n        return provider\n    return None\n\n\ndef _reset_config_provider() -> Path:\n    \"\"\"Reset config.yaml provider back to auto after logout.\"\"\"\n    config_path = get_config_path()\n    if not config_path.exists():\n        return config_path\n\n    config = read_raw_config()\n    if not config:\n        return config_path\n\n    model = config.get(\"model\")\n    if isinstance(model, dict):\n        model[\"provider\"] = \"auto\"\n        if \"base_url\" in model:\n            model[\"base_url\"] = OPENROUTER_BASE_URL\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _prompt_model_selection(\n    model_ids: List[str],\n    current_model: str = \"\",\n    pricing: Optional[Dict[str, Dict[str, str]]] = None,\n    unavailable_models: Optional[List[str]] = None,\n    portal_url: str = \"\",\n) -> Optional[str]:\n    \"\"\"Interactive model selection. Puts current_model first with a marker. Returns chosen model ID or None.\n\n    If *pricing* is provided (``{model_id: {prompt, completion}}``), a compact\n    price indicator is shown next to each model in aligned columns.\n\n    If *unavailable_models* is provided, those models are shown grayed out\n    and unselectable, with an upgrade link to *portal_url*.\n    \"\"\"\n    from clawbot_cli.models import _format_price_per_mtok\n\n    _unavailable = unavailable_models or []\n\n    # Reorder: current model first, then the rest (deduplicated)\n    ordered = []\n    if current_model and current_model in model_ids:\n        ordered.append(current_model)\n    for mid in model_ids:\n        if mid not in ordered:\n            ordered.append(mid)\n\n    # All models for column-width computation (selectable + unavailable)\n    all_models = list(ordered) + list(_unavailable)\n\n    # Column-aligned labels when pricing is available\n    has_pricing = bool(pricing and any(pricing.get(m) for m in all_models))\n    name_col = max((len(m) for m in all_models), default=0) + 2 if has_pricing else 0\n\n    # Pre-compute formatted prices and dynamic column widths\n    _price_cache: dict[str, tuple[str, str, str]] = {}\n    price_col = 3  # minimum width\n    cache_col = 0  # only set if any model has cache pricing\n    has_cache = False\n    if has_pricing:\n        for mid in all_models:\n            p = pricing.get(mid)  # type: ignore[union-attr]\n            if p:\n                inp = _format_price_per_mtok(p.get(\"prompt\", \"\"))\n                out = _format_price_per_mtok(p.get(\"completion\", \"\"))\n                cache_read = p.get(\"input_cache_read\", \"\")\n                cache = _format_price_per_mtok(cache_read) if cache_read else \"\"\n                if cache:\n                    has_cache = True\n            else:\n                inp, out, cache = \"\", \"\", \"\"\n            _price_cache[mid] = (inp, out, cache)\n            price_col = max(price_col, len(inp), len(out))\n            cache_col = max(cache_col, len(cache))\n        if has_cache:\n            cache_col = max(cache_col, 5)  # minimum: \"Cache\" header\n\n    def _label(mid):\n        if has_pricing:\n            inp, out, cache = _price_cache.get(mid, (\"\", \"\", \"\"))\n            price_part = f\" {inp:>{price_col}}  {out:>{price_col}}\"\n            if has_cache:\n                price_part += f\"  {cache:>{cache_col}}\"\n            base = f\"{mid:<{name_col}}{price_part}\"\n        else:\n            base = mid\n        if mid == current_model:\n            base += \"  ← currently in use\"\n        return base\n\n    # Default cursor on the current model (index 0 if it was reordered to top)\n    default_idx = 0\n\n    # Build a pricing header hint for the menu title\n    menu_title = \"Select default model:\"\n    if has_pricing:\n        # Align the header with the model column.\n        # Each choice is \"  {label}\" (2 spaces) and simple_term_menu prepends\n        # a 3-char cursor region (\"-> \" or \"   \"), so content starts at col 5.\n        pad = \" \" * 5\n        header = f\"\\n{pad}{'':>{name_col}} {'In':>{price_col}}  {'Out':>{price_col}}\"\n        if has_cache:\n            header += f\"  {'Cache':>{cache_col}}\"\n        menu_title += header + \"  /Mtok\"\n\n    # ANSI escape for dim text\n    _DIM = \"\\033[2m\"\n    _RESET = \"\\033[0m\"\n\n    # Try arrow-key menu first, fall back to number input\n    try:\n        from simple_term_menu import TerminalMenu\n\n        choices = [f\"  {_label(mid)}\" for mid in ordered]\n        choices.append(\"  Enter custom model name\")\n        choices.append(\"  Skip (keep current)\")\n\n        # Print the unavailable block BEFORE the menu via regular print().\n        # simple_term_menu pads title lines to terminal width (causes wrapping),\n        # so we keep the title minimal and use stdout for the static block.\n        # clear_screen=False means our printed output stays visible above.\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        if _unavailable:\n            print(menu_title)\n            print()\n            for mid in _unavailable:\n                print(f\"{_DIM}     {_label(mid)}{_RESET}\")\n            print()\n            print(f\"{_DIM}  ── Upgrade at {_upgrade_url} for paid models ──{_RESET}\")\n            print()\n            effective_title = \"Available free models:\"\n        else:\n            effective_title = menu_title\n\n        menu = TerminalMenu(\n            choices,\n            cursor_index=default_idx,\n            menu_cursor=\"-> \",\n            menu_cursor_style=(\"fg_green\", \"bold\"),\n            menu_highlight_style=(\"fg_green\",),\n            cycle_cursor=True,\n            clear_screen=False,\n            title=effective_title,\n        )\n        idx = menu.show()\n        from clawbot_cli.curses_ui import flush_stdin\n        flush_stdin()\n        if idx is None:\n            return None\n        print()\n        if idx < len(ordered):\n            return ordered[idx]\n        elif idx == len(ordered):\n            custom = input(\"Enter model name: \").strip()\n            return custom if custom else None\n        return None\n    except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError):\n        pass\n\n    # Fallback: numbered list\n    print(menu_title)\n    num_width = len(str(len(ordered) + 2))\n    for i, mid in enumerate(ordered, 1):\n        print(f\"  {i:>{num_width}}. {_label(mid)}\")\n    n = len(ordered)\n    print(f\"  {n + 1:>{num_width}}. Enter custom model name\")\n    print(f\"  {n + 2:>{num_width}}. Skip (keep current)\")\n\n    if _unavailable:\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        print()\n        print(f\"  {_DIM}── Unavailable models (requires paid tier — upgrade at {_upgrade_url}) ──{_RESET}\")\n        for mid in _unavailable:\n            print(f\"  {'':>{num_width}}  {_DIM}{_label(mid)}{_RESET}\")\n    print()\n\n    while True:\n        try:\n            choice = input(f\"Choice [1-{n + 2}] (default: skip): \").strip()\n            if not choice:\n                return None\n            idx = int(choice)\n            if 1 <= idx <= n:\n                return ordered[idx - 1]\n            elif idx == n + 1:\n                custom = input(\"Enter model name: \").strip()\n                return custom if custom else None\n            elif idx == n + 2:\n                return None\n            print(f\"Please enter 1-{n + 2}\")\n        except ValueError:\n            print(\"Please enter a number\")\n        except (KeyboardInterrupt, EOFError):\n            return None\n\n\ndef _save_model_choice(model_id: str) -> None:\n    \"\"\"Save the selected model to config.yaml (single source of truth).\n\n    The model is stored in config.yaml only — NOT in .env.  This avoids\n    conflicts in multi-agent setups where env vars would stomp each other.\n    \"\"\"\n    from clawbot_cli.config import save_config, load_config\n\n    config = load_config()\n    # Always use dict format so provider/base_url can be stored alongside\n    if isinstance(config.get(\"model\"), dict):\n        config[\"model\"][\"default\"] = model_id\n    else:\n        config[\"model\"] = {\"default\": model_id}\n    save_config(config)\n\n\ndef login_command(args) -> None:\n    \"\"\"Deprecated: use 'clawbot model' or 'clawbot setup' instead.\"\"\"\n    print(\"The 'clawbot login' command has been removed.\")\n    print(\"Use 'clawbot auth' to manage credentials,\")\n    print(\"'clawbot model' to select a provider, or 'clawbot setup' for full setup.\")\n    raise SystemExit(0)\n\n\ndef _login_openai_codex(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    \"\"\"OpenAI Codex login via device code flow. Tokens stored in ~/.clawbot/auth.json.\"\"\"\n\n    del args, pconfig  # kept for parity with other provider login helpers\n\n    # Check for existing Clawbot-owned credentials\n    if not force_new_login:\n        try:\n            existing = resolve_codex_runtime_credentials()\n            # Verify the resolved token is actually usable (not expired).\n            # resolve_codex_runtime_credentials attempts refresh, so if we get\n            # here the token should be valid — but double-check before telling\n            # the user \"Login successful!\".\n            _resolved_key = existing.get(\"api_key\", \"\")\n            if isinstance(_resolved_key, str) and _resolved_key and not _codex_access_token_is_expiring(_resolved_key, 60):\n                print(\"Existing Codex credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\"openai-codex\", existing.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                    return\n            else:\n                print(\"Existing Codex credentials are expired. Starting fresh login...\")\n        except AuthError:\n            pass\n\n    # Check for existing Codex CLI tokens we can import\n    if not force_new_login:\n        cli_tokens = _import_codex_cli_tokens()\n        if cli_tokens:\n            print(\"Found existing Codex CLI credentials at ~/.codex/auth.json\")\n            print(\"Clawbot will create its own session to avoid conflicts with Codex CLI / VS Code.\")\n            try:\n                do_import = input(\"Import these credentials? (a separate login is recommended) [y/N]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"n\"\n            if do_import in {\"y\", \"yes\"}:\n                _save_codex_tokens(cli_tokens)\n                base_url = os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_CODEX_BASE_URL\n                config_path = _update_config_for_provider(\"openai-codex\", base_url)\n                print()\n                print(\"Credentials imported. Note: if Codex CLI refreshes its token,\")\n                print(\"Clawbot will keep working independently with its own session.\")\n                print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                return\n\n    # Run a fresh device code flow — Clawbot gets its own OAuth session\n    print()\n    print(\"Signing in to OpenAI Codex...\")\n    print(\"(Clawbot creates its own session — won't affect Codex CLI or VS Code)\")\n    print()\n\n    creds = _codex_device_code_login()\n\n    # Save tokens to Clawbot auth store\n    _save_codex_tokens(creds[\"tokens\"], creds.get(\"last_refresh\"))\n    config_path = _update_config_for_provider(\"openai-codex\", creds.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n\n\ndef _login_xai_oauth(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    del pconfig\n\n    if not force_new_login:\n        try:\n            existing = resolve_xai_oauth_runtime_credentials()\n            api_key = existing.get(\"api_key\", \"\")\n            if isinstance(api_key, str) and api_key and not _xai_access_token_is_expiring(api_key, 60):\n                print(\"Existing xAI OAuth credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\n                        \"xai-oauth\",\n                        existing.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL),\n                    )\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n                    return\n        except AuthError:\n            pass\n\n    print()\n    print(\"Signing in to xAI Grok OAuth (SuperGrok Subscription)...\")\n    print(\"(Clawbot creates its own local OAuth session)\")\n    print()\n\n    timeout_seconds = float(getattr(args, \"timeout\", None) or 20.0)\n    open_browser = not getattr(args, \"no_browser\", False)\n    if _is_remote_session():\n        open_browser = False\n\n    creds = _xai_oauth_loopback_login(timeout_seconds=timeout_seconds, open_browser=open_browser)\n    _save_xai_oauth_tokens(\n        creds[\"tokens\"],\n        discovery=creds.get(\"discovery\"),\n        redirect_uri=creds.get(\"redirect_uri\", \"\"),\n        last_refresh=creds.get(\"last_refresh\"),\n    )\n    config_path = _update_config_for_provider(\"xai-oauth\", creds.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n\n\ndef _xai_oauth_build_authorize_url(\n    *,\n    authorization_endpoint: str,\n    redirect_uri: str,\n    code_challenge: str,\n    state: str,\n    nonce: str,\n) -> str:\n    # `plan=generic` opts the consent screen into xAI's generic OAuth plan\n    # tier instead of falling back to the per-account default. Without it,\n    # accounts.x.ai rejects loopback OAuth from non-allowlisted clients.\n    # `referrer=clawbot-agent` lets xAI attribute Clawbot-originated logins\n    # in their OAuth server logs (we still impersonate the upstream Grok-CLI\n    # client_id; this is best-effort attribution until xAI mints us our own).\n    authorize_params = {\n        \"response_type\": \"code\",\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"redirect_uri\": redirect_uri,\n        \"scope\": XAI_OAUTH_SCOPE,\n        \"code_challenge\": code_challenge,\n        \"code_challenge_method\": \"S256\",\n        \"state\": state,\n        \"nonce\": nonce,\n        \"plan\": \"generic\",\n        \"referrer\": \"clawbot-agent\",\n    }\n    return f\"{authorization_endpoint}?{urlencode(authorize_params)}\"\n\n\ndef _xai_oauth_exchange_code_for_tokens(\n    *,\n    token_endpoint: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    code_challenge: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"POST the authorization code to xAI's token endpoint and return\n    the parsed JSON payload.\n\n    Sends ``code_verifier`` as required by RFC 7636 §4.5.  Also echoes\n    ``code_challenge`` + ``code_challenge_method`` in the request body\n    as a defense-in-depth measure for OAuth servers (xAI's among them,\n    per #26990) that re-validate the challenge at the token step\n    instead of relying solely on server-side session state captured\n    during the authorize step.  Echoing the challenge is harmless for\n    strict RFC-compliant servers — RFC 7636 doesn't forbid additional\n    parameters at the token endpoint — and decisively fixes the\n    ``code_challenge is required`` failure mode users hit on the\n    loopback flow.\n\n    Raises :class:`AuthError` on any non-2xx response or transport\n    failure; the error message embeds the HTTP status code and the\n    full response body so users can disambiguate cause at a glance.\n    \"\"\"\n    # Paranoia: if upstream call sites ever drop ``code_verifier`` we\n    # want to surface a precise, local error rather than send a\n    # missing-PKCE request to xAI and receive their generic \"code\n    # challenge required\" message back.\n    if not code_verifier:\n        raise AuthError(\n            \"xAI token exchange refused locally: PKCE code_verifier is empty. \"\n            \"This is a bug in Clawbot — please report at \"\n            \"https://github.com/aayushsoam/clawbot-agent/issues/26990.\",\n            provider=\"xai-oauth\",\n            code=\"xai_pkce_verifier_missing\",\n        )\n\n    data = {\n        \"grant_type\": \"authorization_code\",\n        \"code\": code,\n        \"redirect_uri\": redirect_uri,\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"code_verifier\": code_verifier,\n    }\n    # Defense-in-depth: include the original ``code_challenge`` and\n    # ``code_challenge_method``.  Some OAuth servers (including xAI's\n    # auth.x.ai implementation, per the symptom reported in #26990)\n    # validate these at the token endpoint instead of relying purely on\n    # state captured during the authorize step — without them, xAI\n    # rejects the exchange with ``code_challenge is required`` even\n    # though we sent a valid ``code_verifier``.\n    if code_challenge:\n        data[\"code_challenge\"] = code_challenge\n        data[\"code_challenge_method\"] = \"S256\"\n\n    try:\n        response = httpx.post(\n            token_endpoint,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data=data,\n            timeout=max(20.0, timeout_seconds),\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code != 200:\n        body = response.text.strip()\n        raise AuthError(\n            f\"xAI token exchange failed (HTTP {response.status_code}).\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token exchange response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _xai_oauth_loopback_login(\n    *,\n    timeout_seconds: float = 20.0,\n    open_browser: bool = True,\n) -> Dict[str, Any]:\n    discovery = _xai_oauth_discovery(timeout_seconds)\n    authorization_endpoint = discovery[\"authorization_endpoint\"]\n    token_endpoint = discovery[\"token_endpoint\"]\n\n    server, thread, callback_result, redirect_uri = _xai_start_callback_server()\n    try:\n        _xai_validate_loopback_redirect_uri(redirect_uri)\n        code_verifier = _oauth_pkce_code_verifier()\n        code_challenge = _oauth_pkce_code_challenge(code_verifier)\n        state = uuid.uuid4().hex\n        nonce = uuid.uuid4().hex\n        authorize_url = _xai_oauth_build_authorize_url(\n            authorization_endpoint=authorization_endpoint,\n            redirect_uri=redirect_uri,\n            code_challenge=code_challenge,\n            state=state,\n            nonce=nonce,\n        )\n\n        print(\"Open this URL to authorize Clawbot with xAI:\")\n        print(authorize_url)\n        print()\n        print(f\"Waiting for callback on {redirect_uri}\")\n\n        _print_loopback_ssh_hint(redirect_uri, docs_url=XAI_OAUTH_DOCS_URL)\n\n        if open_browser and not _is_remote_session():\n            try:\n                opened = webbrowser.open(authorize_url)\n            except Exception:\n                opened = False\n            if opened:\n                print(\"Browser opened for xAI authorization.\")\n            else:\n                print(\"Could not open the browser automatically; use the URL above.\")\n\n        callback = _xai_wait_for_callback(\n            server,\n            thread,\n            callback_result,\n            timeout_seconds=max(30.0, timeout_seconds * 9),\n        )\n    except Exception:\n        try:\n            server.shutdown()\n            server.server_close()\n        except Exception:\n            pass\n        try:\n            thread.join(timeout=1.0)\n        except Exception:\n            pass\n        raise\n\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise AuthError(\n            f\"xAI authorization failed: {detail}\",\n            provider=\"xai-oauth\",\n            code=\"xai_authorization_failed\",\n        )\n    if callback.get(\"state\") != state:\n        raise AuthError(\n            \"xAI authorization failed: state mismatch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_state_mismatch\",\n        )\n    code = str(callback.get(\"code\") or \"\").strip()\n    if not code:\n        raise AuthError(\n            \"xAI authorization failed: missing authorization code.\",\n            provider=\"xai-oauth\",\n            code=\"xai_code_missing\",\n        )\n\n    payload = _xai_oauth_exchange_code_for_tokens(\n        token_endpoint=token_endpoint,\n        code=code,\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        code_challenge=code_challenge,\n        timeout_seconds=timeout_seconds,\n    )\n    access_token = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(payload.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI token exchange did not return an access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI token exchange did not return a refresh_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n            \"id_token\": str(payload.get(\"id_token\", \"\") or \"\").strip(),\n            \"expires_in\": payload.get(\"expires_in\"),\n            \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        },\n        \"discovery\": discovery,\n        \"redirect_uri\": redirect_uri,\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"source\": \"oauth-loopback\",\n    }\n\n\ndef _codex_device_code_login() -> Dict[str, Any]:\n    \"\"\"Run the OpenAI device code login flow and return credentials dict.\"\"\"\n    import time as _time\n\n    issuer = \"https://auth.openai.com\"\n    client_id = CODEX_OAUTH_CLIENT_ID\n\n    # Step 1: Request device code\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            resp = client.post(\n                f\"{issuer}/api/accounts/deviceauth/usercode\",\n                json={\"client_id\": client_id},\n                headers={\"Content-Type\": \"application/json\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to request device code: {exc}\",\n            provider=\"openai-codex\", code=\"device_code_request_failed\",\n        )\n\n    if resp.status_code != 200:\n        raise AuthError(\n            f\"Device code request returned status {resp.status_code}.\",\n            provider=\"openai-codex\", code=\"device_code_request_error\",\n        )\n\n    device_data = resp.json()\n    user_code = device_data.get(\"user_code\", \"\")\n    device_auth_id = device_data.get(\"device_auth_id\", \"\")\n    poll_interval = max(3, int(device_data.get(\"interval\", \"5\")))\n\n    if not user_code or not device_auth_id:\n        raise AuthError(\n            \"Device code response missing required fields.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete\",\n        )\n\n    # Step 2: Show user the code\n    print(\"To continue, follow these steps:\\n\")\n    print(\"  1. Open this URL in your browser:\")\n    print(f\"     \\033[94m{issuer}/codex/device\\033[0m\\n\")\n    print(\"  2. Enter this code:\")\n    print(f\"     \\033[94m{user_code}\\033[0m\\n\")\n    print(\"Waiting for sign-in... (press Ctrl+C to cancel)\")\n\n    # Step 3: Poll for authorization code\n    max_wait = 15 * 60  # 15 minutes\n    start = _time.monotonic()\n    code_resp = None\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            while _time.monotonic() - start < max_wait:\n                _time.sleep(poll_interval)\n                poll_resp = client.post(\n                    f\"{issuer}/api/accounts/deviceauth/token\",\n                    json={\"device_auth_id\": device_auth_id, \"user_code\": user_code},\n                    headers={\"Content-Type\": \"application/json\"},\n                )\n\n                if poll_resp.status_code == 200:\n                    code_resp = poll_resp.json()\n                    break\n                elif poll_resp.status_code in {403, 404}:\n                    continue  # User hasn't completed login yet\n                else:\n                    raise AuthError(\n                        f\"Device auth polling returned status {poll_resp.status_code}.\",\n                        provider=\"openai-codex\", code=\"device_code_poll_error\",\n                    )\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n\n    if code_resp is None:\n        raise AuthError(\n            \"Login timed out after 15 minutes.\",\n            provider=\"openai-codex\", code=\"device_code_timeout\",\n        )\n\n    # Step 4: Exchange authorization code for tokens\n    authorization_code = code_resp.get(\"authorization_code\", \"\")\n    code_verifier = code_resp.get(\"code_verifier\", \"\")\n    redirect_uri = f\"{issuer}/deviceauth/callback\"\n\n    if not authorization_code or not code_verifier:\n        raise AuthError(\n            \"Device auth response missing authorization_code or code_verifier.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete_exchange\",\n        )\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            token_resp = client.post(\n                CODEX_OAUTH_TOKEN_URL,\n                data={\n                    \"grant_type\": \"authorization_code\",\n                    \"code\": authorization_code,\n                    \"redirect_uri\": redirect_uri,\n                    \"client_id\": client_id,\n                    \"code_verifier\": code_verifier,\n                },\n                headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Token exchange failed: {exc}\",\n            provider=\"openai-codex\", code=\"token_exchange_failed\",\n        )\n\n    if token_resp.status_code != 200:\n        raise AuthError(\n            f\"Token exchange returned status {token_resp.status_code}.\",\n            provider=\"openai-codex\", code=\"token_exchange_error\",\n        )\n\n    tokens = token_resp.json()\n    access_token = tokens.get(\"access_token\", \"\")\n    refresh_token = tokens.get(\"refresh_token\", \"\")\n\n    if not access_token:\n        raise AuthError(\n            \"Token exchange did not return an access_token.\",\n            provider=\"openai-codex\", code=\"token_exchange_no_access_token\",\n        )\n\n    # Return tokens for the caller to persist (no longer writes to ~/.codex/)\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n        },\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"auth_mode\": \"chatgpt\",\n        \"source\": \"device-code\",\n    }\n\n\n# ==================== MiniMax Portal OAuth ====================\n\ndef _minimax_pkce_pair() -> tuple:\n    \"\"\"Generate (code_verifier, code_challenge_S256, state) for MiniMax OAuth.\"\"\"\n    import secrets\n    verifier = secrets.token_urlsafe(64)[:96]\n    challenge = base64.urlsafe_b64encode(\n        hashlib.sha256(verifier.encode()).digest()\n    ).decode().rstrip(\"=\")\n    state = secrets.token_urlsafe(16)\n    return verifier, challenge, state\n\n\ndef _minimax_request_user_code(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    code_challenge: str, state: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/oauth/code\",\n        data={\n            \"response_type\": \"code\",\n            \"client_id\": client_id,\n            \"scope\": MINIMAX_OAUTH_SCOPE,\n            \"code_challenge\": code_challenge,\n            \"code_challenge_method\": \"S256\",\n            \"state\": state,\n        },\n        headers={\n            \"Content-Type\": \"application/x-www-form-urlencoded\",\n            \"Accept\": \"application/json\",\n            \"x-request-id\": str(uuid.uuid4()),\n        },\n    )\n    if response.status_code != 200:\n        raise AuthError(\n            f\"MiniMax OAuth authorization failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"authorization_failed\",\n        )\n    payload = response.json()\n    for field in (\"user_code\", \"verification_uri\", \"expired_in\"):\n        if field not in payload:\n            raise AuthError(\n                f\"MiniMax OAuth response missing field: {field}\",\n                provider=\"minimax-oauth\", code=\"authorization_incomplete\",\n            )\n    if payload.get(\"state\") != state:\n        raise AuthError(\n            \"MiniMax OAuth state mismatch (possible CSRF).\",\n            provider=\"minimax-oauth\", code=\"state_mismatch\",\n        )\n    return payload\n\n\ndef _minimax_expired_in_looks_like_unix_ms(expired_in: int, *, now_ms: int) -> bool:\n    \"\"\"True if ``expired_in`` is plausibly a unix-ms absolute time (vs TTL seconds).\"\"\"\n    return int(expired_in) > (now_ms // 2)\n\n\ndef _minimax_resolve_token_expiry_unix(expired_in: int, *, now: datetime) -> float:\n    \"\"\"Return access-token expiry as unix seconds (MiniMax uses ms epoch or TTL seconds).\"\"\"\n    raw = int(expired_in)\n    now_ms = int(now.timestamp() * 1000)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        return raw / 1000.0\n    return now.timestamp() + max(1, raw)\n\n\ndef _minimax_poll_token(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    user_code: str, code_verifier: str, expired_in: int, interval_ms: Optional[int],\n) -> Dict[str, Any]:\n    # OpenClaw treats expired_in as a unix-ms timestamp (Date.now() < expireTimeMs).\n    # Defensive parsing: if it's small enough to be a duration, treat as seconds.\n    import time as _time\n    now_ms = int(_time.time() * 1000)\n    raw = int(expired_in)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        deadline = raw / 1000.0\n    else:\n        deadline = _time.time() + max(1, raw)\n    interval = max(2.0, (interval_ms or 2000) / 1000.0)\n\n    while _time.time() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": MINIMAX_OAUTH_GRANT_TYPE,\n                \"client_id\": client_id,\n                \"user_code\": user_code,\n                \"code_verifier\": code_verifier,\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n        try:\n            payload = response.json() if response.text else {}\n        except Exception:\n            payload = {}\n\n        if response.status_code != 200:\n            msg = (payload.get(\"base_resp\", {}) or {}).get(\"status_msg\") or response.text\n            raise AuthError(\n                f\"MiniMax OAuth error: {msg or 'unknown'}\",\n                provider=\"minimax-oauth\", code=\"token_exchange_failed\",\n            )\n\n        status = payload.get(\"status\")\n        if status == \"error\":\n            raise AuthError(\n                \"MiniMax OAuth reported an error. Please try again later.\",\n                provider=\"minimax-oauth\", code=\"authorization_denied\",\n            )\n        if status == \"success\":\n            if not all(payload.get(k) for k in (\"access_token\", \"refresh_token\", \"expired_in\")):\n                raise AuthError(\n                    \"MiniMax OAuth success payload missing required token fields.\",\n                    provider=\"minimax-oauth\", code=\"token_incomplete\",\n                )\n            return payload\n        # \"pending\" or any other status -> keep polling\n        _time.sleep(interval)\n\n    raise AuthError(\n        \"MiniMax OAuth timed out before authorization completed.\",\n        provider=\"minimax-oauth\", code=\"timeout\",\n    )\n\n\ndef _minimax_save_auth_state(auth_state: Dict[str, Any]) -> None:\n    \"\"\"Persist MiniMax OAuth state to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"minimax-oauth\", auth_state)\n        _save_auth_store(auth_store)\n\n\ndef _minimax_oauth_login(\n    *, region: str = \"global\", open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n) -> Dict[str, Any]:\n    \"\"\"Run MiniMax OAuth flow, persist tokens, return auth state dict.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"minimax-oauth\"]\n    if region == \"cn\":\n        portal_base_url = pconfig.extra[\"cn_portal_base_url\"]\n        inference_base_url = pconfig.extra[\"cn_inference_base_url\"]\n    else:\n        portal_base_url = pconfig.portal_base_url\n        inference_base_url = pconfig.inference_base_url\n\n    verifier, challenge, state = _minimax_pkce_pair()\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via MiniMax ({region}) OAuth...\")\n    print(f\"Portal: {portal_base_url}\")\n\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      headers={\"Accept\": \"application/json\"},\n                      follow_redirects=True) as client:\n        code_data = _minimax_request_user_code(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            code_challenge=challenge, state=state,\n        )\n        verification_url = str(code_data[\"verification_uri\"])\n        user_code = str(code_data[\"user_code\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n        if open_browser:\n            if webbrowser.open(verification_url):\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically -- use the URL above.\")\n\n        interval_raw = code_data.get(\"interval\")\n        interval_ms = int(interval_raw) if interval_raw is not None else None\n        print(\"Waiting for approval...\")\n\n        token_data = _minimax_poll_token(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            user_code=user_code, code_verifier=verifier,\n            expired_in=int(code_data[\"expired_in\"]),\n            interval_ms=interval_ms,\n        )\n\n    now = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(token_data[\"expired_in\"]), now=now,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now.timestamp()))\n\n    auth_state = {\n        \"provider\": \"minimax-oauth\",\n        \"region\": region,\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": inference_base_url,\n        \"client_id\": pconfig.client_id,\n        \"scope\": MINIMAX_OAUTH_SCOPE,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data[\"refresh_token\"],\n        \"resource_url\": token_data.get(\"resource_url\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    }\n\n    _minimax_save_auth_state(auth_state)\n    print(\"\\u2713 MiniMax OAuth login successful.\")\n    if msg := token_data.get(\"notification_message\"):\n        print(f\"Note from MiniMax: {msg}\")\n    return auth_state\n\n\ndef _refresh_minimax_oauth_state(\n    state: Dict[str, Any], *, timeout_seconds: float = 15.0,\n    force: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Refresh MiniMax OAuth access token if close to expiry (or forced).\"\"\"\n    if not state.get(\"refresh_token\"):\n        raise AuthError(\n            \"MiniMax OAuth state has no refresh_token; please re-login.\",\n            provider=\"minimax-oauth\", code=\"no_refresh_token\", relogin_required=True,\n        )\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n    except Exception:\n        expires_at = 0.0\n    now = time.time()\n    if not force and (expires_at - now) > MINIMAX_OAUTH_REFRESH_SKEW_SECONDS:\n        return state\n\n    portal_base_url = state[\"portal_base_url\"]\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      follow_redirects=True) as client:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": state[\"client_id\"],\n                \"refresh_token\": state[\"refresh_token\"],\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n    if response.status_code != 200:\n        body = response.text.lower()\n        relogin = any(m in body for m in\n                      (\"invalid_grant\", \"refresh_token_reused\", \"invalid_refresh_token\"))\n        raise AuthError(\n            f\"MiniMax OAuth refresh failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=relogin,\n        )\n    payload = response.json()\n    if payload.get(\"status\") != \"success\":\n        raise AuthError(\n            \"MiniMax OAuth refresh did not return success.\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=True,\n        )\n    now_dt = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(payload[\"expired_in\"]), now=now_dt,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now_dt.timestamp()))\n    new_state = dict(state)\n    new_state.update({\n        \"access_token\": payload[\"access_token\"],\n        \"refresh_token\": payload.get(\"refresh_token\", state[\"refresh_token\"]),\n        \"obtained_at\": now_dt.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    })\n    _minimax_save_auth_state(new_state)\n    return new_state\n\n\ndef resolve_minimax_oauth_runtime_credentials(\n    *, min_token_ttl_seconds: int = MINIMAX_OAUTH_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Return {provider, api_key, base_url, source} for minimax-oauth.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        raise AuthError(\n            \"Not logged into MiniMax OAuth. Run `clawbot model` and select \"\n            \"MiniMax (OAuth).\",\n            provider=\"minimax-oauth\", code=\"not_logged_in\", relogin_required=True,\n        )\n    state = _refresh_minimax_oauth_state(state)\n    return {\n        \"provider\": \"minimax-oauth\",\n        \"api_key\": state[\"access_token\"],\n        \"base_url\": state[\"inference_base_url\"].rstrip(\"/\"),\n        \"source\": \"oauth\",\n    }\n\n\ndef get_minimax_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return auth status dict for MiniMax OAuth provider.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        return {\"logged_in\": False, \"provider\": \"minimax-oauth\"}\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n        token_valid = (expires_at - time.time()) > 0\n    except Exception:\n        token_valid = bool(state.get(\"access_token\"))\n    return {\n        \"logged_in\": token_valid,\n        \"provider\": \"minimax-oauth\",\n        \"region\": state.get(\"region\", \"global\"),\n        \"expires_at\": state.get(\"expires_at\"),\n    }\n\n\ndef _login_minimax_oauth(args, pconfig: ProviderConfig) -> None:\n    \"\"\"CLI entry for MiniMax OAuth login.\"\"\"\n    region = getattr(args, \"region\", None) or \"global\"\n    open_browser = not getattr(args, \"no_browser\", False)\n    timeout = getattr(args, \"timeout\", None) or 15.0\n    try:\n        _minimax_oauth_login(\n            region=region, open_browser=open_browser, timeout_seconds=timeout,\n        )\n    except AuthError as exc:\n        print(format_auth_error(exc))\n        raise SystemExit(1)\n\n\ndef _soam_device_code_login(\n    *,\n    portal_base_url: Optional[str] = None,\n    inference_base_url: Optional[str] = None,\n    client_id: Optional[str] = None,\n    scope: Optional[str] = None,\n    open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n    insecure: bool = False,\n    ca_bundle: Optional[str] = None,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Dict[str, Any]:\n    \"\"\"Run the Soam device-code flow and return full OAuth state without persisting.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"soam\"]\n    portal_base_url = (\n        portal_base_url\n        or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n        or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n        or pconfig.portal_base_url\n    ).rstrip(\"/\")\n    requested_inference_url = (\n        inference_base_url\n        or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n        or pconfig.inference_base_url\n    ).rstrip(\"/\")\n    client_id = client_id or pconfig.client_id\n    scope, explicit_scope = _soam_device_scope_with_env_override(\n        scope,\n        default_scope=pconfig.scope,\n    )\n    timeout = httpx.Timeout(timeout_seconds)\n    verify: bool | str = False if insecure else (ca_bundle if ca_bundle else True)\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via {pconfig.name}...\")\n    print(f\"Portal: {portal_base_url}\")\n    if insecure:\n        print(\"TLS verification: disabled (--insecure)\")\n    elif ca_bundle:\n        print(f\"TLS verification: custom CA bundle ({ca_bundle})\")\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        device_data, scope = _request_soam_device_code_with_scope_fallback(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            scope=scope,\n            allow_legacy_fallback=not explicit_scope,\n        )\n\n        verification_url = str(device_data[\"verification_uri_complete\"])\n        user_code = str(device_data[\"user_code\"])\n        expires_in = int(device_data[\"expires_in\"])\n        interval = int(device_data[\"interval\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n\n        if open_browser:\n            opened = webbrowser.open(verification_url)\n            if opened:\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically — use the URL above.\")\n\n        effective_interval = max(1, min(interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n        print(f\"Waiting for approval (polling every {effective_interval}s)...\")\n\n        token_data = _poll_for_token(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            device_code=str(device_data[\"device_code\"]),\n            expires_in=expires_in,\n            poll_interval=interval,\n        )\n\n    now = datetime.now(timezone.utc)\n    token_expires_in = _coerce_ttl_seconds(token_data.get(\"expires_in\", 0))\n    expires_at = now.timestamp() + token_expires_in\n    resolved_inference_url = (\n        _optional_base_url(token_data.get(\"inference_base_url\"))\n        or requested_inference_url\n    )\n    if resolved_inference_url != requested_inference_url:\n        print(f\"Using portal-provided inference URL: {resolved_inference_url}\")\n\n    auth_state = {\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": resolved_inference_url,\n        \"client_id\": client_id,\n        \"scope\": token_data.get(\"scope\") or scope,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data.get(\"refresh_token\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(),\n        \"expires_in\": token_expires_in,\n        \"tls\": {\n            \"insecure\": verify is False,\n            \"ca_bundle\": verify if isinstance(verify, str) else None,\n        },\n        \"agent_key\": None,\n        \"agent_key_id\": None,\n        \"agent_key_expires_at\": None,\n        \"agent_key_expires_in\": None,\n        \"agent_key_reused\": None,\n        \"agent_key_obtained_at\": None,\n    }\n    try:\n        return refresh_soam_oauth_from_state(\n            auth_state,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            timeout_seconds=timeout_seconds,\n            force_refresh=False,\n            inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n        )\n    except AuthError as exc:\n        if exc.code == \"subscription_required\":\n            portal_url = auth_state.get(\n                \"portal_base_url\", DEFAULT_SOAM_PORTAL_URL\n            ).rstrip(\"/\")\n            print()\n            print(\"Your Soam Portal account does not have an active subscription.\")\n            print(f\"  Subscribe here: {portal_url}/billing\")\n            print()\n            print(\"After subscribing, run `clawbot model` again to finish setup.\")\n            raise SystemExit(1)\n        raise\n\n\ndef _login_soam(args, pconfig: ProviderConfig) -> None:\n    \"\"\"Soam Portal device authorization flow.\"\"\"\n    timeout_seconds = getattr(args, \"timeout\", None) or 15.0\n    insecure = bool(getattr(args, \"insecure\", False))\n    ca_bundle = (\n        getattr(args, \"ca_bundle\", None)\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n    )\n\n    try:\n        auth_state = None\n\n        # Codex-style auto-import: before launching a fresh device-code\n        # flow, check the shared store for an existing Soam credential\n        # from any other profile. If present, offer to rehydrate it.\n        shared = _read_shared_soam_state()\n        if shared:\n            try:\n                shared_path = _soam_shared_store_path()\n            except RuntimeError:\n                shared_path = None\n            print()\n            if shared_path:\n                print(f\"Found existing Soam OAuth credentials at {shared_path}\")\n            else:\n                print(\"Found existing shared Soam OAuth credentials\")\n            try:\n                do_import = input(\"Import these credentials? [Y/n]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"y\"\n            if do_import in {\"\", \"y\", \"yes\"}:\n                print(\"Rehydrating Soam session from shared credentials...\")\n                auth_state = _try_import_shared_soam_state(\n                    timeout_seconds=timeout_seconds,\n                    min_key_ttl_seconds=5 * 60,\n                )\n                if auth_state is None:\n                    print(\"Could not refresh shared credentials — falling back to device-code login.\")\n\n        if auth_state is None:\n            auth_state = _soam_device_code_login(\n                portal_base_url=getattr(args, \"portal_url\", None),\n                inference_base_url=getattr(args, \"inference_url\", None),\n                client_id=getattr(args, \"client_id\", None) or pconfig.client_id,\n                scope=getattr(args, \"scope\", None),\n                open_browser=not getattr(args, \"no_browser\", False),\n                timeout_seconds=timeout_seconds,\n                insecure=insecure,\n                ca_bundle=ca_bundle,\n                min_key_ttl_seconds=5 * 60,\n            )\n\n        inference_base_url = auth_state[\"inference_base_url\"]\n\n        # Snapshot the prior active_provider BEFORE _save_provider_state\n        # overwrites it to \"soam\".  If the user picks \"Skip (keep current)\"\n        # during model selection below, we restore this so the user's previous\n        # provider (e.g. openrouter) is preserved.\n        with _auth_store_lock():\n            _prior_store = _load_auth_store()\n            prior_active_provider = _prior_store.get(\"active_provider\")\n\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n            _save_provider_state(auth_store, \"soam\", auth_state)\n            saved_to = _save_auth_store(auth_store)\n\n        # Mirror to the shared store so other profiles can one-tap import\n        # these credentials. Best-effort: any I/O failure is logged and\n        # swallowed inside the helper.\n        _write_shared_soam_state(auth_state)\n        _sync_soam_pool_from_auth_store()\n\n        print()\n        print(\"Login successful!\")\n        print(f\"  Auth state: {saved_to}\")\n\n        # Resolve model BEFORE writing provider to config.yaml so we never\n        # leave the config in a half-updated state (provider=soam but model\n        # still set to the previous provider's model, e.g. opus from\n        # OpenRouter).  The auth.json active_provider was already set above.\n        selected_model = None\n        try:\n            runtime_key = auth_state.get(\"agent_key\") or auth_state.get(\"access_token\")\n            if not isinstance(runtime_key, str) or not runtime_key:\n                raise AuthError(\n                    \"No runtime API key available to fetch models\",\n                    provider=\"soam\",\n                    code=\"invalid_token\",\n                )\n\n            from clawbot_cli.models import (\n                get_curated_soam_model_ids, get_pricing_for_provider,\n                check_soam_free_tier, partition_soam_models_by_tier,\n                union_with_portal_free_recommendations,\n                union_with_portal_paid_recommendations,\n            )\n            model_ids = get_curated_soam_model_ids()\n\n            print()\n            unavailable_models: list = []\n            if model_ids:\n                pricing = get_pricing_for_provider(\"soam\")\n                free_tier = check_soam_free_tier()\n                _portal_for_recs = auth_state.get(\"portal_base_url\", \"\")\n                if free_tier:\n                    # The Portal's freeRecommendedModels endpoint is the\n                    # source of truth for what's free *right now*. Augment\n                    # the curated list with anything new the Portal flags\n                    # as free so users on older Clawbot builds still see\n                    # newly-launched free models without a CLI release.\n                    model_ids, pricing = union_with_portal_free_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n                    model_ids, unavailable_models = partition_soam_models_by_tier(\n                        model_ids, pricing, free_tier=True,\n                    )\n                else:\n                    # Paid-tier mirror: pull paidRecommendedModels so newly\n                    # launched paid models surface in the picker even if\n                    # the in-repo curated list and docs-hosted manifest\n                    # haven't caught up yet.\n                    model_ids, pricing = union_with_portal_paid_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n            _portal = auth_state.get(\"portal_base_url\", \"\")\n            if model_ids:\n                print(f\"Showing {len(model_ids)} curated models — use \\\"Enter custom model name\\\" for others.\")\n                selected_model = _prompt_model_selection(\n                    model_ids, pricing=pricing,\n                    unavailable_models=unavailable_models,\n                    portal_url=_portal,\n                )\n            elif unavailable_models:\n                _url = (_portal or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n                print(\"No free models currently available.\")\n                print(f\"Upgrade at {_url} to access paid models.\")\n            else:\n                print(\"No curated models available for Soam Portal.\")\n        except Exception as exc:\n            message = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc)\n            print()\n            print(f\"Login succeeded, but could not fetch available models. Reason: {message}\")\n\n        # Write provider + model atomically so config is never mismatched.\n        # If no model was selected (user picked \"Skip (keep current)\",\n        # model list fetch failed, or no curated models were available),\n        # preserve the user's previous provider — don't silently switch\n        # them to Soam with a mismatched model.  The Soam OAuth tokens\n        # stay saved for future use.\n        if not selected_model:\n            # Restore the prior active_provider that _save_provider_state\n            # overwrote to \"soam\".  config.yaml model.provider is left\n            # untouched, so the user's previous provider is fully preserved.\n            with _auth_store_lock():\n                auth_store = _load_auth_store()\n                if prior_active_provider:\n                    auth_store[\"active_provider\"] = prior_active_provider\n                else:\n                    auth_store.pop(\"active_provider\", None)\n                _save_auth_store(auth_store)\n            print()\n            print(\"No provider change. Soam credentials saved for future use.\")\n            print(\"  Run `clawbot model` again to switch to Soam Portal.\")\n            return\n\n        config_path = _update_config_for_provider(\n            \"soam\", inference_base_url, default_model=selected_model,\n        )\n        if selected_model:\n            _save_model_choice(selected_model)\n            print(f\"Default model set to: {selected_model}\")\n        print(f\"  Config updated: {config_path} (model.provider=soam)\")\n\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n    except Exception as exc:\n        print(f\"Login failed: {exc}\")\n        raise SystemExit(1)\n\n\ndef logout_command(args) -> None:\n    \"\"\"Clear auth state for a provider.\"\"\"\n    provider_id = getattr(args, \"provider\", None)\n\n    if provider_id and not is_known_auth_provider(provider_id):\n        print(f\"Unknown provider: {provider_id}\")\n        raise SystemExit(1)\n\n    active = get_active_provider()\n    target = provider_id or active or _logout_default_provider_from_config()\n\n    if not target:\n        print(\"No provider is currently logged in.\")\n        return\n\n    should_reset_config = _should_reset_config_provider_on_logout(target)\n    provider_name = get_auth_provider_display_name(target)\n\n    if clear_provider_auth(target) or should_reset_config:\n        if should_reset_config:\n            _reset_config_provider()\n        print(f\"Logged out of {provider_name}.\")\n        if should_reset_config and os.getenv(\"OPENROUTER_API_KEY\"):\n            print(\"Clawbot will use OpenRouter for inference.\")\n        elif should_reset_config:\n            print(\"Run `clawbot model` or configure an API key to use Clawbot.\")\n        else:\n            print(\"Model provider configuration was unchanged.\")\n    else:\n        print(f\"No auth state found for {provider_name}.\")\n"}, "85d8cca23eb4cce593ff6f4b84c753169fdbd322": {"t": 1785763619.17669, "n": 273725, "h": "843cbe846f3510d2", "c": "\"\"\"\nMulti-provider authentication system for Clawbot Agent.\n\nSupports OAuth device code flows (Soam Portal, future: OpenAI Codex) and\ntraditional API key providers (OpenRouter, custom endpoints). Auth state\nis persisted in ~/.clawbot/auth.json with cross-process file locking.\n\nArchitecture:\n- ProviderConfig registry defines known OAuth providers\n- Auth store (auth.json) holds per-provider credential state\n- resolve_provider() picks the active provider via priority chain\n- resolve_*_runtime_credentials() handles token refresh and key minting\n- logout_command() is the CLI entry point for clearing auth\n\nSoam authentication paths:\n- Invoke JWT (preferred): use a scoped access_token directly for inference.\n- Legacy session key (fallback): mint an opaque 24h key when JWT auth is\n  unavailable, or when CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS is set for\n  debugging or rollback.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport shutil\nimport shlex\nimport ssl\nimport stat\nimport sys\nimport base64\nimport hashlib\nimport subprocess\nimport threading\nimport time\nimport uuid\nimport webbrowser\nfrom contextlib import contextmanager\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\nfrom pathlib import Path\nfrom typing import Any, Callable, Dict, List, Optional, Tuple\nfrom urllib.parse import parse_qs, urlencode, urlparse\n\nimport httpx\nimport yaml\n\nfrom clawbot_cli.config import get_clawbot_home, get_config_path, read_raw_config\nfrom clawbot_constants import OPENROUTER_BASE_URL\nfrom utils import atomic_replace, atomic_yaml_write, is_truthy_value\n\nlogger = logging.getLogger(__name__)\n\ntry:\n    import fcntl\nexcept Exception:\n    fcntl = None\ntry:\n    import msvcrt\nexcept Exception:\n    msvcrt = None\n\n# =============================================================================\n# Constants\n# =============================================================================\n\nAUTH_STORE_VERSION = 1\nAUTH_LOCK_TIMEOUT_SECONDS = 15.0\n\n# Soam Portal defaults\nDEFAULT_SOAM_PORTAL_URL = \"https://portal.aayushsoam.com\"\nDEFAULT_SOAM_INFERENCE_URL = \"https://inference-api.aayushsoam.com/v1\"\nDEFAULT_SOAM_CLIENT_ID = \"clawbot-cli\"\nSOAM_LEGACY_AGENT_KEY_SCOPE = \"inference:mint_agent_key\"\nSOAM_INFERENCE_INVOKE_SCOPE = \"inference:invoke\"\nDEFAULT_SOAM_SCOPE = f\"{SOAM_INFERENCE_INVOKE_SCOPE} {SOAM_LEGACY_AGENT_KEY_SCOPE}\"\nSOAM_LEGACY_SESSION_KEYS_ENV = \"CLAWBOT_AGENT_USE_LEGACY_SESSION_KEYS\"\nSOAM_DEVICE_CODE_SOURCE = \"device_code\"\nSOAM_INFERENCE_AUTH_MODE_AUTO = \"auto\"\nSOAM_INFERENCE_AUTH_MODE_FRESH = \"fresh\"\nSOAM_INFERENCE_AUTH_MODE_LEGACY = \"legacy\"\nSOAM_INFERENCE_AUTH_MODES = frozenset({\n    SOAM_INFERENCE_AUTH_MODE_AUTO,\n    SOAM_INFERENCE_AUTH_MODE_FRESH,\n    SOAM_INFERENCE_AUTH_MODE_LEGACY,\n})\nSOAM_AUTH_PATH_INVOKE_JWT = \"invoke_jwt\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE = \"legacy_session_key_cache\"\nSOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT = \"legacy_session_key_mint\"\nDEFAULT_AGENT_KEY_MIN_TTL_SECONDS = 30 * 60  # 30 minutes\nACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120       # refresh 2 min before expiry\nSOAM_INVOKE_JWT_MIN_TTL_SECONDS = ACCESS_TOKEN_REFRESH_SKEW_SECONDS\nDEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS = 1     # poll at most every 1s\nDEFAULT_CODEX_BASE_URL = \"https://chatgpt.com/backend-api/codex\"\nDEFAULT_XAI_OAUTH_BASE_URL = \"https://api.x.ai/v1\"\nMINIMAX_OAUTH_CLIENT_ID = \"78257093-7e40-4613-99e0-527b14b39113\"\nMINIMAX_OAUTH_SCOPE = \"group_id profile model.completion\"\nMINIMAX_OAUTH_GRANT_TYPE = \"urn:ietf:params:oauth:grant-type:user_code\"\nMINIMAX_OAUTH_GLOBAL_BASE = \"https://api.minimax.io\"\nMINIMAX_OAUTH_CN_BASE = \"https://api.minimaxi.com\"\nMINIMAX_OAUTH_GLOBAL_INFERENCE = \"https://api.minimax.io/anthropic\"\nMINIMAX_OAUTH_CN_INFERENCE = \"https://api.minimaxi.com/anthropic\"\nMINIMAX_OAUTH_REFRESH_SKEW_SECONDS = 60\nDEFAULT_QWEN_BASE_URL = \"https://portal.qwen.ai/v1\"\nDEFAULT_GITHUB_MODELS_BASE_URL = \"https://api.githubcopilot.com\"\nDEFAULT_COPILOT_ACP_BASE_URL = \"acp://copilot\"\nDEFAULT_OLLAMA_CLOUD_BASE_URL = \"https://ollama.com/v1\"\nSTEPFUN_STEP_PLAN_INTL_BASE_URL = \"https://api.stepfun.ai/step_plan/v1\"\nSTEPFUN_STEP_PLAN_CN_BASE_URL = \"https://api.stepfun.com/step_plan/v1\"\nCODEX_OAUTH_CLIENT_ID = \"app_EMoamEEZ73f0CkXaXp7hrann\"\nCODEX_OAUTH_TOKEN_URL = \"https://auth.openai.com/oauth/token\"\nCODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nXAI_OAUTH_ISSUER = \"https://auth.x.ai\"\nXAI_OAUTH_DISCOVERY_URL = f\"{XAI_OAUTH_ISSUER}/.well-known/openid-configuration\"\nXAI_OAUTH_CLIENT_ID = \"b1a00492-073a-47ea-816f-4c329264a828\"\nXAI_OAUTH_SCOPE = \"openid profile email offline_access grok-cli:access api:access\"\nXAI_OAUTH_REDIRECT_HOST = \"127.0.0.1\"\nXAI_OAUTH_REDIRECT_PORT = 56121\nXAI_OAUTH_REDIRECT_PATH = \"/callback\"\nXAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nQWEN_OAUTH_CLIENT_ID = \"f0304373b74a44d2b584a3fb70ca9e56\"\nQWEN_OAUTH_TOKEN_URL = \"https://chat.qwen.ai/api/v1/oauth2/token\"\nQWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\nDEFAULT_SPOTIFY_ACCOUNTS_BASE_URL = \"https://accounts.spotify.com\"\nDEFAULT_SPOTIFY_API_BASE_URL = \"https://api.spotify.com/v1\"\nDEFAULT_SPOTIFY_REDIRECT_URI = \"http://127.0.0.1:43827/spotify/callback\"\nSPOTIFY_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/user-guide/features/spotify\"\nSPOTIFY_DASHBOARD_URL = \"https://developer.spotify.com/dashboard\"\nSPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120\n\nXAI_OAUTH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/xai-grok-oauth\"\nOAUTH_OVER_SSH_DOCS_URL = \"https://clawbot-agent.aayushsoam.com/docs/guides/oauth-over-ssh\"\nDEFAULT_SPOTIFY_SCOPE = \" \".join((\n    \"user-modify-playback-state\",\n    \"user-read-playback-state\",\n    \"user-read-currently-playing\",\n    \"user-read-recently-played\",\n    \"playlist-read-private\",\n    \"playlist-read-collaborative\",\n    \"playlist-modify-public\",\n    \"playlist-modify-private\",\n    \"user-library-read\",\n    \"user-library-modify\",\n))\nSERVICE_PROVIDER_NAMES: Dict[str, str] = {\n    \"spotify\": \"Spotify\",\n}\n\n# Google Gemini OAuth (google-gemini-cli provider, Cloud Code Assist backend)\nDEFAULT_GEMINI_CLOUDCODE_BASE_URL = \"cloudcode-pa://google\"\nGEMINI_OAUTH_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 60  # refresh 60s before expiry\n\n# LM Studio's default no-auth mode still requires *some* non-empty bearer for\n# the API-key code paths (auxiliary_client, runtime resolver) to treat the\n# provider as configured. This sentinel is sent only to LM Studio, never to\n# any remote service.\nLMSTUDIO_NOAUTH_PLACEHOLDER = \"dummy-lm-api-key\"\n\n\n# =============================================================================\n# Provider Registry\n# =============================================================================\n\n@dataclass\nclass ProviderConfig:\n    \"\"\"Describes a known inference provider.\"\"\"\n    id: str\n    name: str\n    auth_type: str  # \"oauth_device_code\", \"oauth_external\", \"oauth_minimax\", or \"api_key\"\n    portal_base_url: str = \"\"\n    inference_base_url: str = \"\"\n    client_id: str = \"\"\n    scope: str = \"\"\n    extra: Dict[str, Any] = field(default_factory=dict)\n    # For API-key providers: env vars to check (in priority order)\n    api_key_env_vars: tuple = ()\n    # Optional env var for base URL override\n    base_url_env_var: str = \"\"\n\n\nPROVIDER_REGISTRY: Dict[str, ProviderConfig] = {\n    \"soam\": ProviderConfig(\n        id=\"soam\",\n        name=\"Soam Portal\",\n        auth_type=\"oauth_device_code\",\n        portal_base_url=DEFAULT_SOAM_PORTAL_URL,\n        inference_base_url=DEFAULT_SOAM_INFERENCE_URL,\n        client_id=DEFAULT_SOAM_CLIENT_ID,\n        scope=DEFAULT_SOAM_SCOPE,\n    ),\n    \"openai-codex\": ProviderConfig(\n        id=\"openai-codex\",\n        name=\"OpenAI Codex\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_CODEX_BASE_URL,\n    ),\n    \"xai-oauth\": ProviderConfig(\n        id=\"xai-oauth\",\n        name=\"xAI Grok OAuth (SuperGrok Subscription)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_XAI_OAUTH_BASE_URL,\n    ),\n    \"qwen-oauth\": ProviderConfig(\n        id=\"qwen-oauth\",\n        name=\"Qwen OAuth\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_QWEN_BASE_URL,\n    ),\n    \"google-gemini-cli\": ProviderConfig(\n        id=\"google-gemini-cli\",\n        name=\"Google Gemini (OAuth)\",\n        auth_type=\"oauth_external\",\n        inference_base_url=DEFAULT_GEMINI_CLOUDCODE_BASE_URL,\n    ),\n    \"lmstudio\": ProviderConfig(\n        id=\"lmstudio\",\n        name=\"LM Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"http://127.0.0.1:1234/v1\",\n        api_key_env_vars=(\"LM_API_KEY\",),\n        base_url_env_var=\"LM_BASE_URL\",\n    ),\n    \"copilot\": ProviderConfig(\n        id=\"copilot\",\n        name=\"GitHub Copilot\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_GITHUB_MODELS_BASE_URL,\n        api_key_env_vars=(\"COPILOT_GITHUB_TOKEN\", \"GH_TOKEN\", \"GITHUB_TOKEN\"),\n        base_url_env_var=\"COPILOT_API_BASE_URL\",\n    ),\n    \"copilot-acp\": ProviderConfig(\n        id=\"copilot-acp\",\n        name=\"GitHub Copilot ACP\",\n        auth_type=\"external_process\",\n        inference_base_url=DEFAULT_COPILOT_ACP_BASE_URL,\n        base_url_env_var=\"COPILOT_ACP_BASE_URL\",\n    ),\n    \"gemini\": ProviderConfig(\n        id=\"gemini\",\n        name=\"Google AI Studio\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://generativelanguage.googleapis.com/v1beta\",\n        api_key_env_vars=(\"GOOGLE_API_KEY\", \"GEMINI_API_KEY\"),\n        base_url_env_var=\"GEMINI_BASE_URL\",\n    ),\n    \"zai\": ProviderConfig(\n        id=\"zai\",\n        name=\"Z.AI / GLM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.z.ai/api/paas/v4\",\n        api_key_env_vars=(\"GLM_API_KEY\", \"ZAI_API_KEY\", \"Z_AI_API_KEY\"),\n        base_url_env_var=\"GLM_BASE_URL\",\n    ),\n    \"kimi-coding\": ProviderConfig(\n        id=\"kimi-coding\",\n        name=\"Kimi / Moonshot\",\n        auth_type=\"api_key\",\n        # Legacy platform.moonshot.ai keys use this endpoint (OpenAI-compat).\n        # sk-kimi- (Kimi Code) keys are auto-redirected to api.kimi.com/coding\n        # by _resolve_kimi_base_url() below.\n        inference_base_url=\"https://api.moonshot.ai/v1\",\n        api_key_env_vars=(\"KIMI_API_KEY\", \"KIMI_CODING_API_KEY\"),\n        base_url_env_var=\"KIMI_BASE_URL\",\n    ),\n    \"kimi-coding-cn\": ProviderConfig(\n        id=\"kimi-coding-cn\",\n        name=\"Kimi / Moonshot (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.moonshot.cn/v1\",\n        api_key_env_vars=(\"KIMI_CN_API_KEY\",),\n    ),\n    \"stepfun\": ProviderConfig(\n        id=\"stepfun\",\n        name=\"StepFun Step Plan\",\n        auth_type=\"api_key\",\n        inference_base_url=STEPFUN_STEP_PLAN_INTL_BASE_URL,\n        api_key_env_vars=(\"STEPFUN_API_KEY\",),\n        base_url_env_var=\"STEPFUN_BASE_URL\",\n    ),\n    \"arcee\": ProviderConfig(\n        id=\"arcee\",\n        name=\"Arcee AI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.arcee.ai/api/v1\",\n        api_key_env_vars=(\"ARCEEAI_API_KEY\",),\n        base_url_env_var=\"ARCEE_BASE_URL\",\n    ),\n    \"gmi\": ProviderConfig(\n        id=\"gmi\",\n        name=\"GMI Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.gmi-serving.com/v1\",\n        api_key_env_vars=(\"GMI_API_KEY\",),\n        base_url_env_var=\"GMI_BASE_URL\",\n    ),\n    \"minimax\": ProviderConfig(\n        id=\"minimax\",\n        name=\"MiniMax\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimax.io/anthropic\",\n        api_key_env_vars=(\"MINIMAX_API_KEY\",),\n        base_url_env_var=\"MINIMAX_BASE_URL\",\n    ),\n    \"minimax-oauth\": ProviderConfig(\n        id=\"minimax-oauth\",\n        name=\"MiniMax (OAuth \\u00b7 minimax.io)\",\n        auth_type=\"oauth_minimax\",\n        portal_base_url=MINIMAX_OAUTH_GLOBAL_BASE,\n        inference_base_url=MINIMAX_OAUTH_GLOBAL_INFERENCE,\n        client_id=MINIMAX_OAUTH_CLIENT_ID,\n        scope=MINIMAX_OAUTH_SCOPE,\n        extra={\"region\": \"global\", \"cn_portal_base_url\": MINIMAX_OAUTH_CN_BASE,\n               \"cn_inference_base_url\": MINIMAX_OAUTH_CN_INFERENCE},\n    ),\n    \"anthropic\": ProviderConfig(\n        id=\"anthropic\",\n        name=\"Anthropic\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.anthropic.com\",\n        api_key_env_vars=(\"ANTHROPIC_API_KEY\", \"ANTHROPIC_TOKEN\", \"CLAUDE_CODE_OAUTH_TOKEN\"),\n        base_url_env_var=\"ANTHROPIC_BASE_URL\",\n    ),\n    \"alibaba\": ProviderConfig(\n        id=\"alibaba\",\n        name=\"Qwen Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://dashscope-intl.aliyuncs.com/compatible-mode/v1\",\n        api_key_env_vars=(\"DASHSCOPE_API_KEY\",),\n        base_url_env_var=\"DASHSCOPE_BASE_URL\",\n    ),\n    \"alibaba-coding-plan\": ProviderConfig(\n        id=\"alibaba-coding-plan\",\n        name=\"Alibaba Cloud (Coding Plan)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://coding-intl.dashscope.aliyuncs.com/v1\",\n        api_key_env_vars=(\"ALIBABA_CODING_PLAN_API_KEY\", \"DASHSCOPE_API_KEY\"),\n        base_url_env_var=\"ALIBABA_CODING_PLAN_BASE_URL\",\n    ),\n    \"minimax-cn\": ProviderConfig(\n        id=\"minimax-cn\",\n        name=\"MiniMax (China)\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.minimaxi.com/anthropic\",\n        api_key_env_vars=(\"MINIMAX_CN_API_KEY\",),\n        base_url_env_var=\"MINIMAX_CN_BASE_URL\",\n    ),\n    \"deepseek\": ProviderConfig(\n        id=\"deepseek\",\n        name=\"DeepSeek\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.deepseek.com/v1\",\n        api_key_env_vars=(\"DEEPSEEK_API_KEY\",),\n        base_url_env_var=\"DEEPSEEK_BASE_URL\",\n    ),\n    \"xai\": ProviderConfig(\n        id=\"xai\",\n        name=\"xAI\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.x.ai/v1\",\n        api_key_env_vars=(\"XAI_API_KEY\",),\n        base_url_env_var=\"XAI_BASE_URL\",\n    ),\n    \"nvidia\": ProviderConfig(\n        id=\"nvidia\",\n        name=\"NVIDIA NIM\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://integrate.api.nvidia.com/v1\",\n        api_key_env_vars=(\"NVIDIA_API_KEY\",),\n        base_url_env_var=\"NVIDIA_BASE_URL\",\n    ),\n    \"ai-gateway\": ProviderConfig(\n        id=\"ai-gateway\",\n        name=\"Vercel AI Gateway\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://ai-gateway.vercel.sh/v1\",\n        api_key_env_vars=(\"AI_GATEWAY_API_KEY\",),\n        base_url_env_var=\"AI_GATEWAY_BASE_URL\",\n    ),\n    \"opencode-zen\": ProviderConfig(\n        id=\"opencode-zen\",\n        name=\"OpenCode Zen\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://opencode.ai/zen/v1\",\n        api_key_env_vars=(\"OPENCODE_ZEN_API_KEY\",),\n        base_url_env_var=\"OPENCODE_ZEN_BASE_URL\",\n    ),\n    \"opencode-go\": ProviderConfig(\n        id=\"opencode-go\",\n        name=\"OpenCode Go\",\n        auth_type=\"api_key\",\n        # OpenCode Go mixes API surfaces by model:\n        # - GLM / Kimi use OpenAI-compatible chat completions under /v1\n        # - MiniMax models use Anthropic Messages under /v1/messages\n        # Keep the provider base at /v1 and select api_mode per-model.\n        inference_base_url=\"https://opencode.ai/zen/go/v1\",\n        api_key_env_vars=(\"OPENCODE_GO_API_KEY\",),\n        base_url_env_var=\"OPENCODE_GO_BASE_URL\",\n    ),\n    \"kilocode\": ProviderConfig(\n        id=\"kilocode\",\n        name=\"Kilo Code\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.kilo.ai/api/gateway\",\n        api_key_env_vars=(\"KILOCODE_API_KEY\",),\n        base_url_env_var=\"KILOCODE_BASE_URL\",\n    ),\n    \"huggingface\": ProviderConfig(\n        id=\"huggingface\",\n        name=\"Hugging Face\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://router.huggingface.co/v1\",\n        api_key_env_vars=(\"HF_TOKEN\",),\n        base_url_env_var=\"HF_BASE_URL\",\n    ),\n    \"xiaomi\": ProviderConfig(\n        id=\"xiaomi\",\n        name=\"Xiaomi MiMo\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://api.xiaomimimo.com/v1\",\n        api_key_env_vars=(\"XIAOMI_API_KEY\",),\n        base_url_env_var=\"XIAOMI_BASE_URL\",\n    ),\n    \"tencent-tokenhub\": ProviderConfig(\n        id=\"tencent-tokenhub\",\n        name=\"Tencent TokenHub\",\n        auth_type=\"api_key\",\n        inference_base_url=\"https://tokenhub.tencentmaas.com/v1\",\n        api_key_env_vars=(\"TOKENHUB_API_KEY\",),\n        base_url_env_var=\"TOKENHUB_BASE_URL\",\n    ),\n    \"ollama-cloud\": ProviderConfig(\n        id=\"ollama-cloud\",\n        name=\"Ollama Cloud\",\n        auth_type=\"api_key\",\n        inference_base_url=DEFAULT_OLLAMA_CLOUD_BASE_URL,\n        api_key_env_vars=(\"OLLAMA_API_KEY\",),\n        base_url_env_var=\"OLLAMA_BASE_URL\",\n    ),\n    \"bedrock\": ProviderConfig(\n        id=\"bedrock\",\n        name=\"AWS Bedrock\",\n        auth_type=\"aws_sdk\",\n        inference_base_url=\"https://bedrock-runtime.us-east-1.amazonaws.com\",\n        api_key_env_vars=(),\n        base_url_env_var=\"BEDROCK_BASE_URL\",\n    ),\n    \"azure-foundry\": ProviderConfig(\n        id=\"azure-foundry\",\n        name=\"Azure Foundry\",\n        auth_type=\"api_key\",\n        inference_base_url=\"\",  # User-provided endpoint\n        api_key_env_vars=(\"AZURE_FOUNDRY_API_KEY\",),\n        base_url_env_var=\"AZURE_FOUNDRY_BASE_URL\",\n    ),\n}\n\n# Auto-extend PROVIDER_REGISTRY with any api-key provider registered in\n# providers/ that is not already declared above.  New providers only need a\n# plugins/model-providers/<name>/ plugin — no edits to this file required.\ntry:\n    from providers import list_providers as _list_providers_for_registry\n    for _pp in _list_providers_for_registry():\n        if _pp.name in PROVIDER_REGISTRY:\n            continue\n        if _pp.auth_type != \"api_key\" or not _pp.env_vars:\n            continue\n        # Skip providers that need custom token resolution or are special-cased\n        # in resolve_provider() (copilot/kimi/zai have bespoke token refresh;\n        # openrouter/custom are aggregator/user-supplied and handled outside\n        # the registry — adding them here breaks runtime_provider resolution\n        # that relies on `openrouter not in PROVIDER_REGISTRY`).\n        if _pp.name in {\"copilot\", \"kimi-coding\", \"kimi-coding-cn\", \"zai\", \"openrouter\", \"custom\"}:\n            continue\n        _api_key_vars = tuple(v for v in _pp.env_vars if not v.endswith(\"_BASE_URL\") and not v.endswith(\"_URL\"))\n        _base_url_var = next((v for v in _pp.env_vars if v.endswith(\"_BASE_URL\") or v.endswith(\"_URL\")), None)\n        PROVIDER_REGISTRY[_pp.name] = ProviderConfig(\n            id=_pp.name,\n            name=_pp.display_name or _pp.name,\n            auth_type=\"api_key\",\n            inference_base_url=_pp.base_url,\n            api_key_env_vars=_api_key_vars or _pp.env_vars,\n            base_url_env_var=_base_url_var or \"\",\n        )\n        # Also register aliases so resolve_provider() resolves them\n        for _alias in _pp.aliases:\n            if _alias not in PROVIDER_REGISTRY:\n                PROVIDER_REGISTRY[_alias] = PROVIDER_REGISTRY[_pp.name]\nexcept Exception:\n    pass\n\n\n# =============================================================================\n# Anthropic Key Helper\n# =============================================================================\n\ndef get_anthropic_key() -> str:\n    \"\"\"Return the first usable Anthropic credential, or ``\"\"``.\n\n    Checks both the ``.env`` file (via ``get_env_value``) and the process\n    environment (``os.getenv``).  The fallback order mirrors the\n    ``PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars`` tuple:\n\n        ANTHROPIC_API_KEY -> ANTHROPIC_TOKEN -> CLAUDE_CODE_OAUTH_TOKEN\n    \"\"\"\n    from clawbot_cli.config import get_env_value\n\n    for var in PROVIDER_REGISTRY[\"anthropic\"].api_key_env_vars:\n        value = get_env_value(var) or os.getenv(var, \"\")\n        if value:\n            return value\n    return \"\"\n\n\n# =============================================================================\n# Kimi Code Endpoint Detection\n# =============================================================================\n\n# Kimi Code (kimi.com/code) issues keys prefixed \"sk-kimi-\" that only work\n# on api.kimi.com/coding.  Legacy keys from platform.moonshot.ai work on\n# api.moonshot.ai/v1 (the old default).  Auto-detect when user hasn't set\n# KIMI_BASE_URL explicitly.\n#\n# Note: the base URL intentionally has NO /v1 suffix.  The /coding endpoint\n# speaks the Anthropic Messages protocol, and the anthropic SDK appends\n# \"/v1/messages\" internally — so \"/coding\" + SDK suffix → \"/coding/v1/messages\"\n# (the correct target). Using \"/coding/v1\" here would produce\n# \"/coding/v1/v1/messages\" (a 404).\nKIMI_CODE_BASE_URL = \"https://api.kimi.com/coding\"\n\n\ndef _resolve_kimi_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Kimi base URL based on the API key prefix.\n\n    If the user has explicitly set KIMI_BASE_URL, that always wins.\n    Otherwise, sk-kimi- prefixed keys route to api.kimi.com/coding/v1.\n    \"\"\"\n    if env_override:\n        return env_override\n    # No key → nothing to infer from.  Return default without inspecting.\n    if not api_key:\n        return default_url\n    if api_key.startswith(\"sk-kimi-\"):\n        return KIMI_CODE_BASE_URL\n    return default_url\n\n\n\n_PLACEHOLDER_SECRET_VALUES = {\n    \"*\",\n    \"**\",\n    \"***\",\n    \"changeme\",\n    \"your_api_key\",\n    \"your-api-key\",\n    \"placeholder\",\n    \"example\",\n    \"dummy\",\n    \"null\",\n    \"none\",\n}\n\n\ndef has_usable_secret(value: Any, *, min_length: int = 4) -> bool:\n    \"\"\"Return True when a configured secret looks usable, not empty/placeholder.\"\"\"\n    if not isinstance(value, str):\n        return False\n    cleaned = value.strip()\n    if len(cleaned) < min_length:\n        return False\n    if cleaned.lower() in _PLACEHOLDER_SECRET_VALUES:\n        return False\n    return True\n\n\ndef _resolve_api_key_provider_secret(\n    provider_id: str, pconfig: ProviderConfig\n) -> tuple[str, str]:\n    \"\"\"Resolve an API-key provider's token and indicate where it came from.\"\"\"\n    if provider_id == \"copilot\":\n        # Use the dedicated copilot auth module for proper token validation\n        try:\n            from clawbot_cli.copilot_auth import resolve_copilot_token, get_copilot_api_token\n            token, source = resolve_copilot_token()\n            if token:\n                return get_copilot_api_token(token), source\n        except ValueError as exc:\n            logger.warning(\"Copilot token validation failed: %s\", exc)\n        except Exception:\n            pass\n        return \"\", \"\"\n\n    from clawbot_cli.config import get_env_value\n    for env_var in pconfig.api_key_env_vars:\n        # Check both os.environ and ~/.clawbot/.env file\n        val = (get_env_value(env_var) or \"\").strip()\n        if has_usable_secret(val):\n            return val, env_var\n\n    # Fallback: try credential pool (e.g. zai key stored via auth.json)\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(provider_id)\n        if pool and pool.has_credentials():\n            entry = pool.peek()\n            if entry:\n                key = getattr(entry, \"access_token\", \"\") or getattr(entry, \"runtime_api_key\", \"\")\n                key = str(key).strip()\n                if has_usable_secret(key):\n                    return key, f\"credential_pool:{provider_id}\"\n    except Exception:\n        pass\n\n    return \"\", \"\"\n\n\n# =============================================================================\n# Z.AI Endpoint Detection\n# =============================================================================\n\n# Z.AI has separate billing for general vs coding plans, and global vs China\n# endpoints.  A key that works on one may return \"Insufficient balance\" on\n# another.  We probe at setup time and store the working endpoint.\n# Each entry lists candidate models to try in order — newer coding plan accounts\n# may only have access to recent models (glm-5.1, glm-5v-turbo) while older\n# ones still use glm-4.7.\n\nZAI_ENDPOINTS = [\n    # (id, base_url, probe_models, label)\n    (\"global\",        \"https://api.z.ai/api/paas/v4\",        [\"glm-5\"],   \"Global\"),\n    (\"cn\",            \"https://open.bigmodel.cn/api/paas/v4\", [\"glm-5\"],   \"China\"),\n    (\"coding-global\", \"https://api.z.ai/api/coding/paas/v4\",  [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"Global (Coding Plan)\"),\n    (\"coding-cn\",     \"https://open.bigmodel.cn/api/coding/paas/v4\", [\"glm-5.1\", \"glm-5v-turbo\", \"glm-4.7\"], \"China (Coding Plan)\"),\n]\n\n\ndef detect_zai_endpoint(api_key: str, timeout: float = 8.0) -> Optional[Dict[str, str]]:\n    \"\"\"Probe z.ai endpoints to find one that accepts this API key.\n\n    Returns {\"id\": ..., \"base_url\": ..., \"model\": ..., \"label\": ...} for the\n    first working endpoint, or None if all fail.  For endpoints with multiple\n    candidate models, tries each in order and returns the first that succeeds.\n    \"\"\"\n    for ep_id, base_url, probe_models, label in ZAI_ENDPOINTS:\n        for model in probe_models:\n            try:\n                resp = httpx.post(\n                    f\"{base_url}/chat/completions\",\n                    headers={\n                        \"Authorization\": f\"Bearer {api_key}\",\n                        \"Content-Type\": \"application/json\",\n                    },\n                    json={\n                        \"model\": model,\n                        \"stream\": False,\n                        \"max_tokens\": 1,\n                        \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}],\n                    },\n                    timeout=timeout,\n                )\n                if resp.status_code == 200:\n                    logger.debug(\"Z.AI endpoint probe: %s (%s) model=%s OK\", ep_id, base_url, model)\n                    return {\n                        \"id\": ep_id,\n                        \"base_url\": base_url,\n                        \"model\": model,\n                        \"label\": label,\n                    }\n                logger.debug(\"Z.AI endpoint probe: %s model=%s returned %s\", ep_id, model, resp.status_code)\n            except Exception as exc:\n                logger.debug(\"Z.AI endpoint probe: %s model=%s failed: %s\", ep_id, model, exc)\n    return None\n\n\ndef _resolve_zai_base_url(api_key: str, default_url: str, env_override: str) -> str:\n    \"\"\"Return the correct Z.AI base URL by probing endpoints.\n\n    If the user has explicitly set GLM_BASE_URL, that always wins.\n    Otherwise, probe the candidate endpoints to find one that accepts the\n    key.  The detected endpoint is cached in provider state (auth.json) keyed\n    on a hash of the API key so subsequent starts skip the probe.\n    \"\"\"\n    if env_override:\n        return env_override\n\n    # No API key set → don't probe (would fire N×M HTTPS requests with an\n    # empty Bearer token, all returning 401).  This path is hit during\n    # auxiliary-client auto-detection when the user has no Z.AI credentials\n    # at all — the caller discards the result immediately, so the probe is\n    # pure latency for every AIAgent construction.\n    if not api_key:\n        return default_url\n\n    # Check provider-state cache for a previously-detected endpoint.\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"zai\") or {}\n    cached = state.get(\"detected_endpoint\")\n    if isinstance(cached, dict) and cached.get(\"base_url\"):\n        key_hash = cached.get(\"key_hash\", \"\")\n        if key_hash == hashlib.sha256(api_key.encode()).hexdigest()[:16]:\n            logger.debug(\"Z.AI: using cached endpoint %s\", cached[\"base_url\"])\n            return cached[\"base_url\"]\n\n    # Probe — may take up to ~8s per endpoint.\n    detected = detect_zai_endpoint(api_key)\n    if detected and detected.get(\"base_url\"):\n        # Persist the detection result keyed on the API key hash.\n        key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]\n        state[\"detected_endpoint\"] = {\n            \"base_url\": detected[\"base_url\"],\n            \"endpoint_id\": detected.get(\"id\", \"\"),\n            \"model\": detected.get(\"model\", \"\"),\n            \"label\": detected.get(\"label\", \"\"),\n            \"key_hash\": key_hash,\n        }\n        _save_provider_state(auth_store, \"zai\", state)\n        logger.info(\"Z.AI: auto-detected endpoint %s (%s)\", detected[\"label\"], detected[\"base_url\"])\n        return detected[\"base_url\"]\n\n    logger.debug(\"Z.AI: probe failed, falling back to default %s\", default_url)\n    return default_url\n\n\n# =============================================================================\n# Error Types\n# =============================================================================\n\nclass AuthError(RuntimeError):\n    \"\"\"Structured auth error with UX mapping hints.\"\"\"\n\n    def __init__(\n        self,\n        message: str,\n        *,\n        provider: str = \"\",\n        code: Optional[str] = None,\n        relogin_required: bool = False,\n    ) -> None:\n        super().__init__(message)\n        self.provider = provider\n        self.code = code\n        self.relogin_required = relogin_required\n\n\ndef format_auth_error(error: Exception) -> str:\n    \"\"\"Map auth failures to concise user-facing guidance.\"\"\"\n    if not isinstance(error, AuthError):\n        return str(error)\n\n    if error.relogin_required:\n        return f\"{error} Run `clawbot model` to re-authenticate.\"\n\n    if error.code == \"subscription_required\":\n        return (\n            \"No active paid subscription found on Soam Portal. \"\n            \"Please purchase/activate a subscription, then retry.\"\n        )\n\n    if error.code == \"insufficient_credits\":\n        return (\n            \"Subscription credits are exhausted. \"\n            \"Top up/renew credits in Soam Portal, then retry.\"\n        )\n\n    if error.code == \"temporarily_unavailable\":\n        return f\"{error} Please retry in a few seconds.\"\n\n    return str(error)\n\n\ndef _token_fingerprint(token: Any) -> Optional[str]:\n    \"\"\"Return a short hash fingerprint for telemetry without leaking token bytes.\"\"\"\n    if not isinstance(token, str):\n        return None\n    cleaned = token.strip()\n    if not cleaned:\n        return None\n    return hashlib.sha256(cleaned.encode(\"utf-8\")).hexdigest()[:12]\n\n\ndef _oauth_trace_enabled() -> bool:\n    raw = os.getenv(\"CLAWBOT_OAUTH_TRACE\", \"\").strip().lower()\n    return raw in {\"1\", \"true\", \"yes\", \"on\"}\n\n\ndef _oauth_trace(event: str, *, sequence_id: Optional[str] = None, **fields: Any) -> None:\n    if not _oauth_trace_enabled():\n        return\n    payload: Dict[str, Any] = {\"event\": event}\n    if sequence_id:\n        payload[\"sequence_id\"] = sequence_id\n    payload.update(fields)\n    logger.info(\"oauth_trace %s\", json.dumps(payload, sort_keys=True, ensure_ascii=False))\n\n\n# =============================================================================\n# Auth Store — persistence layer for ~/.clawbot/auth.json\n# =============================================================================\n\ndef _auth_file_path() -> Path:\n    path = get_clawbot_home() / \"auth.json\"\n    # Seat belt: if pytest is running and CLAWBOT_HOME resolves to the real\n    # user's auth store, refuse rather than silently corrupt it. This catches\n    # tests that forgot to monkeypatch CLAWBOT_HOME, tests invoked without the\n    # clawbotic conftest, or sandbox escapes via threads/subprocesses. In\n    # production (no PYTEST_CURRENT_TEST) this is a single dict lookup.\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_auth = (Path.home() / \".clawbot\" / \"auth.json\").resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_auth:\n            raise RuntimeError(\n                f\"Refusing to touch real user auth store during test run: {path}. \"\n                \"Set CLAWBOT_HOME to a tmp_path in your test fixture, or run \"\n                \"via scripts/run_tests.sh for clawbotic CI-parity env.\"\n            )\n    return path\n\n\ndef _global_auth_file_path() -> Optional[Path]:\n    \"\"\"Return the global-root auth.json when the process is in profile mode.\n\n    Returns ``None`` when the profile and global root resolve to the same\n    directory (classic mode, or custom CLAWBOT_HOME that is not a profile).\n    Used by read-only fallback paths so providers authed at the root are\n    visible to profile processes that haven't configured them locally.\n\n    See issue #18594 follow-up (credential_pool shadowing).\n    \"\"\"\n    try:\n        from clawbot_constants import get_default_clawbot_root\n        global_root = get_default_clawbot_root()\n    except Exception:\n        return None\n    profile_home = get_clawbot_home()\n    try:\n        if profile_home.resolve(strict=False) == global_root.resolve(strict=False):\n            return None\n    except Exception:\n        if profile_home == global_root:\n            return None\n    # No pytest seat belt here: this is a pure read-only path, and\n    # ``_load_global_auth_store()`` wraps the read in a try/except so an\n    # unreadable global file can never break the profile process.  The\n    # write-side seat belt still lives on ``_auth_file_path()`` where it\n    # belongs (that's what protects the real user's auth store from being\n    # corrupted by a mis-configured test).\n    return global_root / \"auth.json\"\n\n\ndef _load_global_auth_store() -> Dict[str, Any]:\n    \"\"\"Load the global-root auth store (read-only fallback).\n\n    Returns an empty dict when no global fallback exists (classic mode,\n    or the global auth.json is absent). Never raises on missing file.\n\n    Seat belt: under pytest, refuses to read the real user's\n    ``~/.clawbot/auth.json`` even when CLAWBOT_HOME is set to a profile\n    path. The clawbotic conftest does not redirect ``HOME``, so\n    ``get_default_clawbot_root()`` for a profile-shaped CLAWBOT_HOME can\n    still resolve to the real user's home on a dev machine. That would\n    leak real credentials into tests. This guard uses the unmodified\n    ``HOME`` env var (what ``os.path.expanduser('~')`` would resolve to),\n    not ``Path.home()``, because ``Path.home`` is sometimes monkeypatched\n    by fixtures that want to relocate the global root to a tmp path.\n    \"\"\"\n    global_path = _global_auth_file_path()\n    if global_path is None or not global_path.exists():\n        return {}\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        real_home_env = os.environ.get(\"HOME\", \"\")\n        if real_home_env:\n            real_root = Path(real_home_env) / \".clawbot\" / \"auth.json\"\n            try:\n                if global_path.resolve(strict=False) == real_root.resolve(strict=False):\n                    return {}\n            except Exception:\n                pass\n    try:\n        return _load_auth_store(global_path)\n    except Exception:\n        # A malformed global store must not break profile reads. The\n        # profile's own auth store is still authoritative.\n        return {}\n\n\ndef _auth_lock_path() -> Path:\n    return _auth_file_path().with_suffix(\".lock\")\n\n\n_auth_lock_holder = threading.local()\n\n\n@contextmanager\ndef _file_lock(\n    lock_path: Path,\n    holder: threading.local,\n    timeout_seconds: float,\n    timeout_message: str,\n):\n    \"\"\"Cross-process advisory flock helper.\n\n    Reentrant per-thread via ``holder.depth``. Falls back to a depth-only\n    guard when neither ``fcntl`` nor ``msvcrt`` is available (rare).\n    Callers supply their own ``threading.local`` so independent locks\n    (e.g. profile auth.json vs shared Soam store) don't share reentrancy\n    state — that would let one lock's reentrant acquisition silently skip\n    the other's kernel-level flock.\n    \"\"\"\n    if getattr(holder, \"depth\", 0) > 0:\n        holder.depth += 1\n        try:\n            yield\n        finally:\n            holder.depth -= 1\n        return\n\n    lock_path.parent.mkdir(parents=True, exist_ok=True)\n\n    if fcntl is None and msvcrt is None:\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n        return\n\n    # On Windows, msvcrt.locking needs the file to have content and the\n    # file pointer at position 0. Ensure the lock file has at least 1 byte.\n    if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):\n        lock_path.write_text(\" \", encoding=\"utf-8\")\n\n    with lock_path.open(\"r+\" if msvcrt else \"a+\", encoding=\"utf-8\") as lock_file:\n        deadline = time.monotonic() + max(1.0, timeout_seconds)\n        while True:\n            try:\n                if fcntl:\n                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)\n                else:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)\n                break\n            except (BlockingIOError, OSError, PermissionError):\n                if time.monotonic() >= deadline:\n                    raise TimeoutError(timeout_message)\n                time.sleep(0.05)\n\n        holder.depth = 1\n        try:\n            yield\n        finally:\n            holder.depth = 0\n            if fcntl:\n                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n            elif msvcrt:\n                try:\n                    lock_file.seek(0)\n                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)\n                except (OSError, IOError):\n                    pass\n\n\n@contextmanager\ndef _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-process advisory lock for auth.json reads+writes.  Reentrant.\n\n    Lock ordering invariant: when this lock is held together with\n    ``_soam_shared_store_lock``, acquire ``_auth_store_lock`` FIRST\n    (outer) and the shared Soam lock SECOND (inner). All runtime\n    refresh paths follow this order; violating it risks deadlock\n    against a concurrent import on the shared store.\n    \"\"\"\n    with _file_lock(\n        _auth_lock_path(),\n        _auth_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for auth store lock\",\n    ):\n        yield\n\n\ndef _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:\n    auth_file = auth_file or _auth_file_path()\n    if not auth_file.exists():\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    try:\n        raw = json.loads(auth_file.read_text())\n    except Exception as exc:\n        corrupt_path = auth_file.with_suffix(\".json.corrupt\")\n        try:\n            import shutil\n            shutil.copy2(auth_file, corrupt_path)\n        except Exception:\n            pass\n        logger.warning(\n            \"auth: failed to parse %s (%s) — starting with empty store. \"\n            \"Corrupt file preserved at %s\",\n            auth_file, exc, corrupt_path,\n        )\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n    if isinstance(raw, dict) and (\n        isinstance(raw.get(\"providers\"), dict)\n        or isinstance(raw.get(\"credential_pool\"), dict)\n    ):\n        raw.setdefault(\"providers\", {})\n        return raw\n\n    # Migrate from PR's \"systems\" format if present\n    if isinstance(raw, dict) and isinstance(raw.get(\"systems\"), dict):\n        systems = raw[\"systems\"]\n        providers = {}\n        if \"soam_portal\" in systems:\n            providers[\"soam\"] = systems[\"soam_portal\"]\n        return {\"version\": AUTH_STORE_VERSION, \"providers\": providers,\n                \"active_provider\": \"soam\" if providers else None}\n\n    return {\"version\": AUTH_STORE_VERSION, \"providers\": {}}\n\n\ndef _save_auth_store(auth_store: Dict[str, Any]) -> Path:\n    auth_file = _auth_file_path()\n    auth_file.parent.mkdir(parents=True, exist_ok=True)\n    # Tighten parent dir to 0o700 so siblings can't traverse to creds.\n    # No-op on Windows (POSIX mode bits not enforced); ignore failures.\n    try:\n        os.chmod(auth_file.parent, 0o700)\n    except OSError:\n        pass\n    auth_store[\"version\"] = AUTH_STORE_VERSION\n    auth_store[\"updated_at\"] = datetime.now(timezone.utc).isoformat()\n    payload = json.dumps(auth_store, indent=2) + \"\\n\"\n    tmp_path = auth_file.with_name(f\"{auth_file.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    try:\n        # Create with 0o600 atomically via os.open(O_EXCL) + fdopen to close\n        # the TOCTOU window where default umask (often 0o644) briefly exposed\n        # OAuth tokens to other local users between open() and chmod().\n        # Mirrors agent/google_oauth.py (#19673) and tools/mcp_oauth.py (#21148).\n        fd = os.open(\n            str(tmp_path),\n            os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n            stat.S_IRUSR | stat.S_IWUSR,\n        )\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as handle:\n            handle.write(payload)\n            handle.flush()\n            os.fsync(handle.fileno())\n        atomic_replace(tmp_path, auth_file)\n        try:\n            dir_fd = os.open(str(auth_file.parent), os.O_RDONLY)\n        except OSError:\n            dir_fd = None\n        if dir_fd is not None:\n            try:\n                os.fsync(dir_fd)\n            finally:\n                os.close(dir_fd)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    # Restrict file permissions to owner only\n    try:\n        auth_file.chmod(stat.S_IRUSR | stat.S_IWUSR)\n    except OSError:\n        pass\n    return auth_file\n\n\ndef _load_provider_state(auth_store: Dict[str, Any], provider_id: str) -> Optional[Dict[str, Any]]:\n    providers = auth_store.get(\"providers\")\n    if not isinstance(providers, dict):\n        return None\n    state = providers.get(provider_id)\n    return dict(state) if isinstance(state, dict) else None\n\n\ndef _save_provider_state(auth_store: Dict[str, Any], provider_id: str, state: Dict[str, Any]) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    auth_store[\"active_provider\"] = provider_id\n\n\ndef _store_provider_state(\n    auth_store: Dict[str, Any],\n    provider_id: str,\n    state: Dict[str, Any],\n    *,\n    set_active: bool = True,\n) -> None:\n    providers = auth_store.setdefault(\"providers\", {})\n    if not isinstance(providers, dict):\n        auth_store[\"providers\"] = {}\n        providers = auth_store[\"providers\"]\n    providers[provider_id] = state\n    if set_active:\n        auth_store[\"active_provider\"] = provider_id\n\n\ndef is_known_auth_provider(provider_id: str) -> bool:\n    normalized = (provider_id or \"\").strip().lower()\n    return normalized in PROVIDER_REGISTRY or normalized in SERVICE_PROVIDER_NAMES\n\n\ndef get_auth_provider_display_name(provider_id: str) -> str:\n    normalized = (provider_id or \"\").strip().lower()\n    if normalized in PROVIDER_REGISTRY:\n        return PROVIDER_REGISTRY[normalized].name\n    return SERVICE_PROVIDER_NAMES.get(normalized, provider_id)\n\n\ndef read_credential_pool(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Return the persisted credential pool, or one provider slice.\n\n    In profile mode, the profile's credential pool is authoritative. If a\n    provider has no entries in the profile, entries from the global-root\n    ``auth.json`` are used as a read-only fallback — so workers spawned in a\n    profile can see providers that were only authenticated at global scope.\n\n    Profile entries always win: the global fallback only applies per-provider\n    when the profile has zero entries for that provider. Once the user runs\n    ``clawbot auth add <provider>`` inside the profile, profile entries\n    fully shadow global for that provider on the next read.\n\n    Writes always go to the profile (``write_credential_pool`` is unchanged).\n    See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        pool = {}\n\n    global_pool: Dict[str, Any] = {}\n    global_store = _load_global_auth_store()\n    maybe_global_pool = global_store.get(\"credential_pool\") if global_store else None\n    if isinstance(maybe_global_pool, dict):\n        global_pool = maybe_global_pool\n\n    if provider_id is None:\n        merged = dict(pool)\n        for gp_key, gp_entries in global_pool.items():\n            if not isinstance(gp_entries, list) or not gp_entries:\n                continue\n            # Per-provider shadowing: profile wins whenever it has ANY entries.\n            existing = merged.get(gp_key)\n            if isinstance(existing, list) and existing:\n                continue\n            merged[gp_key] = list(gp_entries)\n        return merged\n\n    provider_entries = pool.get(provider_id)\n    if isinstance(provider_entries, list) and provider_entries:\n        return list(provider_entries)\n    # Profile has no entries for this provider — fall back to global.\n    global_entries = global_pool.get(provider_id)\n    return list(global_entries) if isinstance(global_entries, list) else []\n\n\ndef write_credential_pool(provider_id: str, entries: List[Dict[str, Any]]) -> Path:\n    \"\"\"Persist one provider's credential pool under auth.json.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n        pool[provider_id] = list(entries)\n        return _save_auth_store(auth_store)\n\n\ndef suppress_credential_source(provider_id: str, source: str) -> None:\n    \"\"\"Mark a credential source as suppressed so it won't be re-seeded.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.setdefault(\"suppressed_sources\", {})\n        provider_list = suppressed.setdefault(provider_id, [])\n        if source not in provider_list:\n            provider_list.append(source)\n        _save_auth_store(auth_store)\n\n\ndef is_source_suppressed(provider_id: str, source: str) -> bool:\n    \"\"\"Check if a credential source has been suppressed by the user.\"\"\"\n    try:\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\", {})\n        return source in suppressed.get(provider_id, [])\n    except Exception:\n        return False\n\n\ndef unsuppress_credential_source(provider_id: str, source: str) -> bool:\n    \"\"\"Clear a suppression marker so the source will be re-seeded on the next load.\n\n    Returns True if a marker was cleared, False if no marker existed.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        suppressed = auth_store.get(\"suppressed_sources\")\n        if not isinstance(suppressed, dict):\n            return False\n        provider_list = suppressed.get(provider_id)\n        if not isinstance(provider_list, list) or source not in provider_list:\n            return False\n        provider_list.remove(source)\n        if not provider_list:\n            suppressed.pop(provider_id, None)\n        if not suppressed:\n            auth_store.pop(\"suppressed_sources\", None)\n        _save_auth_store(auth_store)\n        return True\n\n\ndef get_provider_auth_state(provider_id: str) -> Optional[Dict[str, Any]]:\n    \"\"\"Return persisted auth state for a provider, or None.\n\n    In profile mode, falls back to the global-root ``auth.json`` when the\n    profile has no state for this provider. Profile state always wins when\n    present. Writes (``_save_auth_store`` / ``persist_*_credentials``) are\n    unchanged — they still target the profile only. This mirrors\n    ``read_credential_pool``'s per-provider shadowing semantics so that\n    ``_seed_from_singletons`` can reseed a profile's credential pool from\n    global-scope provider state (e.g. a globally-authenticated Anthropic\n    OAuth or Soam device-code session). See issue #18594 follow-up.\n    \"\"\"\n    auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, provider_id)\n    if state is not None:\n        return state\n    global_store = _load_global_auth_store()\n    if not global_store:\n        return None\n    return _load_provider_state(global_store, provider_id)\n\n\ndef get_active_provider() -> Optional[str]:\n    \"\"\"Return the currently active provider ID from auth store.\"\"\"\n    auth_store = _load_auth_store()\n    return auth_store.get(\"active_provider\")\n\n\ndef is_provider_explicitly_configured(provider_id: str) -> bool:\n    \"\"\"Return True only if the user has explicitly configured this provider.\n\n    Checks:\n      1. active_provider in auth.json matches\n      2. model.provider in config.yaml matches\n      3. Provider-specific env vars are set (e.g. ANTHROPIC_API_KEY)\n\n    This is used to gate auto-discovery of external credentials (e.g.\n    Claude Code's ~/.claude/.credentials.json) so they are never used\n    without the user's explicit choice.  See PR #4210 for the same\n    pattern applied to the setup wizard gate.\n    \"\"\"\n    normalized = (provider_id or \"\").strip().lower()\n\n    # 1. Check auth.json active_provider\n    try:\n        auth_store = _load_auth_store()\n        active = (auth_store.get(\"active_provider\") or \"\").strip().lower()\n        if active and active == normalized:\n            return True\n    except Exception:\n        pass\n\n    # 2. Check config.yaml model.provider\n    try:\n        from clawbot_cli.config import load_config\n        cfg = load_config()\n        model_cfg = cfg.get(\"model\")\n        if isinstance(model_cfg, dict):\n            cfg_provider = (model_cfg.get(\"provider\") or \"\").strip().lower()\n            if cfg_provider == normalized:\n                return True\n    except Exception:\n        pass\n\n    # 3. Check provider-specific env vars\n    # Exclude CLAUDE_CODE_OAUTH_TOKEN — it's set by Claude Code itself,\n    # not by the user explicitly configuring anthropic in Clawbot.\n    _IMPLICIT_ENV_VARS = {\"CLAUDE_CODE_OAUTH_TOKEN\"}\n    pconfig = PROVIDER_REGISTRY.get(normalized)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        for env_var in pconfig.api_key_env_vars:\n            if env_var in _IMPLICIT_ENV_VARS:\n                continue\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return True\n\n    return False\n\n\ndef clear_provider_auth(provider_id: Optional[str] = None) -> bool:\n    \"\"\"\n    Clear auth state for a provider. Used by `clawbot logout`.\n    If provider_id is None, clears the active provider.\n    Returns True if something was cleared.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        target = provider_id or auth_store.get(\"active_provider\")\n        if not target:\n            return False\n\n        providers = auth_store.get(\"providers\", {})\n        if not isinstance(providers, dict):\n            providers = {}\n            auth_store[\"providers\"] = providers\n\n        pool = auth_store.get(\"credential_pool\")\n        if not isinstance(pool, dict):\n            pool = {}\n            auth_store[\"credential_pool\"] = pool\n\n        cleared = False\n        if target in providers:\n            del providers[target]\n            cleared = True\n        if target in pool:\n            del pool[target]\n            cleared = True\n\n        if auth_store.get(\"active_provider\") == target:\n            auth_store[\"active_provider\"] = None\n            cleared = True\n\n        if not cleared:\n            return False\n        _save_auth_store(auth_store)\n    return True\n\n\ndef deactivate_provider() -> None:\n    \"\"\"\n    Clear active_provider in auth.json without deleting credentials.\n    Used when the user switches to a non-OAuth provider (OpenRouter, custom)\n    so auto-resolution doesn't keep picking the OAuth provider.\n    \"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = None\n        _save_auth_store(auth_store)\n\n\n# =============================================================================\n# Provider Resolution — picks which provider to use\n# =============================================================================\n\n\ndef _get_config_hint_for_unknown_provider(provider_name: str) -> str:\n    \"\"\"Return a helpful hint string when provider resolution fails.\n\n    Checks for common config.yaml mistakes (malformed custom_providers, etc.)\n    and returns a human-readable diagnostic, or empty string if nothing found.\n    \"\"\"\n    try:\n        from clawbot_cli.config import validate_config_structure\n        issues = validate_config_structure()\n        if not issues:\n            return \"\"\n\n        lines = [\"Config issue detected — run 'clawbot doctor' for full diagnostics:\"]\n        for ci in issues:\n            prefix = \"ERROR\" if ci.severity == \"error\" else \"WARNING\"\n            lines.append(f\"  [{prefix}] {ci.message}\")\n            # Show first line of hint\n            first_hint = ci.hint.splitlines()[0] if ci.hint else \"\"\n            if first_hint:\n                lines.append(f\"    → {first_hint}\")\n        return \"\\n\".join(lines)\n    except Exception:\n        return \"\"\n\n\ndef resolve_provider(\n    requested: Optional[str] = None,\n    *,\n    explicit_api_key: Optional[str] = None,\n    explicit_base_url: Optional[str] = None,\n) -> str:\n    \"\"\"\n    Determine which inference provider to use.\n\n    Priority (when requested=\"auto\" or None):\n    1. active_provider in auth.json with valid credentials\n    2. Explicit CLI api_key/base_url -> \"openrouter\"\n    3. OPENAI_API_KEY or OPENROUTER_API_KEY env vars -> \"openrouter\"\n    4. Provider-specific API keys (GLM, Kimi, MiniMax) -> that provider\n    5. Fallback: \"openrouter\"\n    \"\"\"\n    normalized = (requested or \"auto\").strip().lower()\n\n    # Normalize provider aliases\n    _PROVIDER_ALIASES = {\n        \"glm\": \"zai\", \"z-ai\": \"zai\", \"z.ai\": \"zai\", \"zhipu\": \"zai\",\n        \"google\": \"gemini\", \"google-gemini\": \"gemini\", \"google-ai-studio\": \"gemini\",\n        \"x-ai\": \"xai\", \"x.ai\": \"xai\", \"grok\": \"xai\",\n        \"xai-oauth\": \"xai-oauth\", \"x-ai-oauth\": \"xai-oauth\",\n        \"grok-oauth\": \"xai-oauth\", \"xai-grok-oauth\": \"xai-oauth\",\n        \"kimi\": \"kimi-coding\", \"kimi-for-coding\": \"kimi-coding\", \"moonshot\": \"kimi-coding\",\n        \"kimi-cn\": \"kimi-coding-cn\", \"moonshot-cn\": \"kimi-coding-cn\",\n        \"step\": \"stepfun\", \"stepfun-coding-plan\": \"stepfun\",\n        \"arcee-ai\": \"arcee\", \"arceeai\": \"arcee\",\n        \"gmi-cloud\": \"gmi\", \"gmicloud\": \"gmi\",\n        \"minimax-china\": \"minimax-cn\", \"minimax_cn\": \"minimax-cn\",\n        \"minimax-portal\": \"minimax-oauth\", \"minimax-global\": \"minimax-oauth\", \"minimax_oauth\": \"minimax-oauth\",\n        \"alibaba_coding\": \"alibaba-coding-plan\", \"alibaba-coding\": \"alibaba-coding-plan\",\n        \"alibaba_coding_plan\": \"alibaba-coding-plan\",\n        \"claude\": \"anthropic\", \"claude-code\": \"anthropic\",\n        \"github\": \"copilot\", \"github-copilot\": \"copilot\",\n        \"github-models\": \"copilot\", \"github-model\": \"copilot\",\n        \"github-copilot-acp\": \"copilot-acp\", \"copilot-acp-agent\": \"copilot-acp\",\n        \"aigateway\": \"ai-gateway\", \"vercel\": \"ai-gateway\", \"vercel-ai-gateway\": \"ai-gateway\",\n        \"opencode\": \"opencode-zen\", \"zen\": \"opencode-zen\",\n        \"qwen-portal\": \"qwen-oauth\", \"qwen-cli\": \"qwen-oauth\", \"qwen-oauth\": \"qwen-oauth\", \"google-gemini-cli\": \"google-gemini-cli\", \"gemini-cli\": \"google-gemini-cli\", \"gemini-oauth\": \"google-gemini-cli\",\n        \"hf\": \"huggingface\", \"hugging-face\": \"huggingface\", \"huggingface-hub\": \"huggingface\",\n        \"mimo\": \"xiaomi\", \"xiaomi-mimo\": \"xiaomi\",\n        \"tencent\": \"tencent-tokenhub\", \"tokenhub\": \"tencent-tokenhub\",\n        \"tencent-cloud\": \"tencent-tokenhub\", \"tencentmaas\": \"tencent-tokenhub\",\n        \"aws\": \"bedrock\", \"aws-bedrock\": \"bedrock\", \"amazon-bedrock\": \"bedrock\", \"amazon\": \"bedrock\",\n        \"go\": \"opencode-go\", \"opencode-go-sub\": \"opencode-go\",\n        \"kilo\": \"kilocode\", \"kilo-code\": \"kilocode\", \"kilo-gateway\": \"kilocode\",\n        \"lmstudio\": \"lmstudio\", \"lm-studio\": \"lmstudio\", \"lm_studio\": \"lmstudio\",\n        # Local server aliases — route through the generic custom provider\n        \"ollama\": \"custom\", \"ollama_cloud\": \"ollama-cloud\",\n        \"vllm\": \"custom\", \"llamacpp\": \"custom\",\n        \"llama.cpp\": \"custom\", \"llama-cpp\": \"custom\",\n    }\n    # Extend with aliases declared in plugins/model-providers/<name>/ that aren't already mapped.\n    # This keeps providers/ as the single source for new aliases while the\n    # hardcoded dict above remains authoritative for existing ones.\n    try:\n        from providers import list_providers as _lp\n        for _pp in _lp():\n            for _alias in _pp.aliases:\n                if _alias not in _PROVIDER_ALIASES:\n                    _PROVIDER_ALIASES[_alias] = _pp.name\n    except Exception:\n        pass\n    normalized = _PROVIDER_ALIASES.get(normalized, normalized)\n\n    if normalized == \"openrouter\":\n        return \"openrouter\"\n    if normalized == \"custom\":\n        return \"custom\"\n    if normalized in PROVIDER_REGISTRY:\n        return normalized\n    if normalized != \"auto\":\n        # Check for common config.yaml issues that cause this error\n        _config_hint = _get_config_hint_for_unknown_provider(normalized)\n        msg = f\"Unknown provider '{normalized}'.\"\n        if _config_hint:\n            msg += f\"\\n\\n{_config_hint}\"\n        else:\n            msg += \" Check 'clawbot model' for available providers, or run 'clawbot doctor' to diagnose config issues.\"\n        raise AuthError(msg, code=\"invalid_provider\")\n\n    # Explicit one-off CLI creds always mean openrouter/custom\n    if explicit_api_key or explicit_base_url:\n        return \"openrouter\"\n\n    # Check auth store for an active OAuth provider\n    try:\n        auth_store = _load_auth_store()\n        active = auth_store.get(\"active_provider\")\n        if active and active in PROVIDER_REGISTRY:\n            status = get_auth_status(active)\n            if status.get(\"logged_in\"):\n                return active\n    except Exception as e:\n        logger.debug(\"Could not detect active auth provider: %s\", e)\n\n    if has_usable_secret(os.getenv(\"OPENAI_API_KEY\")) or has_usable_secret(os.getenv(\"OPENROUTER_API_KEY\")):\n        return \"openrouter\"\n\n    # Auto-detect API-key providers by checking their env vars\n    for pid, pconfig in PROVIDER_REGISTRY.items():\n        if pconfig.auth_type != \"api_key\":\n            continue\n        # GitHub tokens are commonly present for repo/tool access but should not\n        # hijack inference auto-selection unless the user explicitly chooses\n        # Copilot/GitHub Models as the provider. LM Studio is a local server\n        # whose availability isn't implied by LM_API_KEY presence (it may be\n        # offline, and the no-auth setup uses a placeholder value), so it\n        # also requires explicit selection.\n        if pid in {\"copilot\", \"lmstudio\"}:\n            continue\n        for env_var in pconfig.api_key_env_vars:\n            if has_usable_secret(os.getenv(env_var, \"\")):\n                return pid\n\n    # AWS Bedrock — detect via boto3 credential chain (IAM roles, SSO, env vars).\n    # This runs after API-key providers so explicit keys always win.\n    try:\n        from agent.bedrock_adapter import has_aws_credentials\n        if has_aws_credentials():\n            return \"bedrock\"\n    except ImportError:\n        pass  # boto3 not installed — skip Bedrock auto-detection\n\n    raise AuthError(\n        \"No inference provider configured. Run 'clawbot model' to choose a \"\n        \"provider and model, or set an API key (OPENROUTER_API_KEY, \"\n        \"OPENAI_API_KEY, etc.) in ~/.clawbot/.env.\",\n        code=\"no_provider_configured\",\n    )\n\n\n# =============================================================================\n# Timestamp / TTL helpers\n# =============================================================================\n\ndef _parse_iso_timestamp(value: Any) -> Optional[float]:\n    if not isinstance(value, str) or not value:\n        return None\n    text = value.strip()\n    if not text:\n        return None\n    if text.endswith(\"Z\"):\n        text = text[:-1] + \"+00:00\"\n    try:\n        parsed = datetime.fromisoformat(text)\n    except Exception:\n        return None\n    if parsed.tzinfo is None:\n        parsed = parsed.replace(tzinfo=timezone.utc)\n    return parsed.timestamp()\n\n\ndef _is_expiring(expires_at_iso: Any, skew_seconds: int) -> bool:\n    expires_epoch = _parse_iso_timestamp(expires_at_iso)\n    if expires_epoch is None:\n        return True\n    return expires_epoch <= (time.time() + skew_seconds)\n\n\ndef _coerce_ttl_seconds(expires_in: Any) -> int:\n    try:\n        ttl = int(expires_in)\n    except Exception:\n        ttl = 0\n    return max(0, ttl)\n\n\ndef _optional_base_url(value: Any) -> Optional[str]:\n    if not isinstance(value, str):\n        return None\n    cleaned = value.strip().rstrip(\"/\")\n    return cleaned if cleaned else None\n\n\ndef _decode_jwt_claims(token: Any) -> Dict[str, Any]:\n    if not isinstance(token, str) or token.count(\".\") != 2:\n        return {}\n    payload = token.split(\".\")[1]\n    payload += \"=\" * ((4 - len(payload) % 4) % 4)\n    try:\n        raw = base64.urlsafe_b64decode(payload.encode(\"utf-8\"))\n        claims = json.loads(raw.decode(\"utf-8\"))\n    except Exception:\n        return {}\n    return claims if isinstance(claims, dict) else {}\n\n\ndef _scope_values(raw_scope: Any) -> set[str]:\n    # OAuth token responses normally return a space-separated string. Keep\n    # collection support for JWT ``scp`` claims and older stored test fixtures.\n    scopes: set[str] = set()\n    if isinstance(raw_scope, str):\n        for part in raw_scope.replace(\",\", \" \").split():\n            cleaned = part.strip()\n            if cleaned:\n                scopes.add(cleaned)\n    elif isinstance(raw_scope, (list, tuple, set, frozenset)):\n        for item in raw_scope:\n            if isinstance(item, str):\n                scopes.update(_scope_values(item))\n    return scopes\n\n\ndef _soam_legacy_session_keys_forced() -> bool:\n    return is_truthy_value(os.getenv(SOAM_LEGACY_SESSION_KEYS_ENV), default=False)\n\n\ndef _soam_scope_has_invoke(raw_scope: Any) -> bool:\n    return SOAM_INFERENCE_INVOKE_SCOPE in _scope_values(raw_scope)\n\n\ndef _normalize_soam_inference_auth_mode(inference_auth_mode: Optional[str]) -> str:\n    mode = str(inference_auth_mode or SOAM_INFERENCE_AUTH_MODE_AUTO).strip().lower()\n    if mode not in SOAM_INFERENCE_AUTH_MODES:\n        allowed = \", \".join(sorted(SOAM_INFERENCE_AUTH_MODES))\n        raise ValueError(\n            \"Invalid Soam inference auth mode \"\n            f\"{inference_auth_mode!r}; expected one of: {allowed}\"\n        )\n    return mode\n\n\ndef _soam_invoke_jwt_status(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> Optional[str]:\n    \"\"\"Return None when the token can be used for inference, else a reason.\"\"\"\n    claims = _decode_jwt_claims(token)\n    if not claims:\n        return \"access_token_not_jwt\"\n    scopes = (\n        _scope_values(scope)\n        | _scope_values(claims.get(\"scope\"))\n        | _scope_values(claims.get(\"scp\"))\n    )\n    if SOAM_INFERENCE_INVOKE_SCOPE not in scopes:\n        return \"missing_inference_invoke_scope\"\n    exp = claims.get(\"exp\")\n    skew = max(0, int(min_ttl_seconds))\n    if isinstance(exp, (int, float)):\n        if float(exp) <= (time.time() + skew):\n            return \"invoke_jwt_expiring\"\n        return None\n    if _is_expiring(expires_at, skew):\n        return \"invoke_jwt_expiry_unknown_or_expiring\"\n    return None\n\n\ndef _soam_invoke_jwt_is_usable(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    min_ttl_seconds: int = SOAM_INVOKE_JWT_MIN_TTL_SECONDS,\n) -> bool:\n    return (\n        _soam_invoke_jwt_status(\n            token,\n            scope=scope,\n            expires_at=expires_at,\n            min_ttl_seconds=min_ttl_seconds,\n        )\n        is None\n    )\n\n\ndef _soam_legacy_session_key_reason(\n    token: Any,\n    *,\n    scope: Any = None,\n    expires_at: Any = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> str:\n    if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY:\n        return \"forced_legacy_session_key\"\n    if _soam_legacy_session_keys_forced():\n        return \"forced_legacy_session_keys\"\n    return (\n        _soam_invoke_jwt_status(token, scope=scope, expires_at=expires_at)\n        or \"invoke_jwt_unavailable\"\n    )\n\n\ndef _choose_soam_inference_auth_path(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Tuple[str, Optional[str]]:\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    token = state.get(\"access_token\") if access_token is None else access_token\n    if (\n        not _soam_legacy_session_keys_forced()\n        and inference_auth_mode != SOAM_INFERENCE_AUTH_MODE_LEGACY\n        and _soam_invoke_jwt_is_usable(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n        )\n    ):\n        return SOAM_AUTH_PATH_INVOKE_JWT, None\n    if (\n        inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_AUTO\n        and _agent_key_is_usable(\n            state,\n            max(60, int(min_key_ttl_seconds)),\n        )\n    ):\n        return SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE, None\n    return (\n        SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT,\n        _soam_legacy_session_key_reason(\n            token,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"expires_at\"),\n            inference_auth_mode=inference_auth_mode,\n        ),\n    )\n\n\ndef _log_soam_invoke_jwt_selected(\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\"Soam inference auth: using NAS invoke JWT\")\n    _oauth_trace(\n        \"soam_invoke_jwt_selected\",\n        sequence_id=sequence_id,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _log_soam_legacy_session_key_selected(\n    reason: str,\n    *,\n    access_token: Any,\n    sequence_id: Optional[str] = None,\n) -> None:\n    logger.info(\n        \"Soam inference auth: using legacy session key path (%s)\",\n        reason,\n    )\n    _oauth_trace(\n        \"soam_legacy_session_key_selected\",\n        sequence_id=sequence_id,\n        reason=reason,\n        access_token_fp=_token_fingerprint(access_token),\n    )\n\n\ndef _soam_jwt_expires_at(token: Any, fallback_expires_at: Any = None) -> Optional[str]:\n    claims = _decode_jwt_claims(token)\n    exp = claims.get(\"exp\")\n    if isinstance(exp, (int, float)):\n        try:\n            return datetime.fromtimestamp(float(exp), tz=timezone.utc).isoformat()\n        except Exception:\n            pass\n    return fallback_expires_at if isinstance(fallback_expires_at, str) else None\n\n\ndef _set_soam_agent_key_from_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    obtained_at: Optional[str] = None,\n) -> None:\n    access_token = state.get(\"access_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        return\n    now = datetime.now(timezone.utc)\n    existing_obtained_at = state.get(\"agent_key_obtained_at\")\n    if obtained_at:\n        effective_obtained_at = obtained_at\n    elif (\n        state.get(\"agent_key\") == access_token\n        and isinstance(existing_obtained_at, str)\n        and existing_obtained_at.strip()\n    ):\n        effective_obtained_at = existing_obtained_at\n    else:\n        effective_obtained_at = now.isoformat()\n    expires_at = _soam_jwt_expires_at(access_token, state.get(\"expires_at\"))\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"expires_in\"))\n    )\n    if expires_at:\n        state[\"expires_at\"] = expires_at\n        state[\"expires_in\"] = expires_in\n    state[\"agent_key\"] = access_token\n    state[\"agent_key_id\"] = None\n    state[\"agent_key_expires_at\"] = expires_at\n    state[\"agent_key_expires_in\"] = expires_in\n    state[\"agent_key_reused\"] = False\n    state[\"agent_key_obtained_at\"] = effective_obtained_at\n\n\ndef _select_soam_invoke_jwt(\n    state: Dict[str, Any],\n    *,\n    access_token: Any = None,\n    sequence_id: Optional[str] = None,\n) -> None:\n    if isinstance(access_token, str) and access_token.strip():\n        state[\"access_token\"] = access_token\n    _set_soam_agent_key_from_invoke_jwt(state)\n    _log_soam_invoke_jwt_selected(\n        access_token=state.get(\"access_token\"),\n        sequence_id=sequence_id,\n    )\n\n\n_SOAM_EFFECTIVE_STATE_IGNORED_KEYS = frozenset({\n    # These are derived from expires_at/JWT exp and naturally tick down between\n    # reads. Persisting only these changes makes auth.json noisy and defeats\n    # the mtime-keyed auth-status cache.\n    \"expires_in\",\n    \"agent_key_expires_in\",\n})\n\n\ndef _soam_effective_provider_state(state: Dict[str, Any]) -> Dict[str, Any]:\n    return {\n        key: value\n        for key, value in state.items()\n        if key not in _SOAM_EFFECTIVE_STATE_IGNORED_KEYS\n    }\n\n\ndef _codex_access_token_is_expiring(access_token: Any, skew_seconds: int) -> bool:\n    claims = _decode_jwt_claims(access_token)\n    exp = claims.get(\"exp\")\n    if not isinstance(exp, (int, float)):\n        return False\n    return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n\n\ndef _qwen_cli_auth_path() -> Path:\n    return Path.home() / \".qwen\" / \"oauth_creds.json\"\n\n\ndef _read_qwen_cli_tokens() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    if not auth_path.exists():\n        raise AuthError(\n            \"Qwen CLI credentials not found. Run 'qwen auth qwen-oauth' first.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_missing\",\n        )\n    try:\n        data = json.loads(auth_path.read_text(encoding=\"utf-8\"))\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to read Qwen CLI credentials from {auth_path}: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_read_failed\",\n        ) from exc\n    if not isinstance(data, dict):\n        raise AuthError(\n            f\"Invalid Qwen CLI credentials in {auth_path}.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_auth_invalid\",\n        )\n    return data\n\n\ndef _save_qwen_cli_tokens(tokens: Dict[str, Any]) -> Path:\n    auth_path = _qwen_cli_auth_path()\n    auth_path.parent.mkdir(parents=True, exist_ok=True)\n    try:\n        os.chmod(auth_path.parent, 0o700)\n    except OSError:\n        pass\n    # Per-process random temp suffix avoids collisions between concurrent\n    # writers and stale leftovers from a crashed prior write.\n    tmp_path = auth_path.with_name(f\"{auth_path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n    # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n    # window where write_text() + post-write chmod briefly exposed tokens\n    # at process umask (typically 0o644). See #19673, #21148.\n    fd = os.open(\n        str(tmp_path),\n        os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n        stat.S_IRUSR | stat.S_IWUSR,\n    )\n    try:\n        with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n            fh.write(json.dumps(tokens, indent=2, sort_keys=True) + \"\\n\")\n            fh.flush()\n            os.fsync(fh.fileno())\n        atomic_replace(tmp_path, auth_path)\n    finally:\n        try:\n            if tmp_path.exists():\n                tmp_path.unlink()\n        except OSError:\n            pass\n    return auth_path\n\n\ndef _qwen_access_token_is_expiring(expiry_date_ms: Any, skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS) -> bool:\n    try:\n        expiry_ms = int(expiry_date_ms)\n    except Exception:\n        return True\n    return (time.time() + max(0, int(skew_seconds))) * 1000 >= expiry_ms\n\n\ndef _refresh_qwen_cli_tokens(tokens: Dict[str, Any], timeout_seconds: float = 20.0) -> Dict[str, Any]:\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Qwen OAuth refresh token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_token_missing\",\n        )\n\n    try:\n        response = httpx.post(\n            QWEN_OAUTH_TOKEN_URL,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": QWEN_OAUTH_CLIENT_ID,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh failed: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        body = response.text.strip()\n        raise AuthError(\n            \"Qwen OAuth refresh failed. Re-run 'qwen auth qwen-oauth'.\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"Qwen OAuth refresh returned invalid JSON: {exc}\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_json\",\n        ) from exc\n\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Qwen OAuth refresh response missing access_token.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_refresh_invalid_response\",\n        )\n\n    expires_in = payload.get(\"expires_in\")\n    try:\n        expires_in_seconds = int(expires_in)\n    except Exception:\n        expires_in_seconds = 6 * 60 * 60\n\n    refreshed = {\n        \"access_token\": str(payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(payload.get(\"refresh_token\", refresh_token) or refresh_token).strip(),\n        \"token_type\": str(payload.get(\"token_type\", tokens.get(\"token_type\", \"Bearer\")) or \"Bearer\").strip() or \"Bearer\",\n        \"resource_url\": str(payload.get(\"resource_url\", tokens.get(\"resource_url\", \"portal.qwen.ai\")) or \"portal.qwen.ai\").strip(),\n        \"expiry_date\": int(time.time() * 1000) + max(1, expires_in_seconds) * 1000,\n    }\n    _save_qwen_cli_tokens(refreshed)\n    return refreshed\n\n\ndef resolve_qwen_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    tokens = _read_qwen_cli_tokens()\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    should_refresh = bool(force_refresh)\n    if not should_refresh and refresh_if_expiring:\n        should_refresh = _qwen_access_token_is_expiring(tokens.get(\"expiry_date\"), refresh_skew_seconds)\n    if should_refresh:\n        tokens = _refresh_qwen_cli_tokens(tokens)\n        access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Qwen OAuth access token missing. Re-run 'qwen auth qwen-oauth'.\",\n            provider=\"qwen-oauth\",\n            code=\"qwen_access_token_missing\",\n        )\n\n    base_url = os.getenv(\"CLAWBOT_QWEN_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_QWEN_BASE_URL\n    return {\n        \"provider\": \"qwen-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"qwen-cli\",\n        \"expires_at_ms\": tokens.get(\"expiry_date\"),\n        \"auth_file\": str(_qwen_cli_auth_path()),\n    }\n\n\ndef get_qwen_auth_status() -> Dict[str, Any]:\n    auth_path = _qwen_cli_auth_path()\n    try:\n        creds = resolve_qwen_runtime_credentials(refresh_if_expiring=False)\n        return {\n            \"logged_in\": True,\n            \"auth_file\": str(auth_path),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n            \"expires_at_ms\": creds.get(\"expires_at_ms\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": str(exc),\n        }\n\n\n# =============================================================================\n# Google Gemini OAuth (google-gemini-cli) — PKCE flow + Cloud Code Assist.\n#\n# Tokens live in ~/.clawbot/auth/google_oauth.json (managed by agent.google_oauth).\n# The `base_url` here is the marker \"cloudcode-pa://google\" that run_agent.py\n# uses to construct a GeminiCloudCodeClient instead of the default OpenAI SDK.\n# Actual HTTP traffic goes to https://cloudcode-pa.googleapis.com/v1internal:*.\n# =============================================================================\n\ndef resolve_gemini_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime OAuth creds for google-gemini-cli.\"\"\"\n    try:\n        from agent.google_oauth import (\n            GoogleOAuthError,\n            _credentials_path,\n            get_valid_access_token,\n            load_credentials,\n        )\n    except ImportError as exc:\n        raise AuthError(\n            f\"agent.google_oauth is not importable: {exc}\",\n            provider=\"google-gemini-cli\",\n            code=\"google_oauth_module_missing\",\n        ) from exc\n\n    try:\n        access_token = get_valid_access_token(force_refresh=force_refresh)\n    except GoogleOAuthError as exc:\n        raise AuthError(\n            str(exc),\n            provider=\"google-gemini-cli\",\n            code=exc.code,\n        ) from exc\n\n    creds = load_credentials()\n    base_url = DEFAULT_GEMINI_CLOUDCODE_BASE_URL\n    return {\n        \"provider\": \"google-gemini-cli\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"google-oauth\",\n        \"expires_at_ms\": (creds.expires_ms if creds else None),\n        \"auth_file\": str(_credentials_path()),\n        \"email\": (creds.email if creds else \"\") or \"\",\n        \"project_id\": (creds.project_id if creds else \"\") or \"\",\n    }\n\n\ndef get_gemini_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return a status dict for `clawbot auth list` / `clawbot status`.\"\"\"\n    try:\n        from agent.google_oauth import _credentials_path, load_credentials\n    except ImportError:\n        return {\"logged_in\": False, \"error\": \"agent.google_oauth unavailable\"}\n    auth_path = _credentials_path()\n    creds = load_credentials()\n    if creds is None or not creds.access_token:\n        return {\n            \"logged_in\": False,\n            \"auth_file\": str(auth_path),\n            \"error\": \"not logged in\",\n        }\n    return {\n        \"logged_in\": True,\n        \"auth_file\": str(auth_path),\n        \"source\": \"google-oauth\",\n        \"api_key\": creds.access_token,\n        \"expires_at_ms\": creds.expires_ms,\n        \"email\": creds.email,\n        \"project_id\": creds.project_id,\n    }\n# Spotify auth — PKCE tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\n\ndef _spotify_scope_list(raw_scope: Optional[str] = None) -> List[str]:\n    scope_text = (raw_scope or DEFAULT_SPOTIFY_SCOPE).strip()\n    scopes = [part for part in scope_text.split() if part]\n    seen: set[str] = set()\n    ordered: List[str] = []\n    for scope in scopes:\n        if scope not in seen:\n            seen.add(scope)\n            ordered.append(scope)\n    return ordered\n\n\ndef _spotify_scope_string(raw_scope: Optional[str] = None) -> str:\n    return \" \".join(_spotify_scope_list(raw_scope))\n\n\ndef _spotify_client_id(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\"),\n        get_env_value(\"SPOTIFY_CLIENT_ID\"),\n        state.get(\"client_id\") if isinstance(state, dict) else None,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    raise AuthError(\n        \"Spotify client_id is required. Set CLAWBOT_SPOTIFY_CLIENT_ID or pass --client-id.\",\n        provider=\"spotify\",\n        code=\"spotify_client_id_missing\",\n    )\n\n\ndef _spotify_redirect_uri(\n    explicit: Optional[str] = None,\n    state: Optional[Dict[str, Any]] = None,\n) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        explicit,\n        get_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\"),\n        get_env_value(\"SPOTIFY_REDIRECT_URI\"),\n        state.get(\"redirect_uri\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_REDIRECT_URI,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip()\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_REDIRECT_URI\n\n\ndef _spotify_api_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_API_BASE_URL\"),\n        state.get(\"api_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_API_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_API_BASE_URL\n\n\ndef _spotify_accounts_base_url(state: Optional[Dict[str, Any]] = None) -> str:\n    from clawbot_cli.config import get_env_value\n\n    candidates = (\n        get_env_value(\"CLAWBOT_SPOTIFY_ACCOUNTS_BASE_URL\"),\n        state.get(\"accounts_base_url\") if isinstance(state, dict) else None,\n        DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL,\n    )\n    for candidate in candidates:\n        cleaned = str(candidate or \"\").strip().rstrip(\"/\")\n        if cleaned:\n            return cleaned\n    return DEFAULT_SPOTIFY_ACCOUNTS_BASE_URL\n\n\ndef _spotify_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _spotify_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _oauth_pkce_code_verifier(length: int = 64) -> str:\n    raw = base64.urlsafe_b64encode(os.urandom(length)).decode(\"ascii\")\n    return raw.rstrip(\"=\")[:128]\n\n\ndef _oauth_pkce_code_challenge(code_verifier: str) -> str:\n    digest = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n    return base64.urlsafe_b64encode(digest).decode(\"ascii\").rstrip(\"=\")\n\n\ndef _spotify_build_authorize_url(\n    *,\n    client_id: str,\n    redirect_uri: str,\n    scope: str,\n    state: str,\n    code_challenge: str,\n    accounts_base_url: str,\n) -> str:\n    query = urlencode({\n        \"client_id\": client_id,\n        \"response_type\": \"code\",\n        \"redirect_uri\": redirect_uri,\n        \"scope\": scope,\n        \"state\": state,\n        \"code_challenge_method\": \"S256\",\n        \"code_challenge\": code_challenge,\n    })\n    return f\"{accounts_base_url}/authorize?{query}\"\n\n\ndef _spotify_validate_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must use http://localhost or http://127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host not in {\"127.0.0.1\", \"localhost\"}:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must point to localhost or 127.0.0.1.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"Spotify PKCE redirect_uri must include an explicit localhost port.\",\n            provider=\"spotify\",\n            code=\"spotify_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _make_spotify_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _SpotifyCallbackHandler(BaseHTTPRequestHandler):\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>Spotify authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>Spotify authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _SpotifyCallbackHandler, result\n\n\ndef _spotify_wait_for_callback(\n    redirect_uri: str,\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    host, port, path = _spotify_validate_redirect_uri(redirect_uri)\n    handler_cls, result = _make_spotify_callback_handler(path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    try:\n        server = _ReuseHTTPServer((host, port), handler_cls)\n    except OSError as exc:\n        raise AuthError(\n            f\"Could not bind Spotify callback server on {host}:{port}: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_callback_bind_failed\",\n        ) from exc\n\n    thread = threading.Thread(target=server.serve_forever, kwargs={\"poll_interval\": 0.1}, daemon=True)\n    thread.start()\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"Spotify authorization timed out waiting for the local callback.\",\n        provider=\"spotify\",\n        code=\"spotify_callback_timeout\",\n    )\n\n\ndef _xai_validate_loopback_redirect_uri(redirect_uri: str) -> tuple[str, int, str]:\n    parsed = urlparse(redirect_uri)\n    if parsed.scheme != \"http\":\n        raise AuthError(\n            \"xAI OAuth redirect_uri must use http://127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    host = parsed.hostname or \"\"\n    if host != XAI_OAUTH_REDIRECT_HOST:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must point to 127.0.0.1.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    if not parsed.port:\n        raise AuthError(\n            \"xAI OAuth redirect_uri must include an explicit localhost port.\",\n            provider=\"xai-oauth\",\n            code=\"xai_redirect_invalid\",\n        )\n    return host, parsed.port, parsed.path or \"/\"\n\n\ndef _xai_callback_cors_origin(origin: Optional[str]) -> str:\n    # CORS allowlist for the loopback callback.  Only xAI's own auth origins\n    # are accepted; the redirect_uri itself is bound to 127.0.0.1 and gated by\n    # PKCE+state, so additional dev/3p origins are not needed here.\n    allowed = {\n        \"https://accounts.x.ai\",\n        \"https://auth.x.ai\",\n    }\n    return origin if origin in allowed else \"\"\n\n\ndef _make_xai_callback_handler(expected_path: str) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:\n    result: dict[str, Any] = {\n        \"code\": None,\n        \"state\": None,\n        \"error\": None,\n        \"error_description\": None,\n    }\n\n    class _XAICallbackHandler(BaseHTTPRequestHandler):\n        def _maybe_write_cors_headers(self) -> None:\n            origin = self.headers.get(\"Origin\")\n            allow_origin = _xai_callback_cors_origin(origin)\n            if allow_origin:\n                self.send_header(\"Access-Control-Allow-Origin\", allow_origin)\n                self.send_header(\"Access-Control-Allow-Methods\", \"GET, OPTIONS\")\n                self.send_header(\"Access-Control-Allow-Headers\", \"Content-Type\")\n                self.send_header(\"Access-Control-Allow-Private-Network\", \"true\")\n                self.send_header(\"Vary\", \"Origin\")\n\n        def do_OPTIONS(self) -> None:  # noqa: N802\n            self.send_response(204)\n            self._maybe_write_cors_headers()\n            self.end_headers()\n\n        def do_GET(self) -> None:  # noqa: N802\n            parsed = urlparse(self.path)\n            if parsed.path != expected_path:\n                self.send_response(404)\n                self.end_headers()\n                self.wfile.write(b\"Not found.\")\n                return\n\n            params = parse_qs(parsed.query)\n            result[\"code\"] = params.get(\"code\", [None])[0]\n            result[\"state\"] = params.get(\"state\", [None])[0]\n            result[\"error\"] = params.get(\"error\", [None])[0]\n            result[\"error_description\"] = params.get(\"error_description\", [None])[0]\n\n            self.send_response(200)\n            self._maybe_write_cors_headers()\n            self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n            self.end_headers()\n            if result[\"error\"]:\n                body = \"<html><body><h1>xAI authorization failed.</h1>You can close this tab.</body></html>\"\n            else:\n                body = \"<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>\"\n            self.wfile.write(body.encode(\"utf-8\"))\n\n        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003\n            return\n\n    return _XAICallbackHandler, result\n\n\ndef _xai_start_callback_server(\n    preferred_port: int = XAI_OAUTH_REDIRECT_PORT,\n) -> tuple[HTTPServer, threading.Thread, dict[str, Any], str]:\n    host = XAI_OAUTH_REDIRECT_HOST\n    expected_path = XAI_OAUTH_REDIRECT_PATH\n    handler_cls, result = _make_xai_callback_handler(expected_path)\n\n    class _ReuseHTTPServer(HTTPServer):\n        allow_reuse_address = True\n\n    ports_to_try = [preferred_port]\n    if preferred_port != 0:\n        ports_to_try.append(0)\n    server = None\n    last_error: Optional[OSError] = None\n    for port in ports_to_try:\n        try:\n            server = _ReuseHTTPServer((host, port), handler_cls)\n            break\n        except OSError as exc:\n            last_error = exc\n    if server is None:\n        raise AuthError(\n            f\"Could not bind xAI callback server on {host}:{preferred_port}: {last_error}\",\n            provider=\"xai-oauth\",\n            code=\"xai_callback_bind_failed\",\n        ) from last_error\n\n    actual_port = int(server.server_address[1])\n    redirect_uri = f\"http://{host}:{actual_port}{expected_path}\"\n    thread = threading.Thread(\n        target=server.serve_forever,\n        kwargs={\"poll_interval\": 0.1},\n        daemon=True,\n    )\n    thread.start()\n    return server, thread, result, redirect_uri\n\n\ndef _xai_wait_for_callback(\n    server: HTTPServer,\n    thread: threading.Thread,\n    result: dict[str, Any],\n    *,\n    timeout_seconds: float = 180.0,\n) -> dict[str, Any]:\n    deadline = time.monotonic() + max(5.0, timeout_seconds)\n    try:\n        while time.monotonic() < deadline:\n            if result[\"code\"] or result[\"error\"]:\n                return result\n            time.sleep(0.1)\n    finally:\n        server.shutdown()\n        server.server_close()\n        thread.join(timeout=1.0)\n    raise AuthError(\n        \"xAI authorization timed out waiting for the local callback.\",\n        provider=\"xai-oauth\",\n        code=\"xai_callback_timeout\",\n    )\n\n\ndef _spotify_token_payload_to_state(\n    token_payload: Dict[str, Any],\n    *,\n    client_id: str,\n    redirect_uri: str,\n    requested_scope: str,\n    accounts_base_url: str,\n    api_base_url: str,\n    previous_state: Optional[Dict[str, Any]] = None,\n) -> Dict[str, Any]:\n    now = datetime.now(timezone.utc)\n    expires_in = _coerce_ttl_seconds(token_payload.get(\"expires_in\", 0))\n    expires_at = datetime.fromtimestamp(now.timestamp() + expires_in, tz=timezone.utc)\n    state = dict(previous_state or {})\n    state.update({\n        \"client_id\": client_id,\n        \"redirect_uri\": redirect_uri,\n        \"accounts_base_url\": accounts_base_url,\n        \"api_base_url\": api_base_url,\n        \"scope\": requested_scope,\n        \"granted_scope\": str(token_payload.get(\"scope\") or requested_scope).strip(),\n        \"token_type\": str(token_payload.get(\"token_type\", \"Bearer\") or \"Bearer\").strip() or \"Bearer\",\n        \"access_token\": str(token_payload.get(\"access_token\", \"\") or \"\").strip(),\n        \"refresh_token\": str(\n            token_payload.get(\"refresh_token\")\n            or state.get(\"refresh_token\")\n            or \"\"\n        ).strip(),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": expires_at.isoformat(),\n        \"expires_in\": expires_in,\n        \"auth_type\": \"oauth_pkce\",\n    })\n    return state\n\n\ndef _spotify_exchange_code_for_tokens(\n    *,\n    client_id: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    accounts_base_url: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"client_id\": client_id,\n                \"grant_type\": \"authorization_code\",\n                \"code\": code,\n                \"redirect_uri\": redirect_uri,\n                \"code_verifier\": code_verifier,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token exchange failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token exchange failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_failed\",\n        )\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify token response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _refresh_spotify_oauth_state(\n    state: Dict[str, Any],\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    if not refresh_token:\n        raise AuthError(\n            \"Spotify refresh token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_token_missing\",\n            relogin_required=True,\n        )\n\n    client_id = _spotify_client_id(state=state)\n    accounts_base_url = _spotify_accounts_base_url(state)\n    try:\n        response = httpx.post(\n            f\"{accounts_base_url}/api/token\",\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": client_id,\n            },\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"Spotify token refresh failed: {exc}\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n        ) from exc\n\n    if response.status_code >= 400:\n        detail = response.text.strip()\n        raise AuthError(\n            \"Spotify token refresh failed. Run `clawbot auth spotify` again.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"spotify\",\n            code=\"spotify_refresh_failed\",\n            relogin_required=True,\n        )\n\n    payload = response.json()\n    if not isinstance(payload, dict) or not str(payload.get(\"access_token\", \"\") or \"\").strip():\n        raise AuthError(\n            \"Spotify refresh response did not include an access_token.\",\n            provider=\"spotify\",\n            code=\"spotify_refresh_invalid\",\n            relogin_required=True,\n        )\n\n    return _spotify_token_payload_to_state(\n        payload,\n        client_id=client_id,\n        redirect_uri=_spotify_redirect_uri(state=state),\n        requested_scope=str(state.get(\"scope\") or DEFAULT_SPOTIFY_SCOPE),\n        accounts_base_url=accounts_base_url,\n        api_base_url=_spotify_api_base_url(state),\n        previous_state=state,\n    )\n\n\ndef resolve_spotify_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = SPOTIFY_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"spotify\")\n        if not state:\n            raise AuthError(\n                \"Spotify is not authenticated. Run `clawbot auth spotify` first.\",\n                provider=\"spotify\",\n                code=\"spotify_auth_missing\",\n                relogin_required=True,\n            )\n\n        should_refresh = bool(force_refresh)\n        if not should_refresh and refresh_if_expiring:\n            should_refresh = _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds)\n        if should_refresh:\n            state = _refresh_spotify_oauth_state(state)\n            _store_provider_state(auth_store, \"spotify\", state, set_active=False)\n            _save_auth_store(auth_store)\n\n    access_token = str(state.get(\"access_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"Spotify access token missing. Run `clawbot auth spotify` again.\",\n            provider=\"spotify\",\n            code=\"spotify_access_token_missing\",\n            relogin_required=True,\n        )\n\n    return {\n        \"provider\": \"spotify\",\n        \"access_token\": access_token,\n        \"api_key\": access_token,\n        \"token_type\": str(state.get(\"token_type\", \"Bearer\") or \"Bearer\"),\n        \"base_url\": _spotify_api_base_url(state),\n        \"scope\": str(state.get(\"granted_scope\") or state.get(\"scope\") or \"\").strip(),\n        \"client_id\": _spotify_client_id(state=state),\n        \"redirect_uri\": _spotify_redirect_uri(state=state),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"refresh_token\": str(state.get(\"refresh_token\", \"\") or \"\").strip(),\n    }\n\n\ndef get_spotify_auth_status() -> Dict[str, Any]:\n    state = get_provider_auth_state(\"spotify\")\n    if not state:\n        return {\"logged_in\": False}\n\n    expires_at = state.get(\"expires_at\")\n    refresh_token = str(state.get(\"refresh_token\", \"\") or \"\").strip()\n    return {\n        \"logged_in\": bool(refresh_token or not _is_expiring(expires_at, 0)),\n        \"auth_type\": state.get(\"auth_type\", \"oauth_pkce\"),\n        \"client_id\": state.get(\"client_id\"),\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n        \"scope\": state.get(\"granted_scope\") or state.get(\"scope\"),\n        \"expires_at\": expires_at,\n        \"api_base_url\": state.get(\"api_base_url\"),\n        \"has_refresh_token\": bool(refresh_token),\n    }\n\n\ndef _spotify_interactive_setup(redirect_uri_hint: str) -> str:\n    \"\"\"Walk the user through creating a Spotify developer app, persist the\n    resulting client_id to ~/.clawbot/.env, and return it.\n\n    Raises SystemExit if the user aborts or submits an empty value.\n    \"\"\"\n    from clawbot_cli.config import save_env_value\n\n    print()\n    print(\"=\" * 70)\n    print(\"Spotify first-time setup\")\n    print(\"=\" * 70)\n    print()\n    print(\"Spotify requires every user to register their own lightweight\")\n    print(\"developer app. This takes about two minutes and only has to be\")\n    print(\"done once per machine.\")\n    print()\n    print(f\"Full guide: {SPOTIFY_DOCS_URL}\")\n    print()\n    print(\"Steps:\")\n    print(f\"  1. Opening {SPOTIFY_DASHBOARD_URL} in your browser...\")\n    print(\"  2. Click 'Create app' and fill in:\")\n    print(\"       App name:     anything (e.g. clawbot-agent)\")\n    print(\"       Description:  anything\")\n    print(f\"       Redirect URI: {redirect_uri_hint}\")\n    print(\"       API/SDK:      Web API\")\n    print(\"  3. Agree to the terms, click Save.\")\n    print(\"  4. Open the app's Settings page and copy the Client ID.\")\n    print(\"  5. Paste it below.\")\n    print()\n\n    if not _is_remote_session():\n        try:\n            webbrowser.open(SPOTIFY_DASHBOARD_URL)\n        except Exception:\n            pass\n\n    try:\n        raw = input(\"Spotify Client ID: \").strip()\n    except (EOFError, KeyboardInterrupt):\n        print()\n        raise SystemExit(\"Spotify setup cancelled.\")\n\n    if not raw:\n        print()\n        print(f\"No Client ID entered. See {SPOTIFY_DOCS_URL} for the full guide.\")\n        raise SystemExit(\"Spotify setup cancelled: empty Client ID.\")\n\n    # Persist so subsequent `clawbot auth spotify` runs skip the wizard.\n    save_env_value(\"CLAWBOT_SPOTIFY_CLIENT_ID\", raw)\n    # Only persist the redirect URI if it's non-default, to avoid pinning\n    # users to a value the default might later change to.\n    if redirect_uri_hint and redirect_uri_hint != DEFAULT_SPOTIFY_REDIRECT_URI:\n        save_env_value(\"CLAWBOT_SPOTIFY_REDIRECT_URI\", redirect_uri_hint)\n\n    print()\n    print(\"Saved CLAWBOT_SPOTIFY_CLIENT_ID to ~/.clawbot/.env\")\n    print()\n    return raw\n\n\ndef login_spotify_command(args) -> None:\n    existing_state = get_provider_auth_state(\"spotify\") or {}\n\n    # Interactive wizard: if no client_id is configured anywhere, walk the\n    # user through creating the Spotify developer app instead of crashing\n    # with \"CLAWBOT_SPOTIFY_CLIENT_ID is required\".\n    explicit_client_id = getattr(args, \"client_id\", None)\n    try:\n        client_id = _spotify_client_id(explicit_client_id, existing_state)\n    except AuthError as exc:\n        if getattr(exc, \"code\", \"\") != \"spotify_client_id_missing\":\n            raise\n        client_id = _spotify_interactive_setup(\n            redirect_uri_hint=getattr(args, \"redirect_uri\", None) or DEFAULT_SPOTIFY_REDIRECT_URI,\n        )\n\n    redirect_uri = _spotify_redirect_uri(getattr(args, \"redirect_uri\", None), existing_state)\n    scope = _spotify_scope_string(getattr(args, \"scope\", None) or existing_state.get(\"scope\"))\n    accounts_base_url = _spotify_accounts_base_url(existing_state)\n    api_base_url = _spotify_api_base_url(existing_state)\n    open_browser = not getattr(args, \"no_browser\", False)\n\n    code_verifier = _spotify_code_verifier()\n    code_challenge = _spotify_code_challenge(code_verifier)\n    state_nonce = uuid.uuid4().hex\n    authorize_url = _spotify_build_authorize_url(\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        scope=scope,\n        state=state_nonce,\n        code_challenge=code_challenge,\n        accounts_base_url=accounts_base_url,\n    )\n\n    print(\"Starting Spotify PKCE login...\")\n    print(f\"Client ID: {client_id}\")\n    print(f\"Redirect URI: {redirect_uri}\")\n    print(\"Make sure this redirect URI is allow-listed in your Spotify app settings.\")\n    print()\n    print(\"Open this URL to authorize Clawbot:\")\n    print(authorize_url)\n    print()\n    print(f\"Full setup guide: {SPOTIFY_DOCS_URL}\")\n    print()\n\n    _print_loopback_ssh_hint(redirect_uri, docs_url=SPOTIFY_DOCS_URL)\n\n    if open_browser and not _is_remote_session():\n        try:\n            opened = webbrowser.open(authorize_url)\n        except Exception:\n            opened = False\n        if opened:\n            print(\"Browser opened for Spotify authorization.\")\n        else:\n            print(\"Could not open the browser automatically; use the URL above.\")\n\n    callback = _spotify_wait_for_callback(\n        redirect_uri,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 180.0),\n    )\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise SystemExit(f\"Spotify authorization failed: {detail}\")\n    if callback.get(\"state\") != state_nonce:\n        raise SystemExit(\"Spotify authorization failed: state mismatch.\")\n\n    token_payload = _spotify_exchange_code_for_tokens(\n        client_id=client_id,\n        code=str(callback.get(\"code\") or \"\"),\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        accounts_base_url=accounts_base_url,\n        timeout_seconds=float(getattr(args, \"timeout\", None) or 20.0),\n    )\n    spotify_state = _spotify_token_payload_to_state(\n        token_payload,\n        client_id=client_id,\n        redirect_uri=redirect_uri,\n        requested_scope=scope,\n        accounts_base_url=accounts_base_url,\n        api_base_url=api_base_url,\n    )\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _store_provider_state(auth_store, \"spotify\", spotify_state, set_active=False)\n        saved_to = _save_auth_store(auth_store)\n\n    print(\"Spotify login successful!\")\n    print(f\"  Auth state: {saved_to}\")\n    print(\"  Provider state saved under providers.spotify\")\n    print(f\"  Docs: {SPOTIFY_DOCS_URL}\")\n\n# =============================================================================\n# SSH / remote session detection\n# =============================================================================\n\ndef _is_remote_session() -> bool:\n    \"\"\"Detect if running in an SSH session where webbrowser.open() won't work.\"\"\"\n    return bool(os.getenv(\"SSH_CLIENT\") or os.getenv(\"SSH_TTY\"))\n\n\ndef _print_loopback_ssh_hint(redirect_uri: str, *, docs_url: str | None = None) -> None:\n    \"\"\"Print an SSH tunnel hint when running a loopback-redirect OAuth flow on a\n    remote host. The auth server (xAI, Spotify, ...) will redirect the user's\n    browser to ``127.0.0.1:<port>/callback``. If the browser is on a different\n    machine than the loopback listener (the usual SSH case), the redirect can't\n    reach the listener without a local port forward.\n\n    The hint is best-effort: silent if we don't think we're remote, or if we\n    can't parse a host/port out of the redirect URI.\n\n    Pass ``docs_url`` for a provider-specific guide (e.g. the xAI Grok OAuth\n    page); the generic OAuth-over-SSH guide is always shown after it.\n    \"\"\"\n    if not _is_remote_session():\n        return\n    try:\n        parsed = urlparse(redirect_uri)\n    except Exception:\n        return\n    host = parsed.hostname or \"\"\n    port = parsed.port\n    if host not in {\"127.0.0.1\", \"::1\", \"localhost\"} or not port:\n        return\n    print()\n    print(\"Remote session detected. Your browser will redirect to\")\n    print(f\"  {redirect_uri}\")\n    print(\"which the loopback listener on THIS machine is waiting on. If your\")\n    print(\"browser is on a different machine, forward the port first from your\")\n    print(\"local machine in a separate terminal:\")\n    print()\n    print(f\"  ssh -N -L {port}:127.0.0.1:{port} <user>@<this-host>\")\n    print()\n    print(\"Then open the authorize URL above in your local browser.\")\n    if docs_url:\n        print(f\"Provider docs:      {docs_url}\")\n    print(f\"SSH/jump-box guide: {OAUTH_OVER_SSH_DOCS_URL}\")\n    print()\n\n\n# =============================================================================\n# OpenAI Codex auth — tokens stored in ~/.clawbot/auth.json (not ~/.codex/)\n#\n# Clawbot maintains its own Codex OAuth session separate from the Codex CLI\n# and VS Code extension. This prevents refresh token rotation conflicts\n# where one app's refresh invalidates the other's session.\n# =============================================================================\n\ndef _read_codex_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    \"\"\"Read Codex OAuth tokens from Clawbot auth store (~/.clawbot/auth.json).\n    \n    Returns dict with 'tokens' (access_token, refresh_token) and 'last_refresh'.\n    Raises AuthError if no Codex tokens are stored.\n    \"\"\"\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"openai-codex\")\n    if not state:\n        raise AuthError(\n            \"No Codex credentials stored. Run `clawbot auth` to authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"Codex auth state is missing tokens. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = tokens.get(\"access_token\")\n    refresh_token = tokens.get(\"refresh_token\")\n    if not isinstance(access_token, str) or not access_token.strip():\n        raise AuthError(\n            \"Codex auth is missing access_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n    }\n\n\ndef _save_codex_tokens(tokens: Dict[str, str], last_refresh: str = None) -> None:\n    \"\"\"Save Codex OAuth tokens to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"openai-codex\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"chatgpt\"\n        _save_provider_state(auth_store, \"openai-codex\", state)\n        _save_auth_store(auth_store)\n\n\ndef refresh_codex_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Codex OAuth tokens without mutating Clawbot auth state.\"\"\"\n    del access_token  # Access token is only used by callers to decide whether to refresh.\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"Codex auth is missing refresh_token. Run `clawbot auth` to re-authenticate.\",\n            provider=\"openai-codex\",\n            code=\"codex_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            CODEX_OAUTH_TOKEN_URL,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"refresh_token\": refresh_token,\n                \"client_id\": CODEX_OAUTH_CLIENT_ID,\n            },\n        )\n\n    if response.status_code != 200:\n        code = \"codex_refresh_failed\"\n        message = f\"Codex token refresh failed with status {response.status_code}.\"\n        relogin_required = False\n        try:\n            err = response.json()\n            if isinstance(err, dict):\n                err_obj = err.get(\"error\")\n                # OpenAI shape: {\"error\": {\"code\": \"...\", \"message\": \"...\", \"type\": \"...\"}}\n                if isinstance(err_obj, dict):\n                    nested_code = err_obj.get(\"code\") or err_obj.get(\"type\")\n                    if isinstance(nested_code, str) and nested_code.strip():\n                        code = nested_code.strip()\n                    nested_msg = err_obj.get(\"message\")\n                    if isinstance(nested_msg, str) and nested_msg.strip():\n                        message = f\"Codex token refresh failed: {nested_msg.strip()}\"\n                # OAuth spec shape: {\"error\": \"code_str\", \"error_description\": \"...\"}\n                elif isinstance(err_obj, str) and err_obj.strip():\n                    code = err_obj.strip()\n                    err_desc = err.get(\"error_description\") or err.get(\"message\")\n                    if isinstance(err_desc, str) and err_desc.strip():\n                        message = f\"Codex token refresh failed: {err_desc.strip()}\"\n        except Exception:\n            pass\n        if code in {\"invalid_grant\", \"invalid_token\", \"invalid_request\"}:\n            relogin_required = True\n        if code == \"refresh_token_reused\":\n            message = (\n                \"Codex refresh token was already consumed by another client \"\n                \"(e.g. Codex CLI or VS Code extension). \"\n                \"Run `codex` in your terminal to generate fresh tokens, \"\n                \"then run `clawbot auth` to re-authenticate.\"\n            )\n            relogin_required = True\n        # A 401/403 from the token endpoint always means the refresh token\n        # is invalid/expired — force relogin even if the body error code\n        # wasn't one of the known strings above.\n        if response.status_code in {401, 403} and not relogin_required:\n            relogin_required = True\n        raise AuthError(\n            message,\n            provider=\"openai-codex\",\n            code=code,\n            relogin_required=relogin_required,\n        )\n\n    try:\n        refresh_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            \"Codex token refresh returned invalid JSON.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_invalid_json\",\n            relogin_required=True,\n        ) from exc\n\n    refreshed_access = refresh_payload.get(\"access_token\")\n    if not isinstance(refreshed_access, str) or not refreshed_access.strip():\n        raise AuthError(\n            \"Codex token refresh response was missing access_token.\",\n            provider=\"openai-codex\",\n            code=\"codex_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n\n    updated = {\n        \"access_token\": refreshed_access.strip(),\n        \"refresh_token\": refresh_token.strip(),\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    next_refresh = refresh_payload.get(\"refresh_token\")\n    if isinstance(next_refresh, str) and next_refresh.strip():\n        updated[\"refresh_token\"] = next_refresh.strip()\n    return updated\n\n\ndef _refresh_codex_auth_tokens(\n    tokens: Dict[str, str],\n    timeout_seconds: float,\n) -> Dict[str, str]:\n    \"\"\"Refresh Codex access token using the refresh token.\n    \n    Saves the new tokens to Clawbot auth store automatically.\n    \"\"\"\n    refreshed = refresh_codex_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n\n    _save_codex_tokens(updated_tokens)\n    return updated_tokens\n\n\ndef _import_codex_cli_tokens() -> Optional[Dict[str, str]]:\n    \"\"\"Try to read tokens from ~/.codex/auth.json (Codex CLI shared file).\n    \n    Returns tokens dict if valid and not expired, None otherwise.\n    Does NOT write to the shared file.\n    \"\"\"\n    codex_home = os.getenv(\"CODEX_HOME\", \"\").strip()\n    if not codex_home:\n        codex_home = str(Path.home() / \".codex\")\n    auth_path = Path(codex_home).expanduser() / \"auth.json\"\n    if not auth_path.is_file():\n        return None\n    try:\n        payload = json.loads(auth_path.read_text())\n        tokens = payload.get(\"tokens\")\n        if not isinstance(tokens, dict):\n            return None\n        access_token = tokens.get(\"access_token\")\n        refresh_token = tokens.get(\"refresh_token\")\n        if not access_token or not refresh_token:\n            return None\n        # Reject expired tokens — importing stale tokens from ~/.codex/\n        # that can't be refreshed leaves the user stuck with \"Login successful!\"\n        # but no working credentials.\n        if _codex_access_token_is_expiring(access_token, 0):\n            logger.debug(\n                \"Codex CLI tokens at %s are expired — skipping import.\", auth_path,\n            )\n            return None\n        return dict(tokens)\n    except Exception:\n        return None\n\n\ndef resolve_codex_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Resolve runtime credentials from Clawbot's own Codex token store.\"\"\"\n    data = _read_codex_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_CODEX_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        # Re-read under lock to avoid racing with other Clawbot processes\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_codex_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds)\n\n            if should_refresh:\n                tokens = _refresh_codex_auth_tokens(tokens, refresh_timeout_seconds)\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"provider\": \"openai-codex\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"chatgpt\",\n    }\n\n\n# =============================================================================\n# xAI Grok OAuth — tokens stored in ~/.clawbot/auth.json\n# =============================================================================\n\ndef _read_xai_oauth_tokens(*, _lock: bool = True) -> Dict[str, Any]:\n    if _lock:\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n    else:\n        auth_store = _load_auth_store()\n    state = _load_provider_state(auth_store, \"xai-oauth\")\n    if not state:\n        raise AuthError(\n            \"No xAI OAuth credentials stored. Select xAI Grok OAuth (SuperGrok Subscription) in `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing\",\n            relogin_required=True,\n        )\n    tokens = state.get(\"tokens\")\n    if not isinstance(tokens, dict):\n        raise AuthError(\n            \"xAI OAuth state is missing tokens. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_invalid_shape\",\n            relogin_required=True,\n        )\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(tokens.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI OAuth state is missing access_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_access_token\",\n            relogin_required=True,\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI OAuth state is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    return {\n        \"tokens\": tokens,\n        \"last_refresh\": state.get(\"last_refresh\"),\n        \"discovery\": state.get(\"discovery\") or {},\n        \"redirect_uri\": state.get(\"redirect_uri\"),\n    }\n\n\ndef _save_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    discovery: Optional[Dict[str, Any]] = None,\n    redirect_uri: str = \"\",\n    last_refresh: Optional[str] = None,\n) -> None:\n    if last_refresh is None:\n        last_refresh = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"xai-oauth\") or {}\n        state[\"tokens\"] = tokens\n        state[\"last_refresh\"] = last_refresh\n        state[\"auth_mode\"] = \"oauth_pkce\"\n        if discovery:\n            state[\"discovery\"] = discovery\n        if redirect_uri:\n            state[\"redirect_uri\"] = redirect_uri\n        _save_provider_state(auth_store, \"xai-oauth\", state)\n        _save_auth_store(auth_store)\n\n\ndef _xai_access_token_is_expiring(access_token: str, skew_seconds: int = 0) -> bool:\n    if not isinstance(access_token, str) or \".\" not in access_token:\n        return False\n    try:\n        parts = access_token.split(\".\")\n        if len(parts) < 2:\n            return False\n        payload_b64 = parts[1]\n        payload_b64 += \"=\" * (-len(payload_b64) % 4)\n        payload = json.loads(base64.urlsafe_b64decode(payload_b64.encode(\"ascii\")).decode(\"utf-8\"))\n        exp = payload.get(\"exp\")\n        if not isinstance(exp, (int, float)):\n            return False\n        return float(exp) <= (time.time() + max(0, int(skew_seconds)))\n    except Exception:\n        return False\n\n\ndef _xai_validate_oauth_endpoint(url: str, *, field: str) -> str:\n    \"\"\"Refuse any OIDC discovery endpoint that isn't HTTPS on the xAI origin.\n\n    The OIDC discovery response is a long-lived, low-frequency request whose\n    output is cached in ``~/.clawbot/auth.json``. A single MITM during initial\n    login could substitute a malicious ``token_endpoint``; that URL would\n    then receive the refresh_token on every subsequent refresh — a permanent\n    credential leak from a one-time MITM. Validating scheme + host pins the\n    cached endpoint to the xAI auth origin (or a future ``*.x.ai`` subdomain\n    if xAI migrates) so the cache poisoning loses its persistence guarantee.\n\n    RFC 8414 §2 requires the issuer to be ``https://`` and SHOULD-keeps the\n    token_endpoint on the same origin; we enforce both. ``x.ai`` is the\n    bare apex, so we accept either exact host match or any ``.x.ai`` suffix.\n    \"\"\"\n    parsed = urlparse(url)\n    if parsed.scheme != \"https\":\n        raise AuthError(\n            f\"xAI OIDC discovery returned a non-HTTPS {field}: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    host = (parsed.hostname or \"\").lower()\n    if not host:\n        raise AuthError(\n            f\"xAI OIDC discovery {field} is missing a hostname: {url!r}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    if host != \"x.ai\" and not host.endswith(\".x.ai\"):\n        raise AuthError(\n            f\"xAI OIDC discovery {field} host {host!r} is not on the xAI origin \"\n            f\"(expected x.ai or a *.x.ai subdomain). Refusing to use a cached \"\n            f\"endpoint that may have been substituted by a MITM during initial \"\n            f\"discovery; re-authenticate with `clawbot model` to re-fetch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid\",\n        )\n    return url\n\n\ndef _xai_oauth_discovery(timeout_seconds: float = 15.0) -> Dict[str, str]:\n    try:\n        response = httpx.get(\n            XAI_OAUTH_DISCOVERY_URL,\n            headers={\"Accept\": \"application/json\"},\n            timeout=timeout_seconds,\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        ) from exc\n    if response.status_code != 200:\n        raise AuthError(\n            f\"xAI OIDC discovery returned status {response.status_code}.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_failed\",\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI OIDC discovery returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI OIDC discovery response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    authorization_endpoint = str(payload.get(\"authorization_endpoint\", \"\") or \"\").strip()\n    token_endpoint = str(payload.get(\"token_endpoint\", \"\") or \"\").strip()\n    if not authorization_endpoint or not token_endpoint:\n        raise AuthError(\n            \"xAI OIDC discovery response was missing required endpoints.\",\n            provider=\"xai-oauth\",\n            code=\"xai_discovery_incomplete\",\n        )\n    _xai_validate_oauth_endpoint(authorization_endpoint, field=\"authorization_endpoint\")\n    _xai_validate_oauth_endpoint(token_endpoint, field=\"token_endpoint\")\n    return {\n        \"authorization_endpoint\": authorization_endpoint,\n        \"token_endpoint\": token_endpoint,\n    }\n\n\ndef refresh_xai_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    *,\n    token_endpoint: str = \"\",\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    del access_token\n    if not isinstance(refresh_token, str) or not refresh_token.strip():\n        raise AuthError(\n            \"xAI OAuth is missing refresh_token. Re-authenticate with `clawbot model`.\",\n            provider=\"xai-oauth\",\n            code=\"xai_auth_missing_refresh_token\",\n            relogin_required=True,\n        )\n    endpoint = token_endpoint.strip() or _xai_oauth_discovery(timeout_seconds)[\"token_endpoint\"]\n    # Re-validate cached endpoints on the refresh hot path: an auth.json\n    # written by an older Clawbot (or hand-edited) may carry a non-xAI\n    # token_endpoint that would receive every future refresh_token in\n    # plaintext if we trusted it blindly. Cheap suffix check; fast-fail\n    # with a clear error so the user can re-run `clawbot model` to refetch.\n    _xai_validate_oauth_endpoint(endpoint, field=\"token_endpoint\")\n    timeout = httpx.Timeout(max(5.0, float(timeout_seconds)))\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}) as client:\n        response = client.post(\n            endpoint,\n            headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": XAI_OAUTH_CLIENT_ID,\n                \"refresh_token\": refresh_token,\n            },\n        )\n    if response.status_code != 200:\n        detail = response.text.strip()\n        raise AuthError(\n            \"xAI token refresh failed.\"\n            + (f\" Response: {detail}\" if detail else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_failed\",\n            relogin_required=(response.status_code in {400, 401, 403}),\n        )\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token refresh returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_json\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token refresh response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_invalid_response\",\n            relogin_required=True,\n        )\n    refreshed_access = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    if not refreshed_access:\n        raise AuthError(\n            \"xAI token refresh response was missing access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_refresh_missing_access_token\",\n            relogin_required=True,\n        )\n    updated = {\n        \"access_token\": refreshed_access,\n        \"refresh_token\": str(payload.get(\"refresh_token\") or refresh_token).strip(),\n        \"id_token\": str(payload.get(\"id_token\") or \"\").strip(),\n        \"expires_in\": payload.get(\"expires_in\"),\n        \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n    }\n    return updated\n\n\ndef _refresh_xai_oauth_tokens(\n    tokens: Dict[str, Any],\n    *,\n    token_endpoint: str,\n    redirect_uri: str = \"\",\n    timeout_seconds: float,\n) -> Dict[str, Any]:\n    refreshed = refresh_xai_oauth_pure(\n        str(tokens.get(\"access_token\", \"\") or \"\"),\n        str(tokens.get(\"refresh_token\", \"\") or \"\"),\n        token_endpoint=token_endpoint,\n        timeout_seconds=timeout_seconds,\n    )\n    updated_tokens = dict(tokens)\n    updated_tokens[\"access_token\"] = refreshed[\"access_token\"]\n    updated_tokens[\"refresh_token\"] = refreshed[\"refresh_token\"]\n    if refreshed.get(\"id_token\"):\n        updated_tokens[\"id_token\"] = refreshed[\"id_token\"]\n    if refreshed.get(\"expires_in\") is not None:\n        updated_tokens[\"expires_in\"] = refreshed[\"expires_in\"]\n    if refreshed.get(\"token_type\"):\n        updated_tokens[\"token_type\"] = refreshed[\"token_type\"]\n    _save_xai_oauth_tokens(\n        updated_tokens,\n        discovery={\"token_endpoint\": token_endpoint},\n        redirect_uri=redirect_uri,\n        last_refresh=refreshed[\"last_refresh\"],\n    )\n    return updated_tokens\n\n\ndef resolve_xai_oauth_runtime_credentials(\n    *,\n    force_refresh: bool = False,\n    refresh_if_expiring: bool = True,\n    refresh_skew_seconds: int = XAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    data = _read_xai_oauth_tokens()\n    tokens = dict(data[\"tokens\"])\n    access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n    refresh_timeout_seconds = float(os.getenv(\"CLAWBOT_XAI_REFRESH_TIMEOUT_SECONDS\", \"20\"))\n    discovery = dict(data.get(\"discovery\") or {})\n    token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n    redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n\n    should_refresh = bool(force_refresh)\n    if (not should_refresh) and refresh_if_expiring:\n        should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n    if should_refresh:\n        with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)):\n            data = _read_xai_oauth_tokens(_lock=False)\n            tokens = dict(data[\"tokens\"])\n            access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n            discovery = dict(data.get(\"discovery\") or {})\n            token_endpoint = str(discovery.get(\"token_endpoint\", \"\") or \"\").strip()\n            redirect_uri = str(data.get(\"redirect_uri\", \"\") or \"\").strip()\n            should_refresh = bool(force_refresh)\n            if (not should_refresh) and refresh_if_expiring:\n                should_refresh = _xai_access_token_is_expiring(access_token, refresh_skew_seconds)\n            if should_refresh:\n                if not token_endpoint:\n                    token_endpoint = _xai_oauth_discovery(refresh_timeout_seconds)[\"token_endpoint\"]\n                tokens = _refresh_xai_oauth_tokens(\n                    tokens,\n                    token_endpoint=token_endpoint,\n                    redirect_uri=redirect_uri,\n                    timeout_seconds=refresh_timeout_seconds,\n                )\n                access_token = str(tokens.get(\"access_token\", \"\") or \"\").strip()\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"provider\": \"xai-oauth\",\n        \"base_url\": base_url,\n        \"api_key\": access_token,\n        \"source\": \"clawbot-auth-store\",\n        \"last_refresh\": data.get(\"last_refresh\"),\n        \"auth_mode\": \"oauth_pkce\",\n    }\n\n\n# =============================================================================\n# TLS verification helper\n# =============================================================================\n\ndef _default_verify() -> bool | ssl.SSLContext:\n    \"\"\"Platform-aware default SSL verify for httpx clients.\n\n    On macOS with Homebrew Python, the system OpenSSL cannot locate the\n    system trust store and valid public certs fail verification. When\n    certifi is importable we pin its bundle explicitly; elsewhere we\n    defer to httpx's built-in default (certifi via its own dependency).\n    Mirrors the weixin fix in 3a0ec1d93.\n    \"\"\"\n    if sys.platform == \"darwin\":\n        try:\n            import certifi\n            return ssl.create_default_context(cafile=certifi.where())\n        except ImportError:\n            pass\n    return True\n\n\ndef _resolve_verify(\n    *,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    auth_state: Optional[Dict[str, Any]] = None,\n) -> bool | ssl.SSLContext:\n    tls_state = auth_state.get(\"tls\") if isinstance(auth_state, dict) else {}\n    tls_state = tls_state if isinstance(tls_state, dict) else {}\n\n    effective_insecure = (\n        is_truthy_value(insecure, default=False) if insecure is not None\n        else is_truthy_value(tls_state.get(\"insecure\", False), default=False)\n    )\n    effective_ca = (\n        ca_bundle\n        or tls_state.get(\"ca_bundle\")\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n        or os.getenv(\"REQUESTS_CA_BUNDLE\")\n    )\n\n    if effective_insecure:\n        return False\n    if effective_ca:\n        ca_path = str(effective_ca)\n        if not os.path.isfile(ca_path):\n            logger.warning(\n                \"CA bundle path does not exist: %s — falling back to default certificates\",\n                ca_path,\n            )\n            return _default_verify()\n        return ssl.create_default_context(cafile=ca_path)\n    return _default_verify()\n\n\n# =============================================================================\n# OAuth Device Code Flow — generic, parameterized by provider\n# =============================================================================\n\ndef _request_device_code(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: Optional[str],\n) -> Dict[str, Any]:\n    \"\"\"POST to the device code endpoint. Returns device_code, user_code, etc.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/device/code\",\n        data={\n            \"client_id\": client_id,\n            **({\"scope\": scope} if scope else {}),\n        },\n    )\n    response.raise_for_status()\n    data = response.json()\n\n    required_fields = [\n        \"device_code\", \"user_code\", \"verification_uri\",\n        \"verification_uri_complete\", \"expires_in\", \"interval\",\n    ]\n    missing = [f for f in required_fields if f not in data]\n    if missing:\n        raise ValueError(f\"Device code response missing fields: {', '.join(missing)}\")\n    return data\n\n\ndef _is_soam_invoke_scope_refusal(exc: Exception) -> bool:\n    if not isinstance(exc, httpx.HTTPStatusError):\n        return False\n    response = exc.response\n    if response.status_code not in {400, 401, 403}:\n        return False\n    try:\n        payload = response.json()\n    except Exception:\n        payload = {}\n    text = \" \".join(\n        str(value)\n        for value in (\n            payload.get(\"error\") if isinstance(payload, dict) else None,\n            payload.get(\"error_description\") if isinstance(payload, dict) else None,\n            response.text,\n        )\n        if value\n    ).lower()\n    if not text:\n        return False\n    return (\n        \"invalid_scope\" in text\n        or \"unsupported_scope\" in text\n        or \"scope\" in text and SOAM_INFERENCE_INVOKE_SCOPE in text\n    )\n\n\ndef _soam_device_scope_with_env_override(\n    requested_scope: Optional[str],\n    *,\n    default_scope: str = DEFAULT_SOAM_SCOPE,\n) -> Tuple[str, bool]:\n    explicit_scope = requested_scope is not None\n    scope = requested_scope or default_scope\n    if _soam_legacy_session_keys_forced():\n        scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n    return scope, explicit_scope\n\n\ndef _request_soam_device_code_with_scope_fallback(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    scope: str,\n    allow_legacy_fallback: bool,\n) -> Tuple[Dict[str, Any], str]:\n    try:\n        return (\n            _request_device_code(\n                client=client,\n                portal_base_url=portal_base_url,\n                client_id=client_id,\n                scope=scope,\n            ),\n            scope,\n        )\n    except Exception as exc:\n        if (\n            allow_legacy_fallback\n            and _soam_scope_has_invoke(scope)\n            and _is_soam_invoke_scope_refusal(exc)\n        ):\n            logger.info(\"Soam inference auth: NAS refused invoke scope, retrying legacy scope\")\n            _oauth_trace(\"soam_device_code_invoke_scope_refused\")\n            retry_scope = SOAM_LEGACY_AGENT_KEY_SCOPE\n            return (\n                _request_device_code(\n                    client=client,\n                    portal_base_url=portal_base_url,\n                    client_id=client_id,\n                    scope=retry_scope,\n                ),\n                retry_scope,\n            )\n        raise\n\n\ndef _poll_for_token(\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    device_code: str,\n    expires_in: int,\n    poll_interval: int,\n) -> Dict[str, Any]:\n    \"\"\"Poll the token endpoint until the user approves or the code expires.\"\"\"\n    deadline = time.monotonic() + max(1, expires_in)\n    current_interval = max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n\n    while time.monotonic() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/api/oauth/token\",\n            data={\n                \"grant_type\": \"urn:ietf:params:oauth:grant-type:device_code\",\n                \"client_id\": client_id,\n                \"device_code\": device_code,\n            },\n        )\n\n        if response.status_code == 200:\n            payload = response.json()\n            if \"access_token\" not in payload:\n                raise ValueError(\"Token response did not include access_token\")\n            return payload\n\n        try:\n            error_payload = response.json()\n        except Exception:\n            response.raise_for_status()\n            raise RuntimeError(\"Token endpoint returned a non-JSON error response\")\n\n        error_code = error_payload.get(\"error\", \"\")\n        if error_code == \"authorization_pending\":\n            time.sleep(current_interval)\n            continue\n        if error_code == \"slow_down\":\n            current_interval = min(current_interval + 1, 30)\n            time.sleep(current_interval)\n            continue\n\n        description = error_payload.get(\"error_description\") or \"Unknown authentication error\"\n        raise RuntimeError(f\"{error_code}: {description}\")\n\n    raise TimeoutError(\"Timed out waiting for device authorization\")\n\n\n# =============================================================================\n# Soam Portal — token refresh, agent key minting, model discovery\n# =============================================================================\n\n# -----------------------------------------------------------------------------\n# Shared Soam token store — lets OAuth credentials persist across profiles\n# so a new `clawbot --profile <name> auth add soam --type oauth` can one-tap\n# import instead of running the full device-code flow every time.\n#\n# File lives at ${CLAWBOT_SHARED_AUTH_DIR}/soam_auth.json, defaulting to\n# ``<clawbot-root>/shared/soam_auth.json`` where ``<clawbot-root>`` is what\n# ``get_default_clawbot_root()`` returns — ``~/.clawbot`` on Linux/macOS,\n# ``%LOCALAPPDATA%\\clawbot`` on native Windows, or the Docker/custom root.\n# It is OUTSIDE any named profile's CLAWBOT_HOME so named profiles (which\n# typically live under ``<clawbot-root>/profiles/<name>/``) all see the\n# same file.\n#\n# Written on successful login and on every runtime refresh so the stored\n# refresh_token stays current even if one profile refreshes and rotates it.\n# If ever the stored refresh_token does go stale server-side, import fails\n# gracefully and the user falls back to the normal device-code flow.\n# -----------------------------------------------------------------------------\n\nSOAM_SHARED_STORE_FILENAME = \"soam_auth.json\"\n_soam_shared_lock_holder = threading.local()\n\n\ndef _soam_shared_auth_dir() -> Path:\n    \"\"\"Resolve the directory that holds the shared Soam token store.\n\n    Honors ``CLAWBOT_SHARED_AUTH_DIR`` so tests can redirect it to a tmp\n    path without touching the real user's home. Defaults to\n    ``<clawbot-root>/shared/``, where ``<clawbot-root>`` is what\n    :func:`clawbot_constants.get_default_clawbot_root` returns — so\n    Linux/macOS classic installs land at ``~/.clawbot/shared/``, native\n    Windows installs at ``%LOCALAPPDATA%\\\\clawbot\\\\shared\\\\``, and\n    Docker / custom ``CLAWBOT_HOME`` deployments at\n    ``<CLAWBOT_HOME>/shared/``. Sits outside any named profile so all\n    profiles under the same root share the store.\n    \"\"\"\n    override = os.getenv(\"CLAWBOT_SHARED_AUTH_DIR\", \"\").strip()\n    if override:\n        return Path(override).expanduser()\n    from clawbot_constants import get_default_clawbot_root\n    return get_default_clawbot_root() / \"shared\"\n\n\ndef _soam_shared_store_path() -> Path:\n    path = _soam_shared_auth_dir() / SOAM_SHARED_STORE_FILENAME\n    # Seat belt: if pytest is running and this resolves to a path under the\n    # real user's Clawbot root, refuse rather than silently corrupt cross-profile\n    # state. Tests must set CLAWBOT_SHARED_AUTH_DIR to a tmp_path (conftest\n    # does not do this automatically — mirror the _auth_file_path() guard\n    # so forgetting to set it fails loudly instead of writing to the real\n    # shared store).\n    if os.environ.get(\"PYTEST_CURRENT_TEST\"):\n        from clawbot_constants import get_default_clawbot_root\n        real_home_shared = (\n            get_default_clawbot_root() / \"shared\" / SOAM_SHARED_STORE_FILENAME\n        ).resolve(strict=False)\n        try:\n            resolved = path.resolve(strict=False)\n        except Exception:\n            resolved = path\n        if resolved == real_home_shared:\n            raise RuntimeError(\n                f\"Refusing to touch real user shared Soam auth store during test run: \"\n                f\"{path}. Set CLAWBOT_SHARED_AUTH_DIR to a tmp_path in your test fixture.\"\n            )\n    return path\n\n\n@contextmanager\ndef _soam_shared_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):\n    \"\"\"Cross-profile lock for the shared Soam OAuth store.\n\n    Lock ordering invariant: if both this and ``_auth_store_lock`` need\n    to be held, acquire ``_auth_store_lock`` FIRST. All runtime refresh\n    paths follow this order. The one exception is\n    ``_try_import_shared_soam_state``, which holds this lock alone for\n    the entire refresh+mint cycle so concurrent imports on sibling\n    profiles can't race on the single-use shared refresh token; that\n    helper must NOT be called with ``_auth_store_lock`` already held.\n    \"\"\"\n    try:\n        lock_path = _soam_shared_store_path().with_suffix(\".lock\")\n    except RuntimeError:\n        # No CLAWBOT_HOME yet (pre-setup): fall through without locking.\n        yield\n        return\n\n    with _file_lock(\n        lock_path,\n        _soam_shared_lock_holder,\n        timeout_seconds,\n        \"Timed out waiting for shared Soam auth lock\",\n    ):\n        yield\n\n\ndef _merge_shared_soam_oauth_state(state: Dict[str, Any]) -> bool:\n    \"\"\"Copy fresher shared OAuth tokens into a profile-local Soam state.\"\"\"\n    shared = _read_shared_soam_state()\n    if not shared:\n        return False\n\n    shared_refresh = shared.get(\"refresh_token\")\n    if not isinstance(shared_refresh, str) or not shared_refresh.strip():\n        return False\n\n    local_refresh = state.get(\"refresh_token\")\n    shared_access_exp = _parse_iso_timestamp(shared.get(\"expires_at\")) or 0.0\n    local_access_exp = _parse_iso_timestamp(state.get(\"expires_at\")) or 0.0\n    refresh_changed = shared_refresh.strip() != str(local_refresh or \"\").strip()\n    fresher_access = shared_access_exp > local_access_exp\n    if not refresh_changed and not fresher_access:\n        return False\n\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"token_type\",\n        \"scope\",\n        \"client_id\",\n        \"portal_base_url\",\n        \"inference_base_url\",\n        \"obtained_at\",\n        \"expires_at\",\n    ):\n        value = shared.get(key)\n        if value not in {None, \"\"}:\n            state[key] = value\n    return True\n\n\ndef _write_shared_soam_state(state: Dict[str, Any]) -> None:\n    \"\"\"Persist a minimal copy of the Soam OAuth state to the shared store.\n\n    Best-effort: any failure is swallowed after logging. The shared store\n    is a convenience layer; the per-profile auth.json remains the source\n    of truth.\n\n    We deliberately omit the runtime ``agent_key`` compatibility field\n    (either an invoke JWT or legacy opaque session key) — only OAuth tokens\n    are cross-profile useful.\n    \"\"\"\n    refresh_token = state.get(\"refresh_token\")\n    access_token = state.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        # No refresh_token = nothing worth sharing across profiles\n        return\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return\n\n    shared = {\n        \"_schema\": 1,\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"token_type\": state.get(\"token_type\") or \"Bearer\",\n        \"scope\": state.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n        \"client_id\": state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": state.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n        \"inference_base_url\": state.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n        \"obtained_at\": state.get(\"obtained_at\"),\n        \"expires_at\": state.get(\"expires_at\"),\n        \"updated_at\": datetime.now(timezone.utc).isoformat(),\n    }\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            path.parent.mkdir(parents=True, exist_ok=True)\n            try:\n                os.chmod(path.parent, 0o700)\n            except OSError:\n                pass\n            tmp = path.with_name(f\"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}\")\n            # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU\n            # window where write_text() + post-write chmod briefly exposed Soam\n            # refresh_token at process umask. See #19673, #21148.\n            fd = os.open(\n                str(tmp),\n                os.O_WRONLY | os.O_CREAT | os.O_EXCL,\n                stat.S_IRUSR | stat.S_IWUSR,\n            )\n            try:\n                with os.fdopen(fd, \"w\", encoding=\"utf-8\") as fh:\n                    fh.write(json.dumps(shared, indent=2, sort_keys=True))\n                    fh.flush()\n                    os.fsync(fh.fileno())\n                os.replace(tmp, path)\n            finally:\n                try:\n                    if tmp.exists():\n                        tmp.unlink()\n                except OSError:\n                    pass\n        _oauth_trace(\n            \"soam_shared_store_written\",\n            path=str(path),\n            refresh_token_fp=_token_fingerprint(refresh_token),\n        )\n    except Exception as exc:\n        logger.debug(\"Failed to write shared Soam auth store: %s\", exc)\n\n\ndef _read_shared_soam_state() -> Optional[Dict[str, Any]]:\n    \"\"\"Return the shared Soam OAuth state if present and well-formed.\n\n    Returns ``None`` when the file is missing, unreadable, malformed, or\n    lacks required fields. Callers should treat ``None`` as \"no shared\n    credentials available — fall through to device-code\".\n    \"\"\"\n    try:\n        path = _soam_shared_store_path()\n    except RuntimeError:\n        # Test seat belt tripped — treat as missing\n        return None\n    if not path.is_file():\n        return None\n    try:\n        payload = json.loads(path.read_text())\n    except (OSError, ValueError) as exc:\n        logger.debug(\"Shared Soam auth store at %s is unreadable: %s\", path, exc)\n        return None\n    if not isinstance(payload, dict):\n        return None\n    refresh_token = payload.get(\"refresh_token\")\n    access_token = payload.get(\"access_token\")\n    if not (isinstance(refresh_token, str) and refresh_token.strip()):\n        return None\n    if not (isinstance(access_token, str) and access_token.strip()):\n        return None\n    return payload\n\n\ndef _clear_shared_soam_state(reason: str) -> None:\n    \"\"\"Remove the shared Soam OAuth store after a terminal token failure.\"\"\"\n    try:\n        with _soam_shared_store_lock():\n            path = _soam_shared_store_path()\n            try:\n                path.unlink()\n            except FileNotFoundError:\n                pass\n        _oauth_trace(\"soam_shared_store_cleared\", reason=reason)\n    except Exception as exc:\n        logger.debug(\"Failed to clear shared Soam auth store: %s\", exc)\n\n\ndef _is_terminal_soam_refresh_error(exc: Exception) -> bool:\n    \"\"\"True when retrying the same Soam refresh token cannot succeed.\"\"\"\n    return (\n        isinstance(exc, AuthError)\n        and exc.provider == \"soam\"\n        and exc.code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n        and bool(exc.relogin_required)\n    )\n\n\ndef _quarantine_soam_oauth_state(\n    state: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> None:\n    \"\"\"Keep routing metadata but remove dead OAuth material so it is not replayed.\"\"\"\n    for key in (\n        \"access_token\",\n        \"refresh_token\",\n        \"expires_at\",\n        \"expires_in\",\n        \"obtained_at\",\n        \"agent_key\",\n        \"agent_key_id\",\n        \"agent_key_expires_at\",\n        \"agent_key_expires_in\",\n        \"agent_key_reused\",\n        \"agent_key_obtained_at\",\n    ):\n        state.pop(key, None)\n    state[\"last_auth_error\"] = {\n        \"provider\": \"soam\",\n        \"code\": error.code,\n        \"message\": str(error),\n        \"reason\": reason,\n        \"relogin_required\": True,\n        \"at\": datetime.now(timezone.utc).isoformat(),\n    }\n    _clear_shared_soam_state(reason)\n    invalidate_soam_auth_status_cache()\n\n\ndef _quarantine_soam_pool_entries(\n    auth_store: Dict[str, Any],\n    error: AuthError,\n    *,\n    reason: str,\n) -> bool:\n    \"\"\"Remove singleton-seeded Soam pool entries that contain dead OAuth state.\"\"\"\n    pool = auth_store.get(\"credential_pool\")\n    if not isinstance(pool, dict):\n        return False\n    entries = pool.get(\"soam\")\n    if not isinstance(entries, list):\n        return False\n\n    retained = []\n    removed = False\n    singleton_sources = {SOAM_DEVICE_CODE_SOURCE, f\"manual:{SOAM_DEVICE_CODE_SOURCE}\"}\n    for entry in entries:\n        if isinstance(entry, dict) and entry.get(\"source\") in singleton_sources:\n            removed = True\n            continue\n        retained.append(entry)\n\n    if removed:\n        pool[\"soam\"] = retained\n        _oauth_trace(\n            \"soam_pool_device_code_quarantined\",\n            reason=reason,\n            error_code=error.code,\n        )\n    return removed\n\n\ndef _try_import_shared_soam_state(\n    *,\n    timeout_seconds: float = 15.0,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Optional[Dict[str, Any]]:\n    \"\"\"Attempt to rehydrate Soam OAuth state from the shared store.\n\n    Reads the shared file (if present), runs a forced refresh+mint using\n    the stored refresh_token to produce a fresh access_token + agent_key\n    scoped to this profile, and returns the full auth_state dict ready\n    for ``persist_soam_credentials()``.\n\n    Returns ``None`` when no shared state is available or the rehydrate\n    fails for any reason (expired refresh_token, portal unreachable,\n    etc.) — caller should then fall through to the normal device-code\n    flow.\n    \"\"\"\n    try:\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            shared = _read_shared_soam_state()\n            if not shared:\n                return None\n\n            # Build a full state dict so refresh_soam_oauth_from_state has every\n            # field it needs. force_refresh=True gets us a fresh access_token\n            # for this profile; fresh auth mode avoids stale cached legacy keys.\n            state: Dict[str, Any] = {\n                \"access_token\": shared.get(\"access_token\"),\n                \"refresh_token\": shared.get(\"refresh_token\"),\n                \"client_id\": shared.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID,\n                \"portal_base_url\": shared.get(\"portal_base_url\") or DEFAULT_SOAM_PORTAL_URL,\n                \"inference_base_url\": shared.get(\"inference_base_url\") or DEFAULT_SOAM_INFERENCE_URL,\n                \"token_type\": shared.get(\"token_type\") or \"Bearer\",\n                \"scope\": shared.get(\"scope\") or DEFAULT_SOAM_SCOPE,\n                \"obtained_at\": shared.get(\"obtained_at\"),\n                \"expires_at\": shared.get(\"expires_at\"),\n                \"agent_key\": None,\n                \"agent_key_expires_at\": None,\n                \"tls\": {\"insecure\": False, \"ca_bundle\": None},\n            }\n\n            def _persist_shared_refresh(updated_state: Dict[str, Any], _reason: str) -> None:\n                _write_shared_soam_state(updated_state)\n\n            refreshed = refresh_soam_oauth_from_state(\n                state,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                timeout_seconds=timeout_seconds,\n                force_refresh=True,\n                inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n                on_state_update=_persist_shared_refresh,\n            )\n            _write_shared_soam_state(refreshed)\n    except AuthError as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n            error_code=getattr(exc, \"code\", None),\n        )\n        if _is_terminal_soam_refresh_error(exc):\n            _clear_shared_soam_state(\"shared_import_terminal_refresh_failure\")\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n    except Exception as exc:\n        _oauth_trace(\n            \"soam_shared_import_failed\",\n            error_type=type(exc).__name__,\n        )\n        logger.debug(\"Shared Soam import failed: %s\", exc)\n        return None\n\n    return refreshed\n\n\ndef _refresh_access_token(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    client_id: str,\n    refresh_token: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/token\",\n        headers={\"x-soam-refresh-token\": refresh_token},\n        data={\n            \"grant_type\": \"refresh_token\",\n            \"client_id\": client_id,\n        },\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"access_token\" not in payload:\n            raise AuthError(\"Refresh response missing access_token\",\n                            provider=\"soam\", code=\"invalid_token\", relogin_required=True)\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Refresh token exchange failed\",\n                        provider=\"soam\", relogin_required=True) from exc\n\n    code = str(error_payload.get(\"error\", \"invalid_grant\"))\n    description = str(error_payload.get(\"error_description\") or \"Refresh token exchange failed\")\n    relogin = code in {\"invalid_grant\", \"invalid_token\", \"refresh_token_reused\"}\n\n    # Detect the OAuth 2.1 \"refresh token reuse\" signal from the Soam portal\n    # server and surface an actionable message.  This fires when an external\n    # process (health-check script, monitoring tool, custom self-heal hook)\n    # called POST /api/oauth/token with Clawbot's refresh_token without\n    # persisting the rotated token back to auth.json — the server then\n    # retires the original RT, Clawbot's next refresh uses it, and the whole\n    # session chain gets revoked as a token-theft signal (#15099).\n    lowered = description.lower()\n    if code == \"refresh_token_reused\" or \"reuse\" in lowered or \"reuse detected\" in lowered:\n        description = (\n            \"Soam Portal detected refresh-token reuse and revoked this session.\\n\"\n            \"This usually means an external process (monitoring script, \"\n            \"custom self-heal hook, or another Clawbot install sharing \"\n            \"~/.clawbot/auth.json) called POST /api/oauth/token with Clawbot's \"\n            \"refresh token without persisting the rotated token back.\\n\"\n            \"Soam refresh tokens are single-use — only Clawbot may call the \"\n            \"refresh endpoint. For health checks, use `clawbot auth status` \"\n            \"instead.\\n\"\n            \"Re-authenticate with: clawbot auth add soam\"\n        )\n        relogin = True\n\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef _mint_agent_key(\n    *,\n    client: httpx.Client,\n    portal_base_url: str,\n    access_token: str,\n    min_ttl_seconds: int,\n) -> Dict[str, Any]:\n    \"\"\"Mint (or reuse) a short-lived inference API key.\"\"\"\n    response = client.post(\n        f\"{portal_base_url}/api/oauth/agent-key\",\n        headers={\"Authorization\": f\"Bearer {access_token}\"},\n        json={\"min_ttl_seconds\": max(60, int(min_ttl_seconds))},\n    )\n\n    if response.status_code == 200:\n        payload = response.json()\n        if \"api_key\" not in payload:\n            raise AuthError(\"Mint response missing api_key\",\n                            provider=\"soam\", code=\"server_error\")\n        return payload\n\n    try:\n        error_payload = response.json()\n    except Exception as exc:\n        raise AuthError(\"Agent key mint request failed\",\n                        provider=\"soam\", code=\"server_error\") from exc\n\n    code = str(error_payload.get(\"error\", \"server_error\"))\n    description = str(error_payload.get(\"error_description\") or \"Agent key mint request failed\")\n    relogin = code in {\"invalid_token\", \"invalid_grant\"}\n    raise AuthError(description, provider=\"soam\", code=code, relogin_required=relogin)\n\n\ndef fetch_soam_models(\n    *,\n    inference_base_url: str,\n    api_key: str,\n    timeout_seconds: float = 15.0,\n    verify: bool | str = True,\n) -> List[str]:\n    \"\"\"Fetch available model IDs from the Soam inference API.\"\"\"\n    timeout = httpx.Timeout(timeout_seconds)\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        response = client.get(\n            f\"{inference_base_url.rstrip('/')}/models\",\n            headers={\"Authorization\": f\"Bearer {api_key}\"},\n        )\n\n    if response.status_code != 200:\n        description = f\"/models request failed with status {response.status_code}\"\n        try:\n            err = response.json()\n            description = str(err.get(\"error_description\") or err.get(\"error\") or description)\n        except Exception as e:\n            logger.debug(\"Could not parse error response JSON: %s\", e)\n        raise AuthError(description, provider=\"soam\", code=\"models_fetch_failed\")\n\n    payload = response.json()\n    data = payload.get(\"data\")\n    if not isinstance(data, list):\n        return []\n\n    model_ids: List[str] = []\n    for item in data:\n        if not isinstance(item, dict):\n            continue\n        model_id = item.get(\"id\")\n        if isinstance(model_id, str) and model_id.strip():\n            mid = model_id.strip()\n            # Skip Clawbot models — they're not reliable for agentic tool-calling\n            if \"clawbot\" in mid.lower():\n                continue\n            model_ids.append(mid)\n\n    # Sort: prefer opus > pro > haiku/flash > sonnet (sonnet is cheap/fast,\n    # users who want the best model should see opus first).\n    def _model_priority(mid: str) -> tuple:\n        low = mid.lower()\n        if \"opus\" in low:\n            return (0, mid)\n        if \"pro\" in low and \"sonnet\" not in low:\n            return (1, mid)\n        if \"sonnet\" in low:\n            return (3, mid)\n        return (2, mid)\n\n    model_ids.sort(key=_model_priority)\n    return list(dict.fromkeys(model_ids))\n\n\ndef _agent_key_is_usable(state: Dict[str, Any], min_ttl_seconds: int) -> bool:\n    key = state.get(\"agent_key\")\n    if not isinstance(key, str) or not key.strip():\n        return False\n    if _decode_jwt_claims(key):\n        if _soam_legacy_session_keys_forced():\n            return False\n        return _soam_invoke_jwt_is_usable(\n            key,\n            scope=state.get(\"scope\"),\n            expires_at=state.get(\"agent_key_expires_at\"),\n        )\n    return not _is_expiring(state.get(\"agent_key_expires_at\"), min_ttl_seconds)\n\n\ndef resolve_soam_access_token(\n    *,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    refresh_skew_seconds: int = ACCESS_TOKEN_REFRESH_SKEW_SECONDS,\n) -> str:\n    \"\"\"Resolve a refresh-aware Soam Portal access token for managed tool gateways.\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\n                \"Clawbot is not logged into Soam Portal.\",\n                provider=\"soam\",\n                relogin_required=True,\n            )\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n\n        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n            merged_shared = _merge_shared_soam_oauth_state(state)\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\n                    \"No access token found for Soam Portal login.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            if not _is_expiring(state.get(\"expires_at\"), refresh_skew_seconds):\n                if merged_shared:\n                    _save_provider_state(auth_store, \"soam\", state)\n                    _save_auth_store(auth_store)\n                return access_token\n\n            if not isinstance(refresh_token, str) or not refresh_token:\n                raise AuthError(\n                    \"Session expired and no refresh token is available.\",\n                    provider=\"soam\",\n                    relogin_required=True,\n                )\n\n            timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n            with httpx.Client(\n                timeout=timeout,\n                headers={\"Accept\": \"application/json\"},\n                verify=verify,\n            ) as client:\n                try:\n                    refreshed = _refresh_access_token(\n                        client=client,\n                        portal_base_url=portal_base_url,\n                        client_id=client_id,\n                        refresh_token=refresh_token,\n                    )\n                except AuthError as exc:\n                    if _is_terminal_soam_refresh_error(exc):\n                        _quarantine_soam_oauth_state(\n                            state,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _quarantine_soam_pool_entries(\n                            auth_store,\n                            exc,\n                            reason=\"managed_access_token_refresh_failure\",\n                        )\n                        _save_provider_state(auth_store, \"soam\", state)\n                        _save_auth_store(auth_store)\n                    raise\n\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl,\n                tz=timezone.utc,\n            ).isoformat()\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n            _save_provider_state(auth_store, \"soam\", state)\n            _save_auth_store(auth_store)\n            _write_shared_soam_state(state)\n            return state[\"access_token\"]\n\n\ndef refresh_soam_oauth_pure(\n    access_token: str,\n    refresh_token: str,\n    client_id: str,\n    portal_base_url: str,\n    inference_base_url: str,\n    *,\n    token_type: str = \"Bearer\",\n    scope: str = DEFAULT_SOAM_SCOPE,\n    obtained_at: Optional[str] = None,\n    expires_at: Optional[str] = None,\n    agent_key: Optional[str] = None,\n    agent_key_expires_at: Optional[str] = None,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth state without mutating auth.json directly.\n\n    ``on_state_update`` is called after a successful access-token refresh and\n    before any subsequent agent-key mint. Callers that own persistent state can\n    use it to save the newly rotated refresh token before later work can fail.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    state: Dict[str, Any] = {\n        \"access_token\": access_token,\n        \"refresh_token\": refresh_token,\n        \"client_id\": client_id or DEFAULT_SOAM_CLIENT_ID,\n        \"portal_base_url\": (portal_base_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\"),\n        \"inference_base_url\": (inference_base_url or DEFAULT_SOAM_INFERENCE_URL).rstrip(\"/\"),\n        \"token_type\": token_type or \"Bearer\",\n        \"scope\": scope or DEFAULT_SOAM_SCOPE,\n        \"obtained_at\": obtained_at,\n        \"expires_at\": expires_at,\n        \"agent_key\": agent_key,\n        \"agent_key_expires_at\": agent_key_expires_at,\n        \"tls\": {\n            \"insecure\": bool(insecure),\n            \"ca_bundle\": ca_bundle,\n        },\n    }\n    verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n    timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        min_agent_key_ttl = max(60, int(min_key_ttl_seconds))\n        legacy_session_keys = _soam_legacy_session_keys_forced()\n        current_invoke_jwt_usable = (\n            not legacy_session_keys\n            and _soam_invoke_jwt_is_usable(\n                state.get(\"access_token\"),\n                scope=state.get(\"scope\"),\n                expires_at=state.get(\"expires_at\"),\n            )\n        )\n        if (\n            force_refresh\n            or (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            )\n        ):\n            refreshed = _refresh_access_token(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                client_id=state[\"client_id\"],\n                refresh_token=state[\"refresh_token\"],\n            )\n            now = datetime.now(timezone.utc)\n            access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n            state[\"access_token\"] = refreshed[\"access_token\"]\n            state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or state[\"refresh_token\"]\n            state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n            state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n            refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n            if refreshed_url:\n                state[\"inference_base_url\"] = refreshed_url\n            state[\"obtained_at\"] = now.isoformat()\n            state[\"expires_in\"] = access_ttl\n            state[\"expires_at\"] = datetime.fromtimestamp(\n                now.timestamp() + access_ttl, tz=timezone.utc\n            ).isoformat()\n            if on_state_update is not None:\n                on_state_update(dict(state), \"post_refresh_access_token\")\n\n        selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n            state,\n            min_key_ttl_seconds=min_agent_key_ttl,\n            inference_auth_mode=inference_auth_mode,\n        )\n        if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n            _select_soam_invoke_jwt(state)\n        elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_MINT:\n            _log_soam_legacy_session_key_selected(\n                fallback_reason or \"legacy_session_key_required\",\n                access_token=state.get(\"access_token\"),\n            )\n            mint_payload = _mint_agent_key(\n                client=client,\n                portal_base_url=state[\"portal_base_url\"],\n                access_token=state[\"access_token\"],\n                min_ttl_seconds=min_key_ttl_seconds,\n            )\n            now = datetime.now(timezone.utc)\n            state[\"agent_key\"] = mint_payload.get(\"api_key\")\n            state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n            state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n            state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n            state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n            state[\"agent_key_obtained_at\"] = now.isoformat()\n            minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n            if minted_url:\n                state[\"inference_base_url\"] = minted_url\n\n    return state\n\n\ndef refresh_soam_oauth_from_state(\n    state: Dict[str, Any],\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    force_refresh: bool = False,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n    on_state_update: Optional[Callable[[Dict[str, Any], str], None]] = None,\n) -> Dict[str, Any]:\n    \"\"\"Refresh Soam OAuth from a state dict. Thin wrapper around refresh_soam_oauth_pure.\"\"\"\n    tls = state.get(\"tls\") or {}\n    return refresh_soam_oauth_pure(\n        state.get(\"access_token\", \"\"),\n        state.get(\"refresh_token\", \"\"),\n        state.get(\"client_id\", \"clawbot-cli\"),\n        state.get(\"portal_base_url\", DEFAULT_SOAM_PORTAL_URL),\n        state.get(\"inference_base_url\", DEFAULT_SOAM_INFERENCE_URL),\n        token_type=state.get(\"token_type\", \"Bearer\"),\n        scope=state.get(\"scope\", DEFAULT_SOAM_SCOPE),\n        obtained_at=state.get(\"obtained_at\"),\n        expires_at=state.get(\"expires_at\"),\n        agent_key=state.get(\"agent_key\"),\n        agent_key_expires_at=state.get(\"agent_key_expires_at\"),\n        min_key_ttl_seconds=min_key_ttl_seconds,\n        timeout_seconds=timeout_seconds,\n        insecure=tls.get(\"insecure\"),\n        ca_bundle=tls.get(\"ca_bundle\"),\n        force_refresh=force_refresh,\n        inference_auth_mode=inference_auth_mode,\n        on_state_update=on_state_update,\n    )\n\n\ndef persist_soam_credentials(\n    creds: Dict[str, Any],\n    *,\n    label: Optional[str] = None,\n):\n    \"\"\"Persist minted Soam OAuth credentials as the singleton provider state\n    and ensure the credential pool is in sync.\n\n    Soam credentials are read at runtime from two independent locations:\n\n    - ``providers.soam``: singleton state read by\n      ``resolve_soam_runtime_credentials()`` during 401 recovery and by\n      ``_seed_from_singletons()`` during pool load.\n    - ``credential_pool.soam``: used by the runtime ``pool.select()`` path.\n\n    Historically ``clawbot auth add soam`` wrote a ``manual:device_code`` pool\n    entry only, skipping ``providers.soam``.  When the 24h agent_key TTL\n    expired, the recovery path read the empty singleton state and raised\n    ``AuthError`` silently (``logger.debug`` at INFO level).\n\n    This helper writes ``providers.soam`` then calls ``load_pool(\"soam\")`` so\n    ``_seed_from_singletons`` materialises the canonical ``device_code`` pool\n    entry from the singleton.  Re-running login upserts the same entry in\n    place; the pool never accumulates duplicate device_code rows.\n\n    ``label`` is an optional user-chosen display name (from\n    ``clawbot auth add soam --label <name>``).  It gets embedded in the\n    singleton state so that ``_seed_from_singletons`` uses it as the pool\n    entry's label on every subsequent ``load_pool(\"soam\")`` instead of the\n    auto-derived token fingerprint.  When ``None``, the auto-derived label\n    via ``label_from_token`` is used (unchanged default behaviour).\n\n    Returns the upserted :class:`PooledCredential` entry (or ``None`` if\n    seeding somehow produced no match — shouldn't happen).\n    \"\"\"\n    from agent.credential_pool import load_pool\n\n    state = dict(creds)\n    if label and str(label).strip():\n        state[\"label\"] = str(label).strip()\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"soam\", state)\n        _save_auth_store(auth_store)\n\n    # Mirror to the shared store so a new profile can one-tap import\n    # these credentials via `clawbot auth add soam --type oauth`. Best-\n    # effort: any I/O failure is logged and swallowed (the per-profile\n    # auth.json is still the source of truth).\n    _write_shared_soam_state(state)\n\n    pool = load_pool(\"soam\")\n    return next(\n        (e for e in pool.entries() if e.source == SOAM_DEVICE_CODE_SOURCE),\n        None,\n    )\n\n\ndef _sync_soam_pool_from_auth_store() -> None:\n    \"\"\"Best-effort pool reseed after providers.soam changes; never fail login.\"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        load_pool(\"soam\")\n    except Exception as exc:\n        logger.debug(\"Failed to sync Soam credential pool from auth store: %s\", exc)\n\n\ndef resolve_soam_runtime_credentials(\n    *,\n    min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,\n    timeout_seconds: float = 15.0,\n    insecure: Optional[bool] = None,\n    ca_bundle: Optional[str] = None,\n    inference_auth_mode: str = SOAM_INFERENCE_AUTH_MODE_AUTO,\n) -> Dict[str, Any]:\n    \"\"\"\n    Resolve Soam inference credentials for runtime use.\n\n    Ensures access_token is valid (refreshes if needed) and a short-lived\n    inference key is present with minimum TTL (mints/reuses as needed).\n    Concurrent processes coordinate through the auth store file lock.\n\n    Returns dict with: provider, base_url, api_key, key_id, expires_at,\n    expires_in, source (\"invoke_jwt\", \"cache\", or \"portal\"), and auth_path.\n    \"\"\"\n    inference_auth_mode = _normalize_soam_inference_auth_mode(inference_auth_mode)\n    min_key_ttl_seconds = max(60, int(min_key_ttl_seconds))\n    sequence_id = uuid.uuid4().hex[:12]\n\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        state = _load_provider_state(auth_store, \"soam\")\n\n        if not state:\n            raise AuthError(\"Clawbot is not logged into Soam Portal.\",\n                            provider=\"soam\", relogin_required=True)\n\n        persisted_state = dict(state)\n        state_persisted = False\n\n        portal_base_url = (\n            _optional_base_url(state.get(\"portal_base_url\"))\n            or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n            or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n            or DEFAULT_SOAM_PORTAL_URL\n        ).rstrip(\"/\")\n        inference_base_url = (\n            _optional_base_url(state.get(\"inference_base_url\"))\n            or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n            or DEFAULT_SOAM_INFERENCE_URL\n        ).rstrip(\"/\")\n        client_id = str(state.get(\"client_id\") or DEFAULT_SOAM_CLIENT_ID)\n\n        def _persist_state(reason: str) -> None:\n            nonlocal persisted_state, state_persisted\n            # Skip writes where only derived TTL countdowns changed; this keeps\n            # the mtime-keyed Soam auth-status cache warm during read paths.\n            if (\n                _soam_effective_provider_state(state)\n                == _soam_effective_provider_state(persisted_state)\n            ):\n                _oauth_trace(\n                    \"soam_state_persist_skipped\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                )\n                return\n            try:\n                _save_provider_state(auth_store, \"soam\", state)\n                _save_auth_store(auth_store)\n            except Exception as exc:\n                _oauth_trace(\n                    \"soam_state_persist_failed\",\n                    sequence_id=sequence_id,\n                    reason=reason,\n                    error_type=type(exc).__name__,\n                )\n                raise\n            _oauth_trace(\n                \"soam_state_persisted\",\n                sequence_id=sequence_id,\n                reason=reason,\n                refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n                access_token_fp=_token_fingerprint(state.get(\"access_token\")),\n            )\n            persisted_state = dict(state)\n            state_persisted = True\n            # Mirror post-refresh state to the shared store so sibling\n            # profiles don't hold stale refresh_tokens after rotation.\n            # Best-effort — any failure is logged and swallowed inside\n            # _write_shared_soam_state.\n            _write_shared_soam_state(state)\n\n        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)\n        timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)\n        _oauth_trace(\n            \"soam_runtime_credentials_start\",\n            sequence_id=sequence_id,\n            inference_auth_mode=inference_auth_mode,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            refresh_token_fp=_token_fingerprint(state.get(\"refresh_token\")),\n        )\n\n        with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n            access_token = state.get(\"access_token\")\n            refresh_token = state.get(\"refresh_token\")\n\n            if not isinstance(access_token, str) or not access_token:\n                raise AuthError(\"No access token found for Soam Portal login.\",\n                                provider=\"soam\", relogin_required=True)\n\n            # Step 1: refresh access token if expiring. If the access token\n            # is already a valid invoke JWT, trust its own exp claim even when\n            # older auth.json metadata has a stale/missing expires_at.\n            current_invoke_jwt_usable = (\n                not _soam_legacy_session_keys_forced()\n                and _soam_invoke_jwt_is_usable(\n                    access_token,\n                    scope=state.get(\"scope\"),\n                    expires_at=state.get(\"expires_at\"),\n                )\n            )\n            if (\n                _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                and not current_invoke_jwt_usable\n            ):\n                with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                    if _merge_shared_soam_oauth_state(state):\n                        access_token = state.get(\"access_token\")\n                        refresh_token = state.get(\"refresh_token\")\n                        _persist_state(\"post_shared_merge_access_expiring\")\n\n                    if (\n                        _is_expiring(state.get(\"expires_at\"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS)\n                        and not _soam_invoke_jwt_is_usable(\n                            access_token,\n                            scope=state.get(\"scope\"),\n                            expires_at=state.get(\"expires_at\"),\n                        )\n                    ):\n                        if not isinstance(refresh_token, str) or not refresh_token:\n                            raise AuthError(\"Session expired and no refresh token is available.\",\n                                            provider=\"soam\", relogin_required=True)\n\n                        _oauth_trace(\n                            \"refresh_start\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        try:\n                            refreshed = _refresh_access_token(\n                                client=client, portal_base_url=portal_base_url,\n                                client_id=client_id, refresh_token=refresh_token,\n                            )\n                        except AuthError as exc:\n                            if _is_terminal_soam_refresh_error(exc):\n                                _quarantine_soam_oauth_state(\n                                    state,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _quarantine_soam_pool_entries(\n                                    auth_store,\n                                    exc,\n                                    reason=\"runtime_access_refresh_failure\",\n                                )\n                                _persist_state(\"terminal_runtime_access_refresh_failure\")\n                            raise\n                        now = datetime.now(timezone.utc)\n                        access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                        previous_refresh_token = refresh_token\n                        state[\"access_token\"] = refreshed[\"access_token\"]\n                        state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or refresh_token\n                        state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                        state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                        refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                        if refreshed_url:\n                            inference_base_url = refreshed_url\n                        state[\"obtained_at\"] = now.isoformat()\n                        state[\"expires_in\"] = access_ttl\n                        state[\"expires_at\"] = datetime.fromtimestamp(\n                            now.timestamp() + access_ttl, tz=timezone.utc\n                        ).isoformat()\n                        access_token = state[\"access_token\"]\n                        refresh_token = state[\"refresh_token\"]\n                        _oauth_trace(\n                            \"refresh_success\",\n                            sequence_id=sequence_id,\n                            reason=\"access_expiring\",\n                            previous_refresh_token_fp=_token_fingerprint(previous_refresh_token),\n                            new_refresh_token_fp=_token_fingerprint(refresh_token),\n                        )\n                        # Persist immediately so downstream mint failures cannot drop rotated refresh tokens.\n                        _persist_state(\"post_refresh_access_expiring\")\n\n            # Step 2: resolve the compatibility ``agent_key`` field. Preferred\n            # path stores the NAS invoke JWT there; legacy path mints/reuses\n            # the opaque session key.\n            used_cached_key = False\n            mint_payload: Optional[Dict[str, Any]] = None\n            selected_auth_path, fallback_reason = _choose_soam_inference_auth_path(\n                state,\n                access_token=access_token,\n                min_key_ttl_seconds=min_key_ttl_seconds,\n                inference_auth_mode=inference_auth_mode,\n            )\n\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                _select_soam_invoke_jwt(\n                    state,\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n            elif selected_auth_path == SOAM_AUTH_PATH_LEGACY_SESSION_KEY_CACHE:\n                used_cached_key = True\n                logger.info(\"Soam inference auth: using cached agent_key\")\n                _oauth_trace(\"agent_key_reuse\", sequence_id=sequence_id)\n            else:\n                _log_soam_legacy_session_key_selected(\n                    fallback_reason or \"legacy_session_key_required\",\n                    access_token=access_token,\n                    sequence_id=sequence_id,\n                )\n                try:\n                    _oauth_trace(\n                        \"mint_start\",\n                        sequence_id=sequence_id,\n                        access_token_fp=_token_fingerprint(access_token),\n                    )\n                    mint_payload = _mint_agent_key(\n                        client=client, portal_base_url=portal_base_url,\n                        access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                    )\n                except AuthError as exc:\n                    _oauth_trace(\n                        \"mint_error\",\n                        sequence_id=sequence_id,\n                        code=exc.code,\n                    )\n                    # Retry path: access token may be stale server-side despite local checks\n                    latest_refresh_token = state.get(\"refresh_token\")\n                    if (\n                        exc.code in {\"invalid_token\", \"invalid_grant\"}\n                        and isinstance(latest_refresh_token, str)\n                        and latest_refresh_token\n                    ):\n                        with _soam_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):\n                            if _merge_shared_soam_oauth_state(state):\n                                access_token = state.get(\"access_token\")\n                                latest_refresh_token = state.get(\"refresh_token\")\n                                _persist_state(\"post_shared_merge_mint_retry\")\n                            else:\n                                _oauth_trace(\n                                    \"refresh_start\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                )\n                                try:\n                                    refreshed = _refresh_access_token(\n                                        client=client, portal_base_url=portal_base_url,\n                                        client_id=client_id, refresh_token=latest_refresh_token,\n                                    )\n                                except AuthError as exc:\n                                    if _is_terminal_soam_refresh_error(exc):\n                                        _quarantine_soam_oauth_state(\n                                            state,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _quarantine_soam_pool_entries(\n                                            auth_store,\n                                            exc,\n                                            reason=\"runtime_mint_retry_refresh_failure\",\n                                        )\n                                        _persist_state(\"terminal_runtime_mint_retry_refresh_failure\")\n                                    raise\n                                now = datetime.now(timezone.utc)\n                                access_ttl = _coerce_ttl_seconds(refreshed.get(\"expires_in\"))\n                                state[\"access_token\"] = refreshed[\"access_token\"]\n                                state[\"refresh_token\"] = refreshed.get(\"refresh_token\") or latest_refresh_token\n                                state[\"token_type\"] = refreshed.get(\"token_type\") or state.get(\"token_type\") or \"Bearer\"\n                                state[\"scope\"] = refreshed.get(\"scope\") or state.get(\"scope\")\n                                refreshed_url = _optional_base_url(refreshed.get(\"inference_base_url\"))\n                                if refreshed_url:\n                                    inference_base_url = refreshed_url\n                                state[\"obtained_at\"] = now.isoformat()\n                                state[\"expires_in\"] = access_ttl\n                                state[\"expires_at\"] = datetime.fromtimestamp(\n                                    now.timestamp() + access_ttl, tz=timezone.utc\n                                ).isoformat()\n                                access_token = state[\"access_token\"]\n                                refresh_token = state[\"refresh_token\"]\n                                _oauth_trace(\n                                    \"refresh_success\",\n                                    sequence_id=sequence_id,\n                                    reason=\"mint_retry_after_invalid_token\",\n                                    previous_refresh_token_fp=_token_fingerprint(latest_refresh_token),\n                                    new_refresh_token_fp=_token_fingerprint(refresh_token),\n                                )\n                                # Persist retry refresh immediately for crash safety and cross-process visibility.\n                                _persist_state(\"post_refresh_mint_retry\")\n\n                        retry_inference_auth_mode = (\n                            SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            if inference_auth_mode == SOAM_INFERENCE_AUTH_MODE_LEGACY\n                            else SOAM_INFERENCE_AUTH_MODE_FRESH\n                        )\n                        retry_auth_path, _ = _choose_soam_inference_auth_path(\n                            state,\n                            access_token=access_token,\n                            min_key_ttl_seconds=min_key_ttl_seconds,\n                            inference_auth_mode=retry_inference_auth_mode,\n                        )\n                        if retry_auth_path == SOAM_AUTH_PATH_INVOKE_JWT:\n                            mint_payload = None\n                            selected_auth_path = SOAM_AUTH_PATH_INVOKE_JWT\n                            _select_soam_invoke_jwt(\n                                state,\n                                access_token=access_token,\n                                sequence_id=sequence_id,\n                            )\n                        else:\n                            mint_payload = _mint_agent_key(\n                                client=client, portal_base_url=portal_base_url,\n                                access_token=access_token, min_ttl_seconds=min_key_ttl_seconds,\n                            )\n                    else:\n                        raise\n\n            if mint_payload is not None:\n                now = datetime.now(timezone.utc)\n                state[\"agent_key\"] = mint_payload.get(\"api_key\")\n                state[\"agent_key_id\"] = mint_payload.get(\"key_id\")\n                state[\"agent_key_expires_at\"] = mint_payload.get(\"expires_at\")\n                state[\"agent_key_expires_in\"] = mint_payload.get(\"expires_in\")\n                state[\"agent_key_reused\"] = bool(mint_payload.get(\"reused\", False))\n                state[\"agent_key_obtained_at\"] = now.isoformat()\n                minted_url = _optional_base_url(mint_payload.get(\"inference_base_url\"))\n                if minted_url:\n                    inference_base_url = minted_url\n                _oauth_trace(\n                    \"mint_success\",\n                    sequence_id=sequence_id,\n                    reused=bool(mint_payload.get(\"reused\", False)),\n                )\n\n            # Persist routing and TLS metadata for non-interactive refresh/mint\n            state[\"portal_base_url\"] = portal_base_url\n            state[\"inference_base_url\"] = inference_base_url\n            state[\"client_id\"] = client_id\n            state[\"tls\"] = {\n                \"insecure\": verify is False,\n                \"ca_bundle\": verify if isinstance(verify, str) else None,\n            }\n\n        _persist_state(\"resolve_soam_runtime_credentials_final\")\n\n    if state_persisted:\n        _sync_soam_pool_from_auth_store()\n\n    api_key = state.get(\"agent_key\")\n    if not isinstance(api_key, str) or not api_key:\n        raise AuthError(\"Failed to resolve a Soam inference API key\",\n                        provider=\"soam\", code=\"server_error\")\n\n    expires_at = state.get(\"agent_key_expires_at\")\n    expires_epoch = _parse_iso_timestamp(expires_at)\n    expires_in = (\n        max(0, int(expires_epoch - time.time()))\n        if expires_epoch is not None\n        else _coerce_ttl_seconds(state.get(\"agent_key_expires_in\"))\n    )\n\n    return {\n        \"provider\": \"soam\",\n        \"base_url\": inference_base_url,\n        \"api_key\": api_key,\n        \"key_id\": state.get(\"agent_key_id\"),\n        \"expires_at\": expires_at,\n        \"expires_in\": expires_in,\n        \"source\": (\n            SOAM_AUTH_PATH_INVOKE_JWT\n            if selected_auth_path == SOAM_AUTH_PATH_INVOKE_JWT\n            else (\"cache\" if used_cached_key else \"portal\")\n        ),\n        \"auth_path\": selected_auth_path,\n    }\n\n\n# =============================================================================\n# Status helpers\n# =============================================================================\n\ndef _empty_soam_auth_status() -> Dict[str, Any]:\n    return {\n        \"logged_in\": False,\n        \"portal_base_url\": None,\n        \"inference_base_url\": None,\n        \"access_expires_at\": None,\n        \"agent_key_expires_at\": None,\n        \"has_refresh_token\": False,\n    }\n\n\ndef _snapshot_soam_pool_status() -> Dict[str, Any]:\n    \"\"\"Best-effort status from the credential pool.\n\n    This is a fallback only. The auth-store provider state is the runtime source\n    of truth because it is what ``resolve_soam_runtime_credentials()`` refreshes\n    and mints against.\n    \"\"\"\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"soam\")\n        if not pool or not pool.has_credentials():\n            return _empty_soam_auth_status()\n\n        entries = list(pool.entries())\n        if not entries:\n            return _empty_soam_auth_status()\n\n        def _entry_sort_key(entry: Any) -> tuple[float, float, int]:\n            agent_exp = _parse_iso_timestamp(getattr(entry, \"agent_key_expires_at\", None)) or 0.0\n            access_exp = _parse_iso_timestamp(getattr(entry, \"expires_at\", None)) or 0.0\n            priority = int(getattr(entry, \"priority\", 0) or 0)\n            return (agent_exp, access_exp, -priority)\n\n        entry = max(entries, key=_entry_sort_key)\n        access_token = (\n            getattr(entry, \"access_token\", None)\n            or getattr(entry, \"runtime_api_key\", \"\")\n        )\n        if not access_token:\n            return _empty_soam_auth_status()\n\n        return {\n            \"logged_in\": True,\n            \"portal_base_url\": getattr(entry, \"portal_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"inference_base_url\": getattr(entry, \"inference_base_url\", None)\n            or getattr(entry, \"base_url\", None),\n            \"access_token\": access_token,\n            \"access_expires_at\": getattr(entry, \"expires_at\", None),\n            \"agent_key_expires_at\": getattr(entry, \"agent_key_expires_at\", None),\n            \"has_refresh_token\": bool(getattr(entry, \"refresh_token\", None)),\n            \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n        }\n    except Exception:\n        return _empty_soam_auth_status()\n\n\n# ── Process-level memo for get_soam_auth_status() ──\n# get_soam_auth_status() validates state by calling resolve_soam_runtime_credentials(),\n# which does a synchrosoam OAuth refresh POST to portal.aayushsoam.com. That can take\n# ~350ms even on the failure path, and read-only UI surfaces (`clawbot tools`, status panels,\n# subscription-feature checks) call it many times per render — `clawbot tools` → \"All Platforms\"\n# was firing the refresh ~31× during one menu paint, racking up >13s of HTTP and burning\n# single-use refresh tokens. Cache the snapshot for a few seconds, keyed on the auth.json\n# mtime so that `clawbot auth login/logout/add/remove` invalidate naturally on the next call.\n_SOAM_AUTH_STATUS_CACHE_TTL = 15.0  # seconds\n_soam_auth_status_cache: Optional[Tuple[float, Optional[float], Dict[str, Any]]] = None\n\n\ndef _auth_file_mtime() -> Optional[float]:\n    try:\n        return _auth_file_path().stat().st_mtime\n    except FileNotFoundError:\n        return None\n    except Exception:\n        return None\n\n\ndef invalidate_soam_auth_status_cache() -> None:\n    \"\"\"Clear the get_soam_auth_status() process-level memo.\n\n    Call this from any code path that mutates Soam auth state without going\n    through resolve_soam_runtime_credentials() (e.g. tests). Login/logout\n    flows touch auth.json, so the mtime check below invalidates them\n    automatically — explicit invalidation is the belt-and-braces option.\n    \"\"\"\n    global _soam_auth_status_cache\n    _soam_auth_status_cache = None\n\n\ndef get_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Soam auth.\n\n    Prefer the auth-store provider state, because that is the live source of\n    truth for refresh + mint operations. When provider state exists, validate it\n    by resolving runtime credentials so revoked refresh sessions do not show up\n    as a healthy login. If provider state is absent, fall back to the credential\n    pool for the just-logged-in / not-yet-promoted case.\n\n    The returned snapshot is memoised for ~15s keyed on the auth.json mtime,\n    so menu/status surfaces that ask repeatedly don't trigger one refresh POST\n    per call. Login/logout flows write to auth.json and therefore invalidate\n    the cache automatically; tests can also call\n    ``invalidate_soam_auth_status_cache()`` explicitly.\n    \"\"\"\n    global _soam_auth_status_cache\n    now = time.monotonic()\n    mtime = _auth_file_mtime()\n    cached = _soam_auth_status_cache\n    if cached is not None:\n        cached_at, cached_mtime, cached_status = cached\n        if (\n            cached_mtime == mtime\n            and (now - cached_at) < _SOAM_AUTH_STATUS_CACHE_TTL\n        ):\n            return dict(cached_status)\n\n    status = _compute_soam_auth_status()\n    _soam_auth_status_cache = (now, mtime, dict(status))\n    return status\n\n\ndef _compute_soam_auth_status() -> Dict[str, Any]:\n    \"\"\"Uncached implementation of get_soam_auth_status(). See that function.\"\"\"\n    state = get_provider_auth_state(\"soam\")\n    if state:\n        base_status = {\n            \"logged_in\": bool(state.get(\"access_token\")),\n            \"portal_base_url\": state.get(\"portal_base_url\"),\n            \"inference_base_url\": state.get(\"inference_base_url\"),\n            \"access_expires_at\": state.get(\"expires_at\"),\n            \"agent_key_expires_at\": state.get(\"agent_key_expires_at\"),\n            \"has_refresh_token\": bool(state.get(\"refresh_token\")),\n            \"access_token\": state.get(\"access_token\"),\n            \"source\": \"auth_store\",\n        }\n        try:\n            creds = resolve_soam_runtime_credentials(min_key_ttl_seconds=60)\n            refreshed_state = get_provider_auth_state(\"soam\") or state\n            base_status.update(\n                {\n                    \"logged_in\": True,\n                    \"portal_base_url\": refreshed_state.get(\"portal_base_url\") or base_status.get(\"portal_base_url\"),\n                    \"inference_base_url\": creds.get(\"base_url\")\n                    or refreshed_state.get(\"inference_base_url\")\n                    or base_status.get(\"inference_base_url\"),\n                    \"access_expires_at\": refreshed_state.get(\"expires_at\") or base_status.get(\"access_expires_at\"),\n                    \"agent_key_expires_at\": creds.get(\"expires_at\")\n                    or refreshed_state.get(\"agent_key_expires_at\")\n                    or base_status.get(\"agent_key_expires_at\"),\n                    \"has_refresh_token\": bool(refreshed_state.get(\"refresh_token\")),\n                    \"source\": f\"runtime:{creds.get('source', 'portal')}\",\n                    \"key_id\": creds.get(\"key_id\"),\n                }\n            )\n            return base_status\n        except AuthError as exc:\n            base_status.update({\n                \"logged_in\": False,\n                \"error\": str(exc),\n                \"relogin_required\": bool(getattr(exc, \"relogin_required\", False)),\n                \"error_code\": getattr(exc, \"code\", None),\n            })\n            return base_status\n\n    return _snapshot_soam_pool_status()\n\n\ndef get_codex_auth_status() -> Dict[str, Any]:\n    \"\"\"Status snapshot for Codex auth.\n    \n    Checks the credential pool first (where `clawbot auth` stores credentials),\n    then falls back to the legacy provider state.\n    \"\"\"\n    # Check credential pool first — this is where `clawbot auth` and\n    # `clawbot model` store device_code tokens.\n    try:\n        from agent.credential_pool import load_pool\n        pool = load_pool(\"openai-codex\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _codex_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"chatgpt\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    # Fall back to legacy provider state\n    try:\n        creds = resolve_codex_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_xai_oauth_auth_status() -> Dict[str, Any]:\n    try:\n        from agent.credential_pool import load_pool\n\n        pool = load_pool(\"xai-oauth\")\n        if pool and pool.has_credentials():\n            entry = pool.select()\n            if entry is not None:\n                api_key = (\n                    getattr(entry, \"runtime_api_key\", None)\n                    or getattr(entry, \"access_token\", \"\")\n                )\n                if api_key and not _xai_access_token_is_expiring(api_key, 0):\n                    return {\n                        \"logged_in\": True,\n                        \"auth_store\": str(_auth_file_path()),\n                        \"last_refresh\": getattr(entry, \"last_refresh\", None),\n                        \"auth_mode\": \"oauth_pkce\",\n                        \"source\": f\"pool:{getattr(entry, 'label', 'unknown')}\",\n                        \"api_key\": api_key,\n                    }\n    except Exception:\n        pass\n\n    try:\n        creds = resolve_xai_oauth_runtime_credentials()\n        return {\n            \"logged_in\": True,\n            \"auth_store\": str(_auth_file_path()),\n            \"last_refresh\": creds.get(\"last_refresh\"),\n            \"auth_mode\": creds.get(\"auth_mode\"),\n            \"source\": creds.get(\"source\"),\n            \"api_key\": creds.get(\"api_key\"),\n        }\n    except AuthError as exc:\n        return {\n            \"logged_in\": False,\n            \"auth_store\": str(_auth_file_path()),\n            \"error\": str(exc),\n        }\n\n\ndef get_api_key_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for API-key providers (z.ai, Kimi, MiniMax).\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        return {\"configured\": False}\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"configured\": bool(api_key),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"key_source\": key_source,\n        \"base_url\": base_url,\n        \"logged_in\": bool(api_key),  # compat with OAuth status shape\n    }\n\n\ndef get_external_process_provider_status(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Status snapshot for providers that run a local subprocess.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        return {\"configured\": False}\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    resolved_command = shutil.which(command) if command else None\n    return {\n        \"configured\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n        \"provider\": provider_id,\n        \"name\": pconfig.name,\n        \"command\": command,\n        \"args\": args,\n        \"resolved_command\": resolved_command,\n        \"base_url\": base_url,\n        \"logged_in\": bool(resolved_command or base_url.startswith(\"acp+tcp://\")),\n    }\n\n\ndef get_auth_status(provider_id: Optional[str] = None) -> Dict[str, Any]:\n    \"\"\"Generic auth status dispatcher.\"\"\"\n    target = provider_id or get_active_provider()\n    if target == \"spotify\":\n        return get_spotify_auth_status()\n    if target == \"soam\":\n        return get_soam_auth_status()\n    if target == \"openai-codex\":\n        return get_codex_auth_status()\n    if target == \"xai-oauth\":\n        return get_xai_oauth_auth_status()\n    if target == \"qwen-oauth\":\n        return get_qwen_auth_status()\n    if target == \"google-gemini-cli\":\n        return get_gemini_oauth_auth_status()\n    if target == \"minimax-oauth\":\n        return get_minimax_oauth_auth_status()\n    if target == \"copilot-acp\":\n        return get_external_process_provider_status(target)\n    # API-key providers\n    pconfig = PROVIDER_REGISTRY.get(target)\n    if pconfig and pconfig.auth_type == \"api_key\":\n        return get_api_key_provider_status(target)\n    # AWS SDK providers (Bedrock) — check via boto3 credential chain\n    if pconfig and pconfig.auth_type == \"aws_sdk\":\n        try:\n            from agent.bedrock_adapter import has_aws_credentials\n            return {\"logged_in\": has_aws_credentials(), \"provider\": target}\n        except ImportError:\n            return {\"logged_in\": False, \"provider\": target, \"error\": \"boto3 not installed\"}\n    return {\"logged_in\": False}\n\n\ndef resolve_api_key_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve API key and base URL for an API-key provider.\n\n    Returns dict with: provider, api_key, base_url, source.\n    \"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"api_key\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an API-key provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    api_key = \"\"\n    key_source = \"\"\n    api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig)\n\n    # No-auth LM Studio: substitute a placeholder so runtime / auxiliary_client\n    # see the local server as configured. doctor still reports unconfigured\n    # because get_api_key_provider_status uses the raw secret resolver.\n    if not api_key and provider_id == \"lmstudio\":\n        api_key = LMSTUDIO_NOAUTH_PLACEHOLDER\n        key_source = key_source or \"default\"\n\n    env_url = \"\"\n    if pconfig.base_url_env_var:\n        env_url = os.getenv(pconfig.base_url_env_var, \"\").strip()\n\n    if provider_id in {\"kimi-coding\", \"kimi-coding-cn\"}:\n        base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif provider_id == \"zai\":\n        base_url = _resolve_zai_base_url(api_key, pconfig.inference_base_url, env_url)\n    elif env_url:\n        base_url = env_url.rstrip(\"/\")\n    else:\n        base_url = pconfig.inference_base_url\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": api_key,\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"source\": key_source or \"default\",\n    }\n\n\ndef resolve_external_process_provider_credentials(provider_id: str) -> Dict[str, Any]:\n    \"\"\"Resolve runtime details for local subprocess-backed providers.\"\"\"\n    pconfig = PROVIDER_REGISTRY.get(provider_id)\n    if not pconfig or pconfig.auth_type != \"external_process\":\n        raise AuthError(\n            f\"Provider '{provider_id}' is not an external-process provider.\",\n            provider=provider_id,\n            code=\"invalid_provider\",\n        )\n\n    base_url = os.getenv(pconfig.base_url_env_var, \"\").strip() if pconfig.base_url_env_var else \"\"\n    if not base_url:\n        base_url = pconfig.inference_base_url\n\n    command = (\n        os.getenv(\"CLAWBOT_COPILOT_ACP_COMMAND\", \"\").strip()\n        or os.getenv(\"COPILOT_CLI_PATH\", \"\").strip()\n        or \"copilot\"\n    )\n    raw_args = os.getenv(\"CLAWBOT_COPILOT_ACP_ARGS\", \"\").strip()\n    args = shlex.split(raw_args) if raw_args else [\"--acp\", \"--stdio\"]\n    resolved_command = shutil.which(command) if command else None\n    if not resolved_command and not base_url.startswith(\"acp+tcp://\"):\n        raise AuthError(\n            f\"Could not find the Copilot CLI command '{command}'. \"\n            \"Install GitHub Copilot CLI or set CLAWBOT_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH.\",\n            provider=provider_id,\n            code=\"missing_copilot_cli\",\n        )\n\n    return {\n        \"provider\": provider_id,\n        \"api_key\": \"copilot-acp\",\n        \"base_url\": base_url.rstrip(\"/\"),\n        \"command\": resolved_command or command,\n        \"args\": args,\n        \"source\": \"process\",\n    }\n\n\n# =============================================================================\n# CLI Commands — login / logout\n# =============================================================================\n\ndef _update_config_for_provider(\n    provider_id: str,\n    inference_base_url: str,\n    default_model: Optional[str] = None,\n) -> Path:\n    \"\"\"Update config.yaml and auth.json to reflect the active provider.\n\n    When *default_model* is provided the function also writes it as the\n    ``model.default`` value.  This prevents a race condition where the\n    gateway (which re-reads config per-message) picks up the new provider\n    before the caller has finished model selection, resulting in a\n    mismatched model/provider (e.g. ``anthropic/claude-opus-4.6`` sent to\n    MiniMax's API).\n    \"\"\"\n    # Set active_provider in auth.json so auto-resolution picks this provider\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        auth_store[\"active_provider\"] = provider_id\n        _save_auth_store(auth_store)\n\n    # Update config.yaml model section\n    config_path = get_config_path()\n    config_path.parent.mkdir(parents=True, exist_ok=True)\n\n    config = read_raw_config()\n\n    current_model = config.get(\"model\")\n    if isinstance(current_model, dict):\n        model_cfg = dict(current_model)\n    elif isinstance(current_model, str) and current_model.strip():\n        model_cfg = {\"default\": current_model.strip()}\n    else:\n        model_cfg = {}\n\n    model_cfg[\"provider\"] = provider_id\n    if inference_base_url and inference_base_url.strip():\n        model_cfg[\"base_url\"] = inference_base_url.rstrip(\"/\")\n    else:\n        # Clear stale base_url to prevent contamination when switching providers\n        model_cfg.pop(\"base_url\", None)\n\n    # Clear stale api_key/api_mode left over from a previous custom provider.\n    # When the user switches from e.g. a MiniMax custom endpoint\n    # (api_mode=anthropic_messages, api_key=mxp-...) to a built-in provider\n    # (e.g. OpenRouter), the stale api_key/api_mode would override the new\n    # provider's credentials and transport choice.  Built-in providers that\n    # need a specific api_mode (copilot, xai) set it at request-resolution\n    # time via `_copilot_runtime_api_mode` / `_detect_api_mode_for_url`, so\n    # removing the persisted value here is safe.\n    model_cfg.pop(\"api_key\", None)\n    model_cfg.pop(\"api_mode\", None)\n\n    # When switching to a non-OpenRouter provider, ensure model.default is\n    # valid for the new provider.  An OpenRouter-formatted name like\n    # \"anthropic/claude-opus-4.6\" will fail on direct-API providers.\n    if default_model:\n        cur_default = model_cfg.get(\"default\", \"\")\n        if not cur_default or \"/\" in cur_default:\n            model_cfg[\"default\"] = default_model\n\n    config[\"model\"] = model_cfg\n\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _get_config_provider() -> Optional[str]:\n    \"\"\"Return model.provider from config.yaml, normalized, if present.\"\"\"\n    try:\n        config = read_raw_config()\n    except Exception:\n        return None\n    if not config:\n        return None\n    model = config.get(\"model\")\n    if not isinstance(model, dict):\n        return None\n    provider = model.get(\"provider\")\n    if not isinstance(provider, str):\n        return None\n    provider = provider.strip().lower()\n    return provider or None\n\n\ndef _config_provider_matches(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when config.yaml currently selects *provider_id*.\"\"\"\n    if not provider_id:\n        return False\n    return _get_config_provider() == provider_id.strip().lower()\n\n\ndef _should_reset_config_provider_on_logout(provider_id: Optional[str]) -> bool:\n    \"\"\"Return True when logout should reset the model provider config.\"\"\"\n    if not provider_id:\n        return False\n    normalized = provider_id.strip().lower()\n    return normalized in PROVIDER_REGISTRY and _config_provider_matches(normalized)\n\n\ndef _logout_default_provider_from_config() -> Optional[str]:\n    \"\"\"Fallback logout target when auth.json has no active provider.\n\n    `clawbot logout` historically keyed off auth.json.active_provider only.\n    That left users stuck when auth state had already been cleared but\n    config.yaml still selected an OAuth provider such as openai-codex for the\n    agent model: there was no active auth provider to target, so logout printed\n    \"No provider is currently logged in\" and never reset model.provider.\n    \"\"\"\n    provider = _get_config_provider()\n    if provider in {\"soam\", \"openai-codex\", \"xai-oauth\"}:\n        return provider\n    return None\n\n\ndef _reset_config_provider() -> Path:\n    \"\"\"Reset config.yaml provider back to auto after logout.\"\"\"\n    config_path = get_config_path()\n    if not config_path.exists():\n        return config_path\n\n    config = read_raw_config()\n    if not config:\n        return config_path\n\n    model = config.get(\"model\")\n    if isinstance(model, dict):\n        model[\"provider\"] = \"auto\"\n        if \"base_url\" in model:\n            model[\"base_url\"] = OPENROUTER_BASE_URL\n    atomic_yaml_write(config_path, config, sort_keys=False)\n    return config_path\n\n\ndef _prompt_model_selection(\n    model_ids: List[str],\n    current_model: str = \"\",\n    pricing: Optional[Dict[str, Dict[str, str]]] = None,\n    unavailable_models: Optional[List[str]] = None,\n    portal_url: str = \"\",\n) -> Optional[str]:\n    \"\"\"Interactive model selection. Puts current_model first with a marker. Returns chosen model ID or None.\n\n    If *pricing* is provided (``{model_id: {prompt, completion}}``), a compact\n    price indicator is shown next to each model in aligned columns.\n\n    If *unavailable_models* is provided, those models are shown grayed out\n    and unselectable, with an upgrade link to *portal_url*.\n    \"\"\"\n    from clawbot_cli.models import _format_price_per_mtok\n\n    _unavailable = unavailable_models or []\n\n    # Reorder: current model first, then the rest (deduplicated)\n    ordered = []\n    if current_model and current_model in model_ids:\n        ordered.append(current_model)\n    for mid in model_ids:\n        if mid not in ordered:\n            ordered.append(mid)\n\n    # All models for column-width computation (selectable + unavailable)\n    all_models = list(ordered) + list(_unavailable)\n\n    # Column-aligned labels when pricing is available\n    has_pricing = bool(pricing and any(pricing.get(m) for m in all_models))\n    name_col = max((len(m) for m in all_models), default=0) + 2 if has_pricing else 0\n\n    # Pre-compute formatted prices and dynamic column widths\n    _price_cache: dict[str, tuple[str, str, str]] = {}\n    price_col = 3  # minimum width\n    cache_col = 0  # only set if any model has cache pricing\n    has_cache = False\n    if has_pricing:\n        for mid in all_models:\n            p = pricing.get(mid)  # type: ignore[union-attr]\n            if p:\n                inp = _format_price_per_mtok(p.get(\"prompt\", \"\"))\n                out = _format_price_per_mtok(p.get(\"completion\", \"\"))\n                cache_read = p.get(\"input_cache_read\", \"\")\n                cache = _format_price_per_mtok(cache_read) if cache_read else \"\"\n                if cache:\n                    has_cache = True\n            else:\n                inp, out, cache = \"\", \"\", \"\"\n            _price_cache[mid] = (inp, out, cache)\n            price_col = max(price_col, len(inp), len(out))\n            cache_col = max(cache_col, len(cache))\n        if has_cache:\n            cache_col = max(cache_col, 5)  # minimum: \"Cache\" header\n\n    def _label(mid):\n        if has_pricing:\n            inp, out, cache = _price_cache.get(mid, (\"\", \"\", \"\"))\n            price_part = f\" {inp:>{price_col}}  {out:>{price_col}}\"\n            if has_cache:\n                price_part += f\"  {cache:>{cache_col}}\"\n            base = f\"{mid:<{name_col}}{price_part}\"\n        else:\n            base = mid\n        if mid == current_model:\n            base += \"  ← currently in use\"\n        return base\n\n    # Default cursor on the current model (index 0 if it was reordered to top)\n    default_idx = 0\n\n    # Build a pricing header hint for the menu title\n    menu_title = \"Select default model:\"\n    if has_pricing:\n        # Align the header with the model column.\n        # Each choice is \"  {label}\" (2 spaces) and simple_term_menu prepends\n        # a 3-char cursor region (\"-> \" or \"   \"), so content starts at col 5.\n        pad = \" \" * 5\n        header = f\"\\n{pad}{'':>{name_col}} {'In':>{price_col}}  {'Out':>{price_col}}\"\n        if has_cache:\n            header += f\"  {'Cache':>{cache_col}}\"\n        menu_title += header + \"  /Mtok\"\n\n    # ANSI escape for dim text\n    _DIM = \"\\033[2m\"\n    _RESET = \"\\033[0m\"\n\n    # Try arrow-key menu first, fall back to number input\n    try:\n        from simple_term_menu import TerminalMenu\n\n        choices = [f\"  {_label(mid)}\" for mid in ordered]\n        choices.append(\"  Enter custom model name\")\n        choices.append(\"  Skip (keep current)\")\n\n        # Print the unavailable block BEFORE the menu via regular print().\n        # simple_term_menu pads title lines to terminal width (causes wrapping),\n        # so we keep the title minimal and use stdout for the static block.\n        # clear_screen=False means our printed output stays visible above.\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        if _unavailable:\n            print(menu_title)\n            print()\n            for mid in _unavailable:\n                print(f\"{_DIM}     {_label(mid)}{_RESET}\")\n            print()\n            print(f\"{_DIM}  ── Upgrade at {_upgrade_url} for paid models ──{_RESET}\")\n            print()\n            effective_title = \"Available free models:\"\n        else:\n            effective_title = menu_title\n\n        menu = TerminalMenu(\n            choices,\n            cursor_index=default_idx,\n            menu_cursor=\"-> \",\n            menu_cursor_style=(\"fg_green\", \"bold\"),\n            menu_highlight_style=(\"fg_green\",),\n            cycle_cursor=True,\n            clear_screen=False,\n            title=effective_title,\n        )\n        idx = menu.show()\n        from clawbot_cli.curses_ui import flush_stdin\n        flush_stdin()\n        if idx is None:\n            return None\n        print()\n        if idx < len(ordered):\n            return ordered[idx]\n        elif idx == len(ordered):\n            custom = input(\"Enter model name: \").strip()\n            return custom if custom else None\n        return None\n    except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError):\n        pass\n\n    # Fallback: numbered list\n    print(menu_title)\n    num_width = len(str(len(ordered) + 2))\n    for i, mid in enumerate(ordered, 1):\n        print(f\"  {i:>{num_width}}. {_label(mid)}\")\n    n = len(ordered)\n    print(f\"  {n + 1:>{num_width}}. Enter custom model name\")\n    print(f\"  {n + 2:>{num_width}}. Skip (keep current)\")\n\n    if _unavailable:\n        _upgrade_url = (portal_url or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n        print()\n        print(f\"  {_DIM}── Unavailable models (requires paid tier — upgrade at {_upgrade_url}) ──{_RESET}\")\n        for mid in _unavailable:\n            print(f\"  {'':>{num_width}}  {_DIM}{_label(mid)}{_RESET}\")\n    print()\n\n    while True:\n        try:\n            choice = input(f\"Choice [1-{n + 2}] (default: skip): \").strip()\n            if not choice:\n                return None\n            idx = int(choice)\n            if 1 <= idx <= n:\n                return ordered[idx - 1]\n            elif idx == n + 1:\n                custom = input(\"Enter model name: \").strip()\n                return custom if custom else None\n            elif idx == n + 2:\n                return None\n            print(f\"Please enter 1-{n + 2}\")\n        except ValueError:\n            print(\"Please enter a number\")\n        except (KeyboardInterrupt, EOFError):\n            return None\n\n\ndef _save_model_choice(model_id: str) -> None:\n    \"\"\"Save the selected model to config.yaml (single source of truth).\n\n    The model is stored in config.yaml only — NOT in .env.  This avoids\n    conflicts in multi-agent setups where env vars would stomp each other.\n    \"\"\"\n    from clawbot_cli.config import save_config, load_config\n\n    config = load_config()\n    # Always use dict format so provider/base_url can be stored alongside\n    if isinstance(config.get(\"model\"), dict):\n        config[\"model\"][\"default\"] = model_id\n    else:\n        config[\"model\"] = {\"default\": model_id}\n    save_config(config)\n\n\ndef login_command(args) -> None:\n    \"\"\"Deprecated: use 'clawbot model' or 'clawbot setup' instead.\"\"\"\n    print(\"The 'clawbot login' command has been removed.\")\n    print(\"Use 'clawbot auth' to manage credentials,\")\n    print(\"'clawbot model' to select a provider, or 'clawbot setup' for full setup.\")\n    raise SystemExit(0)\n\n\ndef _login_openai_codex(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    \"\"\"OpenAI Codex login via device code flow. Tokens stored in ~/.clawbot/auth.json.\"\"\"\n\n    del args, pconfig  # kept for parity with other provider login helpers\n\n    # Check for existing Clawbot-owned credentials\n    if not force_new_login:\n        try:\n            existing = resolve_codex_runtime_credentials()\n            # Verify the resolved token is actually usable (not expired).\n            # resolve_codex_runtime_credentials attempts refresh, so if we get\n            # here the token should be valid — but double-check before telling\n            # the user \"Login successful!\".\n            _resolved_key = existing.get(\"api_key\", \"\")\n            if isinstance(_resolved_key, str) and _resolved_key and not _codex_access_token_is_expiring(_resolved_key, 60):\n                print(\"Existing Codex credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\"openai-codex\", existing.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                    return\n            else:\n                print(\"Existing Codex credentials are expired. Starting fresh login...\")\n        except AuthError:\n            pass\n\n    # Check for existing Codex CLI tokens we can import\n    if not force_new_login:\n        cli_tokens = _import_codex_cli_tokens()\n        if cli_tokens:\n            print(\"Found existing Codex CLI credentials at ~/.codex/auth.json\")\n            print(\"Clawbot will create its own session to avoid conflicts with Codex CLI / VS Code.\")\n            try:\n                do_import = input(\"Import these credentials? (a separate login is recommended) [y/N]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"n\"\n            if do_import in {\"y\", \"yes\"}:\n                _save_codex_tokens(cli_tokens)\n                base_url = os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\") or DEFAULT_CODEX_BASE_URL\n                config_path = _update_config_for_provider(\"openai-codex\", base_url)\n                print()\n                print(\"Credentials imported. Note: if Codex CLI refreshes its token,\")\n                print(\"Clawbot will keep working independently with its own session.\")\n                print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n                return\n\n    # Run a fresh device code flow — Clawbot gets its own OAuth session\n    print()\n    print(\"Signing in to OpenAI Codex...\")\n    print(\"(Clawbot creates its own session — won't affect Codex CLI or VS Code)\")\n    print()\n\n    creds = _codex_device_code_login()\n\n    # Save tokens to Clawbot auth store\n    _save_codex_tokens(creds[\"tokens\"], creds.get(\"last_refresh\"))\n    config_path = _update_config_for_provider(\"openai-codex\", creds.get(\"base_url\", DEFAULT_CODEX_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=openai-codex)\")\n\n\ndef _login_xai_oauth(\n    args,\n    pconfig: ProviderConfig,\n    *,\n    force_new_login: bool = False,\n) -> None:\n    del pconfig\n\n    if not force_new_login:\n        try:\n            existing = resolve_xai_oauth_runtime_credentials()\n            api_key = existing.get(\"api_key\", \"\")\n            if isinstance(api_key, str) and api_key and not _xai_access_token_is_expiring(api_key, 60):\n                print(\"Existing xAI OAuth credentials found in Clawbot auth store.\")\n                try:\n                    reuse = input(\"Use existing credentials? [Y/n]: \").strip().lower()\n                except (EOFError, KeyboardInterrupt):\n                    reuse = \"y\"\n                if reuse in {\"\", \"y\", \"yes\"}:\n                    config_path = _update_config_for_provider(\n                        \"xai-oauth\",\n                        existing.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL),\n                    )\n                    print()\n                    print(\"Login successful!\")\n                    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n                    return\n        except AuthError:\n            pass\n\n    print()\n    print(\"Signing in to xAI Grok OAuth (SuperGrok Subscription)...\")\n    print(\"(Clawbot creates its own local OAuth session)\")\n    print()\n\n    timeout_seconds = float(getattr(args, \"timeout\", None) or 20.0)\n    open_browser = not getattr(args, \"no_browser\", False)\n    if _is_remote_session():\n        open_browser = False\n\n    creds = _xai_oauth_loopback_login(timeout_seconds=timeout_seconds, open_browser=open_browser)\n    _save_xai_oauth_tokens(\n        creds[\"tokens\"],\n        discovery=creds.get(\"discovery\"),\n        redirect_uri=creds.get(\"redirect_uri\", \"\"),\n        last_refresh=creds.get(\"last_refresh\"),\n    )\n    config_path = _update_config_for_provider(\"xai-oauth\", creds.get(\"base_url\", DEFAULT_XAI_OAUTH_BASE_URL))\n    print()\n    print(\"Login successful!\")\n    from clawbot_constants import display_clawbot_home as _dhh\n    print(f\"  Auth state: {_dhh()}/auth.json\")\n    print(f\"  Config updated: {config_path} (model.provider=xai-oauth)\")\n\n\ndef _xai_oauth_build_authorize_url(\n    *,\n    authorization_endpoint: str,\n    redirect_uri: str,\n    code_challenge: str,\n    state: str,\n    nonce: str,\n) -> str:\n    # `plan=generic` opts the consent screen into xAI's generic OAuth plan\n    # tier instead of falling back to the per-account default. Without it,\n    # accounts.x.ai rejects loopback OAuth from non-allowlisted clients.\n    # `referrer=clawbot-agent` lets xAI attribute Clawbot-originated logins\n    # in their OAuth server logs (we still impersonate the upstream Grok-CLI\n    # client_id; this is best-effort attribution until xAI mints us our own).\n    authorize_params = {\n        \"response_type\": \"code\",\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"redirect_uri\": redirect_uri,\n        \"scope\": XAI_OAUTH_SCOPE,\n        \"code_challenge\": code_challenge,\n        \"code_challenge_method\": \"S256\",\n        \"state\": state,\n        \"nonce\": nonce,\n        \"plan\": \"generic\",\n        \"referrer\": \"clawbot-agent\",\n    }\n    return f\"{authorization_endpoint}?{urlencode(authorize_params)}\"\n\n\ndef _xai_oauth_exchange_code_for_tokens(\n    *,\n    token_endpoint: str,\n    code: str,\n    redirect_uri: str,\n    code_verifier: str,\n    code_challenge: str,\n    timeout_seconds: float = 20.0,\n) -> Dict[str, Any]:\n    \"\"\"POST the authorization code to xAI's token endpoint and return\n    the parsed JSON payload.\n\n    Sends ``code_verifier`` as required by RFC 7636 §4.5.  Also echoes\n    ``code_challenge`` + ``code_challenge_method`` in the request body\n    as a defense-in-depth measure for OAuth servers (xAI's among them,\n    per #26990) that re-validate the challenge at the token step\n    instead of relying solely on server-side session state captured\n    during the authorize step.  Echoing the challenge is harmless for\n    strict RFC-compliant servers — RFC 7636 doesn't forbid additional\n    parameters at the token endpoint — and decisively fixes the\n    ``code_challenge is required`` failure mode users hit on the\n    loopback flow.\n\n    Raises :class:`AuthError` on any non-2xx response or transport\n    failure; the error message embeds the HTTP status code and the\n    full response body so users can disambiguate cause at a glance.\n    \"\"\"\n    # Paranoia: if upstream call sites ever drop ``code_verifier`` we\n    # want to surface a precise, local error rather than send a\n    # missing-PKCE request to xAI and receive their generic \"code\n    # challenge required\" message back.\n    if not code_verifier:\n        raise AuthError(\n            \"xAI token exchange refused locally: PKCE code_verifier is empty. \"\n            \"This is a bug in Clawbot — please report at \"\n            \"https://github.com/aayushsoam/clawbot-agent/issues/26990.\",\n            provider=\"xai-oauth\",\n            code=\"xai_pkce_verifier_missing\",\n        )\n\n    data = {\n        \"grant_type\": \"authorization_code\",\n        \"code\": code,\n        \"redirect_uri\": redirect_uri,\n        \"client_id\": XAI_OAUTH_CLIENT_ID,\n        \"code_verifier\": code_verifier,\n    }\n    # Defense-in-depth: include the original ``code_challenge`` and\n    # ``code_challenge_method``.  Some OAuth servers (including xAI's\n    # auth.x.ai implementation, per the symptom reported in #26990)\n    # validate these at the token endpoint instead of relying purely on\n    # state captured during the authorize step — without them, xAI\n    # rejects the exchange with ``code_challenge is required`` even\n    # though we sent a valid ``code_verifier``.\n    if code_challenge:\n        data[\"code_challenge\"] = code_challenge\n        data[\"code_challenge_method\"] = \"S256\"\n\n    try:\n        response = httpx.post(\n            token_endpoint,\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            data=data,\n            timeout=max(20.0, timeout_seconds),\n        )\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange failed: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        ) from exc\n\n    if response.status_code != 200:\n        body = response.text.strip()\n        raise AuthError(\n            f\"xAI token exchange failed (HTTP {response.status_code}).\"\n            + (f\" Response: {body}\" if body else \"\"),\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_failed\",\n        )\n\n    try:\n        payload = response.json()\n    except Exception as exc:\n        raise AuthError(\n            f\"xAI token exchange returned invalid JSON: {exc}\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        ) from exc\n    if not isinstance(payload, dict):\n        raise AuthError(\n            \"xAI token exchange response was not a JSON object.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    return payload\n\n\ndef _xai_oauth_loopback_login(\n    *,\n    timeout_seconds: float = 20.0,\n    open_browser: bool = True,\n) -> Dict[str, Any]:\n    discovery = _xai_oauth_discovery(timeout_seconds)\n    authorization_endpoint = discovery[\"authorization_endpoint\"]\n    token_endpoint = discovery[\"token_endpoint\"]\n\n    server, thread, callback_result, redirect_uri = _xai_start_callback_server()\n    try:\n        _xai_validate_loopback_redirect_uri(redirect_uri)\n        code_verifier = _oauth_pkce_code_verifier()\n        code_challenge = _oauth_pkce_code_challenge(code_verifier)\n        state = uuid.uuid4().hex\n        nonce = uuid.uuid4().hex\n        authorize_url = _xai_oauth_build_authorize_url(\n            authorization_endpoint=authorization_endpoint,\n            redirect_uri=redirect_uri,\n            code_challenge=code_challenge,\n            state=state,\n            nonce=nonce,\n        )\n\n        print(\"Open this URL to authorize Clawbot with xAI:\")\n        print(authorize_url)\n        print()\n        print(f\"Waiting for callback on {redirect_uri}\")\n\n        _print_loopback_ssh_hint(redirect_uri, docs_url=XAI_OAUTH_DOCS_URL)\n\n        if open_browser and not _is_remote_session():\n            try:\n                opened = webbrowser.open(authorize_url)\n            except Exception:\n                opened = False\n            if opened:\n                print(\"Browser opened for xAI authorization.\")\n            else:\n                print(\"Could not open the browser automatically; use the URL above.\")\n\n        callback = _xai_wait_for_callback(\n            server,\n            thread,\n            callback_result,\n            timeout_seconds=max(30.0, timeout_seconds * 9),\n        )\n    except Exception:\n        try:\n            server.shutdown()\n            server.server_close()\n        except Exception:\n            pass\n        try:\n            thread.join(timeout=1.0)\n        except Exception:\n            pass\n        raise\n\n    if callback.get(\"error\"):\n        detail = callback.get(\"error_description\") or callback[\"error\"]\n        raise AuthError(\n            f\"xAI authorization failed: {detail}\",\n            provider=\"xai-oauth\",\n            code=\"xai_authorization_failed\",\n        )\n    if callback.get(\"state\") != state:\n        raise AuthError(\n            \"xAI authorization failed: state mismatch.\",\n            provider=\"xai-oauth\",\n            code=\"xai_state_mismatch\",\n        )\n    code = str(callback.get(\"code\") or \"\").strip()\n    if not code:\n        raise AuthError(\n            \"xAI authorization failed: missing authorization code.\",\n            provider=\"xai-oauth\",\n            code=\"xai_code_missing\",\n        )\n\n    payload = _xai_oauth_exchange_code_for_tokens(\n        token_endpoint=token_endpoint,\n        code=code,\n        redirect_uri=redirect_uri,\n        code_verifier=code_verifier,\n        code_challenge=code_challenge,\n        timeout_seconds=timeout_seconds,\n    )\n    access_token = str(payload.get(\"access_token\", \"\") or \"\").strip()\n    refresh_token = str(payload.get(\"refresh_token\", \"\") or \"\").strip()\n    if not access_token:\n        raise AuthError(\n            \"xAI token exchange did not return an access_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n    if not refresh_token:\n        raise AuthError(\n            \"xAI token exchange did not return a refresh_token.\",\n            provider=\"xai-oauth\",\n            code=\"xai_token_exchange_invalid\",\n        )\n\n    base_url = (\n        os.getenv(\"CLAWBOT_XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or os.getenv(\"XAI_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_XAI_OAUTH_BASE_URL\n    )\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n            \"id_token\": str(payload.get(\"id_token\", \"\") or \"\").strip(),\n            \"expires_in\": payload.get(\"expires_in\"),\n            \"token_type\": str(payload.get(\"token_type\") or \"Bearer\").strip() or \"Bearer\",\n        },\n        \"discovery\": discovery,\n        \"redirect_uri\": redirect_uri,\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"source\": \"oauth-loopback\",\n    }\n\n\ndef _codex_device_code_login() -> Dict[str, Any]:\n    \"\"\"Run the OpenAI device code login flow and return credentials dict.\"\"\"\n    import time as _time\n\n    issuer = \"https://auth.openai.com\"\n    client_id = CODEX_OAUTH_CLIENT_ID\n\n    # Step 1: Request device code\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            resp = client.post(\n                f\"{issuer}/api/accounts/deviceauth/usercode\",\n                json={\"client_id\": client_id},\n                headers={\"Content-Type\": \"application/json\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Failed to request device code: {exc}\",\n            provider=\"openai-codex\", code=\"device_code_request_failed\",\n        )\n\n    if resp.status_code != 200:\n        raise AuthError(\n            f\"Device code request returned status {resp.status_code}.\",\n            provider=\"openai-codex\", code=\"device_code_request_error\",\n        )\n\n    device_data = resp.json()\n    user_code = device_data.get(\"user_code\", \"\")\n    device_auth_id = device_data.get(\"device_auth_id\", \"\")\n    poll_interval = max(3, int(device_data.get(\"interval\", \"5\")))\n\n    if not user_code or not device_auth_id:\n        raise AuthError(\n            \"Device code response missing required fields.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete\",\n        )\n\n    # Step 2: Show user the code\n    print(\"To continue, follow these steps:\\n\")\n    print(\"  1. Open this URL in your browser:\")\n    print(f\"     \\033[94m{issuer}/codex/device\\033[0m\\n\")\n    print(\"  2. Enter this code:\")\n    print(f\"     \\033[94m{user_code}\\033[0m\\n\")\n    print(\"Waiting for sign-in... (press Ctrl+C to cancel)\")\n\n    # Step 3: Poll for authorization code\n    max_wait = 15 * 60  # 15 minutes\n    start = _time.monotonic()\n    code_resp = None\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            while _time.monotonic() - start < max_wait:\n                _time.sleep(poll_interval)\n                poll_resp = client.post(\n                    f\"{issuer}/api/accounts/deviceauth/token\",\n                    json={\"device_auth_id\": device_auth_id, \"user_code\": user_code},\n                    headers={\"Content-Type\": \"application/json\"},\n                )\n\n                if poll_resp.status_code == 200:\n                    code_resp = poll_resp.json()\n                    break\n                elif poll_resp.status_code in {403, 404}:\n                    continue  # User hasn't completed login yet\n                else:\n                    raise AuthError(\n                        f\"Device auth polling returned status {poll_resp.status_code}.\",\n                        provider=\"openai-codex\", code=\"device_code_poll_error\",\n                    )\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n\n    if code_resp is None:\n        raise AuthError(\n            \"Login timed out after 15 minutes.\",\n            provider=\"openai-codex\", code=\"device_code_timeout\",\n        )\n\n    # Step 4: Exchange authorization code for tokens\n    authorization_code = code_resp.get(\"authorization_code\", \"\")\n    code_verifier = code_resp.get(\"code_verifier\", \"\")\n    redirect_uri = f\"{issuer}/deviceauth/callback\"\n\n    if not authorization_code or not code_verifier:\n        raise AuthError(\n            \"Device auth response missing authorization_code or code_verifier.\",\n            provider=\"openai-codex\", code=\"device_code_incomplete_exchange\",\n        )\n\n    try:\n        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:\n            token_resp = client.post(\n                CODEX_OAUTH_TOKEN_URL,\n                data={\n                    \"grant_type\": \"authorization_code\",\n                    \"code\": authorization_code,\n                    \"redirect_uri\": redirect_uri,\n                    \"client_id\": client_id,\n                    \"code_verifier\": code_verifier,\n                },\n                headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n            )\n    except Exception as exc:\n        raise AuthError(\n            f\"Token exchange failed: {exc}\",\n            provider=\"openai-codex\", code=\"token_exchange_failed\",\n        )\n\n    if token_resp.status_code != 200:\n        raise AuthError(\n            f\"Token exchange returned status {token_resp.status_code}.\",\n            provider=\"openai-codex\", code=\"token_exchange_error\",\n        )\n\n    tokens = token_resp.json()\n    access_token = tokens.get(\"access_token\", \"\")\n    refresh_token = tokens.get(\"refresh_token\", \"\")\n\n    if not access_token:\n        raise AuthError(\n            \"Token exchange did not return an access_token.\",\n            provider=\"openai-codex\", code=\"token_exchange_no_access_token\",\n        )\n\n    # Return tokens for the caller to persist (no longer writes to ~/.codex/)\n    base_url = (\n        os.getenv(\"CLAWBOT_CODEX_BASE_URL\", \"\").strip().rstrip(\"/\")\n        or DEFAULT_CODEX_BASE_URL\n    )\n\n    return {\n        \"tokens\": {\n            \"access_token\": access_token,\n            \"refresh_token\": refresh_token,\n        },\n        \"base_url\": base_url,\n        \"last_refresh\": datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\"),\n        \"auth_mode\": \"chatgpt\",\n        \"source\": \"device-code\",\n    }\n\n\n# ==================== MiniMax Portal OAuth ====================\n\ndef _minimax_pkce_pair() -> tuple:\n    \"\"\"Generate (code_verifier, code_challenge_S256, state) for MiniMax OAuth.\"\"\"\n    import secrets\n    verifier = secrets.token_urlsafe(64)[:96]\n    challenge = base64.urlsafe_b64encode(\n        hashlib.sha256(verifier.encode()).digest()\n    ).decode().rstrip(\"=\")\n    state = secrets.token_urlsafe(16)\n    return verifier, challenge, state\n\n\ndef _minimax_request_user_code(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    code_challenge: str, state: str,\n) -> Dict[str, Any]:\n    response = client.post(\n        f\"{portal_base_url}/oauth/code\",\n        data={\n            \"response_type\": \"code\",\n            \"client_id\": client_id,\n            \"scope\": MINIMAX_OAUTH_SCOPE,\n            \"code_challenge\": code_challenge,\n            \"code_challenge_method\": \"S256\",\n            \"state\": state,\n        },\n        headers={\n            \"Content-Type\": \"application/x-www-form-urlencoded\",\n            \"Accept\": \"application/json\",\n            \"x-request-id\": str(uuid.uuid4()),\n        },\n    )\n    if response.status_code != 200:\n        raise AuthError(\n            f\"MiniMax OAuth authorization failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"authorization_failed\",\n        )\n    payload = response.json()\n    for field in (\"user_code\", \"verification_uri\", \"expired_in\"):\n        if field not in payload:\n            raise AuthError(\n                f\"MiniMax OAuth response missing field: {field}\",\n                provider=\"minimax-oauth\", code=\"authorization_incomplete\",\n            )\n    if payload.get(\"state\") != state:\n        raise AuthError(\n            \"MiniMax OAuth state mismatch (possible CSRF).\",\n            provider=\"minimax-oauth\", code=\"state_mismatch\",\n        )\n    return payload\n\n\ndef _minimax_expired_in_looks_like_unix_ms(expired_in: int, *, now_ms: int) -> bool:\n    \"\"\"True if ``expired_in`` is plausibly a unix-ms absolute time (vs TTL seconds).\"\"\"\n    return int(expired_in) > (now_ms // 2)\n\n\ndef _minimax_resolve_token_expiry_unix(expired_in: int, *, now: datetime) -> float:\n    \"\"\"Return access-token expiry as unix seconds (MiniMax uses ms epoch or TTL seconds).\"\"\"\n    raw = int(expired_in)\n    now_ms = int(now.timestamp() * 1000)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        return raw / 1000.0\n    return now.timestamp() + max(1, raw)\n\n\ndef _minimax_poll_token(\n    client: httpx.Client, *, portal_base_url: str, client_id: str,\n    user_code: str, code_verifier: str, expired_in: int, interval_ms: Optional[int],\n) -> Dict[str, Any]:\n    # OpenClaw treats expired_in as a unix-ms timestamp (Date.now() < expireTimeMs).\n    # Defensive parsing: if it's small enough to be a duration, treat as seconds.\n    import time as _time\n    now_ms = int(_time.time() * 1000)\n    raw = int(expired_in)\n    if _minimax_expired_in_looks_like_unix_ms(raw, now_ms=now_ms):\n        deadline = raw / 1000.0\n    else:\n        deadline = _time.time() + max(1, raw)\n    interval = max(2.0, (interval_ms or 2000) / 1000.0)\n\n    while _time.time() < deadline:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": MINIMAX_OAUTH_GRANT_TYPE,\n                \"client_id\": client_id,\n                \"user_code\": user_code,\n                \"code_verifier\": code_verifier,\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n        try:\n            payload = response.json() if response.text else {}\n        except Exception:\n            payload = {}\n\n        if response.status_code != 200:\n            msg = (payload.get(\"base_resp\", {}) or {}).get(\"status_msg\") or response.text\n            raise AuthError(\n                f\"MiniMax OAuth error: {msg or 'unknown'}\",\n                provider=\"minimax-oauth\", code=\"token_exchange_failed\",\n            )\n\n        status = payload.get(\"status\")\n        if status == \"error\":\n            raise AuthError(\n                \"MiniMax OAuth reported an error. Please try again later.\",\n                provider=\"minimax-oauth\", code=\"authorization_denied\",\n            )\n        if status == \"success\":\n            if not all(payload.get(k) for k in (\"access_token\", \"refresh_token\", \"expired_in\")):\n                raise AuthError(\n                    \"MiniMax OAuth success payload missing required token fields.\",\n                    provider=\"minimax-oauth\", code=\"token_incomplete\",\n                )\n            return payload\n        # \"pending\" or any other status -> keep polling\n        _time.sleep(interval)\n\n    raise AuthError(\n        \"MiniMax OAuth timed out before authorization completed.\",\n        provider=\"minimax-oauth\", code=\"timeout\",\n    )\n\n\ndef _minimax_save_auth_state(auth_state: Dict[str, Any]) -> None:\n    \"\"\"Persist MiniMax OAuth state to Clawbot auth store (~/.clawbot/auth.json).\"\"\"\n    with _auth_store_lock():\n        auth_store = _load_auth_store()\n        _save_provider_state(auth_store, \"minimax-oauth\", auth_state)\n        _save_auth_store(auth_store)\n\n\ndef _minimax_oauth_login(\n    *, region: str = \"global\", open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n) -> Dict[str, Any]:\n    \"\"\"Run MiniMax OAuth flow, persist tokens, return auth state dict.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"minimax-oauth\"]\n    if region == \"cn\":\n        portal_base_url = pconfig.extra[\"cn_portal_base_url\"]\n        inference_base_url = pconfig.extra[\"cn_inference_base_url\"]\n    else:\n        portal_base_url = pconfig.portal_base_url\n        inference_base_url = pconfig.inference_base_url\n\n    verifier, challenge, state = _minimax_pkce_pair()\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via MiniMax ({region}) OAuth...\")\n    print(f\"Portal: {portal_base_url}\")\n\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      headers={\"Accept\": \"application/json\"},\n                      follow_redirects=True) as client:\n        code_data = _minimax_request_user_code(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            code_challenge=challenge, state=state,\n        )\n        verification_url = str(code_data[\"verification_uri\"])\n        user_code = str(code_data[\"user_code\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n        if open_browser:\n            if webbrowser.open(verification_url):\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically -- use the URL above.\")\n\n        interval_raw = code_data.get(\"interval\")\n        interval_ms = int(interval_raw) if interval_raw is not None else None\n        print(\"Waiting for approval...\")\n\n        token_data = _minimax_poll_token(\n            client, portal_base_url=portal_base_url,\n            client_id=pconfig.client_id,\n            user_code=user_code, code_verifier=verifier,\n            expired_in=int(code_data[\"expired_in\"]),\n            interval_ms=interval_ms,\n        )\n\n    now = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(token_data[\"expired_in\"]), now=now,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now.timestamp()))\n\n    auth_state = {\n        \"provider\": \"minimax-oauth\",\n        \"region\": region,\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": inference_base_url,\n        \"client_id\": pconfig.client_id,\n        \"scope\": MINIMAX_OAUTH_SCOPE,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data[\"refresh_token\"],\n        \"resource_url\": token_data.get(\"resource_url\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    }\n\n    _minimax_save_auth_state(auth_state)\n    print(\"\\u2713 MiniMax OAuth login successful.\")\n    if msg := token_data.get(\"notification_message\"):\n        print(f\"Note from MiniMax: {msg}\")\n    return auth_state\n\n\ndef _refresh_minimax_oauth_state(\n    state: Dict[str, Any], *, timeout_seconds: float = 15.0,\n    force: bool = False,\n) -> Dict[str, Any]:\n    \"\"\"Refresh MiniMax OAuth access token if close to expiry (or forced).\"\"\"\n    if not state.get(\"refresh_token\"):\n        raise AuthError(\n            \"MiniMax OAuth state has no refresh_token; please re-login.\",\n            provider=\"minimax-oauth\", code=\"no_refresh_token\", relogin_required=True,\n        )\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n    except Exception:\n        expires_at = 0.0\n    now = time.time()\n    if not force and (expires_at - now) > MINIMAX_OAUTH_REFRESH_SKEW_SECONDS:\n        return state\n\n    portal_base_url = state[\"portal_base_url\"]\n    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),\n                      follow_redirects=True) as client:\n        response = client.post(\n            f\"{portal_base_url}/oauth/token\",\n            data={\n                \"grant_type\": \"refresh_token\",\n                \"client_id\": state[\"client_id\"],\n                \"refresh_token\": state[\"refresh_token\"],\n            },\n            headers={\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n        )\n    if response.status_code != 200:\n        body = response.text.lower()\n        relogin = any(m in body for m in\n                      (\"invalid_grant\", \"refresh_token_reused\", \"invalid_refresh_token\"))\n        raise AuthError(\n            f\"MiniMax OAuth refresh failed: {response.text or response.reason_phrase}\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=relogin,\n        )\n    payload = response.json()\n    if payload.get(\"status\") != \"success\":\n        raise AuthError(\n            \"MiniMax OAuth refresh did not return success.\",\n            provider=\"minimax-oauth\", code=\"refresh_failed\",\n            relogin_required=True,\n        )\n    now_dt = datetime.now(timezone.utc)\n    expires_at_unix = _minimax_resolve_token_expiry_unix(\n        int(payload[\"expired_in\"]), now=now_dt,\n    )\n    expires_in_s = max(0, int(expires_at_unix - now_dt.timestamp()))\n    new_state = dict(state)\n    new_state.update({\n        \"access_token\": payload[\"access_token\"],\n        \"refresh_token\": payload.get(\"refresh_token\", state[\"refresh_token\"]),\n        \"obtained_at\": now_dt.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at_unix, tz=timezone.utc).isoformat(),\n        \"expires_in\": expires_in_s,\n    })\n    _minimax_save_auth_state(new_state)\n    return new_state\n\n\ndef resolve_minimax_oauth_runtime_credentials(\n    *, min_token_ttl_seconds: int = MINIMAX_OAUTH_REFRESH_SKEW_SECONDS,\n) -> Dict[str, Any]:\n    \"\"\"Return {provider, api_key, base_url, source} for minimax-oauth.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        raise AuthError(\n            \"Not logged into MiniMax OAuth. Run `clawbot model` and select \"\n            \"MiniMax (OAuth).\",\n            provider=\"minimax-oauth\", code=\"not_logged_in\", relogin_required=True,\n        )\n    state = _refresh_minimax_oauth_state(state)\n    return {\n        \"provider\": \"minimax-oauth\",\n        \"api_key\": state[\"access_token\"],\n        \"base_url\": state[\"inference_base_url\"].rstrip(\"/\"),\n        \"source\": \"oauth\",\n    }\n\n\ndef get_minimax_oauth_auth_status() -> Dict[str, Any]:\n    \"\"\"Return auth status dict for MiniMax OAuth provider.\"\"\"\n    state = get_provider_auth_state(\"minimax-oauth\")\n    if not state or not state.get(\"access_token\"):\n        return {\"logged_in\": False, \"provider\": \"minimax-oauth\"}\n    try:\n        expires_at = datetime.fromisoformat(state.get(\"expires_at\", \"\")).timestamp()\n        token_valid = (expires_at - time.time()) > 0\n    except Exception:\n        token_valid = bool(state.get(\"access_token\"))\n    return {\n        \"logged_in\": token_valid,\n        \"provider\": \"minimax-oauth\",\n        \"region\": state.get(\"region\", \"global\"),\n        \"expires_at\": state.get(\"expires_at\"),\n    }\n\n\ndef _login_minimax_oauth(args, pconfig: ProviderConfig) -> None:\n    \"\"\"CLI entry for MiniMax OAuth login.\"\"\"\n    region = getattr(args, \"region\", None) or \"global\"\n    open_browser = not getattr(args, \"no_browser\", False)\n    timeout = getattr(args, \"timeout\", None) or 15.0\n    try:\n        _minimax_oauth_login(\n            region=region, open_browser=open_browser, timeout_seconds=timeout,\n        )\n    except AuthError as exc:\n        print(format_auth_error(exc))\n        raise SystemExit(1)\n\n\ndef _soam_device_code_login(\n    *,\n    portal_base_url: Optional[str] = None,\n    inference_base_url: Optional[str] = None,\n    client_id: Optional[str] = None,\n    scope: Optional[str] = None,\n    open_browser: bool = True,\n    timeout_seconds: float = 15.0,\n    insecure: bool = False,\n    ca_bundle: Optional[str] = None,\n    min_key_ttl_seconds: int = 5 * 60,\n) -> Dict[str, Any]:\n    \"\"\"Run the Soam device-code flow and return full OAuth state without persisting.\"\"\"\n    pconfig = PROVIDER_REGISTRY[\"soam\"]\n    portal_base_url = (\n        portal_base_url\n        or os.getenv(\"CLAWBOT_PORTAL_BASE_URL\")\n        or os.getenv(\"SOAM_PORTAL_BASE_URL\")\n        or pconfig.portal_base_url\n    ).rstrip(\"/\")\n    requested_inference_url = (\n        inference_base_url\n        or os.getenv(\"SOAM_INFERENCE_BASE_URL\")\n        or pconfig.inference_base_url\n    ).rstrip(\"/\")\n    client_id = client_id or pconfig.client_id\n    scope, explicit_scope = _soam_device_scope_with_env_override(\n        scope,\n        default_scope=pconfig.scope,\n    )\n    timeout = httpx.Timeout(timeout_seconds)\n    verify: bool | str = False if insecure else (ca_bundle if ca_bundle else True)\n\n    if _is_remote_session():\n        open_browser = False\n\n    print(f\"Starting Clawbot login via {pconfig.name}...\")\n    print(f\"Portal: {portal_base_url}\")\n    if insecure:\n        print(\"TLS verification: disabled (--insecure)\")\n    elif ca_bundle:\n        print(f\"TLS verification: custom CA bundle ({ca_bundle})\")\n\n    with httpx.Client(timeout=timeout, headers={\"Accept\": \"application/json\"}, verify=verify) as client:\n        device_data, scope = _request_soam_device_code_with_scope_fallback(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            scope=scope,\n            allow_legacy_fallback=not explicit_scope,\n        )\n\n        verification_url = str(device_data[\"verification_uri_complete\"])\n        user_code = str(device_data[\"user_code\"])\n        expires_in = int(device_data[\"expires_in\"])\n        interval = int(device_data[\"interval\"])\n\n        print()\n        print(\"To continue:\")\n        print(f\"  1. Open: {verification_url}\")\n        print(f\"  2. If prompted, enter code: {user_code}\")\n\n        if open_browser:\n            opened = webbrowser.open(verification_url)\n            if opened:\n                print(\"  (Opened browser for verification)\")\n            else:\n                print(\"  Could not open browser automatically — use the URL above.\")\n\n        effective_interval = max(1, min(interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))\n        print(f\"Waiting for approval (polling every {effective_interval}s)...\")\n\n        token_data = _poll_for_token(\n            client=client,\n            portal_base_url=portal_base_url,\n            client_id=client_id,\n            device_code=str(device_data[\"device_code\"]),\n            expires_in=expires_in,\n            poll_interval=interval,\n        )\n\n    now = datetime.now(timezone.utc)\n    token_expires_in = _coerce_ttl_seconds(token_data.get(\"expires_in\", 0))\n    expires_at = now.timestamp() + token_expires_in\n    resolved_inference_url = (\n        _optional_base_url(token_data.get(\"inference_base_url\"))\n        or requested_inference_url\n    )\n    if resolved_inference_url != requested_inference_url:\n        print(f\"Using portal-provided inference URL: {resolved_inference_url}\")\n\n    auth_state = {\n        \"portal_base_url\": portal_base_url,\n        \"inference_base_url\": resolved_inference_url,\n        \"client_id\": client_id,\n        \"scope\": token_data.get(\"scope\") or scope,\n        \"token_type\": token_data.get(\"token_type\", \"Bearer\"),\n        \"access_token\": token_data[\"access_token\"],\n        \"refresh_token\": token_data.get(\"refresh_token\"),\n        \"obtained_at\": now.isoformat(),\n        \"expires_at\": datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(),\n        \"expires_in\": token_expires_in,\n        \"tls\": {\n            \"insecure\": verify is False,\n            \"ca_bundle\": verify if isinstance(verify, str) else None,\n        },\n        \"agent_key\": None,\n        \"agent_key_id\": None,\n        \"agent_key_expires_at\": None,\n        \"agent_key_expires_in\": None,\n        \"agent_key_reused\": None,\n        \"agent_key_obtained_at\": None,\n    }\n    try:\n        return refresh_soam_oauth_from_state(\n            auth_state,\n            min_key_ttl_seconds=min_key_ttl_seconds,\n            timeout_seconds=timeout_seconds,\n            force_refresh=False,\n            inference_auth_mode=SOAM_INFERENCE_AUTH_MODE_FRESH,\n        )\n    except AuthError as exc:\n        if exc.code == \"subscription_required\":\n            portal_url = auth_state.get(\n                \"portal_base_url\", DEFAULT_SOAM_PORTAL_URL\n            ).rstrip(\"/\")\n            print()\n            print(\"Your Soam Portal account does not have an active subscription.\")\n            print(f\"  Subscribe here: {portal_url}/billing\")\n            print()\n            print(\"After subscribing, run `clawbot model` again to finish setup.\")\n            raise SystemExit(1)\n        raise\n\n\ndef _login_soam(args, pconfig: ProviderConfig) -> None:\n    \"\"\"Soam Portal device authorization flow.\"\"\"\n    timeout_seconds = getattr(args, \"timeout\", None) or 15.0\n    insecure = bool(getattr(args, \"insecure\", False))\n    ca_bundle = (\n        getattr(args, \"ca_bundle\", None)\n        or os.getenv(\"CLAWBOT_CA_BUNDLE\")\n        or os.getenv(\"SSL_CERT_FILE\")\n    )\n\n    try:\n        auth_state = None\n\n        # Codex-style auto-import: before launching a fresh device-code\n        # flow, check the shared store for an existing Soam credential\n        # from any other profile. If present, offer to rehydrate it.\n        shared = _read_shared_soam_state()\n        if shared:\n            try:\n                shared_path = _soam_shared_store_path()\n            except RuntimeError:\n                shared_path = None\n            print()\n            if shared_path:\n                print(f\"Found existing Soam OAuth credentials at {shared_path}\")\n            else:\n                print(\"Found existing shared Soam OAuth credentials\")\n            try:\n                do_import = input(\"Import these credentials? [Y/n]: \").strip().lower()\n            except (EOFError, KeyboardInterrupt):\n                do_import = \"y\"\n            if do_import in {\"\", \"y\", \"yes\"}:\n                print(\"Rehydrating Soam session from shared credentials...\")\n                auth_state = _try_import_shared_soam_state(\n                    timeout_seconds=timeout_seconds,\n                    min_key_ttl_seconds=5 * 60,\n                )\n                if auth_state is None:\n                    print(\"Could not refresh shared credentials — falling back to device-code login.\")\n\n        if auth_state is None:\n            auth_state = _soam_device_code_login(\n                portal_base_url=getattr(args, \"portal_url\", None),\n                inference_base_url=getattr(args, \"inference_url\", None),\n                client_id=getattr(args, \"client_id\", None) or pconfig.client_id,\n                scope=getattr(args, \"scope\", None),\n                open_browser=not getattr(args, \"no_browser\", False),\n                timeout_seconds=timeout_seconds,\n                insecure=insecure,\n                ca_bundle=ca_bundle,\n                min_key_ttl_seconds=5 * 60,\n            )\n\n        inference_base_url = auth_state[\"inference_base_url\"]\n\n        # Snapshot the prior active_provider BEFORE _save_provider_state\n        # overwrites it to \"soam\".  If the user picks \"Skip (keep current)\"\n        # during model selection below, we restore this so the user's previous\n        # provider (e.g. openrouter) is preserved.\n        with _auth_store_lock():\n            _prior_store = _load_auth_store()\n            prior_active_provider = _prior_store.get(\"active_provider\")\n\n        with _auth_store_lock():\n            auth_store = _load_auth_store()\n            _save_provider_state(auth_store, \"soam\", auth_state)\n            saved_to = _save_auth_store(auth_store)\n\n        # Mirror to the shared store so other profiles can one-tap import\n        # these credentials. Best-effort: any I/O failure is logged and\n        # swallowed inside the helper.\n        _write_shared_soam_state(auth_state)\n        _sync_soam_pool_from_auth_store()\n\n        print()\n        print(\"Login successful!\")\n        print(f\"  Auth state: {saved_to}\")\n\n        # Resolve model BEFORE writing provider to config.yaml so we never\n        # leave the config in a half-updated state (provider=soam but model\n        # still set to the previous provider's model, e.g. opus from\n        # OpenRouter).  The auth.json active_provider was already set above.\n        selected_model = None\n        try:\n            runtime_key = auth_state.get(\"agent_key\") or auth_state.get(\"access_token\")\n            if not isinstance(runtime_key, str) or not runtime_key:\n                raise AuthError(\n                    \"No runtime API key available to fetch models\",\n                    provider=\"soam\",\n                    code=\"invalid_token\",\n                )\n\n            from clawbot_cli.models import (\n                get_curated_soam_model_ids, get_pricing_for_provider,\n                check_soam_free_tier, partition_soam_models_by_tier,\n                union_with_portal_free_recommendations,\n                union_with_portal_paid_recommendations,\n            )\n            model_ids = get_curated_soam_model_ids()\n\n            print()\n            unavailable_models: list = []\n            if model_ids:\n                pricing = get_pricing_for_provider(\"soam\")\n                free_tier = check_soam_free_tier()\n                _portal_for_recs = auth_state.get(\"portal_base_url\", \"\")\n                if free_tier:\n                    # The Portal's freeRecommendedModels endpoint is the\n                    # source of truth for what's free *right now*. Augment\n                    # the curated list with anything new the Portal flags\n                    # as free so users on older Clawbot builds still see\n                    # newly-launched free models without a CLI release.\n                    model_ids, pricing = union_with_portal_free_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n                    model_ids, unavailable_models = partition_soam_models_by_tier(\n                        model_ids, pricing, free_tier=True,\n                    )\n                else:\n                    # Paid-tier mirror: pull paidRecommendedModels so newly\n                    # launched paid models surface in the picker even if\n                    # the in-repo curated list and docs-hosted manifest\n                    # haven't caught up yet.\n                    model_ids, pricing = union_with_portal_paid_recommendations(\n                        model_ids, pricing, _portal_for_recs,\n                    )\n            _portal = auth_state.get(\"portal_base_url\", \"\")\n            if model_ids:\n                print(f\"Showing {len(model_ids)} curated models — use \\\"Enter custom model name\\\" for others.\")\n                selected_model = _prompt_model_selection(\n                    model_ids, pricing=pricing,\n                    unavailable_models=unavailable_models,\n                    portal_url=_portal,\n                )\n            elif unavailable_models:\n                _url = (_portal or DEFAULT_SOAM_PORTAL_URL).rstrip(\"/\")\n                print(\"No free models currently available.\")\n                print(f\"Upgrade at {_url} to access paid models.\")\n            else:\n                print(\"No curated models available for Soam Portal.\")\n        except Exception as exc:\n            message = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc)\n            print()\n            print(f\"Login succeeded, but could not fetch available models. Reason: {message}\")\n\n        # Write provider + model atomically so config is never mismatched.\n        # If no model was selected (user picked \"Skip (keep current)\",\n        # model list fetch failed, or no curated models were available),\n        # preserve the user's previous provider — don't silently switch\n        # them to Soam with a mismatched model.  The Soam OAuth tokens\n        # stay saved for future use.\n        if not selected_model:\n            # Restore the prior active_provider that _save_provider_state\n            # overwrote to \"soam\".  config.yaml model.provider is left\n            # untouched, so the user's previous provider is fully preserved.\n            with _auth_store_lock():\n                auth_store = _load_auth_store()\n                if prior_active_provider:\n                    auth_store[\"active_provider\"] = prior_active_provider\n                else:\n                    auth_store.pop(\"active_provider\", None)\n                _save_auth_store(auth_store)\n            print()\n            print(\"No provider change. Soam credentials saved for future use.\")\n            print(\"  Run `clawbot model` again to switch to Soam Portal.\")\n            return\n\n        config_path = _update_config_for_provider(\n            \"soam\", inference_base_url, default_model=selected_model,\n        )\n        if selected_model:\n            _save_model_choice(selected_model)\n            print(f\"Default model set to: {selected_model}\")\n        print(f\"  Config updated: {config_path} (model.provider=soam)\")\n\n    except KeyboardInterrupt:\n        print(\"\\nLogin cancelled.\")\n        raise SystemExit(130)\n    except Exception as exc:\n        print(f\"Login failed: {exc}\")\n        raise SystemExit(1)\n\n\ndef logout_command(args) -> None:\n    \"\"\"Clear auth state for a provider.\"\"\"\n    provider_id = getattr(args, \"provider\", None)\n\n    if provider_id and not is_known_auth_provider(provider_id):\n        print(f\"Unknown provider: {provider_id}\")\n        raise SystemExit(1)\n\n    active = get_active_provider()\n    target = provider_id or active or _logout_default_provider_from_config()\n\n    if not target:\n        print(\"No provider is currently logged in.\")\n        return\n\n    should_reset_config = _should_reset_config_provider_on_logout(target)\n    provider_name = get_auth_provider_display_name(target)\n\n    if clear_provider_auth(target) or should_reset_config:\n        if should_reset_config:\n            _reset_config_provider()\n        print(f\"Logged out of {provider_name}.\")\n        if should_reset_config and os.getenv(\"OPENROUTER_API_KEY\"):\n            print(\"Clawbot will use OpenRouter for inference.\")\n        elif should_reset_config:\n            print(\"Run `clawbot model` or configure an API key to use Clawbot.\")\n        else:\n            print(\"Model provider configuration was unchanged.\")\n    else:\n        print(f\"No auth state found for {provider_name}.\")\n"}}, ".env.example": {"1e9c7af902bdb628e84f05ba434f634811655eca": {"t": 1785595314.9715564, "n": 22873, "h": "41408036e7401d8b", "c": "# Clawbot Agent Environment Configuration\n# Copy this file to .env and fill in your API keys\n\n# =============================================================================\n# LLM PROVIDER (OpenRouter)\n# =============================================================================\n# OpenRouter provides access to many models through one API\n# All LLM calls go through OpenRouter - no direct provider keys needed\n# Get your key at: https://openrouter.ai/keys\n# OPENROUTER_API_KEY=\n\n# Default model is configured in ~/.clawbot/config.yaml (model.default).\n# Use 'clawbot model' or 'clawbot setup' to change it.\n# LLM_MODEL is no longer read from .env — this line is kept for reference only.\n# LLM_MODEL=anthropic/claude-opus-4.6\n\n# =============================================================================\n# LLM PROVIDER (NovitaAI)\n# =============================================================================\n# NovitaAI — 90+ models, pay-per-use\n# Get your key at: https://novita.ai/settings/key-management\n# NOVITA_API_KEY=\n# NOVITA_BASE_URL=https://api.novita.ai/openai/v1  # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (Google AI Studio / Gemini)\n# =============================================================================\n# Native Gemini API via Google's OpenAI-compatible endpoint.\n# Get your key at: https://aistudio.google.com/app/apikey\n# GOOGLE_API_KEY=your_google_ai_studio_key_here\n# GEMINI_API_KEY=your_gemini_key_here  # alias for GOOGLE_API_KEY\n# Optional base URL override (default: Google's OpenAI-compatible endpoint)\n# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai\n\n# =============================================================================\n# LLM PROVIDER (Ollama Cloud)\n# =============================================================================\n# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.\n# Get your key at: https://ollama.com/settings\n# OLLAMA_API_KEY=your_ollama_key_here\n# Optional base URL override (default: https://ollama.com/v1)\n# OLLAMA_BASE_URL=https://ollama.com/v1\n\n# =============================================================================\n# LLM PROVIDER (z.ai / GLM)\n# =============================================================================\n# z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)\n# Get your key at: https://z.ai or https://open.bigmodel.cn\n# GLM_API_KEY=\n# GLM_BASE_URL=https://api.z.ai/api/paas/v4  # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (Kimi / Moonshot)\n# =============================================================================\n# Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.)\n# Get your key at: https://platform.kimi.ai (Kimi Code console)\n# Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.\n# Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.\n# KIMI_API_KEY=\n# KIMI_BASE_URL=https://api.kimi.com/coding/v1  # Default for sk-kimi- keys\n# KIMI_BASE_URL=https://api.moonshot.ai/v1      # For legacy Moonshot keys\n# KIMI_BASE_URL=https://api.moonshot.cn/v1       # For Moonshot China keys\n# KIMI_CN_API_KEY=                               # Dedicated Moonshot China key\n\n# =============================================================================\n# LLM PROVIDER (Arcee AI)\n# =============================================================================\n# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)\n# Get an Arcee key at: https://chat.arcee.ai/\n# ARCEEAI_API_KEY=\n# ARCEE_BASE_URL=                                 # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (MiniMax)\n# =============================================================================\n# MiniMax provides access to MiniMax models (global endpoint)\n# Get your key at: https://www.minimax.io\n# MINIMAX_API_KEY=\n# MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL\n\n# MiniMax China endpoint (for users in mainland China)\n# MINIMAX_CN_API_KEY=\n# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (OpenCode Zen)\n# =============================================================================\n# OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)\n# Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth\n# OPENCODE_ZEN_API_KEY=\n# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1  # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (OpenCode Go)\n# =============================================================================\n# OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)\n# $10/month subscription. Get your key at: https://opencode.ai/auth\n# OPENCODE_GO_API_KEY=\n\n# =============================================================================\n# LLM PROVIDER (Hugging Face Inference Providers)\n# =============================================================================\n# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.\n# Free tier included ($0.10/month), no markup on provider rates.\n# Get your token at: https://huggingface.co/settings/tokens\n# Required permission: \"Make calls to Inference Providers\"\n# HF_TOKEN=\n# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (Qwen OAuth)\n# =============================================================================\n# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).\n# No API key needed — credentials come from ~/.qwen/oauth_creds.json.\n# Optional base URL override:\n# CLAWBOT_QWEN_BASE_URL=https://portal.qwen.ai/v1\n\n# =============================================================================\n# LLM PROVIDER (Xiaomi MiMo)\n# =============================================================================\n# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).\n# Get your key at: https://platform.xiaomimimo.com\n# XIAOMI_API_KEY=your_key_here\n# Optional base URL override:\n# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1\n\n# =============================================================================\n# TOOL API KEYS\n# =============================================================================\n\n# Exa API Key - AI-native web search and contents\n# Get at: https://exa.ai\n# EXA_API_KEY=\n\n# Parallel API Key - AI-native web search and extract\n# Get at: https://parallel.ai\n# PARALLEL_API_KEY=\n\n# Firecrawl API Key - Web search, extract, and crawl\n# Get at: https://firecrawl.dev/\n# FIRECRAWL_API_KEY=\n\n\n# FAL.ai API Key - Image generation\n# Get at: https://fal.ai/\n# FAL_KEY=\n\n# Honcho - Cross-session AI-native user modeling (optional)\n# Builds a persistent understanding of the user across sessions and tools.\n# Get at: https://app.honcho.dev\n# Also requires ~/.honcho/config.json with enabled=true (see README).\n# HONCHO_API_KEY=\n\n# =============================================================================\n# HYPERLIQUID OPTIONAL SKILL\n# =============================================================================\n# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid\n#\n# Hyperliquid API base URL override\n# Default: https://api.hyperliquid.xyz\n# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz\n#\n# Default address for account-level commands like state, fills, orders, and review\n# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000\n\n# =============================================================================\n# TERMINAL TOOL CONFIGURATION\n# =============================================================================\n# Backend type: \"local\", \"singularity\", \"docker\", \"modal\", or \"ssh\"\n# Terminal backend is configured in ~/.clawbot/config.yaml (terminal.backend).\n# Use 'clawbot setup' or 'clawbot config set terminal.backend docker' to change.\n# Supported: local, docker, singularity, modal, ssh\n#\n# Only override here if you need to force a backend without touching config.yaml:\n# TERMINAL_ENV=local\n\n# Override the container runtime binary (e.g. to use Podman instead of Docker).\n# Useful on systems where Docker's storage driver is broken or unavailable.\n# CLAWBOT_DOCKER_BINARY=/usr/local/bin/podman\n\n# Container images (for singularity/docker/modal backends)\n# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20\n# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20\nTERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20\n\n\n# Working directory for terminal commands\n# For local backend: \".\" means current directory (resolved automatically)\n# For remote backends (ssh/docker/modal/singularity): use an absolute path\n#   INSIDE the target environment, or leave unset for the backend's default\n#   (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.\n# Usually managed by config.yaml (terminal.cwd) — uncomment to override\n# TERMINAL_CWD=.\n\n# Default command timeout in seconds\nTERMINAL_TIMEOUT=60\n\n# Cleanup inactive environments after this many seconds\nTERMINAL_LIFETIME_SECONDS=300\n\n# =============================================================================\n# SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh)\n# =============================================================================\n# Run terminal commands on a remote server via SSH.\n# Agent code stays on your machine, commands execute remotely.\n#\n# SECURITY BENEFITS:\n# - Agent cannot read your .env file (API keys protected)\n# - Agent cannot modify its own code\n# - Remote server acts as isolated sandbox\n# - Can safely configure passwordless sudo on remote\n#\n# TERMINAL_SSH_HOST=192.168.1.100\n# TERMINAL_SSH_USER=agent\n# TERMINAL_SSH_PORT=22\n# TERMINAL_SSH_KEY=~/.ssh/id_rsa\n\n# =============================================================================\n# SUDO SUPPORT (works with ALL terminal backends)\n# =============================================================================\n# If set, enables sudo commands by piping password via `sudo -S`.\n# Works with: local, docker, singularity, modal, and ssh backends.\n# \n# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.\n# \n# ALTERNATIVES:\n# - For SSH backend: Configure passwordless sudo on the remote server\n# - For containers: Run as root inside the container (no sudo needed)\n# - For local: Configure /etc/sudoers for specific commands\n# - For CLI: Leave unset - you'll be prompted interactively with 45s timeout\n#\n# SUDO_PASSWORD=your_password_here\n\n# =============================================================================\n# MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal)\n# =============================================================================\n# Modal uses CLI authentication, not environment variables.\n# Run: pip install modal && modal setup\n# This will authenticate via browser and store credentials locally.\n# No API key needed in .env - Modal handles auth automatically.\n\n# =============================================================================\n# BROWSER TOOL CONFIGURATION (agent-browser + Browserbase)\n# =============================================================================\n# Browser automation requires Browserbase cloud service for remote browser execution.\n# This allows the agent to navigate websites, fill forms, and extract information.\n#\n# STEALTH MODES:\n# - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving)\n# - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only)\n\n# Browserbase API Key - Cloud browser execution\n# Get at: https://browserbase.com/\n# BROWSERBASE_API_KEY=\n\n# Browserbase Project ID - From your Browserbase dashboard\n# BROWSERBASE_PROJECT_ID=\n\n# Enable residential proxies for better CAPTCHA solving (default: true)\n# Routes traffic through residential IPs, significantly improves success rate\nBROWSERBASE_PROXIES=true\n\n# Enable advanced stealth mode (default: false, requires Scale Plan)\n# Uses custom Chromium build to avoid bot detection altogether\nBROWSERBASE_ADVANCED_STEALTH=false\n\n# Browser engine for local mode (default: auto = Chrome)\n# \"auto\"       — use Chrome (don't pass --engine flag)\n# \"lightpanda\" — use Lightpanda (1.3-5.8x faster navigation, no screenshots)\n# \"chrome\"     — explicitly request Chrome\n# Requires agent-browser v0.25.3+. Lightpanda commands that fail or return\n# empty results are automatically retried with Chrome.\n# Also configurable via browser.engine in config.yaml.\n# AGENT_BROWSER_ENGINE=auto\n\n# Browser session timeout in seconds (default: 300)\n# Sessions are cleaned up after this duration of inactivity\nBROWSER_SESSION_TIMEOUT=300\n\n# Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min)\n# Browser sessions are automatically closed after this period of no activity\nBROWSER_INACTIVITY_TIMEOUT=120\n\n# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.\n# Clawbot auto-injects \"--no-sandbox,--disable-dev-shm-usage\" when it detects root\n# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,\n# many container images), so leave this unset unless you need extra flags.\n# Setting this disables the auto-injection.\n# AGENT_BROWSER_ARGS=--no-sandbox\n\n# Camofox local anti-detection browser (Camoufox-based Firefox).\n# Set CAMOFOX_URL to route the browser tools through a local Camofox server\n# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.\n# CAMOFOX_URL=http://localhost:9377\n\n# Externally managed Camofox sessions — when another app owns the visible\n# Camofox browser, set these so Clawbot shares the same userId/profile instead\n# of creating its own isolated session.\n# CAMOFOX_USER_ID=\n# CAMOFOX_SESSION_KEY=\n# Set to true to reuse an already-open Camofox tab for this identity before\n# creating a new one (useful for gateway restarts).\n# CAMOFOX_ADOPT_EXISTING_TAB=false\n\n# =============================================================================\n# SESSION LOGGING\n# =============================================================================\n# Session trajectories are automatically saved to logs/ directory\n# Format: logs/session_YYYYMMDD_HHMMSS_UUID.json\n# Contains full conversation history in trajectory format for debugging/replay\n\n# =============================================================================\n# VOICE TRANSCRIPTION & OPENAI TTS\n# =============================================================================\n# Required for voice message transcription (Whisper) and OpenAI TTS voices.\n# Uses OpenAI's API directly (not via OpenRouter).\n# Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.\n# Get at: https://platform.openai.com/api-keys\n# VOICE_TOOLS_OPENAI_KEY=\n\n# =============================================================================\n# SLACK INTEGRATION\n# =============================================================================\n# Slack Bot Token - From Slack App settings (OAuth & Permissions)\n# Get at: https://api.slack.com/apps\n# SLACK_BOT_TOKEN=xoxb-...\n\n# Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings)\n# SLACK_APP_TOKEN=xapp-...\n\n# Slack allowed users (comma-separated Slack user IDs)\n# SLACK_ALLOWED_USERS=\n\n# =============================================================================\n# TELEGRAM INTEGRATION\n# =============================================================================\n# Telegram Bot Token - From @BotFather (https://t.me/BotFather)\n# TELEGRAM_BOT_TOKEN=\n# TELEGRAM_ALLOWED_USERS=                  # Comma-separated user IDs\n# TELEGRAM_HOME_CHANNEL=                   # Default chat for cron delivery\n# TELEGRAM_HOME_CHANNEL_NAME=              # Display name for home channel\n\n# Webhook mode (optional — for cloud deployments like Fly.io/Railway)\n# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.\n# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram\n# TELEGRAM_WEBHOOK_PORT=8443\n# TELEGRAM_WEBHOOK_SECRET=                 # Recommended for production\n\n# WhatsApp (built-in Baileys bridge — run `clawbot whatsapp` to pair)\n# WHATSAPP_ENABLED=false\n# WHATSAPP_ALLOWED_USERS=15551234567\n\n# Email (IMAP/SMTP — send and receive emails as Clawbot)\n# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords\n# EMAIL_ADDRESS=clawbot@gmail.com\n# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx\n# EMAIL_IMAP_HOST=imap.gmail.com\n# EMAIL_IMAP_PORT=993\n# EMAIL_SMTP_HOST=smtp.gmail.com\n# EMAIL_SMTP_PORT=587\n# EMAIL_POLL_INTERVAL=15\n# EMAIL_ALLOWED_USERS=your@email.com\n# EMAIL_HOME_ADDRESS=your@email.com\n\n# Gateway-wide: allow ALL users without an allowlist (default: false = deny)\n# Only set to true if you intentionally want open access.\n# GATEWAY_ALLOW_ALL_USERS=false\n\n# =============================================================================\n# RESPONSE PACING\n# =============================================================================\n# Human-like delays between message chunks on messaging platforms.\n# Makes the bot feel less robotic.\n# CLAWBOT_HUMAN_DELAY_MODE=off     # off | natural | custom\n# CLAWBOT_HUMAN_DELAY_MIN_MS=800   # Min delay in ms (custom mode)\n# CLAWBOT_HUMAN_DELAY_MAX_MS=2500  # Max delay in ms (custom mode)\n\n# =============================================================================\n# DEBUG OPTIONS\n# =============================================================================\nWEB_TOOLS_DEBUG=false\nVISION_TOOLS_DEBUG=false\nMOA_TOOLS_DEBUG=false\nIMAGE_TOOLS_DEBUG=false\n\n# =============================================================================\n# CONTEXT COMPRESSION (Auto-shrinks long conversations)\n# =============================================================================\n# When conversation approaches model's context limit, middle turns are\n# automatically summarized to free up space.\n#\n# Context compression is configured in ~/.clawbot/config.yaml under compression:\n# CONTEXT_COMPRESSION_ENABLED=true        # Enable auto-compression (default: true)\n# CONTEXT_COMPRESSION_THRESHOLD=0.85      # Compress at 85% of context limit\n# Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)\n\n# =============================================================================\n# SKILLS HUB (GitHub integration for skill search/install/publish)\n# =============================================================================\n\n# GitHub Personal Access Token — for higher API rate limits on skill search/install\n# Get at: https://github.com/settings/tokens (Fine-grained recommended)\n# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx\n\n# GitHub App credentials (optional — for bot identity on PRs)\n# GITHUB_APP_ID=\n# GITHUB_APP_PRIVATE_KEY_PATH=\n# GITHUB_APP_INSTALLATION_ID=\n\n# Groq API key (free tier — used for Whisper STT in voice mode)\n# GROQ_API_KEY=\n\n# =============================================================================\n# STT PROVIDER SELECTION\n# =============================================================================\n# Default STT provider is \"local\" (faster-whisper) — runs on your machine, no API key needed.\n# Install with: pip install faster-whisper\n# Model downloads automatically on first use (~150 MB for \"base\").\n# To use cloud providers instead, set GROQ_API_KEY or VOICE_TOOLS_OPENAI_KEY above.\n# Provider priority: local > groq > openai\n# Configure in config.yaml: stt.provider: local | groq | openai\n\n# =============================================================================\n# STT ADVANCED OVERRIDES (optional)\n# =============================================================================\n# Override default STT models per provider (normally set via stt.model in config.yaml)\n# STT_GROQ_MODEL=whisper-large-v3-turbo\n# STT_OPENAI_MODEL=whisper-1\n\n# Override STT provider endpoints (for proxies or self-hosted instances)\n# GROQ_BASE_URL=https://api.groq.com/openai/v1\n# STT_OPENAI_BASE_URL=https://api.openai.com/v1\n\n# =============================================================================\n# MICROSOFT TEAMS INTEGRATION\n# =============================================================================\n# Register a Bot in Azure: https://dev.botframework.com/ → \"Register a bot\"\n# Or use Azure Portal: Azure Active Directory → App registrations → New registration\n# Then add the bot to Teams via the Bot Framework or App Studio.\n#\n# TEAMS_CLIENT_ID=                     # Azure AD App (client) ID\n# TEAMS_CLIENT_SECRET=                 # Azure AD client secret value\n# TEAMS_TENANT_ID=                     # Azure AD tenant ID (or \"common\" for multi-tenant)\n# TEAMS_ALLOWED_USERS=                 # Comma-separated AAD object IDs or UPNs\n# TEAMS_ALLOW_ALL_USERS=false          # Set true to skip the allowlist\n# TEAMS_HOME_CHANNEL=                  # Default channel/chat ID for cron delivery\n# TEAMS_HOME_CHANNEL_NAME=             # Display name for the home channel\n# TEAMS_PORT=3978                      # Webhook listen port (Bot Framework default)\n\n# =============================================================================\n# GOOGLE CHAT INTEGRATION\n# =============================================================================\n# Connects via Cloud Pub/Sub pull subscription (no public URL required).\n# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.\n# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.\n# 2. Create a Service Account with roles/pubsub.subscriber on the\n#    subscription (NOT project-wide); download the JSON key.\n# 3. Configure your Chat app at console.cloud.google.com/apis/credentials\n#    → Google Chat API → Configuration → Cloud Pub/Sub topic.\n# 4. (Optional, for native attachment delivery) Each user runs\n#    `/setup-files` once in their own DM after Pub/Sub is wired up.\n#\n# GOOGLE_CHAT_PROJECT_ID=                       # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)\n# GOOGLE_CHAT_SUBSCRIPTION_NAME=                # Full path: projects/<id>/subscriptions/<name>\n# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=             # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)\n# GOOGLE_CHAT_ALLOWED_USERS=                    # Comma-separated emails allowed to talk to the bot\n# GOOGLE_CHAT_ALLOW_ALL_USERS=false             # Set true to skip the allowlist\n# GOOGLE_CHAT_HOME_CHANNEL=                     # Default space (spaces/XXXX) for cron delivery\n# GOOGLE_CHAT_HOME_CHANNEL_NAME=                # Display name for the home channel\n"}}, "tests/clawbot_cli/test_provider_config_validation.py": {"1e9c7af902bdb628e84f05ba434f634811655eca": {"t": 1785809843.8900054, "n": 7958, "h": "ef3b7290643e61a0", "c": "\"\"\"Tests for providers config entry validation and normalization.\n\nCovers Issue #9332: camelCase keys silently ignored, non-URL strings\naccepted as base_url, and unknown keys go unreported.\n\"\"\"\n\nimport logging\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom clawbot_cli.config import _normalize_custom_provider_entry\n\n\nclass TestNormalizeCustomProviderEntry:\n    \"\"\"Tests for _normalize_custom_provider_entry validation.\"\"\"\n\n    def test_valid_entry_snake_case(self):\n        \"\"\"Standard snake_case entry should normalize correctly.\"\"\"\n        entry = {\n            \"base_url\": \"https://api.example.com/v1\",\n            \"api_key\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"myhost\")\n        assert result is not None\n        assert result[\"name\"] == \"myhost\"\n        assert result[\"base_url\"] == \"https://api.example.com/v1\"\n        assert result[\"api_key\"] == \"sk-test-key\"\n\n    def test_camel_case_api_key_mapped(self):\n        \"\"\"camelCase apiKey should be auto-mapped to api_key.\"\"\"\n        entry = {\n            \"base_url\": \"https://api.example.com/v1\",\n            \"apiKey\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"myhost\")\n        assert result is not None\n        assert result[\"api_key\"] == \"sk-test-key\"\n\n    def test_camel_case_base_url_mapped(self):\n        \"\"\"camelCase baseUrl should be auto-mapped to base_url.\"\"\"\n        entry = {\n            \"baseUrl\": \"https://api.example.com/v1\",\n            \"api_key\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"myhost\")\n        assert result is not None\n        assert result[\"base_url\"] == \"https://api.example.com/v1\"\n\n    def test_non_url_api_field_rejected(self):\n        \"\"\"Non-URL string in 'api' field should be skipped with a warning.\"\"\"\n        entry = {\n            \"api\": \"openai-reverse-proxy\",\n            \"api_key\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"nvidia\")\n        # Should return None because no valid URL was found\n        assert result is None\n\n    def test_valid_url_in_api_field_accepted(self):\n        \"\"\"Valid URL in 'api' field should still be accepted.\"\"\"\n        entry = {\n            \"api\": \"https://integrate.api.nvidia.com/v1\",\n            \"api_key\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"nvidia\")\n        assert result is not None\n        assert result[\"base_url\"] == \"https://integrate.api.nvidia.com/v1\"\n\n    def test_base_url_preferred_over_api(self):\n        \"\"\"base_url should be checked before api field.\"\"\"\n        entry = {\n            \"base_url\": \"https://correct.example.com/v1\",\n            \"api\": \"https://wrong.example.com/v1\",\n            \"api_key\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"test\")\n        assert result is not None\n        assert result[\"base_url\"] == \"https://correct.example.com/v1\"\n\n    def test_unknown_keys_logged(self, caplog):\n        \"\"\"Unknown config keys should produce a warning.\"\"\"\n        entry = {\n            \"base_url\": \"https://api.example.com/v1\",\n            \"api_key\": \"***\",\n            \"unknownField\": \"value\",\n            \"anotherBad\": 42,\n        }\n        with caplog.at_level(logging.WARNING):\n            result = _normalize_custom_provider_entry(entry, provider_key=\"test\")\n        assert result is not None\n        assert any(\"unknown config keys\" in r.message.lower() for r in caplog.records)\n\n    def test_timeout_keys_not_flagged_unknown(self, caplog):\n        \"\"\"request_timeout_seconds and stale_timeout_seconds should not produce warnings.\"\"\"\n        entry = {\n            \"base_url\": \"https://api.example.com/v1\",\n            \"api_key\": \"***\",\n            \"request_timeout_seconds\": 300,\n            \"stale_timeout_seconds\": 900,\n        }\n        with caplog.at_level(logging.WARNING):\n            result = _normalize_custom_provider_entry(entry, provider_key=\"test\")\n        assert result is not None\n        assert not any(\"unknown config keys\" in r.message.lower() for r in caplog.records)\n\n    def test_camel_case_warning_logged(self, caplog):\n        \"\"\"camelCase alias mapping should produce a warning.\"\"\"\n        entry = {\n            \"baseUrl\": \"https://api.example.com/v1\",\n            \"apiKey\": \"sk-test-key\",\n        }\n        with caplog.at_level(logging.WARNING):\n            result = _normalize_custom_provider_entry(entry, provider_key=\"test\")\n        assert result is not None\n        camel_warnings = [r for r in caplog.records if \"camelcase\" in r.message.lower() or \"auto-mapped\" in r.message.lower()]\n        assert len(camel_warnings) >= 1\n\n    def test_snake_case_takes_precedence_over_camel(self):\n        \"\"\"If both snake_case and camelCase exist, snake_case wins.\"\"\"\n        entry = {\n            \"api_key\": \"snake-key\",\n            \"apiKey\": \"camel-key\",\n            \"base_url\": \"https://api.example.com/v1\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"test\")\n        assert result is not None\n        assert result[\"api_key\"] == \"snake-key\"\n\n    def test_non_dict_returns_none(self):\n        \"\"\"Non-dict entry should return None.\"\"\"\n        assert _normalize_custom_provider_entry(\"not-a-dict\") is None\n        assert _normalize_custom_provider_entry(42) is None\n        assert _normalize_custom_provider_entry(None) is None\n\n    def test_no_url_returns_none(self):\n        \"\"\"Entry with no valid URL in any field should return None.\"\"\"\n        entry = {\n            \"api_key\": \"sk-test-key\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"test\")\n        assert result is None\n\n    def test_no_name_returns_none(self):\n        \"\"\"Entry with no name and no provider_key should return None.\"\"\"\n        entry = {\n            \"base_url\": \"https://api.example.com/v1\",\n        }\n        result = _normalize_custom_provider_entry(entry, provider_key=\"\")\n        assert result is None\n\n    def test_models_list_converted_to_dict(self):\n        \"\"\"List-format models should be preserved as an empty-value dict so\n        /model picks them up instead of showing the provider with (0) models.\"\"\"\n        entry = {\n            \"name\": \"tencent-coding-plan\",\n            \"base_url\": \"https://api.lkeap.cloud.tencent.com/coding/v3\",\n            \"models\": [\"glm-5\", \"kimi-k2.5\", \"minimax-m2.5\"],\n        }\n        result = _normalize_custom_provider_entry(entry)\n        assert result is not None\n        assert result[\"models\"] == {\"glm-5\": {}, \"kimi-k2.5\": {}, \"minimax-m2.5\": {}}\n\n    def test_models_dict_preserved(self):\n        \"\"\"Dict-format models should pass through unchanged.\"\"\"\n        entry = {\n            \"name\": \"acme\",\n            \"base_url\": \"https://api.example.com/v1\",\n            \"models\": {\"gpt-foo\": {\"context_length\": 32000}},\n        }\n        result = _normalize_custom_provider_entry(entry)\n        assert result is not None\n        assert result[\"models\"] == {\"gpt-foo\": {\"context_length\": 32000}}\n\n    def test_models_list_filters_empty_and_non_string(self):\n        \"\"\"List entries that are empty strings or non-strings are skipped.\"\"\"\n        entry = {\n            \"name\": \"acme\",\n            \"base_url\": \"https://api.example.com/v1\",\n            \"models\": [\"valid\", \"\", None, 42, \"  \", \"also-valid\"],\n        }\n        result = _normalize_custom_provider_entry(entry)\n        assert result is not None\n        assert result[\"models\"] == {\"valid\": {}, \"also-valid\": {}}\n\n    def test_models_empty_list_omitted(self):\n        \"\"\"Empty list (falsy) should not produce a models key.\"\"\"\n        entry = {\n            \"name\": \"acme\",\n            \"base_url\": \"https://api.example.com/v1\",\n            \"models\": [],\n        }\n        result = _normalize_custom_provider_entry(entry)\n        assert result is not None\n        assert \"models\" not in result\n"}}, "tests/test_tui_gateway_server.py": {"1e9c7af902bdb628e84f05ba434f634811655eca": {"t": 1786068566.322103, "n": 164358, "h": "6f4eb6704e0d2bf0", "c": "import json\nimport os\nimport sys\nimport threading\nimport time\nimport types\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nfrom tui_gateway import server\n\n\nclass _ChunkyStdout:\n    def __init__(self):\n        self.parts: list[str] = []\n\n    def write(self, text: str) -> int:\n        for ch in text:\n            self.parts.append(ch)\n            time.sleep(0.0001)\n        return len(text)\n\n    def flush(self) -> None:\n        return None\n\n\nclass _BrokenStdout:\n    def write(self, text: str) -> int:\n        raise BrokenPipeError\n\n    def flush(self) -> None:\n        return None\n\n\ndef test_write_json_serializes_concurrent_writes(monkeypatch):\n    out = _ChunkyStdout()\n    monkeypatch.setattr(server, \"_real_stdout\", out)\n\n    threads = [\n        threading.Thread(target=server.write_json, args=({\"seq\": i, \"text\": \"x\" * 24},))\n        for i in range(8)\n    ]\n\n    for t in threads:\n        t.start()\n\n    for t in threads:\n        t.join()\n\n    lines = \"\".join(out.parts).splitlines()\n\n    assert len(lines) == 8\n    assert {json.loads(line)[\"seq\"] for line in lines} == set(range(8))\n\n\ndef test_write_json_returns_false_on_broken_pipe(monkeypatch):\n    monkeypatch.setattr(server, \"_real_stdout\", _BrokenStdout())\n\n    assert server.write_json({\"ok\": True}) is False\n\n\ndef test_dispatch_rejects_non_object_request():\n    resp = server.dispatch([])\n\n    assert resp == {\n        \"jsonrpc\": \"2.0\",\n        \"id\": None,\n        \"error\": {\"code\": -32600, \"message\": \"invalid request: expected an object\"},\n    }\n\n\ndef test_dispatch_rejects_non_object_params():\n    resp = server.dispatch({\"id\": \"1\", \"method\": \"session.create\", \"params\": []})\n\n    assert resp == {\n        \"jsonrpc\": \"2.0\",\n        \"id\": \"1\",\n        \"error\": {\"code\": -32602, \"message\": \"invalid params: expected an object\"},\n    }\n\n\ndef test_voice_toggle_returns_configured_record_key(monkeypatch):\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"voice\": {\"record_key\": \"ctrl+o\"}},\n    )\n    monkeypatch.setitem(\n        sys.modules,\n        \"tools.voice_mode\",\n        types.SimpleNamespace(\n            check_voice_requirements=lambda: {\"available\": True, \"details\": \"\"}\n        ),\n    )\n    # ``voice.toggle`` action=on mutates ``os.environ[\"CLAWBOT_VOICE\"]``\n    # directly (CLI parity, runtime-only flag). Take monkeypatch\n    # ownership of the var so the change is reverted at teardown and\n    # later tests don't inherit a stale ON state (Copilot round-5\n    # review on #19835).\n    monkeypatch.setenv(\"CLAWBOT_VOICE\", \"0\")\n\n    on_resp = server.dispatch(\n        {\"id\": \"voice-on\", \"method\": \"voice.toggle\", \"params\": {\"action\": \"on\"}}\n    )\n    status_resp = server.dispatch(\n        {\"id\": \"voice-status\", \"method\": \"voice.toggle\", \"params\": {\"action\": \"status\"}}\n    )\n\n    assert on_resp[\"result\"][\"record_key\"] == \"ctrl+o\"\n    assert status_resp[\"result\"][\"record_key\"] == \"ctrl+o\"\n\n\ndef test_voice_toggle_handles_non_dict_voice_cfg(monkeypatch):\n    \"\"\"Round-3 Copilot review regression on #19835.\n\n    ``_load_cfg()`` is raw ``yaml.safe_load()`` output — a hand-edited\n    ``voice: true`` / ``voice: cmd+b`` / ``voice: null`` leaves ``voice``\n    as a bool/str/None, not a dict. Previously ``.get(\"record_key\")``\n    on a non-dict broke every ``voice.toggle`` branch. Now it falls\n    back to the documented default.\n    \"\"\"\n    monkeypatch.setitem(\n        sys.modules,\n        \"tools.voice_mode\",\n        types.SimpleNamespace(\n            check_voice_requirements=lambda: {\"available\": True, \"details\": \"\"}\n        ),\n    )\n\n    for bad in (True, \"cmd+b\", None, 42, [\"ctrl+b\"]):\n        monkeypatch.setattr(server, \"_load_cfg\", lambda b=bad: {\"voice\": b})\n\n        status_resp = server.dispatch(\n            {\n                \"id\": \"voice-status\",\n                \"method\": \"voice.toggle\",\n                \"params\": {\"action\": \"status\"},\n            }\n        )\n\n        assert (\n            status_resp[\"result\"][\"record_key\"] == \"ctrl+b\"\n        ), f\"voice.record_key fell back to default for voice={bad!r}\"\n\n    # Round-4 follow-up: the YAML root itself may be a non-dict. A\n    # hand-edit that collapses config.yaml to a scalar / list would\n    # otherwise crash ``.get(\"voice\")`` before the inner isinstance\n    # guard gets a chance to run.\n    for bad_root in (True, None, [], \"ctrl+b\", 42):\n        monkeypatch.setattr(server, \"_load_cfg\", lambda r=bad_root: r)\n\n        status_resp = server.dispatch(\n            {\n                \"id\": \"voice-status-root\",\n                \"method\": \"voice.toggle\",\n                \"params\": {\"action\": \"status\"},\n            }\n        )\n\n        assert (\n            status_resp[\"result\"][\"record_key\"] == \"ctrl+b\"\n        ), f\"voice.record_key fell back to default for root={bad_root!r}\"\n\n\ndef test_voice_record_start_handles_non_dict_voice_cfg(monkeypatch):\n    \"\"\"Round-7 Copilot review regression on #19835.\n\n    The ``voice.record`` start path previously read\n    ``_load_cfg().get(\"voice\", {}).get(...)`` without any shape checks.\n    When ``voice`` is a non-dict (bool/scalar/list) ``get`` raises\n    AttributeError and the handler returns 5025 instead of falling\n    back to the VAD defaults. Now it uses ``_voice_cfg_dict()`` and\n    non-numeric silence values are coerced to the documented defaults.\n    \"\"\"\n    captured: dict = {}\n\n    def fake_start_continuous(**kwargs):\n        captured.update(kwargs)\n\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.voice\",\n        types.SimpleNamespace(\n            start_continuous=fake_start_continuous, stop_continuous=lambda: None\n        ),\n    )\n    monkeypatch.setenv(\"CLAWBOT_VOICE\", \"1\")\n\n    for bad in (True, \"cmd+b\", None, 42, [\"ctrl+b\"], {\"silence_threshold\": \"loud\"}):\n        captured.clear()\n        monkeypatch.setattr(server, \"_load_cfg\", lambda b=bad: {\"voice\": b})\n\n        resp = server.dispatch(\n            {\n                \"id\": \"voice-record\",\n                \"method\": \"voice.record\",\n                \"params\": {\"action\": \"start\"},\n            }\n        )\n\n        assert (\n            \"result\" in resp\n        ), f\"voice.record raised for voice={bad!r}: {resp.get('error')}\"\n        assert resp[\"result\"][\"status\"] == \"recording\"\n        assert captured[\"silence_threshold\"] == 200\n        assert captured[\"silence_duration\"] == 3.0\n        assert captured[\"auto_restart\"] is False\n\n    # Round-12 Copilot review regression on #19835: ``bool`` is a subclass\n    # of ``int``, so the naive ``isinstance(threshold, (int, float))``\n    # guard would forward ``silence_threshold: true`` as ``1`` instead\n    # of falling back to the documented 200 default.\n    for bad_bool_cfg in (\n        {\"silence_threshold\": True, \"silence_duration\": False},\n        {\"silence_threshold\": False},\n        {\"silence_duration\": True},\n    ):\n        captured.clear()\n        monkeypatch.setattr(server, \"_load_cfg\", lambda c=bad_bool_cfg: {\"voice\": c})\n\n        resp = server.dispatch(\n            {\n                \"id\": \"voice-record-bool\",\n                \"method\": \"voice.record\",\n                \"params\": {\"action\": \"start\"},\n            }\n        )\n\n        assert \"result\" in resp, f\"voice.record raised for bool cfg={bad_bool_cfg!r}\"\n        assert (\n            captured[\"silence_threshold\"] == 200\n        ), f\"bool silence_threshold leaked through for {bad_bool_cfg!r}\"\n        assert (\n            captured[\"silence_duration\"] == 3.0\n        ), f\"bool silence_duration leaked through for {bad_bool_cfg!r}\"\n        assert captured[\"auto_restart\"] is False\n\n\ndef test_voice_record_stop_forces_transcription(monkeypatch):\n    captured: dict = {}\n\n    def fake_stop_continuous(**kwargs):\n        captured.update(kwargs)\n\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.voice\",\n        types.SimpleNamespace(\n            start_continuous=lambda **_kwargs: None,\n            stop_continuous=fake_stop_continuous,\n        ),\n    )\n\n    resp = server.dispatch(\n        {\n            \"id\": \"voice-record-stop\",\n            \"method\": \"voice.record\",\n            \"params\": {\"action\": \"stop\"},\n        }\n    )\n\n    assert resp[\"result\"][\"status\"] == \"stopped\"\n    assert captured[\"force_transcribe\"] is True\n\n\ndef test_voice_record_stop_updates_event_session_id(monkeypatch):\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.voice\",\n        types.SimpleNamespace(\n            start_continuous=lambda **_kwargs: True,\n            stop_continuous=lambda **_kwargs: None,\n        ),\n    )\n    monkeypatch.setattr(server, \"_voice_event_sid\", \"old-session\")\n\n    resp = server.dispatch(\n        {\n            \"id\": \"voice-record-stop-session\",\n            \"method\": \"voice.record\",\n            \"params\": {\"action\": \"stop\", \"session_id\": \"new-session\"},\n        }\n    )\n\n    assert resp[\"result\"][\"status\"] == \"stopped\"\n    assert server._voice_event_sid == \"new-session\"\n\n\ndef test_voice_record_start_reports_busy_when_stop_is_in_progress(monkeypatch):\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.voice\",\n        types.SimpleNamespace(\n            start_continuous=lambda **_kwargs: False,\n            stop_continuous=lambda **_kwargs: None,\n        ),\n    )\n    monkeypatch.setenv(\"CLAWBOT_VOICE\", \"1\")\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"voice\": {}})\n\n    resp = server.dispatch(\n        {\n            \"id\": \"voice-record-busy\",\n            \"method\": \"voice.record\",\n            \"params\": {\"action\": \"start\"},\n        }\n    )\n\n    assert resp[\"result\"][\"status\"] == \"busy\"\n\n\ndef test_voice_toggle_tts_branch_also_carries_record_key(monkeypatch):\n    \"\"\"Round-2 Copilot review regression on #19835.\n\n    The ``tts`` branch used to omit ``record_key`` from its response, so a\n    TUI client would parse ``r.record_key ?? 'ctrl+b'`` and reset a\n    custom binding to the default on every TTS toggle. Every branch of\n    ``voice.toggle`` now carries the configured key so frontend state\n    stays authoritative.\n    \"\"\"\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"voice\": {\"record_key\": \"ctrl+space\"}},\n    )\n    monkeypatch.setitem(\n        sys.modules,\n        \"tools.voice_mode\",\n        types.SimpleNamespace(\n            check_voice_requirements=lambda: {\"available\": True, \"details\": \"\"}\n        ),\n    )\n    monkeypatch.setenv(\"CLAWBOT_VOICE\", \"1\")\n    monkeypatch.delenv(\"CLAWBOT_VOICE_TTS\", raising=False)\n\n    tts_resp = server.dispatch(\n        {\"id\": \"voice-tts\", \"method\": \"voice.toggle\", \"params\": {\"action\": \"tts\"}}\n    )\n\n    assert tts_resp[\"result\"][\"record_key\"] == \"ctrl+space\"\n    assert tts_resp[\"result\"][\"tts\"] is True\n\n\ndef test_load_enabled_toolsets_prefers_tui_env(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"web, terminal, ,memory\")\n\n    assert server._load_enabled_toolsets() == [\"web\", \"terminal\", \"memory\"]\n\n\ndef test_load_enabled_toolsets_filters_invalid_tui_env(monkeypatch, capsys):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"web, nope\")\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.plugins\",\n        types.SimpleNamespace(discover_plugins=lambda: None),\n    )\n\n    assert server._load_enabled_toolsets() == [\"web\"]\n    assert \"nope\" in capsys.readouterr().err\n\n\ndef test_load_enabled_toolsets_accepts_plugin_env_after_discovery(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"plugin_demo\")\n\n    import toolsets\n\n    discovered = {\"ready\": False}\n    original_validate = toolsets.validate_toolset\n\n    def fake_validate(name):\n        return name == \"plugin_demo\" and discovered[\"ready\"] or original_validate(name)\n\n    monkeypatch.setattr(toolsets, \"validate_toolset\", fake_validate)\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.plugins\",\n        types.SimpleNamespace(\n            discover_plugins=lambda: discovered.update({\"ready\": True})\n        ),\n    )\n\n    assert server._load_enabled_toolsets() == [\"plugin_demo\"]\n\n\ndef test_load_enabled_toolsets_rejects_disabled_mcp_env(monkeypatch, capsys):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"mcp-off\")\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.plugins\",\n        types.SimpleNamespace(discover_plugins=lambda: None),\n    )\n\n    import clawbot_cli.config as config_mod\n\n    monkeypatch.setattr(\n        config_mod,\n        \"read_raw_config\",\n        lambda: {\"mcp_servers\": {\"mcp-off\": {\"enabled\": False}}},\n    )\n    monkeypatch.setattr(\n        config_mod, \"load_config\", lambda: {\"platform_toolsets\": {\"cli\": [\"memory\"]}}\n    )\n\n    # Sorted: [\"kanban\", \"memory\"]. `kanban` is auto-recovered by\n    # _get_platform_tools because it's a non-configurable platform toolset\n    # whose tools live in clawbot-cli's universe (see toolsets.py).\n    assert server._load_enabled_toolsets() == [\"kanban\", \"memory\"]\n    err = capsys.readouterr().err\n    assert \"ignoring disabled MCP servers\" in err\n    assert \"mcp-off\" in err\n    assert \"using configured CLI toolsets\" in err\n\n\ndef test_load_enabled_toolsets_falls_back_when_tui_env_invalid(monkeypatch, capsys):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"nope\")\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.plugins\",\n        types.SimpleNamespace(discover_plugins=lambda: None),\n    )\n\n    import clawbot_cli.config as config_mod\n\n    monkeypatch.setattr(\n        config_mod, \"load_config\", lambda: {\"platform_toolsets\": {\"cli\": [\"memory\"]}}\n    )\n\n    assert server._load_enabled_toolsets() == [\"kanban\", \"memory\"]\n    assert \"using configured CLI toolsets\" in capsys.readouterr().err\n\n\ndef test_load_enabled_toolsets_warns_when_config_fallback_fails(monkeypatch, capsys):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"nope\")\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.plugins\",\n        types.SimpleNamespace(discover_plugins=lambda: None),\n    )\n\n    import clawbot_cli.config as config_mod\n\n    monkeypatch.setattr(\n        config_mod, \"load_config\", lambda: (_ for _ in ()).throw(RuntimeError(\"boom\"))\n    )\n\n    assert server._load_enabled_toolsets() is None\n    assert \"could not be loaded\" in capsys.readouterr().err\n\n\ndef test_load_enabled_toolsets_honors_builtin_env_if_config_fails(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"web\")\n\n    import clawbot_cli.config as config_mod\n\n    monkeypatch.setattr(\n        config_mod, \"load_config\", lambda: (_ for _ in ()).throw(RuntimeError(\"boom\"))\n    )\n\n    assert server._load_enabled_toolsets() == [\"web\"]\n\n\ndef test_load_enabled_toolsets_all_env_means_all(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"all\")\n\n    assert server._load_enabled_toolsets() is None\n\n\ndef test_load_enabled_toolsets_all_env_warns_about_ignored_extra_entries(\n    monkeypatch, capsys\n):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"all,nope\")\n\n    assert server._load_enabled_toolsets() is None\n    assert \"ignoring additional entries: nope\" in capsys.readouterr().err\n\n\ndef test_load_enabled_toolsets_reports_disabled_mcp_separately(monkeypatch, capsys):\n    monkeypatch.setenv(\"CLAWBOT_TUI_TOOLSETS\", \"web,mcp-off,nope\")\n    monkeypatch.setitem(\n        sys.modules,\n        \"clawbot_cli.plugins\",\n        types.SimpleNamespace(discover_plugins=lambda: None),\n    )\n\n    import clawbot_cli.config as config_mod\n\n    monkeypatch.setattr(\n        config_mod,\n        \"read_raw_config\",\n        lambda: {\"mcp_servers\": {\"mcp-off\": {\"enabled\": False}}},\n    )\n\n    assert server._load_enabled_toolsets() == [\"web\"]\n    err = capsys.readouterr().err\n    assert \"ignoring unknown CLAWBOT_TUI_TOOLSETS entries: nope\" in err\n    assert \"ignoring disabled MCP servers\" in err\n    assert \"mcp-off\" in err\n\n\ndef test_history_to_messages_preserves_tool_calls_for_resume_display():\n    history = [\n        {\"role\": \"user\", \"content\": \"first prompt\"},\n        {\n            \"role\": \"assistant\",\n            \"content\": \"\",\n            \"tool_calls\": [\n                {\n                    \"id\": \"call_1\",\n                    \"function\": {\n                        \"name\": \"search_files\",\n                        \"arguments\": json.dumps({\"pattern\": \"resume\"}),\n                    },\n                }\n            ],\n        },\n        {\"role\": \"tool\", \"content\": \"{}\", \"tool_call_id\": \"call_1\"},\n        {\"role\": \"assistant\", \"content\": \"first answer\"},\n        {\"role\": \"user\", \"content\": \"second prompt\"},\n    ]\n\n    assert server._history_to_messages(history) == [\n        {\"role\": \"user\", \"text\": \"first prompt\"},\n        {\"context\": \"resume\", \"name\": \"search_files\", \"role\": \"tool\"},\n        {\"role\": \"assistant\", \"text\": \"first answer\"},\n        {\"role\": \"user\", \"text\": \"second prompt\"},\n    ]\n\n\ndef test_history_to_messages_renders_multimodal_content():\n    history = [\n        {\n            \"role\": \"user\",\n            \"content\": [\n                {\"type\": \"text\", \"text\": \"look here\"},\n                {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,abc\"}},\n            ],\n        },\n        {\"role\": \"assistant\", \"content\": \"saw it\"},\n    ]\n\n    assert server._history_to_messages(history) == [\n        {\"role\": \"user\", \"text\": \"look here\\n[image]\"},\n        {\"role\": \"assistant\", \"text\": \"saw it\"},\n    ]\n\n\ndef test_session_resume_uses_parent_lineage_for_display(monkeypatch):\n    captured = {}\n\n    class FakeDB:\n        def get_session(self, target):\n            return {\"id\": target}\n\n        def reopen_session(self, target):\n            captured[\"reopened\"] = target\n\n        def get_messages_as_conversation(self, target, include_ancestors=False):\n            captured.setdefault(\"history_calls\", []).append((target, include_ancestors))\n            return (\n                [\n                    {\"role\": \"user\", \"content\": \"root prompt\"},\n                    {\"role\": \"assistant\", \"content\": \"root answer\"},\n                ]\n                if include_ancestors\n                else [{\"role\": \"user\", \"content\": \"tip prompt\"}]\n            )\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: FakeDB())\n    monkeypatch.setattr(server, \"_enable_gateway_prompts\", lambda: None)\n    monkeypatch.setattr(server, \"_set_session_context\", lambda target: [])\n    monkeypatch.setattr(server, \"_clear_session_context\", lambda tokens: None)\n    monkeypatch.setattr(\n        server,\n        \"_make_agent\",\n        lambda *args, **kwargs: types.SimpleNamespace(model=\"test\"),\n    )\n    monkeypatch.setattr(\n        server,\n        \"_session_info\",\n        lambda agent: {\"model\": \"test\", \"tools\": {}, \"skills\": {}},\n    )\n    monkeypatch.setattr(\n        server, \"_init_session\", lambda sid, key, agent, history, cols=80: None\n    )\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.resume\", \"params\": {\"session_id\": \"tip\"}}\n    )\n\n    assert resp[\"result\"][\"messages\"] == [\n        {\"role\": \"user\", \"text\": \"root prompt\"},\n        {\"role\": \"assistant\", \"text\": \"root answer\"},\n    ]\n    assert captured[\"history_calls\"] == [(\"tip\", False), (\"tip\", True)]\n\n\ndef test_status_callback_emits_kind_and_text():\n    with patch(\"tui_gateway.server._emit\") as emit:\n        cb = server._agent_cbs(\"sid\")[\"status_callback\"]\n        cb(\"context_pressure\", \"85% to compaction\")\n\n    emit.assert_called_once_with(\n        \"status.update\",\n        \"sid\",\n        {\"kind\": \"context_pressure\", \"text\": \"85% to compaction\"},\n    )\n\n\ndef test_status_callback_accepts_single_message_argument():\n    with patch(\"tui_gateway.server._emit\") as emit:\n        cb = server._agent_cbs(\"sid\")[\"status_callback\"]\n        cb(\"thinking...\")\n\n    emit.assert_called_once_with(\n        \"status.update\",\n        \"sid\",\n        {\"kind\": \"status\", \"text\": \"thinking...\"},\n    )\n\n\ndef test_resolve_model_uses_inference_model_env(monkeypatch):\n    monkeypatch.delenv(\"CLAWBOT_MODEL\", raising=False)\n    monkeypatch.setenv(\"CLAWBOT_INFERENCE_MODEL\", \" anthropic/claude-sonnet-4.6\\n\")\n\n    assert server._resolve_model() == \"anthropic/claude-sonnet-4.6\"\n\n\ndef test_resolve_model_strips_config_model(monkeypatch):\n    monkeypatch.delenv(\"CLAWBOT_MODEL\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_INFERENCE_MODEL\", raising=False)\n    monkeypatch.setattr(\n        server, \"_load_cfg\", lambda: {\"model\": {\"default\": \" soam/clawbot-test \"}}\n    )\n\n    assert server._resolve_model() == \"soam/clawbot-test\"\n\n\ndef test_startup_runtime_uses_tui_provider_env(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_MODEL\", \"soam/clawbot-test\")\n    monkeypatch.setenv(\"CLAWBOT_TUI_PROVIDER\", \"soam\")\n    monkeypatch.delenv(\"CLAWBOT_INFERENCE_PROVIDER\", raising=False)\n\n    assert server._resolve_startup_runtime() == (\"soam/clawbot-test\", \"soam\")\n\n\ndef test_startup_runtime_does_not_treat_inference_provider_as_explicit(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_MODEL\", \"soam/clawbot-test\")\n    monkeypatch.delenv(\"CLAWBOT_TUI_PROVIDER\", raising=False)\n    monkeypatch.setenv(\"CLAWBOT_INFERENCE_PROVIDER\", \"soam\")\n    monkeypatch.setattr(\n        \"clawbot_cli.models.detect_static_provider_for_model\",\n        lambda model, provider: None,\n    )\n\n    assert server._resolve_startup_runtime() == (\"soam/clawbot-test\", None)\n\n\ndef test_startup_runtime_detects_provider_for_model_env(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_MODEL\", \"sonnet\")\n    monkeypatch.delenv(\"CLAWBOT_TUI_PROVIDER\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_INFERENCE_PROVIDER\", raising=False)\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"model\": {\"provider\": \"auto\"}})\n\n    def fake_detect(model, current_provider):\n        assert model == \"sonnet\"\n        assert current_provider == \"auto\"\n        return \"anthropic\", \"anthropic/claude-sonnet-4.6\"\n\n    monkeypatch.setattr(\n        \"clawbot_cli.models.detect_static_provider_for_model\", fake_detect\n    )\n\n    assert server._resolve_startup_runtime() == (\n        \"anthropic/claude-sonnet-4.6\",\n        \"anthropic\",\n    )\n\n\ndef test_startup_runtime_resolves_short_alias_without_network(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_MODEL\", \"sonnet\")\n    monkeypatch.delenv(\"CLAWBOT_TUI_PROVIDER\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_INFERENCE_PROVIDER\", raising=False)\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"model\": {\"provider\": \"auto\"}})\n    monkeypatch.setattr(\n        \"clawbot_cli.models.fetch_openrouter_models\",\n        lambda *_args, **_kwargs: (_ for _ in ()).throw(\n            AssertionError(\"network lookup should not run\")\n        ),\n    )\n\n    model, provider = server._resolve_startup_runtime()\n\n    assert provider == \"anthropic\"\n    assert model.startswith(\"claude-sonnet\")\n\n\ndef test_startup_runtime_does_not_call_network_detector(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_MODEL\", \"sonnet\")\n    monkeypatch.delenv(\"CLAWBOT_TUI_PROVIDER\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_INFERENCE_PROVIDER\", raising=False)\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"model\": {\"provider\": \"auto\"}})\n    monkeypatch.setattr(\n        \"clawbot_cli.models.detect_provider_for_model\",\n        lambda *_args, **_kwargs: (_ for _ in ()).throw(\n            AssertionError(\"network detector called\")\n        ),\n    )\n\n    model, provider = server._resolve_startup_runtime()\n\n    assert model\n    assert provider in {None, \"anthropic\"}\n\n\ndef _session(agent=None, **extra):\n    return {\n        \"agent\": agent if agent is not None else types.SimpleNamespace(),\n        \"session_key\": \"session-key\",\n        \"history\": [],\n        \"history_lock\": threading.Lock(),\n        \"history_version\": 0,\n        \"running\": False,\n        \"attached_images\": [],\n        \"image_counter\": 0,\n        \"cols\": 80,\n        \"slash_worker\": None,\n        \"show_reasoning\": False,\n        \"tool_progress_mode\": \"all\",\n        **extra,\n    }\n\n\ndef test_session_close_commits_memory_and_fires_finalize_hook(monkeypatch):\n    calls = {\"hooks\": []}\n\n    agent = types.SimpleNamespace(session_id=\"session-key\")\n    agent.commit_memory_session = lambda history: calls.setdefault(\"history\", history)\n    server._sessions[\"sid\"] = _session(\n        agent=agent, history=[{\"role\": \"user\", \"content\": \"hello\"}]\n    )\n    monkeypatch.setattr(\n        server,\n        \"_notify_session_boundary\",\n        lambda event, session_id: calls[\"hooks\"].append((event, session_id)),\n    )\n\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.close\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp[\"result\"][\"closed\"] is True\n        assert calls[\"history\"] == [{\"role\": \"user\", \"content\": \"hello\"}]\n        assert (\"on_session_finalize\", \"session-key\") in calls[\"hooks\"]\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_init_session_fires_reset_hook(monkeypatch):\n    hooks = []\n\n    class _FakeWorker:\n        def __init__(self, key, model):\n            self.key = key\n\n        def close(self):\n            return None\n\n    monkeypatch.setattr(server, \"_SlashWorker\", _FakeWorker)\n    monkeypatch.setattr(server, \"_wire_callbacks\", lambda _sid: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(\n        server,\n        \"_notify_session_boundary\",\n        lambda event, session_id: hooks.append((event, session_id)),\n    )\n\n    import tools.approval as _approval\n\n    monkeypatch.setattr(_approval, \"register_gateway_notify\", lambda key, cb: None)\n    monkeypatch.setattr(_approval, \"load_permanent_allowlist\", lambda: None)\n\n    sid = \"sid\"\n    try:\n        server._init_session(\n            sid,\n            \"session-key\",\n            types.SimpleNamespace(model=\"x\"),\n            history=[],\n            cols=80,\n        )\n        assert (\"on_session_reset\", \"session-key\") in hooks\n    finally:\n        server._sessions.pop(sid, None)\n\n\ndef test_session_title_queues_when_db_row_not_ready(monkeypatch):\n    class _FakeDB:\n        def get_session_title(self, _key):\n            return None\n\n        def get_session(self, _key):\n            return None\n\n        def set_session_title(self, _key, _title):\n            return False\n\n    server._sessions[\"sid\"] = _session(pending_title=None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    try:\n        set_resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.title\",\n                \"params\": {\"session_id\": \"sid\", \"title\": \"queued title\"},\n            }\n        )\n\n        assert set_resp[\"result\"][\"pending\"] is True\n        assert set_resp[\"result\"][\"title\"] == \"queued title\"\n        assert server._sessions[\"sid\"][\"pending_title\"] == \"queued title\"\n\n        get_resp = server.handle_request(\n            {\"id\": \"2\", \"method\": \"session.title\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert get_resp[\"result\"][\"title\"] == \"queued title\"\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_clears_pending_after_persist(monkeypatch):\n    class _FakeDB:\n        def __init__(self):\n            self.title = \"old\"\n\n        def get_session_title(self, _key):\n            return self.title\n\n        def get_session(self, _key):\n            return {\"id\": _key, \"title\": self.title}\n\n        def set_session_title(self, _key, title):\n            self.title = title\n            return True\n\n    db = _FakeDB()\n    server._sessions[\"sid\"] = _session(pending_title=\"stale\")\n    monkeypatch.setattr(server, \"_get_db\", lambda: db)\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.title\",\n                \"params\": {\"session_id\": \"sid\", \"title\": \"fresh\"},\n            }\n        )\n\n        assert resp[\"result\"][\"pending\"] is False\n        assert resp[\"result\"][\"title\"] == \"fresh\"\n        assert server._sessions[\"sid\"][\"pending_title\"] is None\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_does_not_queue_noop_when_row_exists(monkeypatch):\n    class _FakeDB:\n        def __init__(self):\n            self.title = \"same title\"\n\n        def get_session_title(self, _key):\n            return self.title\n\n        def get_session(self, _key):\n            return {\"id\": _key, \"title\": self.title}\n\n        def set_session_title(self, _key, _title):\n            # Simulate sqlite UPDATE rowcount==0 for no-op update.\n            return False\n\n    server._sessions[\"sid\"] = _session(pending_title=\"stale\")\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.title\",\n                \"params\": {\"session_id\": \"sid\", \"title\": \"same title\"},\n            }\n        )\n\n        assert resp[\"result\"][\"pending\"] is False\n        assert resp[\"result\"][\"title\"] == \"same title\"\n        assert server._sessions[\"sid\"][\"pending_title\"] is None\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_get_falls_back_to_pending_when_db_read_throws(monkeypatch):\n    class _FakeDB:\n        def get_session_title(self, _key):\n            raise RuntimeError(\"db temporarily locked\")\n\n    server._sessions[\"sid\"] = _session(pending_title=\"queued title\")\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.title\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp[\"result\"][\"title\"] == \"queued title\"\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_get_retries_persist_for_pending_title(monkeypatch):\n    class _FakeDB:\n        def __init__(self):\n            self.title = \"\"\n\n        def get_session_title(self, _key):\n            return self.title\n\n        def set_session_title(self, _key, title):\n            self.title = title\n            return True\n\n        def get_session(self, _key):\n            return {\"id\": _key, \"title\": self.title}\n\n    db = _FakeDB()\n    server._sessions[\"sid\"] = _session(pending_title=\"queued title\")\n    monkeypatch.setattr(server, \"_get_db\", lambda: db)\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.title\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp[\"result\"][\"title\"] == \"queued title\"\n        assert server._sessions[\"sid\"][\"pending_title\"] is None\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_get_retries_pending_even_when_db_has_title(monkeypatch):\n    class _FakeDB:\n        def __init__(self):\n            self.title = \"auto title\"\n\n        def get_session_title(self, _key):\n            return self.title\n\n        def set_session_title(self, _key, title):\n            self.title = title\n            return True\n\n        def get_session(self, _key):\n            return {\"id\": _key, \"title\": self.title}\n\n    db = _FakeDB()\n    server._sessions[\"sid\"] = _session(pending_title=\"queued title\")\n    monkeypatch.setattr(server, \"_get_db\", lambda: db)\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.title\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp[\"result\"][\"title\"] == \"queued title\"\n        assert server._sessions[\"sid\"][\"pending_title\"] is None\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_rejects_empty_title_with_specific_error_code(monkeypatch):\n    class _FakeDB:\n        def get_session_title(self, _key):\n            return \"\"\n\n    server._sessions[\"sid\"] = _session()\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.title\",\n                \"params\": {\"session_id\": \"sid\", \"title\": \"   \"},\n            }\n        )\n        assert \"error\" in resp\n        assert resp[\"error\"][\"code\"] == 4021\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_set_maps_valueerror_to_user_error(monkeypatch):\n    class _FakeDB:\n        def get_session_title(self, _key):\n            return \"\"\n\n        def get_session(self, _key):\n            return {\"id\": _key}\n\n        def set_session_title(self, _key, _title):\n            raise ValueError(\"Title already in use\")\n\n    server._sessions[\"sid\"] = _session()\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.title\",\n                \"params\": {\"session_id\": \"sid\", \"title\": \"dup\"},\n            }\n        )\n        assert \"error\" in resp\n        assert resp[\"error\"][\"code\"] == 4022\n        assert \"already in use\" in resp[\"error\"][\"message\"]\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_title_set_errors_when_row_lookup_fails_after_noop(monkeypatch):\n    class _FakeDB:\n        def get_session_title(self, _key):\n            return \"\"\n\n        def get_session(self, _key):\n            raise RuntimeError(\"row lookup failed\")\n\n        def set_session_title(self, _key, _title):\n            return False\n\n    server._sessions[\"sid\"] = _session()\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.title\",\n                \"params\": {\"session_id\": \"sid\", \"title\": \"fresh\"},\n            }\n        )\n        assert \"error\" in resp\n        assert resp[\"error\"][\"code\"] == 5007\n        assert \"row lookup failed\" in resp[\"error\"][\"message\"]\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_create_drops_pending_title_on_valueerror(monkeypatch):\n    \"\"\"When set_session_title raises ValueError during post-message title flush,\n    pending_title should be dropped (non-retryable). Updated for post-#18370\n    lazy session creation where title is applied post-first-message.\n    \"\"\"\n\n    class _Agent:\n        session_id = \"test-session\"\n        model = \"x\"\n        provider = \"openrouter\"\n        base_url = \"\"\n        api_key = \"\"\n        _cached_system_prompt = \"\"\n\n        def run_conversation(self, prompt, **kw):\n            return {\n                \"final_response\": \"ok\",\n                \"messages\": [{\"role\": \"assistant\", \"content\": \"ok\"}],\n            }\n\n    class _FakeDB:\n        def set_session_title(self, _key, _title):\n            raise ValueError(\"Title already in use\")\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None, **kw):\n            self._target = target\n\n        def start(self):\n            self._target()\n\n    agent = _Agent()\n    session = {\n        \"agent\": agent,\n        \"session_key\": \"test-session\",\n        \"history\": [],\n        \"history_lock\": threading.Lock(),\n        \"history_version\": 0,\n        \"running\": False,\n        \"attached_images\": [],\n        \"image_counter\": 0,\n        \"cols\": 80,\n        \"slash_worker\": None,\n        \"show_reasoning\": False,\n        \"tool_progress_mode\": \"all\",\n        \"pending_title\": \"duplicate title\",\n    }\n\n    server._sessions[\"sid\"] = session\n    monkeypatch.setattr(server, \"_get_db\", lambda: _FakeDB())\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setattr(\n        server, \"_sync_session_key_after_compress\", lambda *a, **kw: None\n    )\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n\n    try:\n        server.handle_request(\n            {\"id\": \"1\", \"method\": \"prompt.submit\", \"params\": {\"session_id\": \"sid\", \"text\": \"hello\"}}\n        )\n        assert session[\"pending_title\"] is None\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_config_set_yolo_toggles_session_scope():\n    from tools.approval import clear_session, is_session_yolo_enabled\n\n    server._sessions[\"sid\"] = _session()\n    try:\n        resp_on = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"yolo\"},\n            }\n        )\n        assert resp_on[\"result\"][\"value\"] == \"1\"\n        assert is_session_yolo_enabled(\"session-key\") is True\n\n        resp_off = server.handle_request(\n            {\n                \"id\": \"2\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"yolo\"},\n            }\n        )\n        assert resp_off[\"result\"][\"value\"] == \"0\"\n        assert is_session_yolo_enabled(\"session-key\") is False\n    finally:\n        clear_session(\"session-key\")\n        server._sessions.clear()\n\n\ndef test_config_set_fast_updates_live_agent_and_config(monkeypatch):\n    writes = []\n    emits = []\n    agent = types.SimpleNamespace(\n        model=\"openai/gpt-5.4\",\n        request_overrides={\"foo\": \"bar\", \"speed\": \"slow\"},\n        service_tier=None,\n    )\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    monkeypatch.setattr(\n        server, \"_write_config_key\", lambda path, value: writes.append((path, value))\n    )\n    monkeypatch.setattr(server, \"_session_info\", lambda _agent: {\"model\": \"x\"})\n    monkeypatch.setattr(server, \"_emit\", lambda *args: emits.append(args))\n    monkeypatch.setattr(\n        \"clawbot_cli.models.resolve_fast_mode_overrides\",\n        lambda _model_id: {\"service_tier\": \"priority\"},\n    )\n\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"fast\", \"value\": \"fast\"},\n            }\n        )\n        assert resp[\"result\"][\"value\"] == \"fast\"\n        assert agent.service_tier == \"priority\"\n        assert agent.request_overrides == {\n            \"foo\": \"bar\",\n            \"service_tier\": \"priority\",\n        }\n        assert (\"agent.service_tier\", \"fast\") in writes\n        assert (\"session.info\", \"sid\", {\"model\": \"x\"}) in emits\n\n        resp_normal = server.handle_request(\n            {\n                \"id\": \"2\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"fast\", \"value\": \"normal\"},\n            }\n        )\n        assert resp_normal[\"result\"][\"value\"] == \"normal\"\n        assert agent.service_tier is None\n        assert agent.request_overrides == {\"foo\": \"bar\"}\n        assert (\"agent.service_tier\", \"normal\") in writes\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_config_set_fast_status_is_non_mutating(monkeypatch):\n    writes = []\n    emits = []\n    agent = types.SimpleNamespace(service_tier=\"priority\")\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    monkeypatch.setattr(\n        server, \"_write_config_key\", lambda path, value: writes.append((path, value))\n    )\n    monkeypatch.setattr(server, \"_emit\", lambda *args: emits.append(args))\n\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"fast\", \"value\": \"status\"},\n            }\n        )\n        assert resp[\"result\"][\"value\"] == \"fast\"\n        assert writes == []\n        assert emits == []\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_config_set_fast_rejects_unsupported_model(monkeypatch):\n    writes = []\n    agent = types.SimpleNamespace(\n        model=\"unsupported-model\",\n        request_overrides={},\n        service_tier=None,\n    )\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    monkeypatch.setattr(\n        server, \"_write_config_key\", lambda path, value: writes.append((path, value))\n    )\n    monkeypatch.setattr(\n        \"clawbot_cli.models.resolve_fast_mode_overrides\",\n        lambda _model_id: None,\n    )\n\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"fast\", \"value\": \"fast\"},\n            }\n        )\n        assert resp[\"error\"][\"code\"] == 4002\n        assert \"not available\" in resp[\"error\"][\"message\"]\n        assert agent.service_tier is None\n        assert agent.request_overrides == {}\n        assert writes == []\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_config_set_fast_rejects_missing_model(monkeypatch):\n    writes = []\n    agent = types.SimpleNamespace(\n        model=\"\",\n        request_overrides={},\n        service_tier=None,\n    )\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    monkeypatch.setattr(\n        server, \"_write_config_key\", lambda path, value: writes.append((path, value))\n    )\n\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"fast\", \"value\": \"fast\"},\n            }\n        )\n        assert resp[\"error\"][\"code\"] == 4002\n        assert \"without a selected model\" in resp[\"error\"][\"message\"]\n        assert agent.service_tier is None\n        assert agent.request_overrides == {}\n        assert writes == []\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_config_busy_get_and_set(monkeypatch):\n    writes = []\n\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"display\": {\"busy_input_mode\": \"steer\"}},\n    )\n    monkeypatch.setattr(\n        server, \"_write_config_key\", lambda path, value: writes.append((path, value))\n    )\n\n    get_resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"busy\"}}\n    )\n    assert get_resp[\"result\"][\"value\"] == \"steer\"\n\n    set_resp = server.handle_request(\n        {\n            \"id\": \"2\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"busy\", \"value\": \"interrupt\"},\n        }\n    )\n    assert set_resp[\"result\"][\"value\"] == \"interrupt\"\n    assert (\"display.busy_input_mode\", \"interrupt\") in writes\n\n\ndef test_config_set_yolo_process_scope_treats_false_like_env_as_disabled(monkeypatch):\n    monkeypatch.setenv(\"CLAWBOT_YOLO_MODE\", \"false\")\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"yolo\"},\n        }\n    )\n\n    assert resp[\"result\"][\"value\"] == \"1\"\n    assert os.environ.get(\"CLAWBOT_YOLO_MODE\") == \"1\"\n\n\ndef test_config_get_statusbar_survives_non_dict_display(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"display\": \"broken\"})\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"statusbar\"}}\n    )\n\n    assert resp[\"result\"][\"value\"] == \"top\"\n\n\ndef test_config_get_busy_survives_non_dict_display(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"display\": \"broken\"})\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"busy\"}}\n    )\n\n    assert resp[\"result\"][\"value\"] == \"interrupt\"\n\n\ndef test_config_set_statusbar_survives_non_dict_display(tmp_path, monkeypatch):\n    import yaml\n\n    cfg_path = tmp_path / \"config.yaml\"\n    cfg_path.write_text(yaml.safe_dump({\"display\": \"broken\"}))\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"statusbar\", \"value\": \"bottom\"},\n        }\n    )\n\n    assert resp[\"result\"][\"value\"] == \"bottom\"\n    saved = yaml.safe_load(cfg_path.read_text())\n    assert saved[\"display\"][\"tui_statusbar\"] == \"bottom\"\n\n\ndef test_config_set_details_mode_pins_all_sections(tmp_path, monkeypatch):\n    import yaml\n\n    cfg_path = tmp_path / \"config.yaml\"\n    cfg_path.write_text(\n        yaml.safe_dump(\n            {\"display\": {\"sections\": {\"tools\": \"expanded\", \"activity\": \"hidden\"}}}\n        )\n    )\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"details_mode\", \"value\": \"collapsed\"},\n        }\n    )\n\n    assert resp[\"result\"] == {\"key\": \"details_mode\", \"value\": \"collapsed\"}\n    saved = yaml.safe_load(cfg_path.read_text())\n    assert saved[\"display\"][\"details_mode\"] == \"collapsed\"\n    assert saved[\"display\"][\"sections\"] == {\n        \"thinking\": \"collapsed\",\n        \"tools\": \"collapsed\",\n        \"subagents\": \"collapsed\",\n        \"activity\": \"collapsed\",\n    }\n\n\ndef test_config_set_section_writes_per_section_override(tmp_path, monkeypatch):\n    import yaml\n\n    cfg_path = tmp_path / \"config.yaml\"\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"details_mode.activity\", \"value\": \"hidden\"},\n        }\n    )\n\n    assert resp[\"result\"] == {\"key\": \"details_mode.activity\", \"value\": \"hidden\"}\n    saved = yaml.safe_load(cfg_path.read_text())\n    assert saved[\"display\"][\"sections\"] == {\"activity\": \"hidden\"}\n\n\ndef test_config_set_section_clears_override_on_empty_value(tmp_path, monkeypatch):\n    import yaml\n\n    cfg_path = tmp_path / \"config.yaml\"\n    cfg_path.write_text(\n        yaml.safe_dump(\n            {\"display\": {\"sections\": {\"activity\": \"hidden\", \"tools\": \"expanded\"}}}\n        )\n    )\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"details_mode.activity\", \"value\": \"\"},\n        }\n    )\n\n    assert resp[\"result\"] == {\"key\": \"details_mode.activity\", \"value\": \"\"}\n    saved = yaml.safe_load(cfg_path.read_text())\n    assert saved[\"display\"][\"sections\"] == {\"tools\": \"expanded\"}\n\n\ndef test_config_set_section_rejects_unknown_section_or_mode(tmp_path, monkeypatch):\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n\n    bad_section = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"details_mode.bogus\", \"value\": \"hidden\"},\n        }\n    )\n    assert bad_section[\"error\"][\"code\"] == 4002\n\n    bad_mode = server.handle_request(\n        {\n            \"id\": \"2\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"details_mode.tools\", \"value\": \"maximised\"},\n        }\n    )\n    assert bad_mode[\"error\"][\"code\"] == 4002\n\n\ndef test_config_mouse_uses_documented_key_with_legacy_fallback(monkeypatch):\n    cfg = {\"display\": {\"tui_mouse\": False}}\n    writes = []\n\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: cfg)\n    monkeypatch.setattr(\n        server, \"_write_config_key\", lambda path, value: writes.append((path, value))\n    )\n\n    get_legacy = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"mouse\"}}\n    )\n    assert get_legacy[\"result\"][\"value\"] == \"off\"\n\n    set_toggle = server.handle_request(\n        {\"id\": \"2\", \"method\": \"config.set\", \"params\": {\"key\": \"mouse\"}}\n    )\n    assert set_toggle[\"result\"] == {\"key\": \"mouse\", \"value\": \"on\"}\n    assert writes == [(\"display.mouse_tracking\", True)]\n\n    cfg[\"display\"] = {\"mouse_tracking\": 0, \"tui_mouse\": True}\n    get_canonical = server.handle_request(\n        {\"id\": \"3\", \"method\": \"config.get\", \"params\": {\"key\": \"mouse\"}}\n    )\n    assert get_canonical[\"result\"][\"value\"] == \"off\"\n\n    cfg[\"display\"] = {\"mouse_tracking\": None, \"tui_mouse\": False}\n    get_null = server.handle_request(\n        {\"id\": \"4\", \"method\": \"config.get\", \"params\": {\"key\": \"mouse\"}}\n    )\n    assert get_null[\"result\"][\"value\"] == \"on\"\n\n\ndef test_enable_gateway_prompts_sets_gateway_env(monkeypatch):\n    monkeypatch.delenv(\"CLAWBOT_EXEC_ASK\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_GATEWAY_SESSION\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_INTERACTIVE\", raising=False)\n\n    server._enable_gateway_prompts()\n\n    assert server.os.environ[\"CLAWBOT_GATEWAY_SESSION\"] == \"1\"\n    assert server.os.environ[\"CLAWBOT_EXEC_ASK\"] == \"1\"\n    assert server.os.environ[\"CLAWBOT_INTERACTIVE\"] == \"1\"\n\n\ndef test_setup_status_reports_provider_config(monkeypatch):\n    monkeypatch.setattr(\"clawbot_cli.main._has_any_provider_configured\", lambda: False)\n\n    resp = server.handle_request({\"id\": \"1\", \"method\": \"setup.status\", \"params\": {}})\n\n    assert resp[\"result\"][\"provider_configured\"] is False\n\n\ndef test_complete_slash_includes_provider_alias():\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"complete.slash\", \"params\": {\"text\": \"/pro\"}}\n    )\n\n    assert any(item[\"text\"] == \"provider\" for item in resp[\"result\"][\"items\"])\n\n\ndef test_complete_slash_includes_tui_details_command():\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"complete.slash\", \"params\": {\"text\": \"/det\"}}\n    )\n\n    assert any(item[\"text\"] == \"/details\" for item in resp[\"result\"][\"items\"])\n\n\ndef test_complete_slash_includes_tui_mouse_command():\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"complete.slash\", \"params\": {\"text\": \"/mou\"}}\n    )\n\n    assert any(item[\"text\"] == \"/mouse\" for item in resp[\"result\"][\"items\"])\n\n\ndef test_complete_slash_details_args():\n    resp_root = server.handle_request(\n        {\"id\": \"0\", \"method\": \"complete.slash\", \"params\": {\"text\": \"/details\"}}\n    )\n    resp_section = server.handle_request(\n        {\"id\": \"1\", \"method\": \"complete.slash\", \"params\": {\"text\": \"/details t\"}}\n    )\n    resp_mode = server.handle_request(\n        {\n            \"id\": \"2\",\n            \"method\": \"complete.slash\",\n            \"params\": {\"text\": \"/details thinking e\"},\n        }\n    )\n\n    assert resp_root[\"result\"][\"replace_from\"] == len(\"/details\")\n    assert any(item[\"text\"] == \" thinking\" for item in resp_root[\"result\"][\"items\"])\n    assert any(item[\"text\"] == \"thinking\" for item in resp_section[\"result\"][\"items\"])\n    assert any(item[\"text\"] == \"expanded\" for item in resp_mode[\"result\"][\"items\"])\n\n\ndef test_config_set_reasoning_updates_live_session_and_agent(tmp_path, monkeypatch):\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n    agent = types.SimpleNamespace(reasoning_config=None)\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    resp_effort = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"session_id\": \"sid\", \"key\": \"reasoning\", \"value\": \"low\"},\n        }\n    )\n    assert resp_effort[\"result\"][\"value\"] == \"low\"\n    assert agent.reasoning_config == {\"enabled\": True, \"effort\": \"low\"}\n\n    resp_show = server.handle_request(\n        {\n            \"id\": \"2\",\n            \"method\": \"config.set\",\n            \"params\": {\"session_id\": \"sid\", \"key\": \"reasoning\", \"value\": \"show\"},\n        }\n    )\n    assert resp_show[\"result\"][\"value\"] == \"show\"\n    assert server._sessions[\"sid\"][\"show_reasoning\"] is True\n    assert server._load_cfg()[\"display\"][\"sections\"][\"thinking\"] == \"expanded\"\n\n    resp_hide = server.handle_request(\n        {\n            \"id\": \"3\",\n            \"method\": \"config.set\",\n            \"params\": {\"session_id\": \"sid\", \"key\": \"reasoning\", \"value\": \"hide\"},\n        }\n    )\n    assert resp_hide[\"result\"][\"value\"] == \"hide\"\n    assert server._sessions[\"sid\"][\"show_reasoning\"] is False\n    assert server._load_cfg()[\"display\"][\"sections\"][\"thinking\"] == \"hidden\"\n\n\ndef test_config_set_verbose_updates_session_mode_and_agent(tmp_path, monkeypatch):\n    monkeypatch.setattr(server, \"_clawbot_home\", tmp_path)\n    agent = types.SimpleNamespace(verbose_logging=False)\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"session_id\": \"sid\", \"key\": \"verbose\", \"value\": \"cycle\"},\n        }\n    )\n\n    assert resp[\"result\"][\"value\"] == \"verbose\"\n    assert server._sessions[\"sid\"][\"tool_progress_mode\"] == \"verbose\"\n    assert agent.verbose_logging is True\n\n\ndef test_config_set_model_uses_live_switch_path(monkeypatch):\n    server._sessions[\"sid\"] = _session()\n    seen = {}\n\n    def _fake_apply(sid, session, raw):\n        seen[\"args\"] = (sid, session[\"session_key\"], raw)\n        return {\"value\": \"new/model\", \"warning\": \"catalog unreachable\"}\n\n    monkeypatch.setattr(server, \"_apply_model_switch\", _fake_apply)\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"session_id\": \"sid\", \"key\": \"model\", \"value\": \"new/model\"},\n        }\n    )\n\n    assert resp[\"result\"][\"value\"] == \"new/model\"\n    assert resp[\"result\"][\"warning\"] == \"catalog unreachable\"\n    assert seen[\"args\"] == (\"sid\", \"session-key\", \"new/model\")\n\n\ndef test_config_set_model_global_persists(monkeypatch):\n    class _Agent:\n        provider = \"openrouter\"\n        model = \"old/model\"\n        base_url = \"\"\n        api_key = \"sk-old\"\n\n        def switch_model(self, **kwargs):\n            return None\n\n    result = types.SimpleNamespace(\n        success=True,\n        new_model=\"anthropic/claude-sonnet-4.6\",\n        target_provider=\"anthropic\",\n        api_key=\"sk-new\",\n        base_url=\"https://api.anthropic.com\",\n        api_mode=\"anthropic_messages\",\n        warning_message=\"\",\n    )\n    seen = {}\n    saved = {}\n\n    def _switch_model(**kwargs):\n        seen.update(kwargs)\n        return result\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(\"clawbot_cli.model_switch.switch_model\", _switch_model)\n    monkeypatch.setattr(server, \"_restart_slash_worker\", lambda session: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(\"clawbot_cli.config.save_config\", lambda cfg: saved.update(cfg))\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\n                \"session_id\": \"sid\",\n                \"key\": \"model\",\n                \"value\": \"anthropic/claude-sonnet-4.6 --global\",\n            },\n        }\n    )\n\n    assert resp[\"result\"][\"value\"] == \"anthropic/claude-sonnet-4.6\"\n    assert seen[\"is_global\"] is True\n    assert saved[\"model\"][\"default\"] == \"anthropic/claude-sonnet-4.6\"\n    assert saved[\"model\"][\"provider\"] == \"anthropic\"\n    assert saved[\"model\"][\"base_url\"] == \"https://api.anthropic.com\"\n\n\ndef test_config_set_model_syncs_inference_provider_env(monkeypatch):\n    \"\"\"After an explicit provider switch, CLAWBOT_INFERENCE_PROVIDER must\n    reflect the user's choice so ambient re-resolution (credential pool\n    refresh, aux clients) picks up the new provider instead of the original\n    one persisted in config or shell env.\n\n    Regression: a TUI user switched openrouter → anthropic and the TUI kept\n    trying openrouter because the env-var-backed resolvers still saw the old\n    provider.\n    \"\"\"\n\n    class _Agent:\n        provider = \"openrouter\"\n        model = \"old/model\"\n        base_url = \"\"\n        api_key = \"sk-or\"\n\n        def switch_model(self, **_kwargs):\n            return None\n\n    result = types.SimpleNamespace(\n        success=True,\n        new_model=\"claude-sonnet-4.6\",\n        target_provider=\"anthropic\",\n        api_key=\"sk-ant\",\n        base_url=\"https://api.anthropic.com\",\n        api_mode=\"anthropic_messages\",\n        warning_message=\"\",\n    )\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setenv(\"CLAWBOT_INFERENCE_PROVIDER\", \"openrouter\")\n    monkeypatch.setattr(\n        \"clawbot_cli.model_switch.switch_model\", lambda **_kwargs: result\n    )\n    monkeypatch.setattr(server, \"_restart_slash_worker\", lambda session: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n\n    server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\n                \"session_id\": \"sid\",\n                \"key\": \"model\",\n                \"value\": \"claude-sonnet-4.6 --provider anthropic\",\n            },\n        }\n    )\n\n    assert os.environ[\"CLAWBOT_INFERENCE_PROVIDER\"] == \"anthropic\"\n\n\ndef test_config_set_model_syncs_tui_provider_unconditionally(monkeypatch):\n    \"\"\"Regression for #16857: /model must set CLAWBOT_TUI_PROVIDER even when\n    it wasn't pre-set on launch, so a later /new (which re-runs\n    _resolve_startup_runtime) honours the user's explicit provider choice\n    instead of falling through to static-catalog detection and picking a\n    coincidentally-matching native provider.\n    \"\"\"\n\n    class _Agent:\n        provider = \"openrouter\"\n        model = \"old/model\"\n        base_url = \"\"\n        api_key = \"sk-or\"\n\n        def switch_model(self, **_kwargs):\n            return None\n\n    result = types.SimpleNamespace(\n        success=True,\n        new_model=\"deepseek-v4-pro\",\n        target_provider=\"custom:xuanji\",\n        api_key=\"sk-xuanji\",\n        base_url=\"https://xuanji.example/v1\",\n        api_mode=\"chat_completions\",\n        warning_message=\"\",\n    )\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.delenv(\"CLAWBOT_TUI_PROVIDER\", raising=False)\n    monkeypatch.delenv(\"CLAWBOT_INFERENCE_PROVIDER\", raising=False)\n    monkeypatch.setattr(\n        \"clawbot_cli.model_switch.switch_model\", lambda **_kwargs: result\n    )\n    monkeypatch.setattr(server, \"_restart_slash_worker\", lambda session: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n\n    server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\n                \"session_id\": \"sid\",\n                \"key\": \"model\",\n                \"value\": \"deepseek-v4-pro --provider custom:xuanji\",\n            },\n        }\n    )\n\n    # Both env vars must reflect the user's choice. CLAWBOT_TUI_PROVIDER is\n    # the canonical explicit-this-process carrier consumed by\n    # _resolve_startup_runtime() on /new.\n    assert os.environ[\"CLAWBOT_TUI_PROVIDER\"] == \"custom:xuanji\"\n    assert os.environ[\"CLAWBOT_INFERENCE_PROVIDER\"] == \"custom:xuanji\"\n\n\ndef test_config_set_model_syncs_tui_provider_env(monkeypatch):\n    class Agent:\n        model = \"gpt-5.3-codex\"\n        provider = \"openai-codex\"\n        base_url = \"\"\n        api_key = \"\"\n\n        def switch_model(self, **kwargs):\n            self.model = kwargs[\"new_model\"]\n            self.provider = kwargs[\"new_provider\"]\n\n    agent = Agent()\n    server._sessions[\"sid\"] = _session(agent=agent)\n    monkeypatch.setenv(\"CLAWBOT_TUI_PROVIDER\", \"openai-codex\")\n    monkeypatch.setattr(server, \"_restart_slash_worker\", lambda session: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n\n    def fake_switch_model(**kwargs):\n        return types.SimpleNamespace(\n            success=True,\n            new_model=\"anthropic/claude-sonnet-4.6\",\n            target_provider=\"anthropic\",\n            api_key=\"key\",\n            base_url=\"https://api.anthropic.com\",\n            api_mode=\"anthropic_messages\",\n            warning_message=\"\",\n        )\n\n    monkeypatch.setattr(\"clawbot_cli.model_switch.switch_model\", fake_switch_model)\n\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\n                    \"session_id\": \"sid\",\n                    \"key\": \"model\",\n                    \"value\": \"anthropic/claude-sonnet-4.6 --provider anthropic\",\n                },\n            }\n        )\n\n        assert resp[\"result\"][\"value\"] == \"anthropic/claude-sonnet-4.6\"\n        assert os.environ[\"CLAWBOT_TUI_PROVIDER\"] == \"anthropic\"\n        assert os.environ[\"CLAWBOT_MODEL\"] == \"anthropic/claude-sonnet-4.6\"\n        assert os.environ[\"CLAWBOT_INFERENCE_MODEL\"] == \"anthropic/claude-sonnet-4.6\"\n    finally:\n        server._sessions.clear()\n\n\ndef test_config_set_personality_rejects_unknown_name(monkeypatch):\n    monkeypatch.setattr(\n        server,\n        \"_available_personalities\",\n        lambda cfg=None: {\"helpful\": \"You are helpful.\"},\n    )\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"personality\", \"value\": \"bogus\"},\n        }\n    )\n\n    assert \"error\" in resp\n    assert \"Unknown personality\" in resp[\"error\"][\"message\"]\n\n\ndef test_config_set_personality_preserves_history_and_returns_info(monkeypatch):\n    agent = types.SimpleNamespace(\n        ephemeral_system_prompt=None, _cached_system_prompt=\"old\"\n    )\n    session = _session(\n        agent=agent,\n        history=[{\"role\": \"user\", \"text\": \"hi\"}],\n        history_version=4,\n    )\n    emits = []\n\n    server._sessions[\"sid\"] = session\n    monkeypatch.setattr(\n        server,\n        \"_available_personalities\",\n        lambda cfg=None: {\"helpful\": \"You are helpful.\"},\n    )\n    monkeypatch.setattr(\n        server, \"_session_info\", lambda agent: {\"model\": getattr(agent, \"model\", \"?\")}\n    )\n    monkeypatch.setattr(server, \"_emit\", lambda *args: emits.append(args))\n    monkeypatch.setattr(server, \"_write_config_key\", lambda path, value: None)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"session_id\": \"sid\", \"key\": \"personality\", \"value\": \"helpful\"},\n        }\n    )\n\n    assert resp[\"result\"][\"history_reset\"] is False\n    assert resp[\"result\"][\"info\"] == {\"model\": \"?\"}\n    # History is preserved with a pivot marker appended\n    assert len(session[\"history\"]) == 2\n    assert session[\"history\"][0] == {\"role\": \"user\", \"text\": \"hi\"}\n    assert session[\"history\"][1][\"role\"] == \"user\"\n    assert \"personality\" in session[\"history\"][1][\"content\"].lower()\n    assert \"You are helpful.\" in session[\"history\"][1][\"content\"]\n    assert session[\"history_version\"] == 5\n    # Agent's system prompt was updated in-place; cached prompt untouched\n    assert agent.ephemeral_system_prompt == \"You are helpful.\"\n    assert agent._cached_system_prompt == \"old\"\n    assert (\"session.info\", \"sid\", {\"model\": \"?\"}) in emits\n\n\ndef test_session_compress_uses_compress_helper(monkeypatch):\n    agent = types.SimpleNamespace()\n    server._sessions[\"sid\"] = _session(agent=agent)\n\n    monkeypatch.setattr(\n        server,\n        \"_compress_session_history\",\n        lambda session, focus_topic=None, **_kw: (2, {\"total\": 42}),\n    )\n    monkeypatch.setattr(server, \"_session_info\", lambda _agent: {\"model\": \"x\"})\n\n    with patch(\"tui_gateway.server._emit\") as emit:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.compress\", \"params\": {\"session_id\": \"sid\"}}\n        )\n\n    assert resp[\"result\"][\"removed\"] == 2\n    assert resp[\"result\"][\"usage\"][\"total\"] == 42\n    emit.assert_any_call(\"session.info\", \"sid\", {\"model\": \"x\"})\n    # Final status.update clears the pinned \"compressing\" indicator so the\n    # status bar can revert to the neutral state when compaction finishes.\n    emit.assert_any_call(\"status.update\", \"sid\", {\"kind\": \"status\", \"text\": \"ready\"})\n\n\ndef test_session_compress_syncs_session_key_after_rotation(monkeypatch):\n    \"\"\"When AIAgent._compress_context rotates session_id (compression split),\n    the gateway session_key must follow so subsequent approval routing,\n    DB title/history lookups, and slash worker resume target the new\n    continuation session — mirrors ClawbotCLI._manual_compress's\n    session_id sync (cli.py).\n    \"\"\"\n    agent = types.SimpleNamespace(session_id=\"rotated-id\")\n    server._sessions[\"sid\"] = _session(agent=agent)\n    server._sessions[\"sid\"][\"session_key\"] = \"old-key\"\n    server._sessions[\"sid\"][\"pending_title\"] = \"stale title\"\n\n    monkeypatch.setattr(\n        server,\n        \"_compress_session_history\",\n        lambda session, focus_topic=None, **_kw: (2, {\"total\": 42}),\n    )\n    monkeypatch.setattr(server, \"_session_info\", lambda _agent: {\"model\": \"x\"})\n    restart_calls = []\n    monkeypatch.setattr(\n        server, \"_restart_slash_worker\", lambda s: restart_calls.append(s)\n    )\n\n    try:\n        with patch(\"tui_gateway.server._emit\"):\n            server.handle_request(\n                {\n                    \"id\": \"1\",\n                    \"method\": \"session.compress\",\n                    \"params\": {\"session_id\": \"sid\"},\n                }\n            )\n\n        assert server._sessions[\"sid\"][\"session_key\"] == \"rotated-id\"\n        assert server._sessions[\"sid\"][\"pending_title\"] is None\n        assert len(restart_calls) == 1\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_prompt_submit_sets_approval_session_key(monkeypatch):\n    from tools.approval import get_current_session_key\n\n    captured = {}\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            captured[\"session_key\"] = get_current_session_key(default=\"\")\n            return {\n                \"final_response\": \"ok\",\n                \"messages\": [{\"role\": \"assistant\", \"content\": \"ok\"}],\n            }\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None):\n            self._target = target\n\n        def start(self):\n            self._target()\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"prompt.submit\",\n            \"params\": {\"session_id\": \"sid\", \"text\": \"ping\"},\n        }\n    )\n\n    assert resp[\"result\"][\"status\"] == \"streaming\"\n    assert captured[\"session_key\"] == \"session-key\"\n\n\ndef test_prompt_submit_expands_context_refs(monkeypatch):\n    captured = {}\n\n    class _Agent:\n        model = \"test/model\"\n        base_url = \"\"\n        api_key = \"\"\n\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            captured[\"prompt\"] = prompt\n            return {\n                \"final_response\": \"ok\",\n                \"messages\": [{\"role\": \"assistant\", \"content\": \"ok\"}],\n            }\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None):\n            self._target = target\n\n        def start(self):\n            self._target()\n\n    fake_ctx = types.ModuleType(\"agent.context_references\")\n    fake_ctx.preprocess_context_references = (\n        lambda message, **kwargs: types.SimpleNamespace(\n            blocked=False,\n            message=\"expanded prompt\",\n            warnings=[],\n            references=[],\n            injected_tokens=0,\n        )\n    )\n    fake_meta = types.ModuleType(\"agent.model_metadata\")\n    fake_meta.get_model_context_length = lambda *args, **kwargs: 100000\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setitem(sys.modules, \"agent.context_references\", fake_ctx)\n    monkeypatch.setitem(sys.modules, \"agent.model_metadata\", fake_meta)\n\n    server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"prompt.submit\",\n            \"params\": {\"session_id\": \"sid\", \"text\": \"@diff\"},\n        }\n    )\n\n    assert captured[\"prompt\"] == \"expanded prompt\"\n\n\ndef test_image_attach_appends_local_image(monkeypatch):\n    fake_cli = types.ModuleType(\"cli\")\n    fake_cli._IMAGE_EXTENSIONS = {\".png\"}\n    fake_cli._detect_file_drop = lambda raw: {\n        \"path\": Path(\"/tmp/cat.png\"),\n        \"is_image\": True,\n        \"remainder\": \"\",\n    }\n    fake_cli._split_path_input = lambda raw: (raw, \"\")\n    fake_cli._resolve_attachment_path = lambda raw: Path(\"/tmp/cat.png\")\n\n    server._sessions[\"sid\"] = _session()\n    monkeypatch.setitem(sys.modules, \"cli\", fake_cli)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"image.attach\",\n            \"params\": {\"session_id\": \"sid\", \"path\": \"/tmp/cat.png\"},\n        }\n    )\n\n    assert resp[\"result\"][\"attached\"] is True\n    assert resp[\"result\"][\"name\"] == \"cat.png\"\n    assert len(server._sessions[\"sid\"][\"attached_images\"]) == 1\n\n\ndef test_image_attach_accepts_unquoted_screenshot_path_with_spaces(monkeypatch):\n    screenshot = Path(\"/tmp/Screenshot 2026-04-21 at 1.04.43 PM.png\")\n    fake_cli = types.ModuleType(\"cli\")\n    fake_cli._IMAGE_EXTENSIONS = {\".png\"}\n    fake_cli._detect_file_drop = lambda raw: {\n        \"path\": screenshot,\n        \"is_image\": True,\n        \"remainder\": \"\",\n    }\n    fake_cli._split_path_input = lambda raw: (\n        \"/tmp/Screenshot\",\n        \"2026-04-21 at 1.04.43 PM.png\",\n    )\n    fake_cli._resolve_attachment_path = lambda raw: None\n\n    server._sessions[\"sid\"] = _session()\n    monkeypatch.setitem(sys.modules, \"cli\", fake_cli)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"image.attach\",\n            \"params\": {\"session_id\": \"sid\", \"path\": str(screenshot)},\n        }\n    )\n\n    assert resp[\"result\"][\"attached\"] is True\n    assert resp[\"result\"][\"path\"] == str(screenshot)\n    assert resp[\"result\"][\"remainder\"] == \"\"\n    assert len(server._sessions[\"sid\"][\"attached_images\"]) == 1\n\n\ndef test_commands_catalog_surfaces_quick_commands(monkeypatch):\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\n            \"quick_commands\": {\n                \"build\": {\"type\": \"exec\", \"command\": \"npm run build\"},\n                \"git\": {\"type\": \"alias\", \"target\": \"/shell git\"},\n                \"notes\": {\n                    \"type\": \"exec\",\n                    \"command\": \"cat NOTES.md\",\n                    \"description\": \"Open design notes\",\n                },\n            }\n        },\n    )\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"commands.catalog\", \"params\": {}}\n    )\n\n    pairs = dict(resp[\"result\"][\"pairs\"])\n    assert \"npm run build\" in pairs[\"/build\"]\n    assert pairs[\"/git\"].startswith(\"alias →\")\n    assert pairs[\"/notes\"] == \"Open design notes\"\n\n    user_cat = next(\n        c for c in resp[\"result\"][\"categories\"] if c[\"name\"] == \"User commands\"\n    )\n    user_pairs = dict(user_cat[\"pairs\"])\n    assert set(user_pairs) == {\"/build\", \"/git\", \"/notes\"}\n\n    assert resp[\"result\"][\"canon\"][\"/build\"] == \"/build\"\n    assert resp[\"result\"][\"canon\"][\"/notes\"] == \"/notes\"\n\n\ndef test_commands_catalog_includes_tui_mouse_command():\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"commands.catalog\", \"params\": {}}\n    )\n\n    pairs = dict(resp[\"result\"][\"pairs\"])\n    tui_cat = next(c for c in resp[\"result\"][\"categories\"] if c[\"name\"] == \"TUI\")\n    tui_pairs = dict(tui_cat[\"pairs\"])\n\n    assert \"/mouse\" in pairs\n    assert \"/mouse\" in tui_pairs\n\n\ndef test_commands_catalog_filters_gateway_only_commands_and_keeps_status_visible():\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"commands.catalog\", \"params\": {}}\n    )\n\n    pairs = dict(resp[\"result\"][\"pairs\"])\n    canon = resp[\"result\"][\"canon\"]\n\n    assert \"/status\" in pairs\n    assert canon[\"/status\"] == \"/status\"\n\n    assert \"/topic\" not in pairs\n    assert \"/approve\" not in pairs\n    assert \"/deny\" not in pairs\n    assert \"/sethome\" not in pairs\n\n    assert \"/topic\" not in canon\n    assert \"/approve\" not in canon\n    assert \"/deny\" not in canon\n    assert \"/set-home\" not in canon\n\n\ndef test_session_status_reads_live_gateway_agent(monkeypatch):\n    agent = types.SimpleNamespace(\n        model=\"live-model\",\n        provider=\"live-provider\",\n        session_total_tokens=1234,\n    )\n    server._sessions[\"sid\"] = _session(agent=agent, running=True)\n\n    class _DB:\n        def get_session(self, key):\n            assert key == \"session-key\"\n            return {\n                \"title\": \"Live TUI\",\n                \"started_at\": 1_700_000_000,\n                \"updated_at\": 1_700_000_060,\n            }\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.status\", \"params\": {\"session_id\": \"sid\"}}\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n    out = resp[\"result\"][\"output\"]\n    assert \"Clawbot TUI Status\" in out\n    assert \"Session ID: session-key\" in out\n    assert \"Title: Live TUI\" in out\n    assert \"Model: live-model (live-provider)\" in out\n    assert \"Tokens: 1,234\" in out\n    assert \"Agent Running: Yes\" in out\n\n\ndef test_skills_reload_runs_in_gateway_process(monkeypatch):\n    import agent.skill_commands as skill_commands\n\n    called = {}\n    monkeypatch.setattr(\n        skill_commands,\n        \"reload_skills\",\n        lambda: called.setdefault(\n            \"result\",\n            {\n                \"added\": [{\"name\": \"new-skill\", \"description\": \"demo\"}],\n                \"removed\": [],\n                \"total\": 42,\n            },\n        ),\n    )\n\n    resp = server.handle_request({\"id\": \"1\", \"method\": \"skills.reload\", \"params\": {}})\n\n    assert called[\"result\"][\"total\"] == 42\n    assert \"new-skill\" in resp[\"result\"][\"output\"]\n    assert \"42 skill(s) available\" in resp[\"result\"][\"output\"]\n\n\ndef test_snapshot_restore_is_blocked_from_tui_worker():\n    server._sessions[\"sid\"] = _session()\n    try:\n        worker_resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"slash.exec\",\n                \"params\": {\"command\": \"snapshot restore latest\", \"session_id\": \"sid\"},\n            }\n        )\n        dispatch_resp = server.handle_request(\n            {\n                \"id\": \"2\",\n                \"method\": \"command.dispatch\",\n                \"params\": {\n                    \"arg\": \"restore latest\",\n                    \"name\": \"snapshot\",\n                    \"session_id\": \"sid\",\n                },\n            }\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n    assert worker_resp[\"error\"][\"code\"] == 4018\n    assert (\n        \"snapshot restore mutates live config/state\" in worker_resp[\"error\"][\"message\"]\n    )\n    assert dispatch_resp[\"result\"][\"type\"] == \"exec\"\n    assert (\n        \"/snapshot restore is blocked in the TUI\" in dispatch_resp[\"result\"][\"output\"]\n    )\n\n\ndef test_command_dispatch_exec_nonzero_surfaces_error(monkeypatch):\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"quick_commands\": {\"boom\": {\"type\": \"exec\", \"command\": \"boom\"}}},\n    )\n    monkeypatch.setattr(\n        server.subprocess,\n        \"run\",\n        lambda *args, **kwargs: types.SimpleNamespace(\n            returncode=1, stdout=\"\", stderr=\"failed\"\n        ),\n    )\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"command.dispatch\", \"params\": {\"name\": \"boom\"}}\n    )\n\n    assert \"error\" in resp\n    assert \"failed\" in resp[\"error\"][\"message\"]\n\n\ndef test_plugins_list_surfaces_loader_error(monkeypatch):\n    with patch(\"clawbot_cli.plugins.get_plugin_manager\", side_effect=Exception(\"boom\")):\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"plugins.list\", \"params\": {}}\n        )\n\n    assert \"error\" in resp\n    assert \"boom\" in resp[\"error\"][\"message\"]\n\n\ndef test_complete_slash_surfaces_completer_error(monkeypatch):\n    with patch(\n        \"clawbot_cli.commands.SlashCommandCompleter\",\n        side_effect=Exception(\"no completer\"),\n    ):\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"complete.slash\", \"params\": {\"text\": \"/mo\"}}\n        )\n\n    assert \"error\" in resp\n    assert \"no completer\" in resp[\"error\"][\"message\"]\n\n\ndef test_input_detect_drop_attaches_image(monkeypatch):\n    fake_cli = types.ModuleType(\"cli\")\n    fake_cli._detect_file_drop = lambda raw: {\n        \"path\": Path(\"/tmp/cat.png\"),\n        \"is_image\": True,\n        \"remainder\": \"\",\n    }\n\n    server._sessions[\"sid\"] = _session()\n    monkeypatch.setitem(sys.modules, \"cli\", fake_cli)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"input.detect_drop\",\n            \"params\": {\"session_id\": \"sid\", \"text\": \"/tmp/cat.png\"},\n        }\n    )\n\n    assert resp[\"result\"][\"matched\"] is True\n    assert resp[\"result\"][\"is_image\"] is True\n    assert resp[\"result\"][\"text\"] == \"[User attached image: cat.png]\"\n\n\ndef test_input_detect_drop_path_with_spaces(tmp_path):\n    \"\"\"input.detect_drop correctly handles image paths containing spaces.\"\"\"\n    # Create a minimal PNG file with a space in its name\n    img = tmp_path / \"screenshot with spaces.png\"\n    img.write_bytes(b\"\\x89PNG\\r\\n\\x1a\\n\")  # valid PNG header\n\n    server._sessions[\"sid\"] = _session()\n\n    resp = server.handle_request(\n        {\n            \"id\": \"2\",\n            \"method\": \"input.detect_drop\",\n            \"params\": {\"session_id\": \"sid\", \"text\": str(img)},\n        }\n    )\n\n    assert resp[\"result\"][\"matched\"] is True\n    assert resp[\"result\"][\"is_image\"] is True\n    assert resp[\"result\"][\"path\"] == str(img)\n    assert resp[\"result\"][\"text\"] == f\"[User attached image: {img.name}]\"\n    # Verify attachment was recorded in the session\n    assert len(server._sessions[\"sid\"][\"attached_images\"]) == 1\n    assert server._sessions[\"sid\"][\"attached_images\"][0] == str(img)\n\n\ndef test_input_detect_drop_path_with_spaces_and_remainder(tmp_path):\n    \"\"\"input.detect_drop splits remainder when path contains spaces.\"\"\"\n    img = tmp_path / \"photo with space.jpg\"\n    img.write_bytes(b\"\\xff\\xd8\\xff\" + b\"fakejpeg\")  # minimal-ish JPEG header\n\n    server._sessions[\"sid\"] = _session()\n\n    user_input = f\"{img} describe this image\"\n    resp = server.handle_request(\n        {\n            \"id\": \"3\",\n            \"method\": \"input.detect_drop\",\n            \"params\": {\"session_id\": \"sid\", \"text\": user_input},\n        }\n    )\n\n    assert resp[\"result\"][\"matched\"] is True\n    assert resp[\"result\"][\"is_image\"] is True\n    assert resp[\"result\"][\"path\"] == str(img)\n    # Remainder becomes the text sent to the model\n    assert resp[\"result\"][\"text\"] == \"describe this image\"\n    assert server._sessions[\"sid\"][\"attached_images\"][0] == str(img)\n\n\ndef test_rollback_restore_resolves_number_and_file_path():\n    calls = {}\n\n    class _Mgr:\n        enabled = True\n\n        def list_checkpoints(self, cwd):\n            return [{\"hash\": \"aaa111\"}, {\"hash\": \"bbb222\"}]\n\n        def restore(self, cwd, target, file_path=None):\n            calls[\"args\"] = (cwd, target, file_path)\n            return {\"success\": True, \"message\": \"done\"}\n\n    server._sessions[\"sid\"] = _session(\n        agent=types.SimpleNamespace(_checkpoint_mgr=_Mgr()), history=[]\n    )\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"rollback.restore\",\n            \"params\": {\"session_id\": \"sid\", \"hash\": \"2\", \"file_path\": \"src/app.tsx\"},\n        }\n    )\n\n    assert resp[\"result\"][\"success\"] is True\n    assert calls[\"args\"][1] == \"bbb222\"\n    assert calls[\"args\"][2] == \"src/app.tsx\"\n\n\n# ── session.steer ────────────────────────────────────────────────────\n\n\ndef test_session_steer_calls_agent_steer_when_agent_supports_it():\n    \"\"\"The TUI RPC method must call agent.steer(text) and return a\n    queued status without touching interrupt state.\n    \"\"\"\n    calls = {}\n\n    class _Agent:\n        def steer(self, text):\n            calls[\"steer_text\"] = text\n            return True\n\n        def interrupt(self, *args, **kwargs):\n            calls[\"interrupt_called\"] = True\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.steer\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"also check auth.log\"},\n            }\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n    assert \"result\" in resp, resp\n    assert resp[\"result\"][\"status\"] == \"queued\"\n    assert resp[\"result\"][\"text\"] == \"also check auth.log\"\n    assert calls[\"steer_text\"] == \"also check auth.log\"\n    assert \"interrupt_called\" not in calls  # must NOT interrupt\n\n\ndef test_session_steer_rejects_empty_text():\n    server._sessions[\"sid\"] = _session(\n        agent=types.SimpleNamespace(steer=lambda t: True)\n    )\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.steer\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"   \"},\n            }\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n    assert \"error\" in resp, resp\n    assert resp[\"error\"][\"code\"] == 4002\n\n\ndef test_session_steer_errors_when_agent_has_no_steer_method():\n    server._sessions[\"sid\"] = _session(agent=types.SimpleNamespace())  # no steer()\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.steer\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"hi\"},\n            }\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n    assert \"error\" in resp, resp\n    assert resp[\"error\"][\"code\"] == 4010\n\n\ndef test_session_info_includes_mcp_servers(monkeypatch):\n    fake_status = [\n        {\"name\": \"github\", \"transport\": \"http\", \"tools\": 12, \"connected\": True},\n        {\"name\": \"filesystem\", \"transport\": \"stdio\", \"tools\": 4, \"connected\": True},\n        {\"name\": \"broken\", \"transport\": \"stdio\", \"tools\": 0, \"connected\": False},\n    ]\n    fake_mod = types.ModuleType(\"tools.mcp_tool\")\n    fake_mod.get_mcp_status = lambda: fake_status\n    monkeypatch.setitem(sys.modules, \"tools.mcp_tool\", fake_mod)\n\n    info = server._session_info(types.SimpleNamespace(tools=[], model=\"\"))\n\n    assert info[\"mcp_servers\"] == fake_status\n\n\n# ---------------------------------------------------------------------------\n# History-mutating commands must reject while session.running is True.\n# Without these guards, prompt.submit's post-run history write either\n# clobbers the mutation (version matches) or silently drops the agent's\n# output (version mismatch) — both produce UI<->backend state desync.\n# ---------------------------------------------------------------------------\n\n\ndef test_session_undo_rejects_while_running():\n    \"\"\"Fix for TUI silent-drop #1: /undo must not mutate history\n    while the agent is mid-turn — would either clobber the undo or\n    cause prompt.submit to silently drop the agent's response.\"\"\"\n    server._sessions[\"sid\"] = _session(\n        running=True,\n        history=[\n            {\"role\": \"user\", \"content\": \"hi\"},\n            {\"role\": \"assistant\", \"content\": \"hello\"},\n        ],\n    )\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.undo\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp.get(\"error\"), \"session.undo should reject while running\"\n        assert resp[\"error\"][\"code\"] == 4009\n        assert \"session busy\" in resp[\"error\"][\"message\"]\n        # History must be unchanged\n        assert len(server._sessions[\"sid\"][\"history\"]) == 2\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_undo_allowed_when_idle():\n    \"\"\"Regression guard: when not running, /undo still works.\"\"\"\n    server._sessions[\"sid\"] = _session(\n        running=False,\n        history=[\n            {\"role\": \"user\", \"content\": \"hi\"},\n            {\"role\": \"assistant\", \"content\": \"hello\"},\n        ],\n    )\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.undo\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp.get(\"result\"), f\"got error: {resp.get('error')}\"\n        assert resp[\"result\"][\"removed\"] == 2\n        assert server._sessions[\"sid\"][\"history\"] == []\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_session_compress_rejects_while_running(monkeypatch):\n    server._sessions[\"sid\"] = _session(running=True)\n    try:\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.compress\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp.get(\"error\")\n        assert resp[\"error\"][\"code\"] == 4009\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_rollback_restore_rejects_full_history_while_running(monkeypatch):\n    \"\"\"Full-history rollback must reject; file-scoped rollback still allowed.\"\"\"\n    server._sessions[\"sid\"] = _session(running=True)\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"rollback.restore\",\n                \"params\": {\"session_id\": \"sid\", \"hash\": \"abc\"},\n            }\n        )\n        assert resp.get(\"error\"), \"full-history rollback should reject while running\"\n        assert resp[\"error\"][\"code\"] == 4009\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_prompt_submit_history_version_mismatch_surfaces_warning(monkeypatch):\n    \"\"\"Fix for TUI silent-drop #2: the defensive backstop at prompt.submit\n    must attach a 'warning' to message.complete when history was\n    mutated externally during the turn (instead of silently dropping\n    the agent's output).\"\"\"\n    # Agent bumps history_version itself mid-run to simulate an external\n    # mutation slipping past the guards.\n    session_ref = {\"s\": None}\n\n    class _RacyAgent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            # Simulate: something external bumped history_version\n            # while we were running.\n            with session_ref[\"s\"][\"history_lock\"]:\n                session_ref[\"s\"][\"history_version\"] += 1\n            return {\n                \"final_response\": \"agent reply\",\n                \"messages\": [{\"role\": \"assistant\", \"content\": \"agent reply\"}],\n            }\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None):\n            self._target = target\n\n        def start(self):\n            self._target()\n\n    server._sessions[\"sid\"] = _session(agent=_RacyAgent())\n    session_ref[\"s\"] = server._sessions[\"sid\"]\n    emits: list[tuple] = []\n    try:\n        monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n        monkeypatch.setattr(server, \"_get_usage\", lambda _a: {})\n        monkeypatch.setattr(server, \"render_message\", lambda _t, _c: \"\")\n        monkeypatch.setattr(server, \"_emit\", lambda *a: emits.append(a))\n\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"prompt.submit\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"hi\"},\n            }\n        )\n        assert resp.get(\"result\"), f\"got error: {resp.get('error')}\"\n\n        # History should NOT contain the agent's output (version mismatch)\n        assert server._sessions[\"sid\"][\"history\"] == []\n\n        # message.complete must carry a 'warning' so the UI / operator\n        # knows the output was not persisted.\n        complete_calls = [a for a in emits if a[0] == \"message.complete\"]\n        assert len(complete_calls) == 1\n        _, _, payload = complete_calls[0]\n        assert \"warning\" in payload, (\n            \"message.complete must include a 'warning' field on \"\n            \"history_version mismatch — otherwise the UI silently \"\n            \"shows output that was never persisted\"\n        )\n        assert (\n            \"not saved\" in payload[\"warning\"].lower()\n            or \"changed\" in payload[\"warning\"].lower()\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_prompt_submit_history_version_match_persists_normally(monkeypatch):\n    \"\"\"Regression guard: the backstop does not affect the happy path.\"\"\"\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            return {\n                \"final_response\": \"reply\",\n                \"messages\": [{\"role\": \"assistant\", \"content\": \"reply\"}],\n            }\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None):\n            self._target = target\n\n        def start(self):\n            self._target()\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    emits: list[tuple] = []\n    try:\n        monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n        monkeypatch.setattr(server, \"_get_usage\", lambda _a: {})\n        monkeypatch.setattr(server, \"render_message\", lambda _t, _c: \"\")\n        monkeypatch.setattr(server, \"_emit\", lambda *a: emits.append(a))\n\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"prompt.submit\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"hi\"},\n            }\n        )\n        assert resp.get(\"result\")\n\n        # History was written\n        assert server._sessions[\"sid\"][\"history\"] == [\n            {\"role\": \"assistant\", \"content\": \"reply\"}\n        ]\n        assert server._sessions[\"sid\"][\"history_version\"] == 1\n\n        # No warning should be attached\n        complete_calls = [a for a in emits if a[0] == \"message.complete\"]\n        assert len(complete_calls) == 1\n        _, _, payload = complete_calls[0]\n        assert \"warning\" not in payload\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\n# ---------------------------------------------------------------------------\n# session.interrupt must only cancel pending prompts owned by the calling\n# session — it must not blast-resolve clarify/sudo/secret prompts on\n# unrelated sessions sharing the same tui_gateway process.  Without\n# session scoping the other sessions' prompts silently resolve to empty\n# strings, unblocking their agent threads as if the user cancelled.\n# ---------------------------------------------------------------------------\n\n\ndef test_interrupt_only_clears_own_session_pending():\n    \"\"\"session.interrupt on session A must NOT release pending prompts\n    that belong to session B.\"\"\"\n    import types\n\n    session_a = _session()\n    session_a[\"agent\"] = types.SimpleNamespace(interrupt=lambda: None)\n    session_b = _session()\n    session_b[\"agent\"] = types.SimpleNamespace(interrupt=lambda: None)\n    server._sessions[\"sid_a\"] = session_a\n    server._sessions[\"sid_b\"] = session_b\n\n    try:\n        # Simulate pending prompts on both sessions (what _block creates\n        # while a clarify/sudo/secret request is outstanding).\n        ev_a = threading.Event()\n        ev_b = threading.Event()\n        server._pending[\"rid-a\"] = (\"sid_a\", ev_a)\n        server._pending[\"rid-b\"] = (\"sid_b\", ev_b)\n        server._answers.clear()\n\n        # Interrupt session A.\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.interrupt\",\n                \"params\": {\"session_id\": \"sid_a\"},\n            }\n        )\n        assert resp.get(\"result\"), f\"got error: {resp.get('error')}\"\n\n        # Session A's pending must be released to empty.\n        assert ev_a.is_set(), \"sid_a pending Event should be set after interrupt\"\n        assert server._answers.get(\"rid-a\") == \"\"\n\n        # Session B's pending MUST remain untouched — no cross-session blast.\n        assert not ev_b.is_set(), (\n            \"CRITICAL: session.interrupt on sid_a released a pending prompt \"\n            \"belonging to sid_b — other sessions' clarify/sudo/secret \"\n            \"prompts are being silently cancelled\"\n        )\n        assert \"rid-b\" not in server._answers\n    finally:\n        server._sessions.pop(\"sid_a\", None)\n        server._sessions.pop(\"sid_b\", None)\n        server._pending.pop(\"rid-a\", None)\n        server._pending.pop(\"rid-b\", None)\n        server._answers.pop(\"rid-a\", None)\n        server._answers.pop(\"rid-b\", None)\n\n\ndef test_interrupt_clears_multiple_own_pending():\n    \"\"\"When a single session has multiple pending prompts (uncommon but\n    possible via nested tool calls), interrupt must release all of them.\"\"\"\n    import types\n\n    sess = _session()\n    sess[\"agent\"] = types.SimpleNamespace(interrupt=lambda: None)\n    server._sessions[\"sid\"] = sess\n\n    try:\n        ev1, ev2 = threading.Event(), threading.Event()\n        server._pending[\"r1\"] = (\"sid\", ev1)\n        server._pending[\"r2\"] = (\"sid\", ev2)\n\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"session.interrupt\", \"params\": {\"session_id\": \"sid\"}}\n        )\n        assert resp.get(\"result\")\n        assert ev1.is_set() and ev2.is_set()\n        assert server._answers.get(\"r1\") == \"\" and server._answers.get(\"r2\") == \"\"\n    finally:\n        server._sessions.pop(\"sid\", None)\n        for key in (\"r1\", \"r2\"):\n            server._pending.pop(key, None)\n            server._answers.pop(key, None)\n\n\ndef test_clear_pending_without_sid_clears_all():\n    \"\"\"_clear_pending(None) is the shutdown path — must still release\n    every pending prompt regardless of owning session.\"\"\"\n    ev1, ev2, ev3 = threading.Event(), threading.Event(), threading.Event()\n    server._pending[\"a\"] = (\"sid_x\", ev1)\n    server._pending[\"b\"] = (\"sid_y\", ev2)\n    server._pending[\"c\"] = (\"sid_z\", ev3)\n    try:\n        server._clear_pending(None)\n        assert ev1.is_set() and ev2.is_set() and ev3.is_set()\n    finally:\n        for key in (\"a\", \"b\", \"c\"):\n            server._pending.pop(key, None)\n            server._answers.pop(key, None)\n\n\ndef test_respond_unpacks_sid_tuple_correctly():\n    \"\"\"After the (sid, Event) tuple change, _respond must still work.\"\"\"\n    ev = threading.Event()\n    server._pending[\"rid-x\"] = (\"sid_x\", ev)\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"clarify.respond\",\n                \"params\": {\"request_id\": \"rid-x\", \"answer\": \"the answer\"},\n            }\n        )\n        assert resp.get(\"result\")\n        assert ev.is_set()\n        assert server._answers.get(\"rid-x\") == \"the answer\"\n    finally:\n        server._pending.pop(\"rid-x\", None)\n        server._answers.pop(\"rid-x\", None)\n\n\n# ---------------------------------------------------------------------------\n# /model switch and other agent-mutating commands must reject while the\n# session is running.  agent.switch_model() mutates self.model, self.provider,\n# self.base_url, self.client etc. in place — the worker thread running\n# agent.run_conversation is reading those on every iteration.  Same class of\n# bug as the session.undo / session.compress mid-run silent-drop; same fix\n# pattern: reject with 4009 while running.\n# ---------------------------------------------------------------------------\n\n\ndef test_config_set_model_rejects_while_running(monkeypatch):\n    \"\"\"/model via config.set must reject during an in-flight turn.\"\"\"\n    seen = {\"called\": False}\n\n    def _fake_apply(sid, session, raw):\n        seen[\"called\"] = True\n        return {\"value\": raw, \"warning\": \"\"}\n\n    monkeypatch.setattr(server, \"_apply_model_switch\", _fake_apply)\n\n    server._sessions[\"sid\"] = _session(running=True)\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\n                    \"session_id\": \"sid\",\n                    \"key\": \"model\",\n                    \"value\": \"anthropic/claude-sonnet-4.6\",\n                },\n            }\n        )\n        assert resp.get(\"error\")\n        assert resp[\"error\"][\"code\"] == 4009\n        assert \"session busy\" in resp[\"error\"][\"message\"]\n        assert not seen[\"called\"], (\n            \"_apply_model_switch was called mid-turn — would race with \"\n            \"the worker thread reading agent.model / agent.client\"\n        )\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_config_set_model_allowed_when_idle(monkeypatch):\n    \"\"\"Regression guard: idle sessions can still switch models.\"\"\"\n    seen = {\"called\": False}\n\n    def _fake_apply(sid, session, raw):\n        seen[\"called\"] = True\n        return {\"value\": \"newmodel\", \"warning\": \"\"}\n\n    monkeypatch.setattr(server, \"_apply_model_switch\", _fake_apply)\n\n    server._sessions[\"sid\"] = _session(running=False)\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"session_id\": \"sid\", \"key\": \"model\", \"value\": \"newmodel\"},\n            }\n        )\n        assert resp.get(\"result\")\n        assert resp[\"result\"][\"value\"] == \"newmodel\"\n        assert seen[\"called\"]\n    finally:\n        server._sessions.pop(\"sid\", None)\n\n\ndef test_mirror_slash_side_effects_rejects_mutating_commands_while_running(monkeypatch):\n    \"\"\"Slash worker passthrough (e.g. /model, /personality, /prompt,\n    /compress) must reject during an in-flight turn.  Same race as\n    config.set — mutates live agent state while run_conversation is\n    reading it.\"\"\"\n    import types\n\n    applied = {\"model\": False, \"compress\": False}\n\n    def _fake_apply_model(sid, session, arg):\n        applied[\"model\"] = True\n        return {\"value\": arg, \"warning\": \"\"}\n\n    def _fake_compress(session, focus):\n        applied[\"compress\"] = True\n        return (0, {})\n\n    monkeypatch.setattr(server, \"_apply_model_switch\", _fake_apply_model)\n    monkeypatch.setattr(server, \"_compress_session_history\", _fake_compress)\n\n    session = _session(running=True)\n    session[\"agent\"] = types.SimpleNamespace(model=\"x\")\n\n    for cmd, expected_name in [\n        (\"/model new/model\", \"model\"),\n        (\"/personality default\", \"personality\"),\n        (\"/prompt\", \"prompt\"),\n        (\"/compress\", \"compress\"),\n    ]:\n        warning = server._mirror_slash_side_effects(\"sid\", session, cmd)\n        assert (\n            \"session busy\" in warning\n        ), f\"{cmd} should have returned busy warning, got: {warning!r}\"\n        assert f\"/{expected_name}\" in warning\n\n    # None of the mutating side-effect helpers should have fired.\n    assert not applied[\"model\"], \"model switch fired despite running session\"\n    assert not applied[\"compress\"], \"compress fired despite running session\"\n\n\ndef test_mirror_slash_side_effects_allowed_when_idle(monkeypatch):\n    \"\"\"Regression guard: idle session still runs the side effects.\"\"\"\n    import types\n\n    applied = {\"model\": False}\n\n    def _fake_apply_model(sid, session, arg):\n        applied[\"model\"] = True\n        return {\"value\": arg, \"warning\": \"\"}\n\n    monkeypatch.setattr(server, \"_apply_model_switch\", _fake_apply_model)\n\n    session = _session(running=False)\n    session[\"agent\"] = types.SimpleNamespace(model=\"x\")\n\n    warning = server._mirror_slash_side_effects(\"sid\", session, \"/model foo\")\n    # Should NOT contain \"session busy\" — the switch went through.\n    assert \"session busy\" not in warning\n    assert applied[\"model\"]\n\n\ndef test_mirror_slash_compress_does_not_prelock_history(monkeypatch):\n    \"\"\"Regression guard: /compress side effect must not hold history_lock\n    when calling _compress_session_history (the helper snapshots under\n    the same non-reentrant lock internally).\"\"\"\n    import types\n\n    seen = {\"compress\": False, \"sync\": False}\n    emitted = []\n\n    def _fake_compress(session, focus_topic=None, **_kw):\n        seen[\"compress\"] = True\n        assert not session[\"history_lock\"].locked()\n        return (0, {\"total\": 0})\n\n    def _fake_sync(_sid, _session):\n        seen[\"sync\"] = True\n\n    monkeypatch.setattr(server, \"_compress_session_history\", _fake_compress)\n    monkeypatch.setattr(server, \"_sync_session_key_after_compress\", _fake_sync)\n    monkeypatch.setattr(server, \"_session_info\", lambda _agent: {\"model\": \"x\"})\n    monkeypatch.setattr(server, \"_emit\", lambda *args: emitted.append(args))\n\n    session = _session(running=False)\n    session[\"agent\"] = types.SimpleNamespace(model=\"x\")\n\n    warning = server._mirror_slash_side_effects(\"sid\", session, \"/compress\")\n\n    assert warning == \"\"\n    assert seen[\"compress\"]\n    assert seen[\"sync\"]\n    assert (\"session.info\", \"sid\", {\"model\": \"x\"}) in emitted\n\n\n# ---------------------------------------------------------------------------\n# session.create / session.close race: fast /new churn must not orphan the\n# slash_worker subprocess or the global approval-notify registration.\n# ---------------------------------------------------------------------------\n\n\ndef test_session_create_close_race_does_not_orphan_worker(monkeypatch):\n    \"\"\"Regression guard: if session.close runs while session.create's\n    _build thread is still constructing the agent, the build thread\n    must detect the orphan and clean up the slash_worker + notify\n    registration it's about to install.  Without the cleanup those\n    resources leak — the subprocess stays alive until atexit and the\n    notify callback lingers in the global registry.\"\"\"\n    import threading\n\n    closed_workers: list[str] = []\n    unregistered_keys: list[str] = []\n\n    class _FakeWorker:\n        def __init__(self, key, model):\n            self.key = key\n            self._closed = False\n\n        def close(self):\n            self._closed = True\n            closed_workers.append(self.key)\n\n    class _FakeAgent:\n        def __init__(self):\n            self.model = \"x\"\n            self.provider = \"openrouter\"\n            self.base_url = \"\"\n            self.api_key = \"\"\n\n    # Make _build block until we release it — simulates slow agent init.\n    # Also signal when _build actually reaches _make_agent so the test\n    # can close the session at the right moment: session.create now\n    # defers _start_agent_build behind a 50ms timer (see the\n    # `_deferred_build` path in @method(\"session.create\")), so closing\n    # before the build thread has even started would skip the orphan\n    # detection entirely and the test would race a non-event.\n    build_started = threading.Event()\n    release_build = threading.Event()\n    build_entered = threading.Event()\n\n    def _slow_make_agent(sid, key, session_id=None):\n        build_started.set()\n        build_entered.set()\n        release_build.wait(timeout=3.0)\n        return _FakeAgent()\n\n    # Stub everything _build touches\n    monkeypatch.setattr(server, \"_make_agent\", _slow_make_agent)\n    monkeypatch.setattr(server, \"_SlashWorker\", _FakeWorker)\n    monkeypatch.setattr(\n        server,\n        \"_get_db\",\n        lambda: types.SimpleNamespace(create_session=lambda *a, **kw: None),\n    )\n    monkeypatch.setattr(server, \"_session_info\", lambda _a: {\"model\": \"x\"})\n    monkeypatch.setattr(server, \"_probe_credentials\", lambda _a: None)\n    monkeypatch.setattr(server, \"_wire_callbacks\", lambda _sid: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: None)\n\n    # Shim register/unregister to observe leaks\n    import tools.approval as _approval\n\n    monkeypatch.setattr(_approval, \"register_gateway_notify\", lambda key, cb: None)\n    monkeypatch.setattr(\n        _approval,\n        \"unregister_gateway_notify\",\n        lambda key: unregistered_keys.append(key),\n    )\n    monkeypatch.setattr(_approval, \"load_permanent_allowlist\", lambda: None)\n\n    # Start: session.create spawns _build thread, returns synchrosoamly\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"session.create\",\n            \"params\": {\"cols\": 80},\n        }\n    )\n    assert resp.get(\"result\"), f\"got error: {resp.get('error')}\"\n    sid = resp[\"result\"][\"session_id\"]\n    assert build_entered.wait(timeout=1.0), \"deferred build did not start\"\n\n    # Wait until the (deferred) build thread has actually entered\n    # _make_agent — otherwise session.close pops _sessions[sid] before\n    # _build ever runs, _start_agent_build never calls _build, and we\n    # never exercise the orphan-cleanup path.\n    assert build_started.wait(timeout=2.0), \"build thread never entered _make_agent\"\n\n    # Build thread is blocked in _slow_make_agent.  Close the session\n    # NOW — this pops _sessions[sid] before _build can install the\n    # worker/notify.\n    close_resp = server.handle_request(\n        {\n            \"id\": \"2\",\n            \"method\": \"session.close\",\n            \"params\": {\"session_id\": sid},\n        }\n    )\n    assert close_resp.get(\"result\", {}).get(\"closed\") is True\n\n    # At this point session.close saw slash_worker=None (not yet\n    # installed) so it didn't close anything.  Release the build thread\n    # and let it finish — it should detect the orphan and clean up the\n    # worker it just allocated + unregister the notify.\n    release_build.set()\n\n    # Give the build thread a moment to run through its finally.\n    for _ in range(100):\n        if closed_workers:\n            break\n        import time\n\n        time.sleep(0.02)\n\n    assert (\n        len(closed_workers) == 1\n    ), f\"orphan worker was not cleaned up — closed_workers={closed_workers}\"\n    # Notify may be unregistered by both session.close (unconditional)\n    # and the orphan-cleanup path; the key guarantee is that the build\n    # thread does at least one unregister call (any prior close\n    # already popped the callback; the duplicate is a no-op).\n    assert len(unregistered_keys) >= 1, (\n        f\"orphan notify registration was not unregistered — \"\n        f\"unregistered_keys={unregistered_keys}\"\n    )\n\n\ndef test_session_create_no_race_keeps_worker_alive(monkeypatch):\n    \"\"\"Regression guard: when session.close does NOT race, the build\n    thread must install the worker + notify normally and leave them\n    alone (no over-eager cleanup).\"\"\"\n    closed_workers: list[str] = []\n    unregistered_keys: list[str] = []\n\n    class _FakeWorker:\n        def __init__(self, key, model):\n            self.key = key\n\n        def close(self):\n            closed_workers.append(self.key)\n\n    class _FakeAgent:\n        def __init__(self):\n            self.model = \"x\"\n            self.provider = \"openrouter\"\n            self.base_url = \"\"\n            self.api_key = \"\"\n\n    monkeypatch.setattr(server, \"_make_agent\", lambda sid, key: _FakeAgent())\n    monkeypatch.setattr(server, \"_SlashWorker\", _FakeWorker)\n    monkeypatch.setattr(\n        server,\n        \"_get_db\",\n        lambda: types.SimpleNamespace(create_session=lambda *a, **kw: None),\n    )\n    monkeypatch.setattr(server, \"_session_info\", lambda _a: {\"model\": \"x\"})\n    monkeypatch.setattr(server, \"_probe_credentials\", lambda _a: None)\n    monkeypatch.setattr(server, \"_wire_callbacks\", lambda _sid: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: None)\n\n    import tools.approval as _approval\n\n    monkeypatch.setattr(_approval, \"register_gateway_notify\", lambda key, cb: None)\n    monkeypatch.setattr(\n        _approval,\n        \"unregister_gateway_notify\",\n        lambda key: unregistered_keys.append(key),\n    )\n    monkeypatch.setattr(_approval, \"load_permanent_allowlist\", lambda: None)\n\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"session.create\",\n            \"params\": {\"cols\": 80},\n        }\n    )\n    sid = resp[\"result\"][\"session_id\"]\n\n    # Wait for the build to finish (ready event inside session dict).\n    session = server._sessions[sid]\n    session[\"agent_ready\"].wait(timeout=2.0)\n\n    # Build finished without a close race — nothing should have been\n    # cleaned up by the orphan check.\n    assert (\n        closed_workers == []\n    ), f\"build thread closed its own worker despite no race: {closed_workers}\"\n    assert (\n        unregistered_keys == []\n    ), f\"build thread unregistered its own notify despite no race: {unregistered_keys}\"\n\n    # Session should have the live worker installed.\n    assert session.get(\"slash_worker\") is not None\n\n    # Cleanup\n    server._sessions.pop(sid, None)\n\n\ndef test_get_db_degrades_cleanly_when_sessiondb_init_fails(monkeypatch):\n    fake_mod = types.ModuleType(\"clawbot_state\")\n\n    class _BrokenSessionDB:\n        def __init__(self):\n            raise RuntimeError(\"locking protocol\")\n\n    fake_mod.SessionDB = _BrokenSessionDB\n    monkeypatch.setitem(sys.modules, \"clawbot_state\", fake_mod)\n    monkeypatch.setattr(server, \"_db\", None)\n    monkeypatch.setattr(server, \"_db_error\", None)\n\n    assert server._get_db() is None\n    assert server._db_error == \"locking protocol\"\n\n\ndef test_session_create_continues_when_state_db_is_unavailable(monkeypatch):\n    class _FakeWorker:\n        def __init__(self, key, model):\n            self.key = key\n\n        def close(self):\n            return None\n\n    class _FakeAgent:\n        def __init__(self):\n            self.model = \"x\"\n            self.provider = \"openrouter\"\n            self.base_url = \"\"\n            self.api_key = \"\"\n\n    emits = []\n\n    monkeypatch.setattr(server, \"_make_agent\", lambda sid, key: _FakeAgent())\n    monkeypatch.setattr(server, \"_SlashWorker\", _FakeWorker)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n    monkeypatch.setattr(server, \"_session_info\", lambda _a: {\"model\": \"x\"})\n    monkeypatch.setattr(server, \"_probe_credentials\", lambda _a: None)\n    monkeypatch.setattr(server, \"_wire_callbacks\", lambda _sid: None)\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: emits.append(a))\n\n    import tools.approval as _approval\n\n    monkeypatch.setattr(_approval, \"register_gateway_notify\", lambda key, cb: None)\n    monkeypatch.setattr(_approval, \"load_permanent_allowlist\", lambda: None)\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.create\", \"params\": {\"cols\": 80}}\n    )\n    sid = resp[\"result\"][\"session_id\"]\n    session = server._sessions[sid]\n    session[\"agent_ready\"].wait(timeout=2.0)\n\n    assert session[\"agent_error\"] is None\n    assert session[\"agent\"] is not None\n    assert not any(args and args[0] == \"error\" for args in emits)\n\n    server._sessions.pop(sid, None)\n\n\ndef test_session_list_returns_clean_error_when_state_db_is_unavailable(monkeypatch):\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n    monkeypatch.setattr(server, \"_db_error\", \"locking protocol\")\n\n    resp = server.handle_request({\"id\": \"1\", \"method\": \"session.list\", \"params\": {}})\n\n    assert \"error\" in resp\n    assert \"state.db unavailable: locking protocol\" in resp[\"error\"][\"message\"]\n\n\n# --------------------------------------------------------------------------\n# session.delete — TUI resume picker `d` key\n# --------------------------------------------------------------------------\n\n\ndef test_session_delete_requires_session_id(monkeypatch):\n    \"\"\"Empty / missing session_id is a 4006 client error (no DB call).\"\"\"\n    called: list[tuple] = []\n\n    class _DB:\n        def delete_session(self, *a, **kw):\n            called.append((a, kw))\n            return True\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n\n    resp = server.handle_request({\"id\": \"1\", \"method\": \"session.delete\", \"params\": {}})\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 4006\n    assert called == []\n\n\ndef test_session_delete_returns_db_unavailable_when_no_db(monkeypatch):\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n    monkeypatch.setattr(server, \"_db_error\", \"locked\")\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.delete\", \"params\": {\"session_id\": \"abc\"}}\n    )\n\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 5036\n    assert \"state.db unavailable\" in resp[\"error\"][\"message\"]\n\n\ndef test_session_delete_refuses_active_session(monkeypatch):\n    \"\"\"Cannot delete a session currently bound to a live TUI session.\"\"\"\n    called: list[str] = []\n\n    class _DB:\n        def delete_session(self, sid, sessions_dir=None):\n            called.append(sid)\n            return True\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n    monkeypatch.setitem(server._sessions, \"live\", {\"session_key\": \"key-live\"})\n    try:\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"session.delete\",\n                \"params\": {\"session_id\": \"key-live\"},\n            }\n        )\n    finally:\n        server._sessions.pop(\"live\", None)\n\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 4023\n    assert \"active session\" in resp[\"error\"][\"message\"]\n    assert called == [], \"delete_session must not be called for active sessions\"\n\n\ndef test_session_delete_fails_closed_when_active_snapshot_raises(monkeypatch):\n    \"\"\"Concurrent ``_sessions`` mutation from another RPC thread can raise\n    ``RuntimeError: dictionary changed size during iteration``.  When the\n    handler can't enumerate active sessions safely it must refuse the\n    delete (fail closed) rather than fall through and allow it.\"\"\"\n\n    class _DB:\n        def delete_session(self, *a, **kw):\n            raise AssertionError(\"delete must not run when active snapshot fails\")\n\n    class _ExplodingDict:\n        def values(self):\n            raise RuntimeError(\"dictionary changed size during iteration\")\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n    monkeypatch.setattr(server, \"_sessions\", _ExplodingDict())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.delete\", \"params\": {\"session_id\": \"x\"}}\n    )\n\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 5036\n    assert \"enumerate active sessions\" in resp[\"error\"][\"message\"]\n\n\ndef test_session_delete_returns_4007_when_missing(monkeypatch):\n    class _DB:\n        def delete_session(self, sid, sessions_dir=None):\n            return False\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.delete\", \"params\": {\"session_id\": \"ghost\"}}\n    )\n\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 4007\n\n\ndef test_session_delete_propagates_db_exception(monkeypatch):\n    class _DB:\n        def delete_session(self, sid, sessions_dir=None):\n            raise RuntimeError(\"disk full\")\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.delete\", \"params\": {\"session_id\": \"x\"}}\n    )\n\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 5036\n    assert \"disk full\" in resp[\"error\"][\"message\"]\n\n\ndef test_session_delete_success_returns_deleted_id(monkeypatch):\n    \"\"\"Happy path — DB delete succeeds, response carries the deleted id\n    and the on-disk sessions dir is forwarded so transcript files get\n    cleaned up alongside the row.\"\"\"\n    captured: dict = {}\n\n    class _DB:\n        def delete_session(self, sid, sessions_dir=None):\n            captured[\"sid\"] = sid\n            captured[\"sessions_dir\"] = sessions_dir\n            return True\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.delete\", \"params\": {\"session_id\": \"old-1\"}}\n    )\n\n    assert \"result\" in resp, resp\n    assert resp[\"result\"] == {\"deleted\": \"old-1\"}\n    assert captured[\"sid\"] == \"old-1\"\n    # sessions_dir must be forwarded so transcript files get cleaned up\n    # too — not just the SQLite row.  The autouse _isolate_clawbot_home\n    # fixture pins CLAWBOT_HOME to a temp dir; the handler should append\n    # /sessions to it.\n    assert captured[\"sessions_dir\"] is not None\n    assert str(captured[\"sessions_dir\"]).endswith(\"sessions\")\n\n\n# --------------------------------------------------------------------------\n# model.options — curated-list parity with `clawbot model` and classic /model\n# --------------------------------------------------------------------------\n\n\ndef test_model_options_does_not_overwrite_curated_models(monkeypatch):\n    \"\"\"The TUI model.options handler must surface the same curated model\n    list as `clawbot model` and the classic CLI /model picker.\n\n    Regression: earlier versions of this handler unconditionally replaced\n    each provider's curated ``models`` field with ``provider_model_ids()``\n    (live /models catalog).  That pulled in hundreds of non-agentic models\n    for providers like Soam whose /models endpoint returns image/video\n    generators, rerankers, embeddings, and TTS models alongside chat models.\n    \"\"\"\n    curated_providers = [\n        {\n            \"slug\": \"soam\",\n            \"name\": \"Soam\",\n            \"models\": [\"moonshotai/kimi-k2.5\", \"anthropic/claude-opus-4.7\"],\n            \"total_models\": 30,\n            \"source\": \"built-in\",\n            \"is_current\": False,\n            \"is_user_defined\": False,\n        },\n    ]\n\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"providers\": {}, \"custom_providers\": []},\n    )\n\n    with patch(\n        \"clawbot_cli.model_switch.list_authenticated_providers\",\n        return_value=curated_providers,\n    ) as listing:\n        # If provider_model_ids gets called at all, the handler is still\n        # overwriting curated with live — that's the regression we're\n        # guarding against.\n        with patch(\"clawbot_cli.models.provider_model_ids\") as live_fetch:\n            resp = server._methods[\"model.options\"](99, {\"session_id\": \"\"})\n\n    assert \"result\" in resp, resp\n    providers = resp[\"result\"][\"providers\"]\n    soam = next((p for p in providers if p.get(\"slug\") == \"soam\"), None)\n    assert soam is not None\n    assert soam[\"models\"] == [\n        \"moonshotai/kimi-k2.5\",\n        \"anthropic/claude-opus-4.7\",\n    ]\n    assert soam[\"total_models\"] == 30\n    # Handler must not consult the live catalog — curated is the truth.\n    live_fetch.assert_not_called()\n    # list_authenticated_providers is the single source.\n    assert listing.call_count == 1\n\n\ndef test_model_options_propagates_list_exception(monkeypatch):\n    \"\"\"If list_authenticated_providers itself raises, surface as an RPC\n    error rather than swallowing to a blank picker.\"\"\"\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"providers\": {}, \"custom_providers\": []},\n    )\n    with patch(\n        \"clawbot_cli.model_switch.list_authenticated_providers\",\n        side_effect=RuntimeError(\"catalog blew up\"),\n    ):\n        resp = server._methods[\"model.options\"](77, {\"session_id\": \"\"})\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 5033\n    assert \"catalog blew up\" in resp[\"error\"][\"message\"]\n\n\n# ---------------------------------------------------------------------------\n# prompt.submit — auto-title\n# ---------------------------------------------------------------------------\n\n\nclass _ImmediateThread:\n    \"\"\"Runs the target callable synchrosoamly so assertions can follow.\"\"\"\n\n    def __init__(self, target=None, daemon=None):\n        self._target = target\n\n    def start(self):\n        self._target()\n\n\ndef test_prompt_submit_auto_titles_session_on_complete(monkeypatch):\n    \"\"\"maybe_auto_title is called after a successful (complete) prompt.\"\"\"\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            return {\n                \"final_response\": \"Rome was founded in 753 BC.\",\n                \"messages\": [\n                    {\"role\": \"user\", \"content\": \"Tell me about Rome\"},\n                    {\"role\": \"assistant\", \"content\": \"Rome was founded in 753 BC.\"},\n                ],\n            }\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n\n    with patch(\"agent.title_generator.maybe_auto_title\") as mock_title:\n        server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"prompt.submit\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"Tell me about Rome\"},\n            }\n        )\n\n    mock_title.assert_called_once()\n    args = mock_title.call_args.args\n    assert args[1] == \"session-key\"\n    assert args[2] == \"Tell me about Rome\"\n    assert args[3] == \"Rome was founded in 753 BC.\"\n\n\ndef test_prompt_submit_skips_auto_title_when_interrupted(monkeypatch):\n    \"\"\"maybe_auto_title must NOT be called when the agent was interrupted.\"\"\"\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            return {\n                \"final_response\": \"partial answer\",\n                \"interrupted\": True,\n                \"messages\": [],\n            }\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n\n    with patch(\"agent.title_generator.maybe_auto_title\") as mock_title:\n        server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"prompt.submit\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"Tell me about Rome\"},\n            }\n        )\n\n    mock_title.assert_not_called()\n\n\ndef test_prompt_submit_skips_auto_title_when_response_empty(monkeypatch):\n    \"\"\"maybe_auto_title must NOT be called when the agent returns an empty reply.\"\"\"\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            return {\n                \"final_response\": \"\",\n                \"messages\": [],\n            }\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *args, **kwargs: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n\n    with patch(\"agent.title_generator.maybe_auto_title\") as mock_title:\n        server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"prompt.submit\",\n                \"params\": {\"session_id\": \"sid\", \"text\": \"Tell me about Rome\"},\n            }\n        )\n\n    mock_title.assert_not_called()\n\n\ndef test_prompt_submit_surfaces_backend_error_as_visible_text(monkeypatch):\n    \"\"\"When the backend fails with no visible response (e.g. invalid model slug\n    → provider 4xx), the TUI must surface result['error'] as visible text\n    instead of emitting a blank message.complete turn.\"\"\"\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            return {\n                \"final_response\": None,\n                \"messages\": [],\n                \"api_calls\": 0,\n                \"completed\": False,\n                \"failed\": True,\n                \"error\": \"HTTP 400: invalid model id 'kimi-k2.6'\",\n            }\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n\n    emitted: list[tuple[str, str, dict]] = []\n    monkeypatch.setattr(\n        server,\n        \"_emit\",\n        lambda event, sid, payload=None: emitted.append((event, sid, payload or {})),\n    )\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n\n    server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"prompt.submit\",\n            \"params\": {\"session_id\": \"sid\", \"text\": \"hello\"},\n        }\n    )\n\n    complete_events = [e for e in emitted if e[0] == \"message.complete\"]\n    assert complete_events, \"expected message.complete to be emitted\"\n    payload = complete_events[-1][2]\n    assert payload.get(\"status\") == \"error\"\n    assert payload.get(\"text\", \"\").startswith(\"Error:\")\n    assert \"kimi-k2.6\" in payload.get(\"text\", \"\")\n\n\ndef test_prompt_submit_preserves_empty_response_without_error(monkeypatch):\n    \"\"\"An empty final_response with NO backend error must stay empty — do not\n    synthesize an error string. Preserves the existing None/empty-sentinel\n    semantics owned by downstream handlers.\"\"\"\n\n    class _Agent:\n        def run_conversation(\n            self, prompt, conversation_history=None, stream_callback=None\n        ):\n            return {\n                \"final_response\": None,\n                \"messages\": [],\n                \"api_calls\": 1,\n                \"completed\": True,\n            }\n\n    server._sessions[\"sid\"] = _session(agent=_Agent())\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n\n    emitted: list[tuple[str, str, dict]] = []\n    monkeypatch.setattr(\n        server,\n        \"_emit\",\n        lambda event, sid, payload=None: emitted.append((event, sid, payload or {})),\n    )\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n\n    server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"prompt.submit\",\n            \"params\": {\"session_id\": \"sid\", \"text\": \"hello\"},\n        }\n    )\n\n    complete_events = [e for e in emitted if e[0] == \"message.complete\"]\n    assert complete_events, \"expected message.complete to be emitted\"\n    payload = complete_events[-1][2]\n    # Status stays \"complete\" because no error flag was set\n    assert payload.get(\"status\") == \"complete\"\n    # Text stays empty — we did NOT fabricate an \"Error:\" string\n    text = payload.get(\"text\", \"\")\n    assert text in {\"\", None}, f\"expected empty text, got {text!r}\"\n\n\n# ── session.most_recent ──────────────────────────────────────────────\n\n\ndef test_session_most_recent_returns_first_non_denied(monkeypatch):\n    \"\"\"Drops `tool` rows like session.list does, returns the first hit.\"\"\"\n\n    class _DB:\n        def list_sessions_rich(self, *, source=None, limit=200):\n            return [\n                {\"id\": \"tool-1\", \"source\": \"tool\", \"title\": \"noise\", \"started_at\": 100},\n                {\"id\": \"tui-1\", \"source\": \"tui\", \"title\": \"real\", \"started_at\": 99},\n            ]\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.most_recent\", \"params\": {}}\n    )\n\n    assert resp[\"result\"][\"session_id\"] == \"tui-1\"\n    assert resp[\"result\"][\"title\"] == \"real\"\n    assert resp[\"result\"][\"source\"] == \"tui\"\n\n\ndef test_session_most_recent_returns_null_when_only_tool_rows(monkeypatch):\n    class _DB:\n        def list_sessions_rich(self, *, source=None, limit=200):\n            return [{\"id\": \"tool-1\", \"source\": \"tool\", \"started_at\": 1}]\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _DB())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.most_recent\", \"params\": {}}\n    )\n\n    assert resp[\"result\"][\"session_id\"] is None\n\n\ndef test_session_most_recent_folds_db_exception_into_null_result(monkeypatch):\n    \"\"\"Per contract, errors are folded into the null-result shape so\n    callers don't have to special-case JSON-RPC error envelopes for\n    'no answer' (Copilot review on #17130).\"\"\"\n\n    class _BrokenDB:\n        def list_sessions_rich(self, *, source=None, limit=200):\n            raise RuntimeError(\"db locked\")\n\n    monkeypatch.setattr(server, \"_get_db\", lambda: _BrokenDB())\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.most_recent\", \"params\": {}}\n    )\n\n    assert \"error\" not in resp\n    assert resp[\"result\"][\"session_id\"] is None\n\n\ndef test_session_most_recent_handles_db_unavailable(monkeypatch):\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"session.most_recent\", \"params\": {}}\n    )\n\n    assert resp[\"result\"][\"session_id\"] is None\n\n\n# ── browser.manage ───────────────────────────────────────────────────\n\n\ndef _stub_urlopen(monkeypatch, *, ok: bool):\n    \"\"\"Patch urllib.request.urlopen used by browser.manage to short-circuit probes.\"\"\"\n\n    class _Resp:\n        status = 200 if ok else 503\n\n        def __enter__(self):\n            return self\n\n        def __exit__(self, *_):\n            return False\n\n    def _opener(_url, timeout=2.0):  # noqa: ARG001 — match urllib signature\n        if not ok:\n            raise OSError(\"probe failed\")\n        return _Resp()\n\n    import urllib.request\n\n    monkeypatch.setattr(urllib.request, \"urlopen\", _opener)\n\n\ndef _stub_urlopen_capture(monkeypatch, *, ok: bool):\n    urls: list[str] = []\n\n    class _Resp:\n        status = 200\n\n        def __enter__(self):\n            return self\n\n        def __exit__(self, *_):\n            return False\n\n    def _opener(url, timeout=2.0):  # noqa: ARG001 — match urllib signature\n        urls.append(url)\n        if not ok:\n            raise OSError(\"probe failed\")\n        return _Resp()\n\n    import urllib.request\n\n    monkeypatch.setattr(urllib.request, \"urlopen\", _opener)\n    return urls\n\n\ndef test_browser_manage_status_reads_env_var(monkeypatch):\n    \"\"\"Status returns the env var verbatim (no network I/O).\"\"\"\n    monkeypatch.setenv(\"BROWSER_CDP_URL\", \"http://127.0.0.1:9222\")\n\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"browser.manage\", \"params\": {\"action\": \"status\"}}\n    )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n\n\ndef test_browser_manage_status_falls_back_to_config_cdp_url(monkeypatch):\n    \"\"\"When env is unset, status surfaces ``browser.cdp_url`` from\n    config.yaml so users see what the next tool call will read.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n\n    fake_cfg = types.SimpleNamespace(\n        read_raw_config=lambda: {\"browser\": {\"cdp_url\": \"http://lan:9222\"}}\n    )\n    with patch.dict(sys.modules, {\"clawbot_cli.config\": fake_cfg}):\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"browser.manage\", \"params\": {\"action\": \"status\"}}\n        )\n\n    assert resp[\"result\"] == {\"connected\": True, \"url\": \"http://lan:9222\"}\n\n\ndef test_browser_manage_status_does_not_call_get_cdp_override(monkeypatch):\n    \"\"\"Regression guard for Copilot's \"status must not block\" review:\n    status must NOT route through `_get_cdp_override`, which performs a\n    `/json/version` HTTP probe with a multi-second timeout.\"\"\"\n    monkeypatch.setenv(\"BROWSER_CDP_URL\", \"http://127.0.0.1:9222\")\n\n    fake = types.SimpleNamespace(\n        _get_cdp_override=lambda: pytest.fail(  # noqa: PT015 — fail loudly if called\n            \"_get_cdp_override must not run on /browser status (network I/O)\"\n        )\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"browser.manage\", \"params\": {\"action\": \"status\"}}\n        )\n\n    assert resp[\"result\"][\"connected\"] is True\n\n\ndef test_browser_manage_connect_sets_env_and_cleans_twice(monkeypatch):\n    \"\"\"`/browser connect` must reach the live process: set env, reap browser\n    sessions before AND after publishing the new URL.  The double-cleanup\n    closes the supervisor swap window where ``_ensure_cdp_supervisor``\n    could re-attach to the *old* CDP endpoint between steps.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    cleanup_calls: list[str] = []\n\n    def _cleanup_all():\n        cleanup_calls.append(os.environ.get(\"BROWSER_CDP_URL\", \"\"))\n\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=_cleanup_all,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=True)\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"browser.manage\",\n                \"params\": {\"action\": \"connect\", \"url\": \"http://127.0.0.1:9222\"},\n            }\n        )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n    assert resp[\"result\"][\"messages\"] == [\"Chrome is already listening on port 9222\"]\n    assert os.environ.get(\"BROWSER_CDP_URL\") == \"http://127.0.0.1:9222\"\n    # First cleanup runs against the OLD env (none here), second against the NEW.\n    assert cleanup_calls == [\"\", \"http://127.0.0.1:9222\"]\n\n\ndef test_browser_manage_connect_defaults_to_loopback(monkeypatch):\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        urls = _stub_urlopen_capture(monkeypatch, ok=True)\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"browser.manage\", \"params\": {\"action\": \"connect\"}}\n        )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n    assert resp[\"result\"][\"messages\"] == [\"Chrome is already listening on port 9222\"]\n    assert urls[0] == \"http://127.0.0.1:9222/json/version\"\n\n\ndef test_browser_manage_connect_default_local_reports_launch_hint(monkeypatch):\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    emitted: list[tuple[str, dict]] = []\n    monkeypatch.setattr(\n        server,\n        \"_emit\",\n        lambda evt, sid, payload=None: emitted.append((evt, payload or {})),\n    )\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=False)\n        with (\n            patch(\n                \"clawbot_cli.browser_connect.try_launch_chrome_debug\", return_value=False\n            ),\n            patch(\n                \"clawbot_cli.browser_connect.get_chrome_debug_candidates\",\n                return_value=[],\n            ),\n        ):\n            resp = server.handle_request(\n                {\n                    \"id\": \"1\",\n                    \"method\": \"browser.manage\",\n                    \"params\": {\n                        \"action\": \"connect\",\n                        \"session_id\": \"sess-1\",\n                        \"url\": \"http://localhost:9222\",\n                    },\n                }\n            )\n\n    assert resp[\"result\"][\"connected\"] is False\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n    assert (\n        resp[\"result\"][\"messages\"][0]\n        == \"Chrome isn't running with remote debugging — attempting to launch...\"\n    )\n    assert any(\n        \"No Chrome/Chromium executable was found\" in line\n        for line in resp[\"result\"][\"messages\"]\n    )\n    assert any(\n        \"--remote-debugging-port=9222\" in line for line in resp[\"result\"][\"messages\"]\n    )\n    assert \"BROWSER_CDP_URL\" not in os.environ\n    progress = [p[\"message\"] for evt, p in emitted if evt == \"browser.progress\"]\n    assert progress == resp[\"result\"][\"messages\"]\n\n\ndef test_browser_manage_connect_no_session_skips_progress_events(monkeypatch):\n    \"\"\"Without a session_id the TUI prints messages from the response;\n    emitting ``browser.progress`` events would double-render. Gate the\n    emit so callers without a session see the bundled list only.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    emitted: list[tuple[str, dict]] = []\n    monkeypatch.setattr(\n        server,\n        \"_emit\",\n        lambda evt, sid, payload=None: emitted.append((evt, payload or {})),\n    )\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=False)\n        with (\n            patch(\n                \"clawbot_cli.browser_connect.try_launch_chrome_debug\", return_value=False\n            ),\n            patch(\n                \"clawbot_cli.browser_connect.get_chrome_debug_candidates\",\n                return_value=[],\n            ),\n        ):\n            resp = server.handle_request(\n                {\n                    \"id\": \"1\",\n                    \"method\": \"browser.manage\",\n                    \"params\": {\"action\": \"connect\", \"url\": \"http://localhost:9222\"},\n                }\n            )\n\n    assert resp[\"result\"][\"connected\"] is False\n    assert resp[\"result\"][\"messages\"]  # bundled list still populated\n    assert [evt for evt, _ in emitted if evt == \"browser.progress\"] == []\n\n\ndef test_browser_manage_connect_handles_null_url(monkeypatch):\n    \"\"\"Explicit ``{\"url\": null}`` (or empty string) must fall back to the\n    default loopback URL instead of raising a TypeError that gets swallowed\n    by the outer 5031 catch.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=True)\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"browser.manage\",\n                \"params\": {\"action\": \"connect\", \"url\": None},\n            }\n        )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n\n\ndef test_browser_manage_connect_rejects_non_string_url(monkeypatch):\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"browser.manage\",\n            \"params\": {\"action\": \"connect\", \"url\": 9222},\n        }\n    )\n\n    assert resp[\"error\"][\"code\"] == 4015\n    assert \"must be a string\" in resp[\"error\"][\"message\"]\n    assert \"BROWSER_CDP_URL\" not in os.environ\n\n\ndef test_browser_manage_connect_default_local_retries_after_launch(monkeypatch):\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    monkeypatch.setattr(server.time, \"sleep\", lambda _seconds: None)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n\n    class _Resp:\n        status = 200\n\n        def __enter__(self):\n            return self\n\n        def __exit__(self, *_):\n            return False\n\n    attempts = {\"n\": 0}\n\n    def _opener(_url, timeout=2.0):  # noqa: ARG001 — match urllib signature\n        attempts[\"n\"] += 1\n        if attempts[\"n\"] < 3:\n            raise OSError(\"not ready\")\n        return _Resp()\n\n    import urllib.request\n\n    monkeypatch.setattr(urllib.request, \"urlopen\", _opener)\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        with patch(\n            \"clawbot_cli.browser_connect.try_launch_chrome_debug\", return_value=True\n        ):\n            resp = server.handle_request(\n                {\"id\": \"1\", \"method\": \"browser.manage\", \"params\": {\"action\": \"connect\"}}\n            )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n    assert resp[\"result\"][\"messages\"] == [\n        \"Chrome isn't running with remote debugging — attempting to launch...\",\n        \"Chrome launched and listening on port 9222\",\n    ]\n    assert os.environ[\"BROWSER_CDP_URL\"] == \"http://127.0.0.1:9222\"\n\n\ndef test_browser_manage_connect_rejects_unreachable_endpoint(monkeypatch):\n    \"\"\"An unreachable endpoint must NOT mutate the env or reap sessions.\"\"\"\n    monkeypatch.setenv(\"BROWSER_CDP_URL\", \"http://existing:9222\")\n    cleanup_calls: list[str] = []\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: cleanup_calls.append(\n            os.environ.get(\"BROWSER_CDP_URL\", \"\")\n        ),\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=False)\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"browser.manage\",\n                \"params\": {\"action\": \"connect\", \"url\": \"http://unreachable:9222\"},\n            }\n        )\n\n    assert \"error\" in resp\n    # Env preserved; nothing reaped.\n    assert os.environ[\"BROWSER_CDP_URL\"] == \"http://existing:9222\"\n    assert cleanup_calls == []\n\n\ndef test_browser_manage_connect_normalizes_bare_host_port(monkeypatch):\n    \"\"\"Persist a parsed `scheme://host:port` URL so `_get_cdp_override`\n    can normalize it; storing a bare host:port would break subsequent\n    tool calls (Copilot review on #17120).\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=True)\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"browser.manage\",\n                \"params\": {\"action\": \"connect\", \"url\": \"127.0.0.1:9222\"},\n            }\n        )\n\n    assert resp[\"result\"][\"connected\"] is True\n    # Bare host:port got promoted to a full URL with explicit scheme.\n    assert resp[\"result\"][\"url\"].startswith(\"http://\")\n    assert os.environ[\"BROWSER_CDP_URL\"].startswith(\"http://\")\n\n\ndef test_browser_manage_connect_strips_discovery_path(monkeypatch):\n    \"\"\"User-supplied discovery paths like `/json` or `/json/version`\n    must collapse to bare `scheme://host:port`; otherwise\n    ``_resolve_cdp_override`` will append ``/json/version`` again and\n    produce a duplicate path (Copilot review round-2 on #17120).\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        _stub_urlopen(monkeypatch, ok=True)\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"browser.manage\",\n                \"params\": {\"action\": \"connect\", \"url\": \"http://127.0.0.1:9222/json\"},\n            }\n        )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == \"http://127.0.0.1:9222\"\n    assert os.environ[\"BROWSER_CDP_URL\"] == \"http://127.0.0.1:9222\"\n\n\ndef test_browser_manage_connect_preserves_devtools_browser_endpoint(monkeypatch):\n    \"\"\"Concrete devtools websocket endpoints (e.g. Browserbase) must\n    survive verbatim — we only collapse discovery-style paths.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    concrete = \"ws://browserbase.example/devtools/browser/abc123\"\n\n    class _OkSocket:\n        def __enter__(self):\n            return self\n\n        def __exit__(self, *a):\n            return False\n\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        # If urlopen is reached for a concrete ws endpoint, the test\n        # would still pass because _stub_urlopen returned ok=True before;\n        # patch it to assert-fail so we prove the HTTP probe is skipped.\n        with patch(\n            \"urllib.request.urlopen\", side_effect=AssertionError(\"urlopen called\")\n        ):\n            with patch(\"socket.create_connection\", return_value=_OkSocket()):\n                resp = server.handle_request(\n                    {\n                        \"id\": \"1\",\n                        \"method\": \"browser.manage\",\n                        \"params\": {\"action\": \"connect\", \"url\": concrete},\n                    }\n                )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == concrete\n    assert os.environ[\"BROWSER_CDP_URL\"] == concrete\n\n\ndef test_browser_manage_connect_local_devtools_ws_preserves_path(monkeypatch):\n    \"\"\"Regression: ``ws://127.0.0.1:9222/devtools/browser/<id>`` is a real\n    connectable endpoint; default-local normalization must not strip the\n    ``/devtools/browser/...`` path or it breaks valid local CDP connects.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    concrete = \"ws://127.0.0.1:9222/devtools/browser/abc123\"\n\n    class _OkSocket:\n        def __enter__(self):\n            return self\n\n        def __exit__(self, *a):\n            return False\n\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        with patch(\"socket.create_connection\", return_value=_OkSocket()):\n            resp = server.handle_request(\n                {\n                    \"id\": \"1\",\n                    \"method\": \"browser.manage\",\n                    \"params\": {\"action\": \"connect\", \"url\": concrete},\n                }\n            )\n\n    assert resp[\"result\"][\"connected\"] is True\n    assert resp[\"result\"][\"url\"] == concrete\n    assert os.environ[\"BROWSER_CDP_URL\"] == concrete\n\n\ndef test_browser_manage_connect_rejects_invalid_port(monkeypatch):\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"browser.manage\",\n            \"params\": {\"action\": \"connect\", \"url\": \"http://localhost:abc\"},\n        }\n    )\n\n    assert resp[\"error\"][\"code\"] == 4015\n    assert \"invalid port\" in resp[\"error\"][\"message\"]\n    assert \"BROWSER_CDP_URL\" not in os.environ\n\n\ndef test_browser_manage_connect_rejects_missing_host(monkeypatch):\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"browser.manage\",\n            \"params\": {\"action\": \"connect\", \"url\": \"http://:9222\"},\n        }\n    )\n\n    assert resp[\"error\"][\"code\"] == 4015\n    assert \"missing host\" in resp[\"error\"][\"message\"]\n    assert \"BROWSER_CDP_URL\" not in os.environ\n\n\ndef test_browser_manage_connect_concrete_ws_skips_http_probe(monkeypatch):\n    \"\"\"Regression for round-2 Copilot review: a hosted CDP endpoint\n    (no HTTP discovery) must connect via TCP-only reachability check.\n    The HTTP probe used to reject these even though they're valid.\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    concrete = \"wss://chrome.browserless.io/devtools/browser/sess-1\"\n\n    seen_targets: list[tuple[str, int]] = []\n\n    class _OkSocket:\n        def __enter__(self):\n            return self\n\n        def __exit__(self, *a):\n            return False\n\n    def _fake_create_connection(addr, timeout=None):\n        seen_targets.append(addr)\n        return _OkSocket()\n\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        # urlopen would 404/ECONNREFUSED on a real hosted CDP endpoint;\n        # asserting it's never called proves the probe was skipped.\n        with patch(\n            \"urllib.request.urlopen\", side_effect=AssertionError(\"urlopen called\")\n        ):\n            with patch(\"socket.create_connection\", side_effect=_fake_create_connection):\n                resp = server.handle_request(\n                    {\n                        \"id\": \"1\",\n                        \"method\": \"browser.manage\",\n                        \"params\": {\"action\": \"connect\", \"url\": concrete},\n                    }\n                )\n\n    assert resp[\"result\"] == {\"connected\": True, \"url\": concrete}\n    # wss → port 443, host preserved verbatim.\n    assert seen_targets == [(\"chrome.browserless.io\", 443)]\n\n\ndef test_browser_manage_connect_concrete_ws_tcp_unreachable(monkeypatch):\n    \"\"\"If the TCP reachability check fails for a concrete ws endpoint,\n    return a clear 5031 error — no fallback to the HTTP probe (which\n    can never succeed for these URLs anyway).\"\"\"\n    monkeypatch.delenv(\"BROWSER_CDP_URL\", raising=False)\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: None,\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    concrete = \"ws://offline.example/devtools/browser/missing\"\n\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        with patch(\"socket.create_connection\", side_effect=OSError(\"ECONNREFUSED\")):\n            resp = server.handle_request(\n                {\n                    \"id\": \"1\",\n                    \"method\": \"browser.manage\",\n                    \"params\": {\"action\": \"connect\", \"url\": concrete},\n                }\n            )\n\n    assert \"error\" in resp\n    assert resp[\"error\"][\"code\"] == 5031\n\n\ndef test_browser_manage_disconnect_drops_env_and_cleans(monkeypatch):\n    monkeypatch.setenv(\"BROWSER_CDP_URL\", \"http://127.0.0.1:9222\")\n    cleanup_count = {\"n\": 0}\n    fake = types.SimpleNamespace(\n        cleanup_all_browsers=lambda: cleanup_count.__setitem__(\n            \"n\", cleanup_count[\"n\"] + 1\n        ),\n        _get_cdp_override=lambda: os.environ.get(\"BROWSER_CDP_URL\", \"\"),\n    )\n    with patch.dict(sys.modules, {\"tools.browser_tool\": fake}):\n        resp = server.handle_request(\n            {\"id\": \"1\", \"method\": \"browser.manage\", \"params\": {\"action\": \"disconnect\"}}\n        )\n\n    assert resp[\"result\"] == {\"connected\": False}\n    assert \"BROWSER_CDP_URL\" not in os.environ\n    # Two cleanups: once before env removal, once after, matching connect.\n    assert cleanup_count[\"n\"] == 2\n\n\n# ── config.get indicator normalization ───────────────────────────────\n\n\ndef test_config_get_indicator_returns_known_value_verbatim(monkeypatch):\n    monkeypatch.setattr(\n        server, \"_load_cfg\", lambda: {\"display\": {\"tui_status_indicator\": \"emoji\"}}\n    )\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"indicator\"}}\n    )\n    assert resp[\"result\"] == {\"value\": \"emoji\"}\n\n\ndef test_config_get_indicator_normalizes_casing_and_whitespace(monkeypatch):\n    \"\"\"Hand-edited config.yaml stays consistent with what the TUI shows.\n\n    Frontend's `normalizeIndicatorStyle` lowercases + trims, so config.get\n    must do the same — otherwise `/indicator` prints 'EMOJI ' while the\n    UI is actually rendering the kaomoji default.\"\"\"\n    monkeypatch.setattr(\n        server, \"_load_cfg\", lambda: {\"display\": {\"tui_status_indicator\": \" EMOJI \"}}\n    )\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"indicator\"}}\n    )\n    assert resp[\"result\"] == {\"value\": \"emoji\"}\n\n\ndef test_config_get_indicator_falls_back_to_default_for_unknown(monkeypatch):\n    \"\"\"An unknown value in config.yaml falls back to the same default\n    the frontend uses (`_INDICATOR_DEFAULT`).\"\"\"\n    monkeypatch.setattr(\n        server, \"_load_cfg\", lambda: {\"display\": {\"tui_status_indicator\": \"rainbow\"}}\n    )\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"indicator\"}}\n    )\n    assert resp[\"result\"] == {\"value\": \"kaomoji\"}\n\n\ndef test_config_get_indicator_falls_back_when_unset(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"display\": {}})\n    resp = server.handle_request(\n        {\"id\": \"1\", \"method\": \"config.get\", \"params\": {\"key\": \"indicator\"}}\n    )\n    assert resp[\"result\"] == {\"value\": \"kaomoji\"}\n\n\n# ── config.set indicator validation ──────────────────────────────────\n\n\ndef test_config_set_indicator_accepts_known_value(monkeypatch):\n    written: dict = {}\n    monkeypatch.setattr(\n        server,\n        \"_write_config_key\",\n        lambda k, v: written.update({k: v}),\n    )\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"indicator\", \"value\": \"EMOJI\"},\n        }\n    )\n    assert resp[\"result\"] == {\"key\": \"indicator\", \"value\": \"emoji\"}\n    assert written == {\"display.tui_status_indicator\": \"emoji\"}\n\n\ndef test_config_set_indicator_falsy_non_string_surfaces_in_error(monkeypatch):\n    \"\"\"`0` / `False` / `[]` are not valid styles, but the error message\n    must still tell the user what they sent — `value or \"\"` would have\n    erased them to a blank string.\"\"\"\n    monkeypatch.setattr(server, \"_write_config_key\", lambda *a, **k: None)\n\n    for bad in (0, False, []):\n        resp = server.handle_request(\n            {\n                \"id\": \"1\",\n                \"method\": \"config.set\",\n                \"params\": {\"key\": \"indicator\", \"value\": bad},\n            }\n        )\n        assert \"error\" in resp\n        msg = resp[\"error\"][\"message\"]\n        assert \"unknown indicator\" in msg\n        # The exact repr varies; `0`/`False` stringify with content,\n        # `[]` becomes an empty list — what matters is the diagnostic\n        # is no longer just `unknown indicator: ` with nothing after.\n        assert msg.split(\"; \")[0] != \"unknown indicator: ''\"\n\n\ndef test_config_set_indicator_none_keeps_blank_repr(monkeypatch):\n    \"\"\"`None` is the genuine 'no value' case — empty raw is acceptable.\"\"\"\n    monkeypatch.setattr(server, \"_write_config_key\", lambda *a, **k: None)\n    resp = server.handle_request(\n        {\n            \"id\": \"1\",\n            \"method\": \"config.set\",\n            \"params\": {\"key\": \"indicator\", \"value\": None},\n        }\n    )\n    assert \"error\" in resp\n    assert \"unknown indicator: ''\" in resp[\"error\"][\"message\"]\n\n\n# ── reload.env ───────────────────────────────────────────────────────\n\n\ndef test_reload_env_rpc_calls_clawbot_cli_reload_env(monkeypatch):\n    \"\"\"reload.env mirrors classic CLI's `/reload` — re-reads ~/.clawbot/.env\n    into the gateway process and reports the count of vars updated.\"\"\"\n    calls = {\"n\": 0}\n\n    def _fake_reload():\n        calls[\"n\"] += 1\n        return 7\n\n    fake = types.SimpleNamespace(reload_env=_fake_reload)\n    with patch.dict(sys.modules, {\"clawbot_cli.config\": fake}):\n        resp = server.handle_request({\"id\": \"1\", \"method\": \"reload.env\", \"params\": {}})\n\n    assert resp[\"result\"] == {\"updated\": 7}\n    assert calls[\"n\"] == 1\n\n\ndef test_reload_env_rpc_surfaces_errors(monkeypatch):\n    def _broken():\n        raise RuntimeError(\"env path locked\")\n\n    fake = types.SimpleNamespace(reload_env=_broken)\n    with patch.dict(sys.modules, {\"clawbot_cli.config\": fake}):\n        resp = server.handle_request({\"id\": \"1\", \"method\": \"reload.env\", \"params\": {}})\n\n    assert \"error\" in resp\n    assert \"env path locked\" in resp[\"error\"][\"message\"]\n\n\n# ── max_iterations config reading ─────────────────────────────────────\n\n\ndef _setup_make_agent_mocks(monkeypatch, cfg):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: cfg)\n    monkeypatch.setattr(\n        server, \"_resolve_startup_runtime\", lambda: (\"test-model\", None)\n    )\n    monkeypatch.setattr(\n        \"clawbot_cli.runtime_provider.resolve_runtime_provider\",\n        lambda requested=None, target_model=None: {\n            \"provider\": None,\n            \"base_url\": None,\n            \"api_key\": None,\n            \"api_mode\": None,\n            \"command\": None,\n            \"args\": None,\n            \"credential_pool\": None,\n        },\n    )\n    monkeypatch.setattr(server, \"_load_tool_progress_mode\", lambda: \"off\")\n    monkeypatch.setattr(server, \"_load_reasoning_config\", lambda: None)\n    monkeypatch.setattr(server, \"_load_service_tier\", lambda: None)\n    monkeypatch.setattr(server, \"_load_enabled_toolsets\", lambda: None)\n    monkeypatch.setattr(server, \"_get_db\", lambda: None)\n    monkeypatch.setattr(server, \"_agent_cbs\", lambda sid: {})\n\n\ndef test_make_agent_reads_nested_max_turns(monkeypatch):\n    _setup_make_agent_mocks(monkeypatch, {\"agent\": {\"max_turns\": 200}})\n\n    with patch(\"run_agent.AIAgent\") as mock_agent:\n        server._make_agent(\"sid1\", \"key1\")\n\n    assert mock_agent.call_args.kwargs[\"max_iterations\"] == 200\n\n\ndef test_make_agent_nested_max_turns_takes_priority(monkeypatch):\n    _setup_make_agent_mocks(\n        monkeypatch, {\"agent\": {\"max_turns\": 500}, \"max_turns\": 100}\n    )\n\n    with patch(\"run_agent.AIAgent\") as mock_agent:\n        server._make_agent(\"sid1\", \"key1\")\n\n    assert mock_agent.call_args.kwargs[\"max_iterations\"] == 500\n\n\ndef test_make_agent_defaults_to_90(monkeypatch):\n    _setup_make_agent_mocks(monkeypatch, {})\n\n    with patch(\"run_agent.AIAgent\") as mock_agent:\n        server._make_agent(\"sid1\", \"key1\")\n\n    assert mock_agent.call_args.kwargs[\"max_iterations\"] == 90\n\n\ndef test_make_agent_handles_null_agent_config(monkeypatch):\n    _setup_make_agent_mocks(monkeypatch, {\"agent\": None, \"max_turns\": 80})\n\n    with patch(\"run_agent.AIAgent\") as mock_agent:\n        server._make_agent(\"sid1\", \"key1\")\n\n    assert mock_agent.call_args.kwargs[\"max_iterations\"] == 80\n\n\nclass _FakeAgentForBackground:\n    base_url = None\n    api_key = None\n    provider = None\n    api_mode = None\n    acp_command = None\n    acp_args = None\n    model = \"test-model\"\n    enabled_toolsets = None\n    ephemeral_system_prompt = None\n    providers_allowed = None\n    providers_ignored = None\n    providers_order = None\n    provider_sort = None\n    provider_require_parameters = False\n    provider_data_collection = None\n    reasoning_config = None\n    service_tier = None\n    request_overrides = {}\n    _fallback_model = None\n\n\ndef test_background_agent_kwargs_reads_nested_max_turns(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"agent\": {\"max_turns\": 300}})\n\n    kwargs = server._background_agent_kwargs(_FakeAgentForBackground(), \"task_1\")\n\n    assert kwargs[\"max_iterations\"] == 300\n\n\ndef test_background_agent_kwargs_falls_back_to_root_max_turns(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"max_turns\": 50})\n\n    kwargs = server._background_agent_kwargs(_FakeAgentForBackground(), \"task_1\")\n\n    assert kwargs[\"max_iterations\"] == 50\n\n\ndef test_background_agent_kwargs_defaults_to_25(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {})\n\n    kwargs = server._background_agent_kwargs(_FakeAgentForBackground(), \"task_1\")\n\n    assert kwargs[\"max_iterations\"] == 25\n\n\ndef test_background_agent_kwargs_handles_null_agent_config(monkeypatch):\n    monkeypatch.setattr(server, \"_load_cfg\", lambda: {\"agent\": None, \"max_turns\": 40})\n\n    kwargs = server._background_agent_kwargs(_FakeAgentForBackground(), \"task_1\")\n\n    assert kwargs[\"max_iterations\"] == 40\n\n\ndef test_config_show_displays_nested_max_turns(monkeypatch):\n    monkeypatch.setattr(\n        server,\n        \"_load_cfg\",\n        lambda: {\"agent\": {\"max_turns\": 120}, \"enabled_toolsets\": [], \"verbose\": False},\n    )\n    monkeypatch.setattr(server, \"_resolve_model\", lambda: \"test-model\")\n\n    resp = server.handle_request({\"id\": \"1\", \"method\": \"config.show\", \"params\": {}})\n    sections = resp[\"result\"][\"sections\"]\n    agent_rows = next(\n        section[\"rows\"] for section in sections if section[\"title\"] == \"Agent\"\n    )\n\n    assert [\"Max Turns\", \"120\"] in agent_rows\n\n\ndef test_notification_poller_delivers_completion(monkeypatch):\n    \"\"\"Poller picks up completion events and triggers agent turns.\"\"\"\n    from tools.process_registry import process_registry\n\n    turns = []\n    emitted = []\n\n    class _Agent:\n        def run_conversation(self, prompt, conversation_history=None, stream_callback=None):\n            turns.append(prompt)\n            return {\n                \"final_response\": \"ok\",\n                \"messages\": [{\"role\": \"assistant\", \"content\": \"ok\"}],\n            }\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None):\n            self._target = target\n        def start(self):\n            self._target()\n\n    sess = _session(agent=_Agent())\n    server._sessions[\"sid_poll\"] = sess\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: emitted.append(a))\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n\n    # Clear queue\n    while not process_registry.completion_queue.empty():\n        process_registry.completion_queue.get_nowait()\n    process_registry._completion_consumed.discard(\"proc_poller_test\")\n\n    stop = threading.Event()\n\n    # Put event on queue, then immediately signal stop so the poller\n    # runs exactly one iteration.\n    process_registry.completion_queue.put({\n        \"type\": \"completion\",\n        \"session_id\": \"proc_poller_test\",\n        \"command\": \"echo hello\",\n        \"exit_code\": 0,\n        \"output\": \"hello\",\n    })\n    stop.set()\n\n    try:\n        server._notification_poller_loop(stop, \"sid_poll\", sess)\n\n        # Should have emitted a status.update with kind=process\n        status_calls = [a for a in emitted if a[0] == \"status.update\"]\n        assert len(status_calls) >= 1\n        assert status_calls[0][2][\"kind\"] == \"process\"\n\n        # Should have triggered an agent turn\n        assert len(turns) == 1\n        assert \"[IMPORTANT: Background process proc_poller_test completed\" in turns[0]\n    finally:\n        server._sessions.pop(\"sid_poll\", None)\n        while not process_registry.completion_queue.empty():\n            process_registry.completion_queue.get_nowait()\n\n\ndef test_notification_poller_skips_consumed(monkeypatch):\n    \"\"\"Already-consumed completions are not dispatched by the poller.\"\"\"\n    from tools.process_registry import process_registry\n\n    turns = []\n\n    class _Agent:\n        def run_conversation(self, prompt, conversation_history=None, stream_callback=None):\n            turns.append(prompt)\n            return {\"final_response\": \"ok\", \"messages\": []}\n\n    class _ImmediateThread:\n        def __init__(self, target=None, daemon=None):\n            self._target = target\n        def start(self):\n            self._target()\n\n    sess = _session(agent=_Agent())\n    server._sessions[\"sid_skip\"] = sess\n    monkeypatch.setattr(server.threading, \"Thread\", _ImmediateThread)\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: None)\n    monkeypatch.setattr(server, \"make_stream_renderer\", lambda cols: None)\n    monkeypatch.setattr(server, \"render_message\", lambda raw, cols: None)\n\n    while not process_registry.completion_queue.empty():\n        process_registry.completion_queue.get_nowait()\n\n    process_registry._completion_consumed.add(\"proc_already_done\")\n    process_registry.completion_queue.put({\n        \"type\": \"completion\",\n        \"session_id\": \"proc_already_done\",\n        \"command\": \"echo x\",\n        \"exit_code\": 0,\n        \"output\": \"x\",\n    })\n\n    stop = threading.Event()\n    stop.set()\n\n    try:\n        server._notification_poller_loop(stop, \"sid_skip\", sess)\n        assert len(turns) == 0\n    finally:\n        server._sessions.pop(\"sid_skip\", None)\n        process_registry._completion_consumed.discard(\"proc_already_done\")\n        while not process_registry.completion_queue.empty():\n            process_registry.completion_queue.get_nowait()\n\n\ndef test_notification_poller_requeues_when_busy(monkeypatch):\n    \"\"\"When the agent is busy, the poller requeues the event.\"\"\"\n    from tools.process_registry import process_registry\n\n    emitted = []\n\n    sess = _session(running=True)  # agent is busy\n    server._sessions[\"sid_busy\"] = sess\n    monkeypatch.setattr(server, \"_emit\", lambda *a, **kw: emitted.append(a))\n\n    while not process_registry.completion_queue.empty():\n        process_registry.completion_queue.get_nowait()\n    process_registry._completion_consumed.discard(\"proc_busy_test\")\n\n    evt = {\n        \"type\": \"completion\",\n        \"session_id\": \"proc_busy_test\",\n        \"command\": \"make build\",\n        \"exit_code\": 0,\n        \"output\": \"ok\",\n    }\n    process_registry.completion_queue.put(evt)\n\n    stop = threading.Event()\n    stop.set()\n\n    try:\n        server._notification_poller_loop(stop, \"sid_busy\", sess)\n\n        # Status update was emitted (user sees it)\n        status_calls = [a for a in emitted if a[0] == \"status.update\"]\n        assert len(status_calls) == 1\n\n        # Event was requeued (agent was busy, no turn triggered)\n        assert not process_registry.completion_queue.empty()\n        requeued = process_registry.completion_queue.get_nowait()\n        assert requeued[\"session_id\"] == \"proc_busy_test\"\n    finally:\n        server._sessions.pop(\"sid_busy\", None)\n        while not process_registry.completion_queue.empty():\n            process_registry.completion_queue.get_nowait()\n"}}}}