nives 2.5.0: warn before the balance runs out

The add-on holds the user's key, and the key can describe itself: the
endpoint's key-info route returns remaining credit and rolling usage
windows. A new server job polls it every six hours, estimates days of
typical use left (weekly/7, else monthly/30, else a default burn), and
walks an ok -> warned (<=3 days) -> paused (<=1 day, or under $0.05)
state machine latched in /data — one HA persistent notification per
transition, never one per poll. Notification first, latch second: if HA
is briefly unreachable the transition retries next poll instead of being
lost. A top-up flips the state back to ok and dismisses both.

Triple-gated so it can never mislead: cloud mode only (options-to-env.sh
now passes LLM_MODE through — a BYOK user must not be told to top up at
nives.house), keys with a scheduled limit reset are skipped (a monthly
allowance is a different message, handled by email), and unlimited keys
have nothing to watch. Conveniently, today's keys all have monthly
resets, so the watcher goes live per user exactly when their key is
converted to a prepaid balance — no launch-day coordination.

The integration's out-of-usage reply (HTTP 402) is reworded from monthly
allowance framing to out-of-balance framing, covering both cloud top-ups
and BYOK users' own provider accounts.

Bundles server 0.15.0. Mirrors the cloud-side balance watcher thresholds
(nives-cloud 1.6.1); estimation is deliberately simpler — no account age
is visible here, and the empty floor catches every truly-empty case.

Author: hoornet

nives/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.5.0
+
+- **Nives now warns you before your balance runs out.** If you use Nives with a key from nives.house, the add-on keeps an eye on the remaining balance and, when about three days of typical use are left, posts a Home Assistant notification inviting you to top up. If the balance does run out, a clearer notification says so. Once you top up, both clear on their own and Nives carries on where it left off — nothing to configure, nothing to restart. If you bring your own key, nothing changes: Nives only watches nives.house balances.
+- **Nives says it plainly when it can't answer for lack of balance.** If a reply is refused because the balance is used up before the warning could reach you, Nives now tells you it's out of balance right in the conversation and points you to nives.house — or to your own provider's account, if you bring your own key. Bundles server 0.15.0.
+
 ## 2.4.24
 
 - **Bring-your-own-key now works with OpenAI's newest models.** Pointing Nives at GPT-5 or the o-series with your own OpenAI key failed before the model ever got a chance to answer: those models renamed the setting that limits how long a reply may be, and Nives was still sending the previous name. Nives now asks the endpoint which name it expects and remembers the answer, so the setting arrives correctly everywhere — OpenAI's newest models, OpenAI's older ones, and every other OpenAI-compatible endpoint Nives supports, local models included. There is nothing to configure, and setups that already worked are untouched. Thanks to @Kristofer-KNE for the report (#60).

nives/DOCS.md

@@ -48,6 +48,10 @@ Use Nives Cloud — a managed AI service with a monthly token budget. No API key
 | LLM Mode | Set to `cloud` |
 | Nives API Key | Your key from nives.house |
 
+### Balance heads-up
+
+Nives keeps an eye on your remaining balance. When about three days of typical use are left, it posts a Home Assistant notification inviting you to top up at [nives.house](https://nives.house); if the balance runs out, a clearer one says so. After a top-up both clear on their own — nothing to configure. This applies to Cloud mode only; keys you bring yourself are never watched.
+
 ---
 
 ## BYOK Mode (Bring Your Own Key)

nives/config.yaml

@@ -1,5 +1,5 @@
 name: "Nives"
-version: "2.4.24"
+version: "2.5.0"
 slug: "nives"
 description: "AI assistant with cognitive memory for Home Assistant"
 url: "https://github.com/hoornet/nives"

nives/rootfs/opt/nives/conversation.py

@@ -104,18 +104,20 @@ async def async_process(self, user_input: ConversationInput) -> ConversationResu
                 "persistent_notification",
                 "create",
                 {
-                    "title": "Nives — Usage Limit Reached",
+                    "title": "Nives — Out of balance",
                     "message": (
-                        "Your monthly usage allowance is depleted. "
-                        "Visit nives.house to renew or upgrade."
+                        "Nives has used up its available balance. "
+                        "Top up at nives.house — or, if you bring your own "
+                        "key, add credit with your provider — and Nives "
+                        "picks right back up."
                     ),
                     "notification_id": "nives_usage_limit",
                 },
             )
             intent_response = intent.IntentResponse(language=user_input.language)
             intent_response.async_set_speech(
-                "Your monthly token allowance is depleted. "
-                "Please visit nives.house to renew or upgrade."
+                "I'm out of balance. "
+                "Please top up at nives.house and I'll pick right back up."
             )
             return ConversationResult(
                 response=intent_response,

nives/rootfs/opt/nives/manifest.json

@@ -9,5 +9,5 @@
   "integration_type": "service",
   "iot_class": "local_polling",
   "requirements": ["aiohttp>=3.8.0"],
-  "version": "2.4.23"
+  "version": "2.5.0"
 }

nives/rootfs/usr/local/bin/options-to-env.sh

@@ -50,6 +50,9 @@ CUSTOM_PROMPT=$(jq -r '.custom_prompt // ""' "$OPTIONS")
 LOG_LEVEL=$(jq -r '.log_level // "info"' "$OPTIONS")
 
 # --- LLM configuration ---
+# The server needs to know the mode itself (not just its consequences): the
+# balance watch runs only in cloud mode, where "top up at nives.house" is true.
+write_env "LLM_MODE" "$LLM_MODE"
 if [ "$LLM_MODE" = "cloud" ]; then
     # Cloud mode: user's managed OpenRouter key (created via Nives Cloud)
     write_env "LLM_PROVIDER" "openai"

server/src/home-mind-server/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@home-mind/server",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Home Mind API server - AI assistant with cognitive memory for Home Assistant",
   "type": "module",
   "main": "dist/index.js",

server/src/home-mind-server/package.json

@@ -7,6 +7,9 @@ const ConfigSchema = z
     logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
 
     // LLM
+    // cloud = key managed via nives.house; byok = user's own key. Set by the
+    // add-on's options-to-env.sh; standalone deployments default to byok.
+    llmMode: z.enum(["cloud", "byok"]).default("byok"),
     llmProvider: z.enum(["anthropic", "openai", "ollama"]).default("anthropic"),
     llmModel: z.string().default("claude-haiku-4-5-20251001"),
     anthropicApiKey: z.string().optional(),
@@ -93,6 +96,7 @@ export function loadConfig(): Config {
   const result = ConfigSchema.safeParse({
     port: process.env.PORT,
     logLevel: emptyToUndefined(process.env.LOG_LEVEL),
+    llmMode: emptyToUndefined(process.env.LLM_MODE),
     llmProvider: emptyToUndefined(process.env.LLM_PROVIDER),
     llmModel: emptyToUndefined(process.env.LLM_MODEL),
     anthropicApiKey: emptyToUndefined(process.env.ANTHROPIC_API_KEY),

server/src/home-mind-server/src/config.ts

@@ -18,6 +18,7 @@ import { createRouter } from "./api/routes.js";
 import { createSttService } from "./stt/stt-service.js";
 import { createTtsService } from "./tts/tts-service.js";
 import { MemoryCleanupJob } from "./jobs/memory-cleanup.js";
+import { BalanceWatchJob } from "./jobs/balance-watch.js";
 
 // Load configuration
 const config = loadConfig();
@@ -154,10 +155,20 @@ Ready to accept requests at http://localhost:${config.port}
 const cleanupJob = new MemoryCleanupJob(memory, conversations, config.memoryCleanupIntervalHours);
 cleanupJob.start();
 
+// Watch the cloud balance (no-op in BYOK mode)
+const balanceJob = new BalanceWatchJob({
+  enabled: config.llmMode === "cloud" && config.llmProvider === "openai",
+  apiKey: config.openaiApiKey,
+  baseUrl: config.openaiBaseUrl,
+  ha,
+});
+balanceJob.start();
+
 // Graceful shutdown
 process.on("SIGTERM", () => {
   console.log("Shutting down...");
   cleanupJob.stop();
+  balanceJob.stop();
   conversations.close();
   memory.close();
   process.exit(0);
@@ -166,6 +177,7 @@ process.on("SIGTERM", () => {
 process.on("SIGINT", () => {
   console.log("Shutting down...");
   cleanupJob.stop();
+  balanceJob.stop();
   conversations.close();
   memory.close();
   process.exit(0);