nives 2.5.1: accept null conversation ids, cache the stable prompt prefix (#63, #66)

Two fixes from alcohen83's report batch, both verified before shipping.

#63 — conversation.process without a conversation_id always 400'd: HA's
integration serialized the missing id as an explicit JSON null, which
z.string().optional() rejects (optional covers ABSENT, not null). Fixed on
both sides: the schema now uses nullish() and normalizes (userId too — same
latent shape), and the integration omits the key entirely when it has no
value. The failure also surfaced as "couldn't reach the Nives server", which
misdirects diagnosis when the server is in fact answering — a
ClientResponseError now gets its own message naming the HTTP status, and the
raised error carries the response body so the log states WHY, not just that.

#66 — prompt caching is a prefix match, and the per-request timestamp led
the uncached block, so the home layout and device cheat sheet (the largest
stable content we send) were re-billed on every turn. Reordered
least-volatile-first on both engines: the Anthropic block path gives the
home description its own cache breakpoint (a rescan invalidates it without
evicting the instruction block), and the plain-text path moves timestamps
and retrieved facts to the tail so provider-side automatic prefix caching
can capture everything before them.

Measured live on a 150-device fixture via the block path: repeat turns went
from 4373/14008 tokens cached (identity only) to 13868/14008 (~99%). On the
OpenAI-compatible path an identical-prefix repeat showed 7229/7232 cached
and a 91% input-cost drop — though large-prefix hits are shard-sensitive
there; a stable prompt_cache_key per install is a possible follow-up.

Bundles server 0.15.1.

Author: hoornet

nives/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.5.1
+
+- **Automations and service calls can now message Nives without a conversation id.** Calling `conversation.process` on the Nives agent without a `conversation_id` — the natural way to use it from an automation or script — was refused before the model ever saw it, with a misleading "couldn't reach the server" reply. It now just works. Voice and the Assist dialog were never affected. Thanks to @alcohen83 for the pinpoint report (#63).
+- **Error replies now say who actually failed.** When the Nives server answers a request with an error, the reply now says so — with the HTTP status — instead of suggesting the server was unreachable, and the add-on log carries the server's own explanation of what it objected to. Connection problems still say "couldn't reach".
+- **Repeat turns got cheaper: the unchanging parts of the prompt can now be cached.** With every message, Nives sends the model your home's layout and device capabilities so it always knows your home. Those now sit ahead of the parts that change each turn (timestamps, retrieved memories), so providers that cache prompts can reuse them between turns instead of billing them again on every "turn off the kitchen light". Measured on an Anthropic key with a mid-size home, repeat turns went from about a third of the prompt cached to ~99% — same content, same answers, noticeably cheaper. The bigger your home, the more this saves. Thanks again to @alcohen83 (#66). Bundles server 0.15.1.
+
 ## 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/config.yaml

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

nives/rootfs/opt/nives/conversation.py

@@ -123,6 +123,21 @@ async def async_process(self, user_input: ConversationInput) -> ConversationResu
                 response=intent_response,
                 conversation_id=conversation_id,
             )
+        except aiohttp.ClientResponseError as err:
+            # The server ANSWERED — with an error status. Saying "couldn't
+            # reach the server" here sends people debugging connectivity when
+            # the log already names the real problem (#63, and #1 before it).
+            _LOGGER.error("Nives server returned an error: %s", err.message)
+            intent_response = intent.IntentResponse(language=user_input.language)
+            intent_response.async_set_error(
+                intent.IntentResponseErrorCode.UNKNOWN,
+                f"Sorry, the Nives server returned an error (HTTP {err.status}). "
+                "The add-on log has the details.",
+            )
+            return ConversationResult(
+                response=intent_response,
+                conversation_id=conversation_id,
+            )
         except (aiohttp.ClientError, TimeoutError) as err:
             _LOGGER.error("Error calling Nives API: %s", err)
             intent_response = intent.IntentResponse(language=user_input.language)
@@ -178,9 +193,13 @@ async def _call_api(
         payload: dict = {
             "message": message,
             "userId": user_id,
-            "conversationId": conversation_id,
             "isVoice": is_voice,
         }
+        # Only send the key when there is a conversation in flight. A service
+        # call without a conversation_id would otherwise put an explicit null
+        # on the wire, which request validation rejects (#63).
+        if conversation_id:
+            payload["conversationId"] = conversation_id
         # The Assist pipeline's language (e.g. "sl", "en"). Without it the model
         # has no anchor at all and infers the language from context that is
         # soaked in native-language entity names — which is how an English
@@ -208,11 +227,15 @@ async def _call_api(
             if response.status == 402:
                 raise UsageLimitError()
             if response.status != 200:
+                # Capture the body: the status alone says "the server
+                # objected", the body says WHY (validation details, error
+                # codes) — and this log line is all a bug report will carry.
+                body = (await response.text())[:300]
                 raise aiohttp.ClientResponseError(
                     response.request_info,
                     response.history,
                     status=response.status,
-                    message=f"API error {response.status}",
+                    message=f"API error {response.status}: {body}",
                 )
             data = await response.json()
             response_text = data.get("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.5.0"
+  "version": "2.5.1"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@home-mind/server",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "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

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { ChatRequestSchema } from "./routes.js";
+
+describe("ChatRequestSchema (#63)", () => {
+  // HA's conversation.process without a conversation_id serialized to an
+  // explicit `"conversationId": null`, which `.optional()` rejects — every
+  // such service call 400'd before any LLM was reached.
+
+  it("accepts conversationId: null and normalizes it to undefined", () => {
+    const result = ChatRequestSchema.safeParse({
+      message: "hello",
+      conversationId: null,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.conversationId).toBeUndefined();
+    }
+  });
+
+  it("accepts an absent conversationId", () => {
+    const result = ChatRequestSchema.safeParse({ message: "hello" });
+    expect(result.success).toBe(true);
+  });
+
+  it("passes a real conversationId through", () => {
+    const result = ChatRequestSchema.safeParse({
+      message: "hello",
+      conversationId: "01ABCDEFGHIJKLMNOPQRSTUVWX",
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.conversationId).toBe("01ABCDEFGHIJKLMNOPQRSTUVWX");
+    }
+  });
+
+  it("accepts userId: null and falls back to default — same latent shape", () => {
+    const result = ChatRequestSchema.safeParse({
+      message: "hello",
+      userId: null,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.userId).toBe("default");
+    }
+  });
+
+  it("still requires a message", () => {
+    const result = ChatRequestSchema.safeParse({ conversationId: null });
+    expect(result.success).toBe(false);
+  });
+});

server/src/home-mind-server/src/api/routes.schema.test.ts

@@ -10,10 +10,20 @@ import type { ITtsService } from "../tts/tts-service.js";
 const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 25 * 1024 * 1024 } });
 
 // Request validation schemas
-const ChatRequestSchema = z.object({
+export const ChatRequestSchema = z.object({
   message: z.string().min(1, "Message is required"),
-  userId: z.string().default("default"),
-  conversationId: z.string().optional(),
+  // JSON callers send an explicit null for "no value" at least as often as
+  // they omit the key — HA's conversation.process without a conversation_id
+  // arrives as `"conversationId": null` (#63). `.optional()`/`.default()`
+  // only cover ABSENT, so both fields accept null and normalize it here.
+  userId: z
+    .string()
+    .nullish()
+    .transform((v) => v ?? "default"),
+  conversationId: z
+    .string()
+    .nullish()
+    .transform((v) => v ?? undefined),
   isVoice: z.boolean().default(false),
   customPrompt: z.string().optional(),
   // The caller's UI language (e.g. "sl", "en-US") — in the add-on this is the

server/src/home-mind-server/src/api/routes.ts

@@ -203,3 +203,63 @@ describe("identity-change requests point at the config field, not forget_memory"
     expect(text).toContain("Custom Prompt");
   });
 });
+
+describe("cache-friendly ordering (#66)", () => {
+  // Prompt caching is a prefix match: anything after the first per-request
+  // byte is uncacheable. The home layout and device cheat sheet change on
+  // rescan (~30 min), not per request, so they must sit BEFORE the
+  // timestamps and retrieved facts, not after.
+  const LAYOUT = "## Home Layout:\n- Ground floor: kitchen";
+  const DEVICES = "## Device Capabilities:\n- light.kitchen: rgbw";
+
+  it("puts the home description in its own cached block, ahead of the volatile one", () => {
+    const blocks = buildSystemPrompt(
+      ["fact1"], false, undefined, DEVICES, LAYOUT
+    ) as TextBlock[];
+
+    expect(blocks).toHaveLength(3);
+    // Home description: cached, no per-request content
+    expect(blocks[1]).toMatchObject({ cache_control: { type: "ephemeral" } });
+    expect(blocks[1].text).toContain("Home Layout");
+    expect(blocks[1].text).toContain("Device Capabilities");
+    expect(blocks[1].text).not.toContain("Date/Time");
+    // Volatile block: timestamps + facts, NOT cached
+    expect(blocks[2]).not.toHaveProperty("cache_control");
+    expect(blocks[2].text).toContain("Date/Time");
+    expect(blocks[2].text).toContain("fact1");
+    expect(blocks[2].text).not.toContain("Home Layout");
+  });
+
+  it("emits no empty home block when there is no layout or cheat sheet", () => {
+    const blocks = buildSystemPrompt(["fact1"]) as TextBlock[];
+    expect(blocks).toHaveLength(2);
+    expect(blocks.every((b) => b.text.length > 0)).toBe(true);
+  });
+
+  it("keeps the plain-text prompt volatile-last for automatic prefix caching", () => {
+    const text = buildSystemPromptText(
+      ["fact1"], false, undefined, DEVICES, LAYOUT
+    );
+    const timestamp = text.indexOf("Date/Time");
+    expect(timestamp).toBeGreaterThan(text.indexOf("Home Layout"));
+    expect(timestamp).toBeGreaterThan(text.indexOf("Device Capabilities"));
+    // Facts are retrieved per message — they stay in the volatile tail too.
+    expect(text.indexOf("fact1")).toBeGreaterThan(text.indexOf("Device Capabilities"));
+  });
+
+  it("keeps every section present after the reorder", () => {
+    const text = buildSystemPromptText(
+      ["fact1"], false, undefined, DEVICES, LAYOUT, "en"
+    );
+    for (const marker of [
+      "You are Nives",
+      "Home Layout",
+      "Device Capabilities",
+      "## Current Context:",
+      "Interface language",
+      "fact1",
+    ]) {
+      expect(text).toContain(marker);
+    }
+  });
+});

server/src/home-mind-server/src/llm/prompts.test.ts

@@ -326,30 +326,43 @@ export function buildSystemPrompt(
     ? `\n- Interface language: ${language} — the default for your reply ONLY when the user's own words don't clearly indicate a language.`
     : "";
 
-  // Dynamic content that changes per request
   const layoutSection = homeLayout ? `\n\n${homeLayout}` : "";
   const deviceSection = deviceCheatSheet ? `\n\n${deviceCheatSheet}` : "";
-  const dynamicContent = `
+
+  // Prompt caching is a prefix match, so content is ordered least-volatile
+  // first: identity + instructions (changes on release/custom prompt), then
+  // the home description (changes on rescan, ~30 min), then the genuinely
+  // per-request parts — timestamps and retrieved facts (#66). The home
+  // description gets its own cache breakpoint: a rescan invalidates it
+  // without touching the instruction block's cache entry.
+  const volatileContent = `
 ## Current Context:
 - Date/Time: ${dateTimeStr}
 - ISO Timestamp (now, UTC): ${isoTimestamp}
 - Local midnight today (UTC): ${localMidnightIso}  ← use this as start_time for "today" history queries, NOT 00:00:00Z${languageLine}
 
 ## What You Remember About This User:
-${factsText}${layoutSection}${deviceSection}`;
+${factsText}`;
 
-  // Build content blocks: identity + instructions (cached) + dynamic
   const blocks: Anthropic.TextBlockParam[] = [
     {
       type: "text" as const,
       text: identity + instructions,
       cache_control: { type: "ephemeral" as const },
     },
-    {
-      type: "text" as const,
-      text: dynamicContent,
-    },
   ];
+  const homeDescription = `${layoutSection}${deviceSection}`;
+  if (homeDescription) {
+    blocks.push({
+      type: "text" as const,
+      text: homeDescription,
+      cache_control: { type: "ephemeral" as const },
+    });
+  }
+  blocks.push({
+    type: "text" as const,
+    text: volatileContent,
+  });
 
   return blocks;
 }
@@ -389,13 +402,16 @@ export function buildSystemPromptText(
   const layoutSection = homeLayout ? `\n\n${homeLayout}` : "";
   const deviceSection = deviceCheatSheet ? `\n\n${deviceCheatSheet}` : "";
 
-  return `${identity}${instructions}
+  // Volatile-last, same reasoning as buildSystemPrompt (#66): providers with
+  // automatic prefix caching can then reuse everything up to the home
+  // description, instead of missing from the first timestamp onward.
+  return `${identity}${instructions}${layoutSection}${deviceSection}
 
 ## Current Context:
 - Date/Time: ${dateTimeStr}
 - ISO Timestamp (now, UTC): ${isoTimestamp}
 - Local midnight today (UTC): ${localMidnightIso}  ← use this as start_time for "today" history queries, NOT 00:00:00Z${languageLine}
 
 ## What You Remember About This User:
-${factsText}${layoutSection}${deviceSection}`;
+${factsText}`;
 }