v1.4.0 - First-Class Telemetry Sensors, Dynamic Descriptions & Cache-Busting

🏷️ Nexus MCP v1.4.0

📈 10 Dedicated First-Class Telemetry Sensors

• Decoupled all quota and limit metrics from hidden modal attributes into 10 independent Home Assistant entities with standard English names and hover descriptions (extra_state_attributes["description"]):
  • Daily Tokens Used
  • Daily Requests Used
  • Daily Requests Remaining
  • Daily Quota Remaining (%)
  • Daily Requests Limit
  • Tokens Per Minute Limit
  • Requests Per Minute Limit
  • Max Window Wait Time
  • Rate Limit Cooldown
  • Conversation History
• For local models (Ollama), cloud quota sensors are automatically omitted.

🌐 Dynamic Localized Entity Descriptions (Oukitel Architecture)

• Bilingual entity descriptions (es / en) delivered dynamically via extra_state_attributes["description"] based on Home Assistant system language settings.
• Hassfest compliant: strictly adheres to Home Assistant standards without non-standard translation keys.

🛡️ Defensive Token Budget Pruning (HTTP 413 Prevention)

• Proactive sliding-window pruning of historical context when prompt tokens approach model input limits (e.g. Qwen's 7,000 TPM limit on Groq).
• System prompt and latest query are strictly preserved without unwanted model mutations.

🔄 Automatic Lovelace Resource Cache-Busting

• Integration startup routine automatically detects and updates Lovelace resource URLs to ?v=1.4.0 via async_update_item, eliminating stale JavaScript cache across browser sessions and companion apps.

⚡ Knowledge Base Limits Harmonization

• Configured precise specifications in const.py (MODEL_SPECS): Groq 120B at 8,000 TPM / 14,400 RPD, Qwen 27B at 7,000 TPM / 14,400 RPD.

🧪 Quality Assurance

• 50/50 unit tests passing (100% success rate) across all modules.

v1.3.4 - LLM Quota Telemetry & Rate-Limit Sensors

🚀 Nexus MCP v1.3.4

✨ Novedades

• Sensores de Consumo Diario de Tokens (sensor.nexus_mcp_[modelo]_consumo_de_tokens_diario):
  • state_class: total_increasing compatible con estadísticas a largo plazo de Home Assistant.
  • Registro desglosado: tokens prompt, completion, total, tokens restantes por minuto (remaining_tokens_minute) y límite TPM (limit_tokens_minute).
• Sensor de Tiempo de Desbloqueo y Rate Limit (sensor.nexus_mcp_[modelo]_tiempo_desbloqueo_rate_limit):
  • Cuenta atrás en tiempo real (s) para la renovación de tokens por minuto si el servidor impone límite.
• Creación Inteligente y Condicional:
  • Exclusivo para modelos cloud con tokens/cuotas (gemini_free, groq_free, qwen_free, custom_openai).
  • Omitido automáticamente para modelos locales (ollama_local), manteniendo la instalación limpia y libre de entidades innecesarias.
• Vinculación por Dispositivo:
  • Todas las entidades de cada modelo quedan agrupadas bajo su propio dispositivo en Ajustes > Dispositivos y Servicios.

v1.3.3 - Request Timeout Resilience, Multiline Chat, Agent Persistence & Universal Vision Detection

What's Changed in v1.3.3

🛡️ Request Timeout Resilience & Anti-Hang Guard

• Explicit Client Timeouts: Added aiohttp.ClientTimeout of 40s for Google Gemini and 45s for OpenAI/Groq/Ollama engines to prevent backend threads from stalling on saturated free tiers or dropped connections.
• Frontend Card Safety Timeout: Protected WebSocket communications in nexus-mcp-card.js with Promise.race: if an AI model or server hangs, the waiting bubble is dismissed, the send button is re-enabled, and a clear error notification is displayed in the chat.

⏎ Multiline Chat Input with Ctrl+Enter

• Ergonomic Line Breaks: Insert newlines in the input box using Ctrl + Enter (or Shift + Enter) without triggering message sending. Standard Enter sends the message instantly.
• Streamlined Textbox Layout: Base height set to 52px with auto-growing textarea and native scrollbars eliminated (overflow: hidden) for a clean, modern aesthetic.

💾 Selected AI Agent Persistence

• Remember Model Choice: The active conversation agent selected in the card header dropdown is persisted to client localStorage. Reloading the page or restarting the dashboard maintains your selected model without reverting to default.

👁️ Dynamic Multimodal Vision Badge & Universal Model Detection

• Real-Time Header Indicator: Displays an elegant, compact Visión / Texto status badge directly in the card header.
• Clean Agent Dropdown Tags: Replaced oversized badges with a clean 👁️ prefix in the model selector.
• Universal Local Vision Support: Expanded regex heuristic to auto-detect vision capabilities across local Ollama, vLLM, and OpenAI-compatible models (gemini, qwen, llava, moondream, minicpm, paligemma, cogvlm, internvl, pixtral, etc.).

🔧 Groq Cloud Tool Message Validator

• Eliminated HTTP 400 Errors: Fixed messages[...].content must be a string validation failure in OpenAI/Groq compatible engines during multi-turn tool calling when receiving empty or JSON outputs.

🧪 100% Passing Test Suite

• 40/40 Unit Tests Passing: Comprehensive test coverage across all configuration flows, engines, multimodal chat, sensor state dispatchers, and tool call handlers.

Full Changelog: v1.3.2...v1.3.3

v1.3.2 - Code Boxes, 1-Click Copy & Multi-Device History Sync

What's Changed in v1.3.2

📦 Syntax-Styled Code Blocks & 1-Click Code Copy

• High-contrast code containers: Markdown code blocks (```yaml, ```python, ```json, etc.) are automatically parsed into styled syntax boxes with language badges.
• Dedicated 1-click copy: Added a dedicated "Copy code" / "Copiar código" button with instant clipboard copy and animated checkmark feedback (mdi:check).
• Resilient parsing heuristics: Automatically handles unclosed backticks and trailing whitespace in language identifiers to guarantee clean display even if the LLM output is truncated.

🔄 Cross-Browser & Multi-Device Persistent History Sync

• Backend WebSocket endpoint (nexus_mcp/get_history): The card now queries Home Assistant server-side persistent conversation storage (.storage/nexus_mcp_history_*) via WebSocket.
• Universal device continuity: Seamlessly loads full conversational history across all your desktop browsers (Chrome, Edge, Firefox, Safari), mobile devices, and tablets without depending on isolated browser client storage.

⚡ Guaranteed Auto-Scroll on Reload & Media Loads

• Multi-phase auto-scroll (_scrollToBottom): Executes immediate and staggered scrolling (40ms, 120ms, 300ms, 600ms) to ensure the chat is always anchored to the latest message regardless of font or card render latency.
• Web component lifecycle hook (connectedCallback): Automatically restores scroll to the latest message when reconnecting to the DOM tree after dashboard tab switches or page reloads.
• Image decoding listeners: Re-anchors scroll position automatically when attached images finish loading.
• Smooth animated scrolling: Smoothly animates down to new sent and received messages.

🛡️ Home Assistant Standards Compliance & Hassfest Clean

• Declared http dependency in manifest.json for static asset serving.
• Defined CONFIG_SCHEMA (cv.config_entry_only_config_schema) in __init__.py to satisfy Home Assistant core standards.
• Synchronized service translations in translations/en.json to match strings.json.
• 100% CI/CD Validation: All GitHub Actions workflows (HACS Validation, Hassfest Validation, Unit Tests) passing green.

Full Changelog: v1.3.1...v1.3.2

v1.3.1 - Multimodal Vision, Image Paste (Ctrl+V) & 1-Click Text Selection

What's Changed in v1.3.1

👁️ Multimodal Vision Support & WebSocket Pipeline (nexus_mcp/chat)

• End-to-end multimodal image understanding: Supports vision models (qwen/qwen3.8-27b, Google Gemini Vision, OpenAI Vision, and Ollama Vision).
• Dedicated WebSocket command: nexus_mcp/chat transmits base64 DataURLs directly to the LLM engine alongside conversational context.
• Text-only safeguard: If an image is sent while using a text-only model (e.g. Groq 120B), Nexus MCP gracefully guides the user to switch to a vision model like Gemini or Qwen.

🖼️ Clipboard Image Paste (Ctrl+V) & Attachment Button (📎)

• Zero-lag clipboard capture: Paste screenshots directly (Win + Shift + S or copied web images) anywhere on the card or input bar with Ctrl + V.
• File attachment button: Dedicated mdi:paperclip button to browse and upload image files from disk or mobile gallery.
• Thumbnail preview card: Shows an instant image preview container above the input bar with 1-click removal (✕).

📋 1-Click Message Copying & Full Text Selection

• 1-click copy: Every message bubble features a 1-click copy button (mdi:content-copy) with animated visual checkmark confirmation (mdi:check).
• Native cursor selection: user-select: text enabled across all message bubbles for seamless manual selection of code blocks, YAML automations, and entity IDs.

🛡️ Corrupted Tool Message Sanitizer & HTTP 400 Prevention

• OpenAI / Groq API validation: Automatically converts orphaned or unlinked role: "tool" execution results into safe assistant notes, eliminating HTTP 400 invalid_request_error.
• Persistent storage cleanup: Sanitizes .storage/nexus_mcp_history_* to ensure only dialogue turns (user and assistant) are persisted.

🧪 Quality Assurance

• 38/38 unit tests passing (100% success rate) across all engines, platforms, and conversation pipelines.

Full Changelog: v1.3.0...v1.3.1

v1.3.0 - Plug & Play Card, Multi-Agent Selector, Hot-Reload Deadlock Fix

🚀 Nexus MCP v1.3.0 - Plug & Play Lovelace Card, Live Multi-Agent AI Selector & Hot-Reload Fix

🎴 Plug & Play Lovelace Card with Visual Card Picker Integration

• Auto-Resource Registration: Frontend card assets are automatically registered into Home Assistant's Lovelace resources upon integration setup.
• Visual Card Picker: Found directly in Home Assistant's "Add Card" visual dialog as «Nexus MCP Chat & Historial» (nexus-mcp-card), complete with interactive preview and graphical card editor.

🤖 Live Multi-Agent AI Selector & Direct WebSocket Communication

• Dynamic Header Dropdown: Switch seamlessly between any configured Home Assistant conversation agent (qwen/qwen3.8-27b, openai/gpt-oss-120b, gemini-3.1-flash-lite, etc.) without changing dashboard configuration.
• Sub-Second Streaming: Direct real-time WebSocket communication via conversation/process with live typing indicators.
• Persistent Memory & Reset: Independent chat histories stored per model with a clean "Reset / Nueva conversación" button triggering both frontend storage clear and native clear_history backend service.
• Microphone Voice Assist: Tap the microphone icon anytime to bring up Home Assistant's native Assist voice overlay.

📊 Dedicated History Sensor & Dashboard Integration

• Native sensor (sensor.nexus_mcp_historial_de_conversaciones) exposing last queries, message counters, and formatted Markdown (formatted_markdown) attribute for standard Markdown cards.
• Reactive dispatcher updates (async_dispatcher_send / async_dispatcher_connect) on every chat message.
• Registered nexus_mcp.clear_history action available in both entry and platform setups.

⚡ Hot-Reconfiguration & Options Flow Deadlock Fix

• Non-blocking, debounced background task coordination (hass.async_create_task with 50ms debounce) for async_reload_entry.
• Completely eliminates Home Assistant UI hanging or freezing when modifying models or credentials in hot-reconfiguration.

🧪 Quality Assurance

• 36/36 Unit Tests Passing (100% Success Rate) across all modules, platforms, and services.

v1.2.0 - Interactive Confirmation, Groq 120B Reasoning Default & Visual Showcase

🌟 Nexus MCP v1.2.0: Interactive Safety, Groq 120B & Visual Showcase

We are thrilled to announce the release of Nexus MCP v1.2.0 for Home Assistant!

This release transforms Nexus MCP from a powerful direct-execution agent into a safe, human-aligned smart home assistant with interactive confirmation, upgrades the default AI brain to the state-of-the-art 120-Billion parameter open reasoning model (openai/gpt-oss-120b) on Groq Cloud, resolves critical options-flow lifecycle freezes, and adds full automated test coverage and visual documentation.

---

🛡️ Interactive Confirmation & Human-in-the-Loop Safety

By default, an AI agent writing automations directly to your smart home can be unpredictable. v1.2.0 introduces interactive human-in-the-loop safety:

• Natural Language Proposal & Confirmation: When Autonomous Mode is unchecked (default), Nexus MCP will:
  1. Semantically search your entities via ha_search_entities.
  2. Inspect current states with ha_get_entity_state.
  3. Formulate the exact triggers, conditions, actions, and entity IDs needed.
  4. Explain its plan in plain language and ask for your explicit confirmation before creating anything.
• Conversational Context Tracking: The integration detects your confirmation in subsequent chat turns (e.g., "Yes, proceed", "Looks good, create it", "Adelante", "Confirmo") and executes the creation only after explicit approval.
• Tool-Level Guardrail: If an LLM attempts to call ha_create_automation without prior user confirmation, Nexus MCP intercepts the call at the execution boundary and requires the model to explain the plan and ask first.
• Instant Autonomous Mode Toggle: Need faster, unsupervised execution? Simply check Autonomous Mode in Settings ➔ Devices & Services ➔ Nexus MCP ➔ Configure anytime without restarting Home Assistant.

---

⚡ Inference Engines & Groq Cloud 120B Default

• Groq Cloud Preconfigured Default: openai/gpt-oss-120b:
  • 120-Billion parameter open reasoning model optimized for complex logic and tool calling.
  • 100% Free: 1-click Google/GitHub login, zero credit card, zero phone verification required.
  • Up to 14,400 free requests per day with ultra-high inference speeds (~0.08s latency).
  • In-flight model fallback and European geographical license redirect support for qwen/qwen3.8-27b and openai/gpt-oss-20b.
  • In-app clickable link to official Groq Model Catalog.
• Google Gemini (Free Tier):
  • Full support for gemini-3.1-flash-lite (500 free requests/day with 250,000 TPM limit) and gemini-flash-latest.
• Qwen Cloud (Alibaba Model Studio / DashScope):
  • High-speed flagship models (qwen-plus-latest, qwen-turbo-latest, qwen2.5-coder-32b-instruct) with millions of free tokens.
• Ollama Local & Custom OpenAI (BYOK):
  • Native endpoints for local offline LLMs (qwen2.5-coder:7b) and OpenRouter/OpenAI proxies.
  • Disclaimer: Implemented using standard OpenAI-compatible API schemas; currently in experimental status pending community testing due to local hardware/resource constraints.

---

🔧 Core Architecture & Lifecycle Stability

• Atomic Options Flow Reloads:
  • Refactored integration lifecycle management to use hass.config_entries.async_reload(entry.entry_id).
  • Completely eliminated the modal spinner deadlock and infinite reload cascade when saving settings.
• Pure Asynchronous Non-Blocking Engine:
  • Built 100% on Home Assistant's native aiohttp event loop with zero background thread overhead and zero memory leaks.
• Linter & Hassfest Compliance:
  • Cleaned all translation strings and manifests to strictly conform to Home Assistant core guidelines.

---

📸 Comprehensive Visual Showcase

The repository now features an extensive 17-screenshot visual guide:

• Provider Setup: Clean configuration modals for Groq, Gemini, Qwen, Ollama, and Custom OpenAI.
• Safety Options: Reconfigure models, keys, and Autonomous Mode dynamically.
• Interactive Chat: Real-world demonstration of entity discovery, plan explanation, user confirmation, and automation generation.
• Home Assistant UI Integration: Inspect created automations and live execution traces in the native HA visual editor.
• Assist Satellite Voice: Full setup guide for Assist pipelines with local Whisper STT and Piper TTS.
• High-Resolution Preview: 1280x640 social preview card for project sharing.

---

🧪 Automated Testing & Continuous Integration

• 26/26 Unit Tests Passing (100% Success Rate):
  • Comprehensive test suite in tests/ covering config flows, options flows, autonomy guards, schema sanitization, and LLM engines.
• GitHub Actions CI/CD Pipeline:
  • Automated validation workflow running on every commit:
    • HACS Action: Verifies repository compliance and structure.
    • Hassfest Action: Official Home Assistant validation for manifests and translations.
    • Unit Tests: Automated execution of the full test suite.
• Official HACS Directory Inclusion:
  • Pull Request #11965 submitted to hacs/default for inclusion in the official HACS directory.

---

📦 Installation & Quick Start

Via HACS (Recommended)

1. In Home Assistant, open HACS ➔ Integrations ➔ Three dots (top right) ➔ Custom repositories.
2. Add URL: https://github.com/VictorCV-DAM/ha-nexus-mcp with category Integration.
3. Click Download, then restart Home Assistant (Settings ➔ System ➔ Restart).
4. Go to Settings ➔ Devices & Services ➔ Add Integration ➔ Nexus MCP.
5. Select your inference engine (Groq, Gemini, Qwen, Ollama) and start chatting with your smart home!

---

Full Changelog: v1.0.0...v1.2.0

v1.0.0 - Initial Official Release

🚀 Nexus MCP v1.0.0 - Initial Official Release

We are excited to announce the first official stable release of Nexus MCP for Home Assistant!

Nexus MCP is the first fully functional, open-source, and free Click & Install Agentic Intercom designed to connect your Home Assistant instance with advanced AI models (Qwen 2.5 Coder and Google Gemini) and the Model Context Protocol (ha-mcp) at zero cost.

---

✨ Key Features

• ⚡ Ultra-Lightweight Intercom Architecture: Protects Home Assistant's event loop and resources. All heavy agentic reasoning happens on external inference servers.
• 🗣️ Official Assist Conversation Integration: Exposes a native ConversationEntity (conversation.nexus_mcp) for seamless text and voice control across the web dashboard, mobile app, and satellite microphones.
• 💸 100% Free AI Inference Options:
  • Google Gemini Free Tier: Fast setup using a free API key from Google AI Studio (15 RPM / 1M TPM, no credit card required).
  • Ollama Local (Qwen 2.5 Coder): Zero-cost, 100% private, offline inference on your local network.
  • Custom BYOK: Connect to Alibaba DashScope, OpenAI, DeepSeek, or any OpenAI-compatible provider.
• 🔌 Model Context Protocol (MCP) Ready: Built-in async SSE/JSON-RPC client designed to interface directly with ha-mcp.
• 📦 1-Click Fast Install via HACS: Direct installation link via my.home-assistant.io badge.
• 🧪 100% Verified Quality: Comprehensive unit test suite with 100% pass rate.

---

📦 Installation

Add this repository as a Custom Repository in HACS:
ext https://github.com/VictorCV-DAM/ha-nexus-mcp
Category: Integration

---

📄 License

Licensed under the MIT License - 100% free and open-source for the entire Home Assistant community.