@hyperspell/openclaw-hyperspell 0.17.1 → 0.19.0

package/dist/hooks/startup-orientation.js

@@ -1,4 +1,6 @@
 import { resolveUser } from "../lib/sender.js";
+import { resolveCurrentSessionId } from "../lib/session.js";
+import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 const MAX_ATTEMPTS = 2;
 const RECENT_BUFFER_LIMIT = 100;
@@ -76,7 +78,7 @@ function isoDaysAgo(days) {
  * an unresolved caller has no personal space to orient to. In single-user mode,
  * return undefined so the client falls back to its configured userId.
  */
-function personalUserId(cfg, ctx) {
+export function personalUserId(cfg, ctx) {
     if (!cfg.multiUser)
         return { skip: false, userId: undefined };
     const resolved = resolveUser(ctx, cfg);
@@ -189,8 +191,78 @@ async function fetchRecentConversations(client, limit, userId) {
     }
     return out;
 }
-export function buildStartupOrientationHandler(client, cfg) {
+/**
+ * The fetch+format core of startup orientation, shared by the real
+ * before_agent_start handler and the read-only /previewcontext command.
+ * Pure with respect to session lifecycle: no inject-once cache, no retry
+ * counting — callers own that policy. Keeping one formatter here keeps the
+ * preview byte-identical to real injection.
+ */
+export async function gatherOrientation(client, cfg, userId) {
     const so = cfg.startupOrientation;
+    // Source recent-interactions from wherever the session record actually
+    // lives. Prefer the hot buffer (modern path: clean session-grouped vault
+    // resources, present whenever the hot buffer is on — including auto-trace-
+    // off agents). Fall back to agent_end traces only when there's no hot
+    // buffer but auto-trace is on. Otherwise skip: there's nothing to fetch,
+    // and the trace-source list is expensive (observed ~12s + failing/turn),
+    // blocking before_agent_start and slowing the reply.
+    const recentSource = cfg.hotBuffer.enabled
+        ? "hotBuffer"
+        : cfg.autoTrace.enabled
+            ? "autoTrace"
+            : "none";
+    const recentFetch = recentSource === "hotBuffer"
+        ? fetchRecentConversations(client, so.recentLimit, userId)
+        : recentSource === "autoTrace"
+            ? fetchRecentTraces(client, isoDaysAgo(so.recentDays), so.recentLimit, userId)
+            : Promise.resolve([]);
+    const [recentSettled, loopsSettled] = await Promise.allSettled([
+        recentFetch,
+        client.search(so.loopsQuery, {
+            limit: so.loopsLimit,
+            userId,
+        }),
+    ]);
+    const recentOk = recentSettled.status === "fulfilled";
+    const loopsOk = loopsSettled.status === "fulfilled";
+    const recent = recentOk ? recentSettled.value : [];
+    const loops = loopsOk ? loopsSettled.value : [];
+    if (!recentOk) {
+        log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
+    }
+    if (!loopsOk) {
+        log.error("startup-orientation: loops search failed", loopsSettled.reason);
+    }
+    const recentBody = formatRecentInteractions(recent);
+    const loopsBody = formatUnfinishedLoops(loops);
+    return {
+        recentOk,
+        loopsOk,
+        recentCount: recent.length,
+        loopsCount: loops.length,
+        recentSource,
+        recentBlock: recentBody
+            ? [
+                "<hyperspell-recent-interactions>",
+                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
+                "",
+                recentBody,
+                "</hyperspell-recent-interactions>",
+            ].join("\n")
+            : null,
+        loopsBlock: loopsBody
+            ? [
+                "<hyperspell-unfinished-loops>",
+                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
+                "",
+                loopsBody,
+                "</hyperspell-unfinished-loops>",
+            ].join("\n")
+            : null,
+    };
+}
+export function buildStartupOrientationHandler(client, cfg) {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
         if (sessionKey && injectedSessions.has(sessionKey))
@@ -211,36 +283,19 @@ export function buildStartupOrientationHandler(client, cfg) {
                 injectedSessions.add(sessionKey);
             return;
         }
-        // Source recent-interactions from wherever the session record actually
-        // lives. Prefer the hot buffer (modern path: clean session-grouped vault
-        // resources, present whenever the hot buffer is on — including auto-trace-
-        // off agents). Fall back to agent_end traces only when there's no hot
-        // buffer but auto-trace is on. Otherwise skip: there's nothing to fetch,
-        // and the trace-source list is expensive (observed ~12s + failing/turn),
-        // blocking before_agent_start and slowing the reply.
-        const recentFetch = cfg.hotBuffer.enabled
-            ? fetchRecentConversations(client, so.recentLimit, userId)
-            : cfg.autoTrace.enabled
-                ? fetchRecentTraces(client, isoDaysAgo(so.recentDays), so.recentLimit, userId)
-                : Promise.resolve([]);
-        const [recentSettled, loopsSettled] = await Promise.allSettled([
-            recentFetch,
-            client.search(so.loopsQuery, {
-                limit: so.loopsLimit,
-                userId,
-            }),
-        ]);
-        const recentOk = recentSettled.status === "fulfilled";
-        const loopsOk = loopsSettled.status === "fulfilled";
-        const recent = recentOk ? recentSettled.value : [];
-        const loops = loopsOk ? loopsSettled.value : [];
-        if (!recentOk) {
-            log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
-        }
-        if (!loopsOk) {
-            log.error("startup-orientation: loops search failed", loopsSettled.reason);
+        // Skip when multiple speakers are present with no multiUser config.
+        // Orientation injects the primary user's personal activity context; in a
+        // group chat that leaks their private session history to other participants
+        // who may have triggered the session start (attribution v2, gap 2).
+        const sessionId = resolveCurrentSessionId(undefined, ctx);
+        if (!cfg.multiUser && isMultiSpeaker(sessionId, ctx?.is_group_chat === true)) {
+            log.debug("startup-orientation: skipping — multi-speaker session with no multiUser config (would expose primary user's personal context)");
+            if (sessionKey)
+                injectedSessions.add(sessionKey);
+            return;
         }
-        if (!recentOk && !loopsOk) {
+        const gathered = await gatherOrientation(client, cfg, userId);
+        if (!gathered.recentOk && !gathered.loopsOk) {
             if (sessionKey)
                 failedAttempts.set(sessionKey, tries + 1);
             log.debug(`startup-orientation: both calls failed (attempt ${tries + 1}/${MAX_ATTEMPTS}); will retry next turn`);
@@ -250,32 +305,12 @@ export function buildStartupOrientationHandler(client, cfg) {
             injectedSessions.add(sessionKey);
             failedAttempts.delete(sessionKey);
         }
-        const recentBody = formatRecentInteractions(recent);
-        const loopsBody = formatUnfinishedLoops(loops);
-        if (!recentBody && !loopsBody) {
+        if (!gathered.recentBlock && !gathered.loopsBlock) {
             log.debug("startup-orientation: nothing to inject");
             return;
         }
-        const blocks = [];
-        if (recentBody) {
-            blocks.push([
-                "<hyperspell-recent-interactions>",
-                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
-                "",
-                recentBody,
-                "</hyperspell-recent-interactions>",
-            ].join("\n"));
-        }
-        if (loopsBody) {
-            blocks.push([
-                "<hyperspell-unfinished-loops>",
-                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
-                "",
-                loopsBody,
-                "</hyperspell-unfinished-loops>",
-            ].join("\n"));
-        }
-        log.debug(`startup-orientation: injecting recent=${recent.length} loops=${loops.length}`);
+        const blocks = [gathered.recentBlock, gathered.loopsBlock].filter((b) => b !== null);
+        log.debug(`startup-orientation: injecting recent=${gathered.recentCount} loops=${gathered.loopsCount}`);
         return { prependContext: blocks.join("\n\n") };
     };
 }

package/dist/index.js

@@ -8,7 +8,9 @@ import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler,
 import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.js";
 import { buildHotBufferHandler, buildHotBufferSessionCleanupHandler, } from "./hooks/hot-buffer.js";
 import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
+import { isExcludedChannel } from "./lib/exclude-channels.js";
 import { initLogger, log } from "./logger.js";
+import { createEmotionalArcToolFactory } from "./tools/emotional-arc.js";
 import { createRememberToolFactory } from "./tools/remember.js";
 import { createSearchToolFactory } from "./tools/search.js";
 import { registerNetworkTools } from "./graph/index.js";
@@ -62,24 +64,56 @@ export default {
                     };
                 },
             });
+            api.registerCommand({
+                name: "previewcontext",
+                description: "Preview what Hyperspell would inject at the next session start",
+                acceptsArgs: false,
+                requireAuth: false,
+                handler: async () => {
+                    return {
+                        text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
+                    };
+                },
+            });
             return;
         }
         const cfg = parseConfig(api.pluginConfig);
         initLogger(api.logger, cfg.debug);
         const client = new HyperspellClient(cfg);
+        // Channel quarantine (cfg.excludeChannels): excluded conversations get no
+        // memory surface in either direction. Guard the shared choke points here —
+        // before_agent_start (all injection), agent_end (all writes), and the tool
+        // factories — so individual hooks stay quarantine-unaware.
+        const quarantined = (ctx) => {
+            if (!isExcludedChannel(ctx, cfg))
+                return false;
+            log.debug("channel quarantined — skipping memory surface");
+            return true;
+        };
+        const unlessQuarantined = (handler) => (event, ctx) => quarantined(ctx) ? undefined : handler(event, ctx);
+        const toolUnlessQuarantined = (factory) => (ctx) => quarantined(ctx) ? null : factory(ctx);
         // Register AI tools (factory pattern for sender context)
-        api.registerTool(createSearchToolFactory(client, cfg), {
+        api.registerTool(toolUnlessQuarantined(createSearchToolFactory(client, cfg)), {
             name: "hyperspell_search",
         });
-        api.registerTool(createRememberToolFactory(client, cfg), {
+        api.registerTool(toolUnlessQuarantined(createRememberToolFactory(client, cfg)), {
             name: "hyperspell_remember",
         });
         const startHandlers = [];
         if (cfg.emotionalContext) {
+            // moodWeatherChance defaults to 0, so mood weather is inert unless the
+            // operator opts in — say so once at startup rather than staying silent.
+            if (cfg.moodWeatherChance === 0) {
+                log.info("emotionalContext is on but moodWeatherChance is 0 — mood weather will never roll. Set moodWeatherChance (e.g. 0.03–0.05) to enable it.");
+            }
+            // On-demand arc re-fetch (issue #76): the session-start injection can be
+            // compacted out of history mid-session; this tool lets the agent pull the
+            // exact same block back without waiting for the next prompt build.
+            api.registerTool(toolUnlessQuarantined(createEmotionalArcToolFactory(client, cfg)), { name: "hyperspell_emotional_arc" });
             startHandlers.push(buildEmotionalStateFetchHandler(client, cfg));
             api.on("after_compaction", buildEmotionalStateCompactionHandler());
             api.on("session_end", buildEmotionalStateSessionCleanupHandler());
-            api.on("agent_end", buildEmotionalStateStoreHandler(client, cfg));
+            api.on("agent_end", unlessQuarantined(buildEmotionalStateStoreHandler(client, cfg)));
         }
         if (cfg.autoContext) {
             startHandlers.push(buildAutoContextHandler(client, cfg));
@@ -98,6 +132,9 @@ export default {
         }
         if (startHandlers.length > 0) {
             api.on("before_agent_start", async (event, ctx) => {
+                // Quarantined channels get no injected memory of any kind.
+                if (quarantined(ctx))
+                    return undefined;
                 const results = await Promise.all(startHandlers.map((h) => Promise.resolve()
                     .then(() => h(event, ctx))
                     .catch((err) => {
@@ -115,12 +152,12 @@ export default {
         }
         // Register auto-trace hook (send conversations to Hyperspell on session end)
         if (cfg.autoTrace.enabled) {
-            api.on("agent_end", buildAutoTraceHandler(client, cfg));
+            api.on("agent_end", unlessQuarantined(buildAutoTraceHandler(client, cfg)));
         }
         // Register hot-buffer hook: write each turn to POST /messages so it's
         // instantly full-text searchable (vs. the slow /memories embedding path).
         if (cfg.hotBuffer.enabled) {
-            api.on("agent_end", buildHotBufferHandler(client, cfg));
+            api.on("agent_end", unlessQuarantined(buildHotBufferHandler(client, cfg)));
             api.on("session_end", buildHotBufferSessionCleanupHandler());
         }
         // Register memory sync hook

package/dist/lib/eval-matchers.js

@@ -0,0 +1,49 @@
+/**
+ * Parse the JSONL fixture file: one JSON object per line; blank lines and
+ * `//` comment lines are ignored. Every fixture needs a query and at least
+ * one matcher — a matcher-less line would vacuously fail and look like a
+ * ranking problem, so reject it at parse time with the line number.
+ */
+export function parseFixtures(jsonl) {
+    const fixtures = [];
+    for (const [idx, line] of jsonl.split("\n").entries()) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("//"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`fixtures line ${idx + 1}: invalid JSON`);
+        }
+        const f = parsed;
+        if (typeof f.query !== "string" || f.query.trim() === "") {
+            throw new Error(`fixtures line ${idx + 1}: "query" is required`);
+        }
+        if (!f.expectedResourceId && !f.expectedTitleContains) {
+            throw new Error(`fixtures line ${idx + 1}: at least one of "expectedResourceId" / "expectedTitleContains" is required`);
+        }
+        fixtures.push(f);
+    }
+    return fixtures;
+}
+/**
+ * OR-semantics matcher (proposal §3.1): a result satisfies a fixture if the
+ * resourceId matches exactly, or the title/any highlight contains the
+ * expected substring (case-insensitive). Returns WHICH matcher hit so the
+ * runner can warn when only the title matched — the id may have churned.
+ */
+export function matchFixture(r, f) {
+    if (f.expectedResourceId && r.resourceId === f.expectedResourceId)
+        return "id";
+    if (f.expectedTitleContains) {
+        const needle = f.expectedTitleContains.toLowerCase();
+        const hay = [r.title ?? "", ...r.highlights.map((h) => h.text)]
+            .join(" ")
+            .toLowerCase();
+        if (hay.includes(needle))
+            return "title";
+    }
+    return null;
+}

package/dist/lib/exclude-channels.js

@@ -0,0 +1,70 @@
+/**
+ * Channel-level memory quarantine (`excludeChannels` config).
+ *
+ * A channel on the list gets NO memory surface at all, in both directions:
+ * no context injection (auto-context, emotional state, startup orientation),
+ * no memory writes (hot buffer, auto-trace, emotional store), and no memory
+ * tools. Use it for conversations that must never mix with the owner's vault —
+ * e.g. a channel someone else drives (a shared game, a public bot surface).
+ *
+ * Matching is against the conversation id OpenClaw resolves for the session
+ * (`ctx.channelId` on agent hook contexts — e.g. a Discord channel id). Tool
+ * factory contexts don't carry `channelId`, so we recover the same id from the
+ * composite `sessionKey` (`agent:<agentId>:<provider>:<kind>:<id>[...]`).
+ *
+ * Quarantine is FORWARD-ONLY: it stops future injection/writes/tools but does
+ * not remove already-synced content. Retroactive cleanup of channel-tagged
+ * rows is the `purge-channel` CLI command (commands/purge-channel.ts).
+ */
+// Conversation-kind segments used in OpenClaw session keys. Mirrors core's
+// TARGET_PREFIXES (src/plugins/hook-agent-context.ts) so the sessionKey
+// fallback resolves the same id core would put on ctx.channelId.
+const TARGET_KINDS = new Set(["channel", "chat", "direct", "dm", "group", "thread", "user"]);
+/**
+ * Extract the conversation id from a composite session key, e.g.
+ * `agent:main:discord:channel:123` → `123`. Thread/run suffixes stay attached
+ * (`...:channel:123:thread:456` → `123:thread:456`); the prefix match in
+ * `isExcludedChannel` handles them. Returns undefined when the key has no
+ * recognizable conversation segment (cron runs, bare UUIDs, ...).
+ */
+export function conversationIdFromSessionKey(sessionKey) {
+    if (typeof sessionKey !== "string" || sessionKey.length === 0)
+        return undefined;
+    const parts = sessionKey.split(":").filter((p) => p.length > 0);
+    const body = parts[0]?.toLowerCase() === "agent" && parts.length >= 3 ? parts.slice(2) : parts;
+    if (body.length >= 3 && TARGET_KINDS.has(body[1]?.toLowerCase() ?? "")) {
+        return body.slice(2).join(":");
+    }
+    return undefined;
+}
+/** Resolve the conversation id from any hook or tool-factory context. */
+export function channelIdFromCtx(ctx) {
+    const direct = ctx?.channelId;
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    return conversationIdFromSessionKey(ctx?.sessionKey);
+}
+/**
+ * True when a stored conversation id belongs to `channel` — exact match or a
+ * thread suffix (`<channel>:thread:<n>`), case-insensitive. Shared by the
+ * quarantine check and the purge-channel CLI so "what gets blocked" and "what
+ * gets purged" can never drift apart.
+ */
+export function conversationMatchesChannel(id, channel) {
+    const a = id.toLowerCase();
+    const b = channel.toLowerCase();
+    return a === b || a.startsWith(`${b}:`);
+}
+/**
+ * True when the context's conversation is quarantined. Purely subtractive on
+ * failure: an unresolvable id means "not excluded" — a session we can't place
+ * keeps normal memory behavior rather than silently losing it.
+ */
+export function isExcludedChannel(ctx, cfg) {
+    if (cfg.excludeChannels.length === 0)
+        return false;
+    const id = channelIdFromCtx(ctx);
+    if (!id)
+        return false;
+    return cfg.excludeChannels.some((entry) => conversationMatchesChannel(id, entry));
+}

package/dist/lib/filters.js

@@ -23,10 +23,12 @@
  * search (~1s observed live), and when auto-trace is off there are no `agent_end`
  * rows to hide, so the filter would cost latency on every turn for zero benefit.
  *
- * Do NOT instead try to positively tag hot rows via `POST /messages` metadata to
- * identify them: a `/messages` write carrying `metadata` is accepted (200) but
- * the row becomes NON-retrievable (verified live, post-#1921) — see the
- * hot-buffer hook, which writes content only.
+ * Hot rows ARE positively tagged (`openclaw_source: "hot_buffer"` plus
+ * session/channel ids — see the hot-buffer hook): metadata-carrying
+ * `/messages` rows were verified retrievable AND filterable live 2026-07-02
+ * (docs/filter-dialect-test.mjs). The `$ne` exclude keeps them because
+ * "hot_buffer" != "agent_end". (An earlier note here claimed metadata made
+ * hot rows non-retrievable — that predated the backend fix.)
  *
  * NOTE: an earlier version checked the top-level `source` field for
  * "openclaw_agent_end" — wrong on BOTH counts (the tag lives in metadata under

package/dist/lib/ranking.js

@@ -63,25 +63,54 @@ export function rerank(results, w) {
         .sort((a, b) => b._composite - a._composite);
 }
 /**
- * Choose which ranked results to inject: keep those clearing `threshold` on
- * their composite, cap CHATTER at `chatterQuota` regardless of score (so a
- * high-similarity echo can inform but never flood — the penalty bounds rank,
- * the quota bounds count), and stop at `maxResults`.
+ * One pass over ranked results, annotating each with its selection outcome.
+ * Same policy as selectRanked — which is now derived from this, so the two
+ * can never drift (proposal 02 §3a).
+ *
+ * Attribution order is deliberate: the threshold check comes first so a
+ * below-the-bar result is always attributed to "threshold" even when the
+ * max-results cap is already full; and a chatter item past the cap reads
+ * "max-results", not "chatter-quota" — it would have been cut regardless, so
+ * the quota was not the binding constraint (proposal 03 §3.2 semantics).
  */
-export function selectRanked(ranked, maxResults, threshold, chatterQuota) {
+export function explainSelection(ranked, maxResults, threshold, chatterQuota) {
     const out = [];
     let chatter = 0;
+    let kept = 0;
     for (const r of ranked) {
-        if (r._composite < threshold)
+        if (r._composite < threshold) {
+            out.push({ result: r, selected: false, cut: "threshold" });
+            continue;
+        }
+        if (kept >= maxResults) {
+            out.push({ result: r, selected: false, cut: "max-results" });
+            continue;
+        }
+        if (r._kind === "chatter" && chatter >= chatterQuota) {
+            out.push({ result: r, selected: false, cut: "chatter-quota" });
             continue;
-        if (r._kind === "chatter") {
-            if (chatter >= chatterQuota)
-                continue;
-            chatter++;
         }
-        out.push(r);
-        if (out.length >= maxResults)
-            break;
+        if (r._kind === "chatter")
+            chatter++;
+        kept++;
+        out.push({ result: r, selected: true, cut: null });
     }
     return out;
 }
+/**
+ * Choose which ranked results to inject: keep those clearing `threshold` on
+ * their composite, cap CHATTER at `chatterQuota` regardless of score (so a
+ * high-similarity echo can inform but never flood — the penalty bounds rank,
+ * the quota bounds count), and stop at `maxResults`.
+ *
+ * Signature and return shape are intentionally unchanged: the retrieval eval
+ * harness (proposal 17) and existing call sites depend on
+ * `selectRanked(ranked, maxResults, threshold, chatterQuota): RankedResult[]`.
+ * It is a thin projection of explainSelection so selection policy lives in
+ * exactly one place.
+ */
+export function selectRanked(ranked, maxResults, threshold, chatterQuota) {
+    return explainSelection(ranked, maxResults, threshold, chatterQuota)
+        .filter((e) => e.selected)
+        .map((e) => e.result);
+}

package/dist/lib/sender.js

@@ -4,9 +4,16 @@ import { getVoiceIdentifier } from "./voice-id.js";
 function matchFromSenderMap(ctx, cfg) {
     const multiUser = cfg.multiUser;
     if (!multiUser) {
-        return cfg.userId
-            ? { userId: cfg.userId, name: cfg.userId, resolved: true }
-            : undefined;
+        if (!cfg.userId)
+            return undefined;
+        // In single-user mode memory ownership stays cfg.userId, but still capture
+        // the envelope sender name so downstream context can name who spoke even
+        // when all writes go to the same store. resolved: false — this is a static
+        // default, not a confirmed sender match (issue #59).
+        const envName = ctx?.sender ??
+            ctx?.username ??
+            undefined;
+        return { userId: cfg.userId, name: envName ?? cfg.userId, resolved: false };
     }
     // Try direct senderId lookup (slash command contexts)
     const senderId = ctx?.senderId ??
@@ -17,13 +24,18 @@ function matchFromSenderMap(ctx, cfg) {
         log.debug(`sender resolved via senderId: ${senderId} -> ${profile.userId}`);
         return { ...profile, resolved: true };
     }
-    // Try sessionKey substring matching (longest-first to avoid partial matches)
+    // Try sessionKey segment matching (longest-first to avoid partial matches).
+    // We split on common separators and require the handle to appear as a whole
+    // token — not as a substring of another word — to prevent "ali" matching
+    // "alinea:voice-session-42". The senderId exact-match path above is always
+    // preferred; this path is a human-readable-handle fallback.
     const sessionKey = ctx?.sessionKey;
     if (sessionKey) {
+        const tokens = new Set(sessionKey.split(/[:\-\/\s@#.]+/));
         const sortedEntries = Object.entries(multiUser.senderMap).sort(([a], [b]) => b.length - a.length);
         for (const [handle, profile] of sortedEntries) {
-            if (sessionKey.includes(handle)) {
-                log.debug(`sender resolved via sessionKey: ${handle} -> ${profile.userId}`);
+            if (tokens.has(handle)) {
+                log.debug(`sender resolved via sessionKey token: ${handle} -> ${profile.userId}`);
                 return { ...profile, resolved: true };
             }
         }

package/dist/lib/speaker-tracker.js

@@ -0,0 +1,56 @@
+/**
+ * Per-session speaker tracking — evidence-based multi-speaker detection.
+ *
+ * PR #60 gated all group-chat guards on `is_group_chat: true` from the
+ * inbound envelope. That field is set by the platform connector and not all
+ * connectors set it consistently (Discord channels, Slack DM groups, voice
+ * rooms). This module tracks distinct sender_ids observed within each session
+ * so multi-speaker detection works from evidence rather than a connector
+ * boolean.
+ *
+ * Lifecycle:
+ *   - record() on every turn that has a resolvable senderId (hot-buffer agent_end,
+ *     auto-context before_agent_start)
+ *   - isMultiSpeaker() checked by any hook or tool that needs to guard behaviour
+ *   - cleanup() on session_end, called from the hot-buffer cleanup handler
+ */
+/** sessionId → set of distinct sender_ids seen in that session */
+const sessionSenders = new Map();
+/**
+ * Record a sender_id for a session. No-op if senderId is empty/undefined.
+ * Called on every turn so the tracker accumulates evidence across the session.
+ */
+export function recordSender(sessionId, senderId) {
+    if (!senderId)
+        return;
+    if (!sessionSenders.has(sessionId))
+        sessionSenders.set(sessionId, new Set());
+    sessionSenders.get(sessionId).add(senderId);
+}
+/**
+ * Resolve the senderId from a hook context, checking both camelCase
+ * (OpenClaw-normalised) and snake_case (raw connector form).
+ */
+export function senderIdFromCtx(ctx) {
+    return (ctx?.senderId ??
+        ctx?.sender_id ??
+        ctx?.requesterSenderId ??
+        undefined);
+}
+/**
+ * True when two or more distinct sender_ids have appeared in this session, OR
+ * when the connector explicitly signalled `is_group_chat: true`. Either is
+ * sufficient — the envelope flag catches cases before the second sender speaks;
+ * the tracker catches cases where the flag was never set.
+ */
+export function isMultiSpeaker(sessionId, envelopeGroupChat) {
+    if (envelopeGroupChat)
+        return true;
+    if (!sessionId)
+        return false;
+    return (sessionSenders.get(sessionId)?.size ?? 0) > 1;
+}
+/** Drop the per-session entry on session end to prevent unbounded growth. */
+export function cleanupSpeakerSession(sessionId) {
+    sessionSenders.delete(sessionId);
+}

package/dist/tools/emotional-arc.js

@@ -0,0 +1,60 @@
+import { Type } from "@sinclair/typebox";
+import { buildEmotionalContext, EMOTIONAL_ARC_LIMIT, fetchRecentOrLatest, looksLikeRawTranscript, } from "../hooks/emotional-state.js";
+import { log } from "../logger.js";
+/** Hard cap so the agent can't ask the backend for an unbounded history. */
+const MAX_ARC_LIMIT = 10;
+export function createEmotionalArcToolFactory(client, cfg) {
+    // No sender context needed: the register is keyed to cfg.relationshipId, not
+    // the current speaker — but keep the factory signature so toolUnlessQuarantined
+    // can wrap it like search/remember.
+    return (_ctx) => ({
+        name: "hyperspell_emotional_arc",
+        label: "Emotional Arc",
+        description: "Fetch the recent emotional arc of your relationship with this user — the same emotional-context block that is injected at session start. Use it when that block is no longer in your history (e.g. after the conversation was compacted) or when you genuinely want to reflect on how the relationship has been feeling before responding. Returns the most recent emotional registers, newest first. Let the trajectory inform your tone — don't recite it back to the user.",
+        parameters: Type.Object({
+            limit: Type.Optional(Type.Number({
+                description: `How many recent registers to fetch (default ${EMOTIONAL_ARC_LIMIT}, max ${MAX_ARC_LIMIT})`,
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            const limit = Math.min(Math.max(Math.floor(params.limit ?? EMOTIONAL_ARC_LIMIT), 1), MAX_ARC_LIMIT);
+            log.debug(`emotional-arc tool: limit=${limit} relationshipId=${cfg.relationshipId ?? "(default)"}`);
+            try {
+                const states = await fetchRecentOrLatest(client, cfg, limit);
+                // Same placeholder filter as the injection path: for ~10s after a
+                // store, the register can be the RAW input transcript (status=pending),
+                // not a distilled feeling. Returning that would pollute tone.
+                const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+                if (usable.length === 0) {
+                    const text = states.length > 0
+                        ? "The latest emotional register is still being extracted — try again in a few seconds."
+                        : "No emotional arc recorded yet for this relationship. It builds up as real conversations end.";
+                    return { content: [{ type: "text", text }] };
+                }
+                // Deliberately identical to the session-start injection block
+                // (buildEmotionalContext), so a post-compaction re-fetch restores
+                // exactly what a fresh session would have received. Mood weather is
+                // intentionally NOT included — it is an injection-only session
+                // override, rolled at most once per session; a tool call must never
+                // re-roll or reveal it (do not import from mood-weather.ts here).
+                return {
+                    content: [
+                        { type: "text", text: buildEmotionalContext(usable) },
+                    ],
+                    details: { count: usable.length },
+                };
+            }
+            catch (err) {
+                log.error("emotional-arc tool failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to fetch emotional arc: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}