openclaw-topic-shift-reset 0.4.0 → 0.4.2

package/README.md

@@ -47,6 +47,7 @@ Add this plugin entry in `~/.openclaw/openclaw.json` (or merge into your existin
           },
           "softSuspect": {
             "action": "ask",
+            "mode": "strict",
             "ttlSeconds": 120
           },
           "dryRun": false,
@@ -116,6 +117,7 @@ When the classifier sees a soft topic-shift signal (`suspect`) but not enough co
 {
   "softSuspect": {
     "action": "ask",
+    "mode": "strict",
     "prompt": "Potential topic shift detected. Ask one short clarification question to confirm the user's new goal before proceeding.",
     "ttlSeconds": 120
   }
@@ -123,6 +125,7 @@ When the classifier sees a soft topic-shift signal (`suspect`) but not enough co
 ```
 
 - `action`: `ask` (default) or `none`.
+- `mode`: `strict` (default, require clarification turn before soft-confirm reset) or `best_effort` (legacy timing-based behavior).
 - `prompt`: optional custom steer text.
 - `ttlSeconds`: max age before a pending steer expires.
 
@@ -151,8 +154,16 @@ All plugin logs are prefixed with `topic-shift-reset:`.
 
 ### Debug (`debug: true`)
 
-- `classify source=<...> kind=<warmup|stable|suspect|rotate-hard|rotate-soft> reason=<...> ...`
-  Full classifier output and metrics for a processed message.
+- `classify source=<...> kind=<warmup|stable|suspect|rotate-hard|rotate-soft> reason=<...> ... textHash=<...> tokens=[...] text="..."`
+  Full classifier output and metrics plus a compact message preview for a processed message.
+- `suspect-queued session=<...>`
+  Soft-suspect state queued for clarification steering.
+- `ask-injected session=<...>`
+  Clarification steer was injected into prompt build for this session.
+- `ask-resolved user-reply session=<...>`
+  A new user reply arrived after the injected clarification turn.
+- `ask-blocked-waiting-injection session=<...>`
+  Strict mode prevented soft-confirm reset until clarification steer is injected.
 - `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>`

package/docs/configuration.md

@@ -19,6 +19,7 @@ This plugin now accepts one canonical key per concept:
   },
   "softSuspect": {
     "action": "ask",
+    "mode": "strict",
     "ttlSeconds": 120
   },
   "dryRun": false,
@@ -29,6 +30,7 @@ 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.
+With `softSuspect.mode: "strict"` (default), a soft-confirm reset is blocked until a clarification steer is injected and a subsequent user reply is observed.
 
 - `enabled`: plugin on/off.
 - `preset`: `conservative | balanced | aggressive`.
@@ -41,10 +43,11 @@ Classifier inputs are limited to inbound user message text and successful outbou
 - `handoff.lastN`: number of transcript messages to include in handoff.
 - `handoff.maxChars`: per-message truncation cap in handoff text.
 - `softSuspect.action`: `ask | none`.
+- `softSuspect.mode`: `strict | best_effort`.
 - `softSuspect.prompt`: optional steer text injected on soft-suspect.
 - `softSuspect.ttlSeconds`: expiry for pending soft-suspect steer.
 - `dryRun`: logs would-rotate events without session resets.
-- `debug`: emits per-message classifier diagnostics.
+- `debug`: emits per-message classifier diagnostics, including compact message previews.
 
 ## Built-in preset defaults
 
@@ -71,6 +74,7 @@ Classifier inputs are limited to inbound user message text and successful outbou
 - `handoff.lastN`: `6`
 - `handoff.maxChars`: `220`
 - `softSuspect.action`: `ask`
+- `softSuspect.mode`: `strict`
 - `softSuspect.ttlSeconds`: `120`
 - `advanced.minSignalChars`: `20`
 - `advanced.minSignalTokenCount`: `3`

package/openclaw.plugin.json

@@ -73,6 +73,11 @@
             "enum": ["none", "ask"],
             "default": "ask"
           },
+          "mode": {
+            "type": "string",
+            "enum": ["strict", "best_effort"],
+            "default": "strict"
+          },
           "prompt": {
             "type": "string",
             "default": "Potential topic shift detected. Ask one short clarification question to confirm the user's new goal before proceeding."
@@ -268,7 +273,7 @@
     },
     "softSuspect": {
       "label": "Soft-Suspect Clarification",
-      "help": "When a soft topic-shift signal appears, optionally steer the model to ask one clarification question before proceeding."
+      "help": "strict = require one clarification turn before soft-confirm reset. best_effort = steer when possible."
     },
     "dryRun": {
       "label": "Dry Run",

package/package.json

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

package/src/index.ts

@@ -12,6 +12,7 @@ type PresetName = "conservative" | "balanced" | "aggressive";
 type EmbeddingProvider = "auto" | "none" | "openai" | "ollama";
 type HandoffMode = "none" | "summary" | "verbatim_last_n";
 type SoftSuspectAction = "none" | "ask";
+type SoftSuspectMode = "best_effort" | "strict";
 
 type EmbeddingConfig = {
   provider?: EmbeddingProvider;
@@ -29,6 +30,7 @@ type HandoffConfig = {
 
 type SoftSuspectConfig = {
   action?: SoftSuspectAction;
+  mode?: SoftSuspectMode;
   prompt?: string;
   ttlSeconds?: number;
 };
@@ -110,6 +112,7 @@ type ResolvedConfig = {
   };
   softSuspect: {
     action: SoftSuspectAction;
+    mode: SoftSuspectMode;
     prompt: string;
     ttlMs: number;
   };
@@ -285,6 +288,7 @@ const DEFAULTS = {
   handoffLastN: 6,
   handoffMaxChars: 220,
   softSuspectAction: "ask" as SoftSuspectAction,
+  softSuspectMode: "strict" as SoftSuspectMode,
   softSuspectPrompt:
     "Potential topic shift detected. Ask one short clarification question to confirm the user's new goal before proceeding.",
   softSuspectTtlSeconds: 120,
@@ -325,6 +329,8 @@ const STALE_SESSION_STATE_MS = 4 * 60 * 60 * 1000;
 const MAX_RECENT_MESSAGE_EVENTS = 20_000;
 const MESSAGE_EVENT_TTL_MS = 5 * 60 * 1000;
 const ROTATION_DEDUPE_MS = 25_000;
+const DEBUG_LOG_TEXT_PREVIEW_CHARS = 180;
+const DEBUG_LOG_TOKEN_PREVIEW_COUNT = 12;
 const PERSISTENCE_SCHEMA_VERSION = 1;
 const PERSISTENCE_FILE_NAME = "runtime-state.v1.json";
 const PERSISTENCE_FLUSH_DEBOUNCE_MS = 1_200;
@@ -408,6 +414,17 @@ function normalizeSoftSuspectAction(value: unknown): SoftSuspectAction {
   return DEFAULTS.softSuspectAction;
 }
 
+function normalizeSoftSuspectMode(value: unknown): SoftSuspectMode {
+  if (typeof value !== "string") {
+    return DEFAULTS.softSuspectMode;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "best_effort" || normalized === "strict") {
+    return normalized;
+  }
+  return DEFAULTS.softSuspectMode;
+}
+
 function compileRegexList(values: unknown, fallback: readonly string[]): RegExp[] {
   const source = Array.isArray(values) ? values : fallback;
   const out: RegExp[] = [];
@@ -790,6 +807,7 @@ function resolveConfig(raw: unknown): ResolvedConfig {
     },
     softSuspect: {
       action: normalizeSoftSuspectAction(softSuspect.action),
+      mode: normalizeSoftSuspectMode(softSuspect.mode),
       prompt:
         typeof softSuspect.prompt === "string" && softSuspect.prompt.trim()
           ? softSuspect.prompt.trim()
@@ -1671,8 +1689,14 @@ export default function register(api: OpenClawPluginApi): void {
   const recentAgentEvents = new Map<string, number>();
   const recentRotationBySession = new Map<string, number>();
   const pendingSoftSuspectSteeringBySession = new Map<string, number>();
+  const awaitingSoftSuspectReplyBySession = new Map<string, number>();
   const sessionWorkQueue = new Map<string, Promise<unknown>>();
 
+  const clearSoftSuspectSteerState = (sessionKey: string) => {
+    pendingSoftSuspectSteeringBySession.delete(sessionKey);
+    awaitingSoftSuspectReplyBySession.delete(sessionKey);
+  };
+
   const persistencePath = (() => {
     try {
       const stateDir = api.runtime.state.resolveStateDir();
@@ -1914,8 +1938,9 @@ export default function register(api: OpenClawPluginApi): void {
     }
 
     const tokens = new Set(tokenList);
-
     const now = Date.now();
+    const entry: HistoryEntry = { tokens, at: now };
+
     const contentHash = hashString(normalizeTextForHash(text));
     const lastRotationAt = recentRotationBySession.get(`${sessionKey}:${contentHash}`);
     if (typeof lastRotationAt === "number" && now - lastRotationAt < ROTATION_DEDUPE_MS) {
@@ -1935,10 +1960,41 @@ export default function register(api: OpenClawPluginApi): void {
       } satisfies SessionState);
     state.lastSeenAt = now;
 
+    if (params.source === "agent") {
+      // Outbound agent text helps keep topic context fresh, but it should not
+      // advance soft-suspect confirmation state by itself.
+      state.history = trimHistory([...state.history, entry], cfg.historyWindow);
+      updateTopicCentroid(state, entry.embedding);
+      sessionState.set(sessionKey, state);
+      pruneStateMaps(sessionState);
+      schedulePersistentFlush(false);
+      return;
+    }
+
+    const pendingSoftSteerAt = pendingSoftSuspectSteeringBySession.get(sessionKey);
+    const pendingSoftSteerActive =
+      typeof pendingSoftSteerAt === "number" && now - pendingSoftSteerAt <= cfg.softSuspect.ttlMs;
+    if (typeof pendingSoftSteerAt === "number" && !pendingSoftSteerActive) {
+      pendingSoftSuspectSteeringBySession.delete(sessionKey);
+    }
+
+    const awaitingSoftReplyAt = awaitingSoftSuspectReplyBySession.get(sessionKey);
+    const awaitingSoftReplyActive =
+      typeof awaitingSoftReplyAt === "number" && now - awaitingSoftReplyAt <= cfg.softSuspect.ttlMs;
+    if (typeof awaitingSoftReplyAt === "number" && !awaitingSoftReplyActive) {
+      awaitingSoftSuspectReplyBySession.delete(sessionKey);
+    }
+    if (awaitingSoftReplyActive) {
+      awaitingSoftSuspectReplyBySession.delete(sessionKey);
+      if (cfg.debug) {
+        api.logger.debug(`topic-shift-reset: ask-resolved user-reply session=${sessionKey}`);
+      }
+    }
+
     const baselineTokens = unionTokens(state.history);
     const lexical = computeLexicalFeatures({
       cfg,
-      entry: { tokens, at: now },
+      entry,
       tokenList,
       baselineTokens,
     });
@@ -1969,12 +2025,14 @@ export default function register(api: OpenClawPluginApi): void {
       }
     }
 
-    const entry: HistoryEntry = { tokens, embedding, at: now };
+    if (Array.isArray(embedding) && embedding.length > 0) {
+      entry.embedding = embedding;
+    }
     const similarity =
       entry.embedding && state.topicCentroid
         ? cosineSimilarity(entry.embedding, state.topicCentroid)
         : undefined;
-    const decision = classifyMessage({
+    let decision = classifyMessage({
       cfg,
       state,
       baselineTokenCount: baselineTokens.size,
@@ -1984,28 +2042,52 @@ export default function register(api: OpenClawPluginApi): void {
       now,
     });
 
+    if (
+      cfg.softSuspect.action === "ask" &&
+      cfg.softSuspect.mode === "strict" &&
+      pendingSoftSteerActive &&
+      decision.kind === "rotate-soft"
+    ) {
+      if (cfg.debug) {
+        api.logger.debug(`topic-shift-reset: ask-blocked-waiting-injection session=${sessionKey}`);
+      }
+      decision = {
+        kind: "suspect",
+        reason: "soft-suspect-awaiting-ask",
+        metrics: decision.metrics,
+      };
+    }
+
     if (cfg.debug) {
-      api.logger.debug(
-        [
-          `topic-shift-reset: classify`,
-          `source=${params.source}`,
-          `kind=${decision.kind}`,
-          `reason=${decision.reason}`,
-          `session=${sessionKey}`,
-          `score=${decision.metrics.score.toFixed(3)}`,
-          `novelty=${decision.metrics.novelty.toFixed(3)}`,
-          `lex=${decision.metrics.lexicalDistance.toFixed(3)}`,
-          `uniq=${decision.metrics.uniqueTokenRatio.toFixed(3)}`,
-          `entropy=${decision.metrics.entropy.toFixed(3)}`,
-          `sim=${typeof decision.metrics.similarity === "number" ? decision.metrics.similarity.toFixed(3) : "n/a"}`,
-          `embed=${decision.metrics.usedEmbedding ? "1" : "0"}`,
-          `pending=${state.pendingSoftSignals}`,
-        ].join(" "),
-      );
+      const textPreview = truncateText(text, DEBUG_LOG_TEXT_PREVIEW_CHARS);
+      const rawPreview = truncateText(rawText, DEBUG_LOG_TEXT_PREVIEW_CHARS);
+      const debugFields = [
+        `topic-shift-reset: classify`,
+        `source=${params.source}`,
+        `kind=${decision.kind}`,
+        `reason=${decision.reason}`,
+        `session=${sessionKey}`,
+        `score=${decision.metrics.score.toFixed(3)}`,
+        `novelty=${decision.metrics.novelty.toFixed(3)}`,
+        `lex=${decision.metrics.lexicalDistance.toFixed(3)}`,
+        `uniq=${decision.metrics.uniqueTokenRatio.toFixed(3)}`,
+        `entropy=${decision.metrics.entropy.toFixed(3)}`,
+        `sim=${typeof decision.metrics.similarity === "number" ? decision.metrics.similarity.toFixed(3) : "n/a"}`,
+        `embed=${decision.metrics.usedEmbedding ? "1" : "0"}`,
+        `pending=${state.pendingSoftSignals}`,
+        `baseline=${baselineTokens.size}`,
+        `textHash=${contentHash}`,
+        `tokens=${maybeJson(tokenList.slice(0, DEBUG_LOG_TOKEN_PREVIEW_COUNT))}`,
+        `text=${maybeJson(textPreview)}`,
+      ];
+      if (rawPreview !== textPreview) {
+        debugFields.push(`raw=${maybeJson(rawPreview)}`);
+      }
+      api.logger.debug(debugFields.join(" "));
     }
 
     if (decision.kind === "warmup") {
-      pendingSoftSuspectSteeringBySession.delete(sessionKey);
+      clearSoftSuspectSteerState(sessionKey);
       state.pendingSoftSignals = 0;
       state.pendingEntries = [];
       state.history = trimHistory([...state.history, entry], cfg.historyWindow);
@@ -2017,7 +2099,7 @@ export default function register(api: OpenClawPluginApi): void {
     }
 
     if (decision.kind === "stable") {
-      pendingSoftSuspectSteeringBySession.delete(sessionKey);
+      clearSoftSuspectSteerState(sessionKey);
       const merged = [...state.history, ...state.pendingEntries, entry];
       for (const item of [...state.pendingEntries, entry]) {
         updateTopicCentroid(state, item.embedding);
@@ -2039,6 +2121,9 @@ export default function register(api: OpenClawPluginApi): void {
           Math.max(cfg.softSuspect.ttlMs * 2, 60_000),
           MAX_RECENT_MESSAGE_EVENTS,
         );
+        if (cfg.debug) {
+          api.logger.debug(`topic-shift-reset: suspect-queued session=${sessionKey}`);
+        }
       }
       state.pendingSoftSignals += 1;
       state.pendingEntries = trimHistory([...state.pendingEntries, entry], cfg.softConsecutiveSignals);
@@ -2065,7 +2150,7 @@ export default function register(api: OpenClawPluginApi): void {
     });
 
     if (rotated) {
-      pendingSoftSuspectSteeringBySession.delete(sessionKey);
+      clearSoftSuspectSteerState(sessionKey);
       if (!cfg.dryRun) {
         recentRotationBySession.set(`${sessionKey}:${contentHash}`, Date.now());
       }
@@ -2229,15 +2314,36 @@ export default function register(api: OpenClawPluginApi): void {
     if (!sessionKey) {
       return;
     }
+    const now = Date.now();
+    const awaitingAt = awaitingSoftSuspectReplyBySession.get(sessionKey);
+    if (typeof awaitingAt === "number") {
+      if (now - awaitingAt > cfg.softSuspect.ttlMs) {
+        awaitingSoftSuspectReplyBySession.delete(sessionKey);
+      }
+      return;
+    }
+
     const seenAt = pendingSoftSuspectSteeringBySession.get(sessionKey);
     if (typeof seenAt !== "number") {
       return;
     }
-    if (Date.now() - seenAt > cfg.softSuspect.ttlMs) {
+    if (now - seenAt > cfg.softSuspect.ttlMs) {
       pendingSoftSuspectSteeringBySession.delete(sessionKey);
       return;
     }
+
+    if (cfg.softSuspect.mode === "strict") {
+      awaitingSoftSuspectReplyBySession.set(sessionKey, now);
+      pruneRecentMap(
+        awaitingSoftSuspectReplyBySession,
+        Math.max(cfg.softSuspect.ttlMs * 2, 60_000),
+        MAX_RECENT_MESSAGE_EVENTS,
+      );
+    }
     pendingSoftSuspectSteeringBySession.delete(sessionKey);
+    if (cfg.debug) {
+      api.logger.debug(`topic-shift-reset: ask-injected session=${sessionKey}`);
+    }
     return { prependContext: cfg.softSuspect.prompt };
   });