Skip to content

2026.02.27 - Keystone

Choose a tag to compare

View all tags
@seiggy seiggy released this 27 Feb 22:40
· 577 commits to master since this release
2026.02.27
462d050
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes - 2026.02.27

Release Date: February 27, 2026
Code Name: "Keystone"

🗝️ Overview

"Keystone" is a UX and resilience release that transforms Lucia's first-run experience into a fully guided, self-healing onboarding wizard. Named after the wedge-shaped stone at the crown of an arch that locks everything into place—Keystone ensures that the dashboard API key, AI provider configuration, and agent initialization all interlock seamlessly before the user ever touches Home Assistant. Once that keystone is set, the arch holds.

🚀 Highlights

  • Guided AI Provider Setup — New wizard step lets users configure Chat and Embedding providers (OpenAI, Azure OpenAI with API Key or Default Credential) directly during onboarding, with live connectivity tests before proceeding.
  • Agent Status Gate — After providers are configured, the wizard waits for all agents to come online with real-time health polling before presenting the Home Assistant integration instructions.
  • Setup Resume Flow — If a user's browser session is lost mid-setup (after key generation but before completion), they can now re-authenticate with their dashboard key and continue where they left off instead of hitting a dead end.
  • Infinite Prompt Cache — Agent-level prompt cache entries no longer expire after 4 hours; they persist until manually evicted via the dashboard, maximizing LLM cost savings.

✨ What's New

🧙 Setup Wizard — AI Provider Configuration (Step 4)

  • Provider type selection — Choose between OpenAI and Azure OpenAI for both Chat and Embedding capabilities.
  • Azure authentication modes — API Key and Azure Default Credential are both supported. Default Credential enables managed identity deployments without storing secrets.
  • Live provider test — Each configured provider is validated with a real API call before it can be saved. Failed tests show the error message inline.
  • Provider cards — Configured providers display as summary cards with model/deployment name and a remove option.
  • Capability badges — Visual indicators show which capabilities (Chat, Embedding) are configured.

⏳ Setup Wizard — Agent Status Gate (Step 5)

  • Real-time agent health polling — After AI providers are saved, the wizard polls /api/agents/status every 3 seconds until all agents report healthy.
  • Per-agent status cards — Each agent shows a spinner (initializing), green check (ready), or red X (failed) with the agent description.
  • Automatic progression — The Next button enables only when all agents are online, preventing the user from configuring Home Assistant before agents are ready to receive commands.

🔄 Setup Resume Flow

  • Session recovery — If the dashboard key was already generated but setup wasn't completed, the wizard detects this state and presents a login form instead of a dead-end message.
  • Cookie-aware authentication — The wizard checks three auth sources: key generated this session, resumed via login form, or existing session cookie from a previous visit.
  • Graceful degradation — Users who lose their key must reset MongoDB storage and start fresh—no backdoor recovery mechanism that could be exploited.

♾️ Infinite Prompt Cache Retention

  • Removed 4-hour TTL — ChatCacheTtl field and all TimeSpan parameters removed from StringSetAsync calls in RedisPromptCacheService.
  • Manual eviction only — Cache entries persist in Redis indefinitely until evicted via the Prompt Cache dashboard page (per-entry or bulk "Clear All").
  • Cost optimization — Long-running instances accumulate cache hits over time without periodic cold-start penalties.

🐛 Bug Fixes

  • Orchestrator URL registration — OrchestratorAgent was registering the internal container address (e.g., http://localhost:5000/agent) as its A2A endpoint instead of a relative /agent path. External callers couldn't reach the agent through the reverse proxy. Fixed to use relative URL resolution.
  • Azure OpenAI embedding 404 — The API-key path for Azure OpenAI embeddings used the plain OpenAI.Embeddings.EmbeddingClient which sends requests to the wrong URL pattern. Azure OpenAI requires AzureOpenAIClient for the /openai/deployments/{name}/embeddings?api-version=... route. Fixed to use AzureOpenAIClient + AzureKeyCredential for both API key and Default Credential paths.
  • Empty agent catalog crash — Home Assistant custom component raised ConfigEntryNotReady when the agent catalog was empty instead of gracefully showing no agents. Fixed to return an empty list.
  • A2A SDK dependency removed — Custom component no longer depends on the experimental a2a-sdk Python package, resolving HACS validation failures and installation issues.
  • Playwright test stability — Rewrote setup wizard E2E tests to handle the resume flow, added Agent Cache tab switching for prompt cache validation, and fixed column mapping for the new cache table layout.
  • StepIndicator overflow — The 6-step wizard progress tracker overflowed its container on narrow viewports. Fixed with proper flex-wrap and sizing.

🧪 Testing

  • 7 setup wizard E2E tests — Covers redirect, welcome page, key generation + HA config, AI provider configuration, agent status gate, dashboard authentication, and setup endpoint lockdown.
  • 5 prompt cache E2E tests — Validates cache login/clear, miss recording, hit detection, different-prompt separation, and manual eviction through the dashboard UI.
  • Resume flow coverage — Tests navigate through the wizard with a pre-existing dashboard key, exercising the resume login path.

📦 Files Changed

  • 20 files changed, +1,201 / −528 lines across dashboard, backend, tests, and HA custom component.
Assets 2
Loading