openclaw-topic-shift-reset 0.3.0 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 OpenClaw plugin that detects topic shifts and rotates to a fresh session automatically.
 
+Classifier input sources: inbound user message text (`message_received`) and successful outbound agent message text (`message_sent`) only. It does not classify `before_model_resolve` prompt wrappers.
+
 ## Why this plugin exists
 
 OpenClaw builds each model call with the current prompt plus session history. As one session accumulates mixed topics, prompts get larger, token usage grows, and context-overflow/compaction pressure increases.
@@ -130,6 +132,59 @@ When the classifier sees a soft topic-shift signal (`suspect`) but not enough co
 openclaw logs --follow --plain | rg topic-shift-reset
 ```
 
+## Log reference
+
+All plugin logs are prefixed with `topic-shift-reset:`.
+
+### Info
+
+- `embedding backend <name>`
+  Embeddings are active (`openai:*` or `ollama:*` backend).
+- `embedding backend unavailable, using lexical-only mode`
+  No embedding backend is available; lexical signals only.
+- `restored state sessions=<n> rotations=<n>`
+  Persisted runtime state restored at startup.
+- `would-rotate source=<user|agent> reason=<...> session=<...> ...`
+  Dry-run rotation decision; no session mutation is written.
+- `rotated source=<user|agent> reason=<...> session=<...> ... handoff=<0|1>`
+  Rotation executed (new `sessionId` written). `handoff=1` means handoff context was enqueued.
+
+### Debug (`debug: true`)
+
+- `classify source=<...> kind=<warmup|stable|suspect|rotate-hard|rotate-soft> reason=<...> ...`
+  Full classifier output and metrics for a processed message.
+- `skip-internal-provider source=<...> provider=<...> session=<...>`
+  Skipped event from internal/non-user provider (for example cron/system paths).
+- `skip-low-signal source=<...> session=<...> chars=<n> tokens=<n>`
+  Skipped message because it did not meet minimum signal thresholds.
+- `user-route-skip channel=<...> peer=<...> err=<...>`
+  User-message route resolution failed, so the inbound event was ignored.
+- `agent-route-skip channel=<...> peer=<...> err=<...>`
+  Agent-message route resolution failed, so the outbound event was ignored.
+- `state-flushed reason=<scheduled|urgent|gateway-stop> sessions=<n> rotations=<n>`
+  In-memory classifier state flushed to persistence storage.
+
+### Warn
+
+- `rotate failed no-session-entry session=<...>`
+  Rotation was requested but no matching session entry was found to mutate.
+- `handoff tail fallback full-read file=<...>`
+  Tail read optimization fell back to a full transcript read.
+- `handoff read failed file=<...> err=<...>`
+  Could not read prior session transcript for handoff injection.
+- `persistence disabled (state path): <err>`
+  Plugin could not resolve state path; persistence is disabled.
+- `state flush failed err=<...>`
+  Failed to write persistent state.
+- `state restore failed err=<...>`
+  Failed to read/parse persistent state.
+- `state version mismatch expected=<...> got=<...>; ignoring persisted state`
+  Stored persistence schema version differs; old state is ignored.
+- `embedding backend init failed: <err>`
+  Embedding backend initialization failed at startup.
+- `embeddings error backend=<name> err=<...>`
+  Runtime embedding request failed for a message; processing continues.
+
 ## Advanced tuning
 
 Use `config.advanced` only if needed. Full reference:
@@ -155,4 +210,4 @@ No build step is required. OpenClaw loads `src/index.ts` via jiti.
 
 ## Known tradeoff (plugin-only)
 
-This plugin improves timing with fast path + fallback, but cannot guarantee 100% that the triggering message becomes the first persisted message of the new session without core pre-session hooks.
+This plugin cannot guarantee 100% that the triggering message becomes the first persisted message of the new session because resets happen in runtime hooks and provider pipelines vary.

package/docs/configuration.md

@@ -28,6 +28,8 @@ This plugin now accepts one canonical key per concept:
 
 ## Public options
 
+Classifier inputs are limited to inbound user message text and successful outbound agent message text.
+
 - `enabled`: plugin on/off.
 - `preset`: `conservative | balanced | aggressive`.
 - `embedding.provider`: `auto | openai | ollama | none`.
@@ -128,7 +130,7 @@ Advanced keys:
 `ignoredProviders` expects canonical provider IDs:
 
 - `telegram`, `whatsapp`, `signal`, `discord`, `slack`, `matrix`, `msteams`, `imessage`, `web`, `voice`
-- model/provider IDs like `openai`, `anthropic`, `ollama` (for fallback hook contexts)
+- internal/system-style providers like `cron-event`, `heartbeat`, `exec-event`
 
 ## Migration note
 
@@ -145,14 +147,14 @@ Legacy alias keys are not supported in this release. Config validation fails if
 Classifier runtime state is persisted automatically under the OpenClaw state directory (`plugins/<plugin-id>/runtime-state.v1.json`).
 
 - Persisted: per-session topic history, pending soft-signal windows, topic centroid, rotation dedupe map.
-- Not persisted: transient fast-event dedupe cache.
+- Not persisted: transient message-event dedupe cache.
 - No extra config is required.
 
 ## Log interpretation
 
 Classifier logs look like:
 
-`topic-shift-reset: classify source=<fast|fallback> kind=<...> reason=<...> ...`
+`topic-shift-reset: classify source=<user|agent> kind=<...> reason=<...> ...`
 
 Kinds:
 
@@ -167,4 +169,4 @@ Other lines:
 - `skip-low-signal`: message skipped by hard signal floor (`minSignalChars`/`minSignalTokenCount`).
 - `would-rotate`: `dryRun=true` synthetic rotate event (no reset mutation).
 - `rotated`: actual session rotation happened.
-- `classify` / `skip-low-signal` / `skip-cross-path-duplicate`: debug-level diagnostics (`debug=true`).
+- `classify` / `skip-low-signal` / `user-route-skip` / `agent-route-skip`: debug-level diagnostics (`debug=true`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-topic-shift-reset",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "OpenClaw plugin that detects topic shifts and starts a fresh session automatically.",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -211,6 +211,8 @@ type FastMessageEventLike = {
   metadata?: Record<string, unknown>;
 };
 
+type ClassificationSource = "user" | "agent";
+
 type TranscriptMessage = {
   role: string;
   text: string;
@@ -320,10 +322,9 @@ const LOCK_OPTIONS = {
 
 const MAX_TRACKED_SESSIONS = 10_000;
 const STALE_SESSION_STATE_MS = 4 * 60 * 60 * 1000;
-const MAX_RECENT_FAST_EVENTS = 20_000;
-const FAST_EVENT_TTL_MS = 5 * 60 * 1000;
+const MAX_RECENT_MESSAGE_EVENTS = 20_000;
+const MESSAGE_EVENT_TTL_MS = 5 * 60 * 1000;
 const ROTATION_DEDUPE_MS = 25_000;
-const CROSS_PATH_DEDUPE_MS = 15_000;
 const PERSISTENCE_SCHEMA_VERSION = 1;
 const PERSISTENCE_FILE_NAME = "runtime-state.v1.json";
 const PERSISTENCE_FLUSH_DEBOUNCE_MS = 1_200;
@@ -1556,40 +1557,12 @@ function pruneRecentMap(map: Map<string, number>, ttlMs: number, maxSize: number
   return changed;
 }
 
-function pruneRecentClassifiedMap(
-  map: Map<string, { at: number; source: "fast" | "fallback" }>,
-  ttlMs: number,
-  maxSize: number,
-): boolean {
-  let changed = false;
-  const now = Date.now();
-  for (const [key, value] of map) {
-    if (now - value.at > ttlMs) {
-      map.delete(key);
-      changed = true;
-    }
-  }
-  if (map.size <= maxSize) {
-    return changed;
-  }
-  const ordered = [...map.entries()].sort((a, b) => a[1].at - b[1].at);
-  const toDrop = map.size - maxSize;
-  for (let i = 0; i < toDrop; i += 1) {
-    const key = ordered[i]?.[0];
-    if (key) {
-      map.delete(key);
-      changed = true;
-    }
-  }
-  return changed;
-}
-
 async function rotateSessionEntry(params: {
   api: OpenClawPluginApi;
   cfg: ResolvedConfig;
   sessionKey: string;
   agentId?: string;
-  source: "fast" | "fallback";
+  source: ClassificationSource;
   reason: string;
   metrics: ClassifierMetrics;
   entry: HistoryEntry;
@@ -1694,13 +1667,10 @@ async function rotateSessionEntry(params: {
 export default function register(api: OpenClawPluginApi): void {
   const cfg = resolveConfig(api.pluginConfig);
   const sessionState = new Map<string, SessionState>();
-  const recentFastEvents = new Map<string, number>();
+  const recentUserEvents = new Map<string, number>();
+  const recentAgentEvents = new Map<string, number>();
   const recentRotationBySession = new Map<string, number>();
   const pendingSoftSuspectSteeringBySession = new Map<string, number>();
-  const recentClassifiedBySessionHash = new Map<
-    string,
-    { at: number; source: "fast" | "fallback" }
-  >();
   const sessionWorkQueue = new Map<string, Promise<unknown>>();
 
   const persistencePath = (() => {
@@ -1741,7 +1711,7 @@ export default function register(api: OpenClawPluginApi): void {
     persistenceFlushPromise = (async () => {
       const now = Date.now();
       pruneStateMaps(sessionState);
-      pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
+      pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_MESSAGE_EVENTS);
 
       const payload: PersistedRuntimeState = {
         version: PERSISTENCE_SCHEMA_VERSION,
@@ -1866,7 +1836,7 @@ export default function register(api: OpenClawPluginApi): void {
         }
         recentRotationBySession.set(key, Math.floor(ts));
       }
-      pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
+      pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_MESSAGE_EVENTS);
 
       api.logger.info(
         `topic-shift-reset: restored state sessions=${sessionState.size} rotations=${recentRotationBySession.size}`,
@@ -1893,7 +1863,7 @@ export default function register(api: OpenClawPluginApi): void {
   }
 
   const classifyAndMaybeRotateInner = async (params: {
-    source: "fast" | "fallback";
+    source: ClassificationSource;
     sessionKey: string;
     text: string;
     messageProvider?: string;
@@ -1947,28 +1917,6 @@ export default function register(api: OpenClawPluginApi): void {
 
     const now = Date.now();
     const contentHash = hashString(normalizeTextForHash(text));
-    const classifyDedupeKey = `${sessionKey}:${contentHash}`;
-    const recentCrossSourceClassification = recentClassifiedBySessionHash.get(classifyDedupeKey);
-    if (
-      recentCrossSourceClassification &&
-      recentCrossSourceClassification.source !== params.source &&
-      now - recentCrossSourceClassification.at < CROSS_PATH_DEDUPE_MS
-    ) {
-      if (cfg.debug) {
-        api.logger.debug(
-          [
-            `topic-shift-reset: skip-cross-path-duplicate`,
-            `session=${sessionKey}`,
-            `source=${params.source}`,
-            `prevSource=${recentCrossSourceClassification.source}`,
-          ].join(" "),
-        );
-      }
-      return;
-    }
-    recentClassifiedBySessionHash.set(classifyDedupeKey, { at: now, source: params.source });
-    pruneRecentClassifiedMap(recentClassifiedBySessionHash, CROSS_PATH_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
-
     const lastRotationAt = recentRotationBySession.get(`${sessionKey}:${contentHash}`);
     if (typeof lastRotationAt === "number" && now - lastRotationAt < ROTATION_DEDUPE_MS) {
       return;
@@ -2089,7 +2037,7 @@ export default function register(api: OpenClawPluginApi): void {
         pruneRecentMap(
           pendingSoftSuspectSteeringBySession,
           Math.max(cfg.softSuspect.ttlMs * 2, 60_000),
-          MAX_RECENT_FAST_EVENTS,
+          MAX_RECENT_MESSAGE_EVENTS,
         );
       }
       state.pendingSoftSignals += 1;
@@ -2129,7 +2077,7 @@ export default function register(api: OpenClawPluginApi): void {
     const prunedRotations = pruneRecentMap(
       recentRotationBySession,
       ROTATION_DEDUPE_MS * 3,
-      MAX_RECENT_FAST_EVENTS,
+      MAX_RECENT_MESSAGE_EVENTS,
     );
     if (prunedRotations) {
       schedulePersistentFlush(false);
@@ -2137,7 +2085,7 @@ export default function register(api: OpenClawPluginApi): void {
   };
 
   const classifyAndMaybeRotate = async (params: {
-    source: "fast" | "fallback";
+    source: ClassificationSource;
     sessionKey: string;
     text: string;
     messageProvider?: string;
@@ -2170,19 +2118,19 @@ export default function register(api: OpenClawPluginApi): void {
       return;
     }
 
-    const fastEventKey = [
+    const userEventKey = [
       channelId,
       ctx.accountId ?? "",
       peer.kind,
       peer.id,
       hashString(normalizeTextForHash(text)),
     ].join("|");
-    const seenAt = recentFastEvents.get(fastEventKey);
-    if (typeof seenAt === "number" && Date.now() - seenAt < FAST_EVENT_TTL_MS) {
+    const seenAt = recentUserEvents.get(userEventKey);
+    if (typeof seenAt === "number" && Date.now() - seenAt < MESSAGE_EVENT_TTL_MS) {
       return;
     }
-    recentFastEvents.set(fastEventKey, Date.now());
-    pruneRecentMap(recentFastEvents, FAST_EVENT_TTL_MS, MAX_RECENT_FAST_EVENTS);
+    recentUserEvents.set(userEventKey, Date.now());
+    pruneRecentMap(recentUserEvents, MESSAGE_EVENT_TTL_MS, MAX_RECENT_MESSAGE_EVENTS);
 
     let resolvedSessionKey = "";
     let resolvedAgentId: string | undefined;
@@ -2198,14 +2146,14 @@ export default function register(api: OpenClawPluginApi): void {
     } catch (error) {
       if (cfg.debug) {
         api.logger.debug(
-          `topic-shift-reset: fast-route-skip channel=${channelId} peer=${maybeJson(peer)} err=${String(error)}`,
+          `topic-shift-reset: user-route-skip channel=${channelId} peer=${maybeJson(peer)} err=${String(error)}`,
         );
       }
       return;
     }
 
     await classifyAndMaybeRotate({
-      source: "fast",
+      source: "user",
       sessionKey: resolvedSessionKey,
       text,
       messageProvider: channelId,
@@ -2213,21 +2161,63 @@ export default function register(api: OpenClawPluginApi): void {
     });
   });
 
-  api.on("before_model_resolve", async (event, ctx) => {
+  api.on("message_sent", async (event, ctx) => {
     if (!cfg.enabled) {
       return;
     }
-    const sessionKey = ctx.sessionKey?.trim();
-    if (!sessionKey) {
+    if (!event.success) {
+      return;
+    }
+    const channelId = ctx.channelId?.trim();
+    if (!channelId) {
+      return;
+    }
+    const text = event.content?.trim() ?? "";
+    if (!text) {
+      return;
+    }
+
+    const peer = inferFastPeer({ from: event.to }, { conversationId: ctx.conversationId });
+    const agentEventKey = [
+      channelId,
+      ctx.accountId ?? "",
+      peer.kind,
+      peer.id,
+      hashString(normalizeTextForHash(text)),
+    ].join("|");
+    const seenAt = recentAgentEvents.get(agentEventKey);
+    if (typeof seenAt === "number" && Date.now() - seenAt < MESSAGE_EVENT_TTL_MS) {
+      return;
+    }
+    recentAgentEvents.set(agentEventKey, Date.now());
+    pruneRecentMap(recentAgentEvents, MESSAGE_EVENT_TTL_MS, MAX_RECENT_MESSAGE_EVENTS);
+
+    let resolvedSessionKey = "";
+    let resolvedAgentId: string | undefined;
+    try {
+      const route = api.runtime.channel.routing.resolveAgentRoute({
+        cfg: api.config,
+        channel: channelId,
+        accountId: ctx.accountId,
+        peer,
+      });
+      resolvedSessionKey = route.sessionKey;
+      resolvedAgentId = route.agentId;
+    } catch (error) {
+      if (cfg.debug) {
+        api.logger.debug(
+          `topic-shift-reset: agent-route-skip channel=${channelId} peer=${maybeJson(peer)} err=${String(error)}`,
+        );
+      }
       return;
     }
 
     await classifyAndMaybeRotate({
-      source: "fallback",
-      sessionKey,
-      text: event.prompt,
-      messageProvider: ctx.messageProvider,
-      agentId: ctx.agentId,
+      source: "agent",
+      sessionKey: resolvedSessionKey,
+      text,
+      messageProvider: channelId,
+      agentId: resolvedAgentId,
     });
   });