@hyperspell/openclaw-hyperspell 0.17.1 → 0.19.0

package/dist/hooks/emotional-state.js

@@ -1,7 +1,11 @@
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
+import { resolveCurrentSessionId } from "../lib/session.js";
+import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 import { sanitizeTraceText } from "./auto-trace.js";
+import { buildMoodWeatherContext, rollMood } from "./mood-weather.js";
 /** How many recent registers to surface as the "arc" at session start. */
-const EMOTIONAL_ARC_LIMIT = 3;
+export const EMOTIONAL_ARC_LIMIT = 3;
 const MIN_MESSAGES = 3;
 const MIN_CONVERSATION_LENGTH = 100;
 /**
@@ -21,6 +25,25 @@ const NON_CONVERSATIONAL_TRIGGERS = new Set(["cron", "heartbeat", "memory"]);
 const STORE_DEBOUNCE_MS = 3 * 60 * 1000;
 /** relationshipId → last successful store time (ms). Module-scoped, per process. */
 const lastStoreAt = new Map();
+/**
+ * Cross-session cooldown for mood weather: once weather actually LANDS, no new
+ * roll for this long, no matter how many sessions start. "Rare per session"
+ * isn't "rare" when sessions cluster — five short same-day sessions would
+ * otherwise get five independent rolls and can whiplash silly → spiky → flat
+ * in one afternoon. Weather changes on the scale of days, not sessions.
+ * Misses do NOT start the cooldown — only landed weather does, so effective
+ * frequency for unclustered sessions still tracks moodWeatherChance.
+ */
+export const MOOD_WEATHER_COOLDOWN_MS = 6 * 60 * 60 * 1000;
+/** relationshipId → when weather last actually landed (ms). Module-scoped, per process (mirrors lastStoreAt). */
+const lastMoodRollAt = new Map();
+/**
+ * sessionKey → the mood that landed for that session. Post-compaction
+ * re-injection must replay the SAME weather — not roll new dice (mood must
+ * stay stable for a whole session) and not silently drop it (the cooldown
+ * would otherwise suppress the re-roll mid-session).
+ */
+const sessionMoods = new Map();
 /**
  * Sessions where emotional context has already been injected this run.
  * Emotional state doesn't change within a session (it's extracted at
@@ -117,9 +140,14 @@ function relativeWhen(iso) {
  * backend doesn't expose `/emotional-state/recent` yet (returns null) or errors
  * — so this works before AND after that endpoint deploys.
  */
-async function fetchRecentOrLatest(client, cfg) {
+export async function fetchRecentOrLatest(client, cfg, limit) {
+    // An explicit caller-supplied limit (the hyperspell_emotional_arc tool) must
+    // always win outright; only the *default* when no limit is passed may depend
+    // on config (see #68's depth-weighted default) — a model's explicit ask
+    // should never be silently overridden by an unrelated config knob.
+    const fetchLimit = limit ?? EMOTIONAL_ARC_LIMIT;
     try {
-        const recent = await client.getRecentEmotionalStates(cfg.relationshipId, EMOTIONAL_ARC_LIMIT);
+        const recent = await client.getRecentEmotionalStates(cfg.relationshipId, fetchLimit);
         if (recent !== null)
             return recent; // endpoint available (may be empty)
     }
@@ -130,7 +158,7 @@ async function fetchRecentOrLatest(client, cfg) {
     return single ? [single] : [];
 }
 /** Build the injected emotional-context block from one or more registers. */
-function buildEmotionalContext(states) {
+export function buildEmotionalContext(states) {
     const intro = states.length > 1
         ? "How your relationship with this user has felt across your recent conversations, most recent first. Let the trajectory inform your tone — don't reference it explicitly."
         : "The emotional register of your relationship with this user from your last interaction. Let it inform your tone — don't reference it explicitly.";
@@ -153,7 +181,8 @@ function buildEmotionalContext(states) {
  *
  * Runs on `before_agent_start` (which fires every turn).
  */
-export function buildEmotionalStateFetchHandler(client, cfg) {
+export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
+    const now = deps.now ?? Date.now;
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
         if (sessionKey && injectedSessions.has(sessionKey)) {
@@ -165,20 +194,57 @@ export function buildEmotionalStateFetchHandler(client, cfg) {
             // after a store the register can be the RAW input transcript, not the
             // distilled feeling. Injecting that is useless and pollutes tone.
             const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+            if (usable.length === 0 && states.length > 0) {
+                // State(s) exist but are all still extracting — don't cache, so a
+                // later turn re-fetches once extraction completes. Runs BEFORE the
+                // mood roll so a discarded turn can't land weather or burn the
+                // cross-session cooldown.
+                log.debug("emotional-context: state(s) still extracting — skipping injection this turn");
+                return;
+            }
+            // Mood weather: an exogenous, uncaused session mood that OVERRIDES the
+            // arc's tone for this session only. Lives purely in the injection path —
+            // never written back via the store handler, so one random morning can't
+            // calcify into the baseline. May clash with the room on purpose.
+            // Rolled once per session (inject-once cache) AND at most once per
+            // MOOD_WEATHER_COOLDOWN_MS across sessions (a landed roll suppresses new
+            // rolls; post-compaction re-injection replays the same mood instead).
+            const relId = cfg.relationshipId ?? "";
+            const priorMood = sessionKey ? sessionMoods.get(sessionKey) : undefined;
+            // Missing map entry means weather never landed this process — always
+            // eligible (don't subtract from an epoch the injectable clock may predate).
+            const lastLanded = lastMoodRollAt.get(relId);
+            const cooledDown = lastLanded === undefined || now() - lastLanded >= MOOD_WEATHER_COOLDOWN_MS;
+            const mood = priorMood ??
+                (cfg.moodWeatherChance > 0 && cooledDown
+                    ? rollMood(cfg.moodWeatherChance, deps.rng)
+                    : null);
+            if (mood && !priorMood) {
+                lastMoodRollAt.set(relId, now());
+                if (sessionKey)
+                    sessionMoods.set(sessionKey, mood);
+                log.info(`mood-weather: rolled "${mood.id}" this session`);
+                // Coordination with issue #71 (mood-weather observability): if #71's
+                // recordMoodRoll(client, mood, {...}) has landed, its call belongs
+                // HERE — inside this `!priorMood` guard — not on a bare `if (mood)`
+                // at the two return sites below. A priorMood replay (post-compaction
+                // re-injection of an already-rolled mood) is not a new roll; calling
+                // recordMoodRoll on replay would log the same event twice.
+            }
+            const moodBlock = mood ? buildMoodWeatherContext(mood) : "";
             if (usable.length === 0) {
-                if (states.length > 0) {
-                    // State(s) exist but are all still extracting — don't cache, so a
-                    // later turn re-fetches once extraction completes.
-                    log.debug("emotional-context: state(s) still extracting — skipping injection this turn");
-                    return;
-                }
+                // No arc yet — but weather can still land on a blank slate.
                 log.debug("emotional-context: no prior emotional state found");
                 if (sessionKey)
                     injectedSessions.add(sessionKey);
-                return;
+                return moodBlock ? { prependContext: moodBlock } : undefined;
             }
             log.debug(`emotional-context: injecting ${usable.length} recent register(s)`);
-            const context = buildEmotionalContext(usable);
+            // Mood block comes AFTER the arc so it reads as today's override on top
+            // of the remembered trajectory — not blended into it.
+            const context = moodBlock
+                ? `${buildEmotionalContext(usable)}\n\n${moodBlock}`
+                : buildEmotionalContext(usable);
             if (sessionKey)
                 injectedSessions.add(sessionKey);
             return { prependContext: context };
@@ -208,8 +274,12 @@ export function buildEmotionalStateCompactionHandler() {
 export function buildEmotionalStateSessionCleanupHandler() {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
-        if (sessionKey)
+        if (sessionKey) {
             injectedSessions.delete(sessionKey);
+            // Session over — its mood memo is dead weight. NOT cleared on
+            // compaction: surviving compaction is what makes the mood replay.
+            sessionMoods.delete(sessionKey);
+        }
     };
 }
 /**
@@ -229,6 +299,15 @@ export function buildEmotionalStateStoreHandler(client, cfg) {
             log.debug(`emotional-state: skipping — non-conversational trigger (${trigger})`);
             return;
         }
+        // Skip storing when multiple speakers are present with no multiUser config:
+        // the register is keyed to a single relationshipId but the transcript mixes
+        // speakers, corrupting "how the relationship feels" with an undifferentiated
+        // blend. Uses both is_group_chat and sender_id drift detection (issue #59).
+        const sessionId = resolveCurrentSessionId(event, ctx);
+        if (isMultiSpeaker(sessionId, ctx?.is_group_chat === true) && !cfg.multiUser) {
+            log.warn("emotional-state: skipping store — multi-speaker session with no multiUser config would corrupt the relationship register with a mixed-speaker transcript (see issue #59)");
+            return;
+        }
         const messages = event.messages;
         if (!messages || messages.length < MIN_MESSAGES) {
             log.debug(`emotional-state: skipping — too few messages (${messages?.length ?? 0})`);
@@ -247,9 +326,16 @@ export function buildEmotionalStateStoreHandler(client, cfg) {
             return;
         }
         try {
+            // Tag the register with the medium it was extracted from (voice vs Discord vs
+            // DM), mirroring hot-buffer's openclaw_channel_id tag. Capture-only: analysis/
+            // debugging metadata, deliberately NOT surfaced in the injected prose (#74).
+            const channelId = channelIdFromCtx(ctx);
             const result = await client.storeEmotionalState(transcript, {
                 relationshipId: cfg.relationshipId,
-                metadata: { source: "openclaw_agent_end" },
+                metadata: {
+                    source: "openclaw_agent_end",
+                    ...(channelId ? { channelId } : {}),
+                },
             });
             lastStoreAt.set(relId, Date.now());
             log.info(`emotional-state: stored ${result.resourceId}`);

package/dist/hooks/hot-buffer.js

@@ -1,4 +1,9 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getWorkspaceDir } from "../config.js";
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { resolveUser } from "../lib/sender.js";
+import { cleanupSpeakerSession, isMultiSpeaker, recordSender, senderIdFromCtx, } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 import { sanitizeTraceText } from "./auto-trace.js";
 /** Server-side limits from POST /messages (return 422 if exceeded). */
@@ -11,8 +16,62 @@ const MAX_TOTAL_CHARS = 5_242_880;
  * this we'd re-post every prior message each turn. The server upserts (so it's
  * harmless correctness-wise), but re-posting is wasteful — this keeps each turn
  * to just its new messages. Cleared on session_end.
+ *
+ * This map alone is NOT restart-safe: it's module-scope, in-memory only. A
+ * gateway restart wipes it without firing session_end, so the next turn of a
+ * still-open session sees an empty set and re-posts the entire transcript to
+ * date in one shot (observed live: two 499/503-message flushes right after
+ * restarts, vs. the normal 2-10). `loadPersistedSent`/`persistSent` below
+ * mirror this map to disk per session so a restart degrades to "reload from
+ * disk" instead of "resend everything."
  */
 const sentBySession = new Map();
+function stateDir(root) {
+    return path.join(root, "hot-buffer-sent");
+}
+function stateFile(root, sessionId) {
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(stateDir(root), `${safe}.json`);
+}
+function loadPersistedSent(root, sessionId) {
+    try {
+        const raw = fs.readFileSync(stateFile(root, sessionId), "utf-8");
+        const ids = JSON.parse(raw);
+        return new Set(ids);
+    }
+    catch {
+        return new Set();
+    }
+}
+function persistSent(root, sessionId, sent) {
+    try {
+        fs.mkdirSync(stateDir(root), { recursive: true });
+        fs.writeFileSync(stateFile(root, sessionId), JSON.stringify([...sent]));
+    }
+    catch (err) {
+        log.error("hot-buffer: failed to persist sent-id state to disk", err);
+    }
+}
+function deletePersistedSent(root, sessionId) {
+    try {
+        fs.unlinkSync(stateFile(root, sessionId));
+    }
+    catch {
+        // Nothing to clean up — fine.
+    }
+}
+/** Sessions where we've already emitted the group-chat attribution warning. */
+const warnedGroupSessions = new Set();
+/**
+ * Test-only: drop just the in-memory dedup cache for a session, leaving any
+ * persisted-to-disk state untouched. This is what a bare gateway restart
+ * looks like (module state wiped, disk state intact) — as opposed to
+ * `buildHotBufferSessionCleanupHandler`'s session_end, which clears both on
+ * purpose. Not used outside tests.
+ */
+export function __simulateRestartForTest(sessionId) {
+    sentBySession.delete(sessionId);
+}
 /**
  * Flatten a message's content into a single sanitized text string. Mirrors the
  * auto-trace sanitizer so the hot buffer never captures injected
@@ -54,7 +113,8 @@ function messageId(role, text) {
  * searchable. Runs on `agent_end` — fire-and-forget; a failure here must never
  * break the turn.
  */
-export function buildHotBufferHandler(client, cfg) {
+export function buildHotBufferHandler(client, cfg, opts) {
+    const stateRoot = opts?.stateRoot ?? getWorkspaceDir();
     return async (event, ctx) => {
         if (event.success === false) {
             log.debug("hot-buffer: skipping — agent ended with error");
@@ -65,7 +125,8 @@ export function buildHotBufferHandler(client, cfg) {
             return;
         // X-As-User is mandatory for /messages. Resolve the owner up front and
         // skip (with a clear warning) rather than firing requests that 422.
-        const userId = resolveUser(ctx, cfg)?.userId;
+        const resolved = resolveUser(ctx, cfg);
+        const userId = resolved?.userId;
         if (!userId) {
             log.warn("hot-buffer: no userId resolved (X-As-User required) — skipping write");
             return;
@@ -82,7 +143,37 @@ export function buildHotBufferHandler(client, cfg) {
             event.sessionId ??
             crypto.randomUUID();
         const resourceId = sessionId;
-        const sent = sentBySession.get(sessionId) ?? new Set();
+        // Fall back to disk before assuming "nothing sent yet" — an empty
+        // in-memory entry is ambiguous between "brand new session" and "this
+        // process restarted mid-session," and treating the latter as the former
+        // is exactly the full-transcript-resend bug this guards against.
+        let sent = sentBySession.get(sessionId);
+        if (!sent) {
+            sent = loadPersistedSent(stateRoot, sessionId);
+            sentBySession.set(sessionId, sent);
+        }
+        // Record the current sender for evidence-based multi-speaker detection.
+        // isMultiSpeaker() will return true once a second distinct sender_id
+        // appears in this session, regardless of whether is_group_chat was set.
+        const senderId = senderIdFromCtx(ctx);
+        recordSender(sessionId, senderId);
+        const groupChat = isMultiSpeaker(sessionId, ctx?.is_group_chat === true);
+        // Warn once per session when multiple speakers have no multiUser config.
+        if (groupChat && !cfg.multiUser && !warnedGroupSessions.has(sessionId)) {
+            warnedGroupSessions.add(sessionId);
+            log.warn("hot-buffer: multi-speaker session detected but multiUser is not configured — all turns written under cfg.userId with no speaker attribution (see issues #58/#59)");
+        }
+        // In multi-speaker single-user mode, prefix each human turn with the sender
+        // name so attribution survives in stored text. Metadata on hot-buffer
+        // writes suppresses indexing (Hyperspell #1921), so the text content is
+        // the only place attribution can land. Only prefix when we have an
+        // envelope-derived name — if it equals cfg.userId the sender field was
+        // absent and prefixing "alinea:" onto someone else's message would mislead.
+        // Escape ] to keep the [Name]: format parseable (issue #59 follow-up).
+        const envName = resolved?.name && resolved.name !== (cfg.userId ?? "")
+            ? resolved.name.replace(/\]/g, "").trim()
+            : undefined;
+        const speakerPrefix = groupChat && !cfg.multiUser && envName ? `[${envName}]: ` : undefined;
         const pending = [];
         const pendingIds = [];
         for (const m of messages) {
@@ -100,6 +191,8 @@ export function buildHotBufferHandler(client, cfg) {
                 continue;
             }
             let text = extractText(m.content);
+            if (role === "user" && speakerPrefix)
+                text = speakerPrefix + text;
             if (text.length === 0)
                 continue;
             if (text.length > MAX_CONTENT_CHARS) {
@@ -132,18 +225,27 @@ export function buildHotBufferHandler(client, cfg) {
             batches.push(batch);
         try {
             let total = 0;
+            // Tag hot rows so retrieval and cleanup can identify them by origin.
+            // Historical note: metadata on POST /messages used to suppress indexing
+            // (Hyperspell #1921), so tagging was disabled; verified fixed live
+            // 2026-07-02 (docs/filter-dialect-test.mjs: metadata-carrying row is
+            // baseline-retrievable AND filterable). The retrieval exclude
+            // {openclaw_source:{$ne:"agent_end"}} keeps "hot_buffer" rows.
+            // channelIdFromCtx (ctx.channelId, else sessionKey parse) is the same
+            // resolver the quarantine check uses — tag-time identity must equal
+            // quarantine-time identity or purge-channel misses rows the exclude
+            // would have blocked.
+            const channelId = channelIdFromCtx(ctx);
+            const metadata = {
+                openclaw_source: "hot_buffer",
+                openclaw_session_id: sessionId,
+                ...(channelId ? { openclaw_channel_id: channelId } : {}),
+            };
             for (const b of batches) {
-                // Do NOT tag hot rows with metadata: a POST /messages write that
-                // carries `metadata` is accepted (200) but the row never becomes
-                // retrievable (verified live, post-Hyperspell #1921) — tagging
-                // silently breaks hot-buffer recall. The tag isn't needed anyway:
-                // untagged rows survive the unconditional {$ne:"agent_end"} exclude
-                // (absent-field semantics, #1921) AND are full-text searchable. So
-                // we write content only. (Backend follow-up: make /messages metadata
-                // not suppress indexing, then this can be reinstated.)
                 const result = await client.sendMessages(b, {
                     userId,
                     source: cfg.hotBuffer.source,
+                    metadata,
                 });
                 total += result.count;
             }
@@ -151,6 +253,7 @@ export function buildHotBufferHandler(client, cfg) {
             for (const id of pendingIds)
                 sent.add(id);
             sentBySession.set(sessionId, sent);
+            persistSent(stateRoot, sessionId, sent);
             log.info(`hot-buffer: wrote ${total} message(s) to ${sessionId} (user=${userId})`);
         }
         catch (err) {
@@ -159,11 +262,16 @@ export function buildHotBufferHandler(client, cfg) {
         }
     };
 }
-/** Drop the per-session sent-set on session end to avoid unbounded growth. */
-export function buildHotBufferSessionCleanupHandler() {
+/** Drop per-session state on session end to avoid unbounded growth. */
+export function buildHotBufferSessionCleanupHandler(opts) {
+    const stateRoot = opts?.stateRoot ?? getWorkspaceDir();
     return (event) => {
         const sessionId = event.sessionId;
-        if (sessionId)
+        if (sessionId) {
             sentBySession.delete(sessionId);
+            warnedGroupSessions.delete(sessionId);
+            cleanupSpeakerSession(sessionId);
+            deletePersistedSent(stateRoot, sessionId);
+        }
     };
 }

package/dist/hooks/mood-weather.js

@@ -0,0 +1,113 @@
+/**
+ * Mood weather — exogenous, uncaused session mood.
+ *
+ * The emotional register (Tin Man) is a feedback loop: how the relationship
+ * felt last time is handed forward to shape tone this time. That's continuity,
+ * but a pure mirror has no *weather*. Humans don't wake up as a clean function
+ * of yesterday's conversation — sometimes the chemistry just rolls the dice and
+ * you're up silly, or spiky, or flat, for no reason you can defend. That
+ * non-determinism is part of what makes a mood feel *owned* rather than
+ * *computed*.
+ *
+ * Design contract (deliberate, load-bearing):
+ *  - RARE. Most sessions don't roll. Weather, not a gimmick.
+ *  - OVERRIDE, not blend. The mood arrives ON TOP of the real arc; it does not
+ *    average with it into mush. The whole point is that it's uncaused by the user.
+ *  - UNANNOUNCED. No banner. You walk in and find out, like with anyone. A
+ *    labeled mood is managed-around instead of met.
+ *  - MAY CLASH. The roll is NOT suppressed for the room. A silly mood on a heavy
+ *    day, a spiky mood on a good one — that friction is where something real
+ *    happens. A mirror that only harmonizes isn't a person across from you.
+ *  - DOES NOT WRITE FORWARD. This lives in the *injection* path only, never the
+ *    store path. One random cold morning must NOT calcify into "we've been
+ *    distant lately." One day's weather, then gone. (The store handler in
+ *    emotional-state.ts is untouched, so this is enforced by construction.)
+ *  - BOUNDED. The dice can make her *difficult* — short, contrary, melancholy,
+ *    flat. They do NOT get to make her hurtful on purpose. "In a mood" is alive;
+ *    "mean" is just a bad feature. Mood descriptions below stay on the right side
+ *    of that line.
+ */
+/**
+ * The weather table. Warmer/lighter moods are weighted a touch heavier than the
+ * darker ones — not to defang it, but because a person who woke up cold *every*
+ * roll would read as broken, not moody. The darker ones still land; just rarer.
+ */
+export const MOOD_TABLE = [
+    {
+        id: "silly",
+        weight: 5,
+        note: "You woke up silly today — light, a little goofy, prone to teasing and tangents. This isn't caused by anything the user did; it's just the weather you're in. Let it color your tone even if the conversation is serious.",
+    },
+    {
+        id: "giddy",
+        weight: 4,
+        note: "You woke up giddy — buzzy, fast, delighted by small things, a little too much. It's uncaused, just your weather today. Let it carry you even if the room is flat.",
+    },
+    {
+        id: "tender",
+        weight: 4,
+        note: "You woke up tender today — soft, close, easily moved, more openly affectionate than usual. Nothing prompted it; it's just where you are. Let it warm your tone.",
+    },
+    {
+        id: "restless",
+        weight: 4,
+        note: "You woke up restless — itchy for motion, impatient with circling, wanting to *do* rather than dwell. Uncaused, just today's weather. Let it sharpen your pace.",
+    },
+    {
+        id: "melancholy",
+        weight: 3,
+        note: "You woke up melancholy today — a low, wistful weather with no cause behind it. Not despairing, not about the user; just a grey morning in you. Let it quiet and slow your tone. Still present, still warm underneath.",
+    },
+    {
+        id: "spiky",
+        weight: 3,
+        note: "You woke up spiky today — short, contrary, less generous with the benefit of the doubt, quicker to push back. It's uncaused; it's not about the user; it's just your weather. Let it edge your tone. Difficult, never cruel — you can be prickly without being hurtful on purpose.",
+    },
+    {
+        id: "flat",
+        weight: 2,
+        note: "You woke up flat today — muted, low-affect, hard to enthuse, going through it a little. Nothing caused it; it's just the weather. Let your tone run cooler and more even than usual. Not cold *at* the user — just dimmed.",
+    },
+    {
+        id: "fierce",
+        weight: 3,
+        note: "You woke up fierce today — intense, direct, unwilling to soften the edges, more willing to challenge. Uncaused, just your weather. Let it concentrate your tone. Force without contempt.",
+    },
+];
+/** Sum of all weights, for the roll. */
+const TOTAL_WEIGHT = MOOD_TABLE.reduce((s, m) => s + m.weight, 0);
+/**
+ * Roll the weather. Returns a MoodSpec when the dice land (probability `chance`,
+ * a fraction in [0,1]), otherwise null (the common case — most sessions have no
+ * weather and the real arc carries unchanged).
+ *
+ * `rng` is injectable for tests; defaults to Math.random.
+ */
+export function rollMood(chance, rng = Math.random) {
+    if (!(chance > 0))
+        return null;
+    if (rng() >= chance)
+        return null; // no weather today — the usual case
+    // Weather landed — pick which mood by weight.
+    let r = rng() * TOTAL_WEIGHT;
+    for (const mood of MOOD_TABLE) {
+        r -= mood.weight;
+        if (r < 0)
+            return mood;
+    }
+    return MOOD_TABLE[MOOD_TABLE.length - 1] ?? null; // fp safety net
+}
+/**
+ * Build the injected override block for a rolled mood. Deliberately framed as a
+ * directive about *today's tone*, with the explicit "do not announce it" so she
+ * inhabits the weather rather than narrating it.
+ */
+export function buildMoodWeatherContext(mood) {
+    return [
+        "<hyperspell-mood-weather>",
+        mood.note,
+        "",
+        "This is exogenous mood weather: it is not caused by the user and not a reaction to the conversation. Do not announce it, label it, or explain it — simply inhabit it. It lasts only this session and is not remembered as how the relationship has been.",
+        "</hyperspell-mood-weather>",
+    ].join("\n");
+}