@argszero/cordis-plugin-thinking-loop-guard 0.1.0 → 0.1.1

package/README.md

@@ -25,13 +25,16 @@ turn never ends until the user aborts it. See
 
 ## How it works
 
-This plugin is a **community-side fix** that needs no harness patch. It subscribes
-to the public `agent/assistant-stream` event (scoped emit) and tallies the
-`StreamChunk` composition of each attempt:
+This plugin is a **community-side fix** that needs no harness patch. It observes
+the public `llm/stream` waterfall (present on **dsh 0.1.2-rc.1 and 0.1.5-alpha.1**)
+and tallies the `StreamChunk` composition of each loop-built model call. The live
+`Agent` is reached from the request's `sessionId` via `ctx.agents.get(...)`,
+so the guard works on the widely-installed 0.1.2-rc.1 as well as current master
+(no dependency on the 0.1.5-alpha.1-only `agent/assistant-stream` seam).
 
 - a chunk of type `text-delta` or `tool-call-delta` **resets** the counter — this
-  step produced output, so it is not a thinking loop;
-- a step that is **only** `reasoning-delta`, and at least `minReasoningChars`
+  call produced output, so it is not a thinking loop;
+- a call that is **only** `reasoning-delta`, and at least `minReasoningChars`
   long, counts toward `maxThinkingSteps`.
 
 When the threshold is crossed (or the reasoning text shows an unambiguous
@@ -66,7 +69,7 @@ interface Config {
   maxThinkingSteps?: number
   /** Minimum reasoning text in one step before it counts. Default 2048 chars. */
   minReasoningChars?: number
-  /** Longest repeated token / total tokens at which the step is flagged. Default 0.5. */
+  /** Repeated-gram coverage of the reasoning text at which the call is flagged. Language-agnostic (handles CJK, no whitespace). Default 0.5. */
   repeatRatio?: number
   /** Action on the threshold: 'warn' | 'steer' (default) | 'cancel'. */
   escalate?: 'warn' | 'steer' | 'cancel'
@@ -82,8 +85,19 @@ interface Config {
   any real output is ignored.
 - Per-`Agent` state is kept in a `WeakMap`, so a disposed agent is collected and
   its counters dropped.
-- The low-entropy check is a cheap heuristic (longest repeated whitespace token
-  over total tokens); it runs only once a step is already long, so cost is bound.
+- The low-entropy check is a cheap O(n) heuristic (repeated fixed-length gram
+  coverage; language-agnostic, so it works for CJK reasoning with no
+  whitespace); it runs only once a call is already long, so cost is bound.
+
+## Compatibility
+
+- **dsh 0.1.2-rc.1** (the widely-installed npm release): works — `llm/stream`,
+  `StreamChunk`, `GenerateOptions.sessionId`, `ctx.agents.get`, and
+  `agent.steer/cancel/inject` are all present.
+- **dsh 0.1.5-alpha.1**: works — same `llm/stream` seam. The newer
+  `agent/assistant-stream` event is NOT required; the guard does not depend on it.
+- The guard needs `@deepseek-ai/dsh-agent` / `@deepseek-ai/dsh-llm` `>=0.1.2`
+  (declared as peer dependencies).
 
 ## License
 

package/lib/index.js

@@ -10,28 +10,39 @@
  * zero `tool-call-delta` — so neither fires, `turn()` never sets `turnEnds`, and
  * the agent-loop `while (true)` never breaks until the user manually aborts.
  *
- * This plugin is the community-side fix. It listens to the public
- * `agent/assistant-stream` event, tallies the `StreamChunk` composition per
- * `(agent, turn, step)`, and detects a step that is reasoning-only AND shows a
- * low-entropy repetition. It then escalates through configured reactions:
- * a `warn` inject, then a `steer`, then a `cancel`.
+ * This plugin is the community-side fix. It observes the public `llm/stream`
+ * waterfall (present on dsh **0.1.2-rc.1 and 0.1.5-alpha.1**), tallies the
+ * `StreamChunk` composition of each loop-built model call, and detects a call
+ * that is reasoning-only AND shows a low-entropy repetition. It then escalates
+ * through configured reactions: a `warn` inject, then a `steer`, then a
+ * `cancel`.
  *
- * Mechanism notes (verified against packages/core/agent-loop/src/agent.ts and
- * packages/core/agent/src/runtime-types.ts on dsh 0.1.5-alpha.1):
- *  - `agent/assistant-stream` is scoped emit; `frame` is one
- *    `AssistantStreamFrame` (`start` | `chunk` | `end`).
- *  - `frame.chunk: StreamChunk` distinguishes `reasoning-delta` / `text-delta` /
+ * Why `llm/stream` and not `agent/assistant-stream`: the latter (scoped emit
+ * with `start`/`chunk`/`end` frames) only exists from dsh 0.1.5-alpha.1; the
+ * widely-installed 0.1.2-rc.1 has neither it nor `AssistantStreamFrame`, so a
+ * plugin pinned to that seam silently no-ops on the common release. `llm/stream`
+ * is a Cordis waterfall around every streaming model call in both versions and
+ * carries the same `StreamChunk` delta types, and its `GenerateOptions` carries
+ * `sessionId`, from which the live Agent is reachable via `ctx.agents.get(...)`.
+ *
+ * Mechanism notes (verified against packages/core/agent-loop/src/agent.ts,
+ * packages/llm/llm/src/index.ts, and packages/core/agent/src/runtime-types.ts on
+ * dsh 0.1.5-alpha.1; the `llm/stream` / `StreamChunk` / `ctx.agents.get` trio is
+ * present unchanged on 0.1.2-rc.1):
+ *  - `llm/stream` is a waterfall; a listener wraps `next()` and sees each chunk.
+ *  - `chunk: StreamChunk` distinguishes `reasoning-delta` / `text-delta` /
  *    `tool-call-delta` (packages/llm/llm/src/types.ts).
- *  - `payload.agent.steer(message)`, `payload.agent.inject(message)`, and
- *    `payload.agent.cancel(cause)` are public methods.
- *  - A listener can react but cannot veto/rewrite an in-flight step; steer and
- *    cancel are sufficient to break the loop.
+ *  - Loop-built requests carry `markAgentLoopRequest`; `isAgentLoopRequest`
+ *    filters out arbitrary non-agent streaming (tool streams, etc.).
+ *  - `options.sessionId` → `ctx.agents.get(sessionId)` yields the live `Agent`.
+ *  - `agent.steer(message)`, `agent.inject(message)`, and `agent.cancel(cause)`
+ *    are public methods; a listener can react but not veto an in-flight step.
  *
  * @module @argszero/cordis-plugin-thinking-loop-guard
  */
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { createUserMessage, isAgentLoopRequest } from '@deepseek-ai/dsh-llm';
 export const Config = z.object({
     maxThinkingSteps: z.number().min(2).default(3),
     minReasoningChars: z.number().min(256).default(2048),
@@ -47,23 +58,35 @@ function message(text, form) {
         source: { ...PLUGIN_SOURCE, form, summary: 'thinking-loop-guard' },
     });
 }
-/** Low-entropy ratio: longest repeated whitespace token / total tokens. */
+/**
+ * Low-entropy ratio: coverage by repeated fixed-length grams.
+ *
+ * The degenerate loops #5976 describes are CJK ("好。执行。好。执行。"), which have
+ * NO whitespace, so a whitespace-token histogram collapses to one token and can
+ * never distinguish repetition. This detector is language-agnostic: it slides a
+ * fixed-length window and reports the fraction of windows that have appeared
+ * before, so a tight repetition ("好。执行。" x N) scores near 1.0 while coherent
+ * reasoning (which rarely repeats a 4-char window verbatim) scores near 0.
+ *
+ * O(n) with a Set — cheap enough even for very long reasoning text (the guard
+ * inspects steps well past `minReasoningChars`).
+ */
 function repeatRatio(reasoning) {
     if (reasoning.length < 16)
         return 0;
-    const tokens = reasoning.split(/\s+/u).filter((t) => t.length > 0);
-    if (tokens.length < 8)
-        return 0;
-    const counts = new Map();
-    for (const tok of tokens) {
-        const key = tok.toLowerCase();
-        counts.set(key, (counts.get(key) ?? 0) + 1);
+    const k = Math.min(4, Math.max(2, Math.floor(reasoning.length / 16)));
+    let repeated = 0;
+    let total = 0;
+    const seen = new Set();
+    for (let i = 0; i + k <= reasoning.length; i++) {
+        const gram = reasoning.slice(i, i + k);
+        total++;
+        if (seen.has(gram))
+            repeated++;
+        else
+            seen.add(gram);
     }
-    let best = 1;
-    for (const [, count] of counts)
-        if (count > best)
-            best = count;
-    return best / tokens.length;
+    return total === 0 ? 0 : repeated / total;
 }
 /**
  * Install the listener. Per-`Agent` state is keyed in a `WeakMap` so a disposed
@@ -79,7 +102,7 @@ export function apply(ctx, config) {
     function stateFor(agent) {
         let state = states.get(agent);
         if (state === undefined) {
-            state = { attempt: null, thinkingSteps: 0, reacted: false };
+            state = { call: null, thinkingSteps: 0, reacted: false };
             states.set(agent, state);
         }
         return state;
@@ -94,7 +117,7 @@ export function apply(ctx, config) {
         state.reacted = true;
         switch (escalate) {
             case 'warn':
-                agent.inject(message('The agent has produced several long reasoning-only steps with no output. '
+                agent.inject(message('The agent has produced several long reasoning-only calls with no output. '
                     + 'If this continues it will be interrupted.', 'notice'));
                 return;
             case 'steer':
@@ -106,46 +129,61 @@ export function apply(ctx, config) {
                 return;
         }
     }
-    ctx.on('agent/assistant-stream', (payload) => {
-        const { agent, frame } = payload;
+    // Observe every streaming model call through the `llm/stream` waterfall. This
+    // is present on both dsh 0.1.2-rc.1 and 0.1.5-alpha.1 and carries the SAME
+    // StreamChunk delta types, so no version branching is needed.
+    ctx.on('llm/stream', (options, next) => {
+        // Only agent-loop-built calls carry the loop identity; skip arbitrary
+        // non-agent streaming (tool streams, assistant replay, etc.).
+        if (!isAgentLoopRequest(options))
+            return next();
+        if (options.sessionId === undefined)
+            return next();
+        const agent = ctx.agents.get(options.sessionId);
+        if (agent === undefined)
+            return next();
         const state = stateFor(agent);
-        if (frame.type === 'start') {
-            state.attempt = { reasoning: '', hasOutput: false };
-            return;
-        }
-        if (frame.type === 'chunk') {
-            if (state.attempt === null)
-                return;
-            const chunk = frame.chunk;
-            if (chunk.type === 'reasoning-delta') {
-                state.attempt.reasoning += chunk.text;
-                return;
+        // Reset the per-call candidate at the boundary; if the call yields any
+        // text or tool-call delta it is NOT a thinking loop.
+        state.call = { reasoning: '', hasOutput: false };
+        return (async function* wrapped() {
+            let reasoning = '';
+            let hasOutput = false;
+            let finished = false;
+            try {
+                for await (const chunk of next()) {
+                    if (chunk.type === 'reasoning-delta') {
+                        reasoning += chunk.text;
+                    }
+                    else if (chunk.type === 'text-delta' || chunk.type === 'tool-call-delta') {
+                        hasOutput = true;
+                    }
+                    yield chunk;
+                }
             }
-            if (chunk.type === 'text-delta' || chunk.type === 'tool-call-delta') {
-                state.attempt.hasOutput = true;
+            finally {
+                if (!finished && !hasOutput) {
+                    const call = state.call;
+                    if (call !== null) {
+                        call.reasoning = reasoning;
+                        call.hasOutput = hasOutput;
+                    }
+                    state.call = null;
+                    finished = true;
+                    if (hasOutput) {
+                        // Any text or tool output means this is NOT a thinking loop.
+                        reset(state);
+                    }
+                    else if (reasoning.length >= minReasoningChars) {
+                        // A long reasoning-only call: count it toward the threshold.
+                        state.thinkingSteps += 1;
+                        const ratio = repeatRatio(reasoning);
+                        if (state.thinkingSteps >= maxThinkingSteps || ratio >= repeatRatioThreshold) {
+                            react(state, agent);
+                        }
+                    }
+                }
             }
-            return;
-        }
-        if (frame.type === 'end') {
-            if (state.attempt === null)
-                return;
-            const attempt = state.attempt;
-            state.attempt = null;
-            if (attempt.hasOutput) {
-                // Any text or tool output means this is NOT a thinking loop.
-                reset(state);
-                return;
-            }
-            if (attempt.reasoning.length < minReasoningChars) {
-                // Too short to be a degenerate run; do not count it.
-                return;
-            }
-            // A long reasoning-only step: count it toward the threshold.
-            state.thinkingSteps += 1;
-            const ratio = repeatRatio(attempt.reasoning);
-            if (state.thinkingSteps >= maxThinkingSteps || ratio >= repeatRatioThreshold) {
-                react(state, agent);
-            }
-        }
+        })();
     });
 }

package/lib/types/index.d.ts

@@ -10,22 +10,33 @@
  * zero `tool-call-delta` — so neither fires, `turn()` never sets `turnEnds`, and
  * the agent-loop `while (true)` never breaks until the user manually aborts.
  *
- * This plugin is the community-side fix. It listens to the public
- * `agent/assistant-stream` event, tallies the `StreamChunk` composition per
- * `(agent, turn, step)`, and detects a step that is reasoning-only AND shows a
- * low-entropy repetition. It then escalates through configured reactions:
- * a `warn` inject, then a `steer`, then a `cancel`.
+ * This plugin is the community-side fix. It observes the public `llm/stream`
+ * waterfall (present on dsh **0.1.2-rc.1 and 0.1.5-alpha.1**), tallies the
+ * `StreamChunk` composition of each loop-built model call, and detects a call
+ * that is reasoning-only AND shows a low-entropy repetition. It then escalates
+ * through configured reactions: a `warn` inject, then a `steer`, then a
+ * `cancel`.
  *
- * Mechanism notes (verified against packages/core/agent-loop/src/agent.ts and
- * packages/core/agent/src/runtime-types.ts on dsh 0.1.5-alpha.1):
- *  - `agent/assistant-stream` is scoped emit; `frame` is one
- *    `AssistantStreamFrame` (`start` | `chunk` | `end`).
- *  - `frame.chunk: StreamChunk` distinguishes `reasoning-delta` / `text-delta` /
+ * Why `llm/stream` and not `agent/assistant-stream`: the latter (scoped emit
+ * with `start`/`chunk`/`end` frames) only exists from dsh 0.1.5-alpha.1; the
+ * widely-installed 0.1.2-rc.1 has neither it nor `AssistantStreamFrame`, so a
+ * plugin pinned to that seam silently no-ops on the common release. `llm/stream`
+ * is a Cordis waterfall around every streaming model call in both versions and
+ * carries the same `StreamChunk` delta types, and its `GenerateOptions` carries
+ * `sessionId`, from which the live Agent is reachable via `ctx.agents.get(...)`.
+ *
+ * Mechanism notes (verified against packages/core/agent-loop/src/agent.ts,
+ * packages/llm/llm/src/index.ts, and packages/core/agent/src/runtime-types.ts on
+ * dsh 0.1.5-alpha.1; the `llm/stream` / `StreamChunk` / `ctx.agents.get` trio is
+ * present unchanged on 0.1.2-rc.1):
+ *  - `llm/stream` is a waterfall; a listener wraps `next()` and sees each chunk.
+ *  - `chunk: StreamChunk` distinguishes `reasoning-delta` / `text-delta` /
  *    `tool-call-delta` (packages/llm/llm/src/types.ts).
- *  - `payload.agent.steer(message)`, `payload.agent.inject(message)`, and
- *    `payload.agent.cancel(cause)` are public methods.
- *  - A listener can react but cannot veto/rewrite an in-flight step; steer and
- *    cancel are sufficient to break the loop.
+ *  - Loop-built requests carry `markAgentLoopRequest`; `isAgentLoopRequest`
+ *    filters out arbitrary non-agent streaming (tool streams, etc.).
+ *  - `options.sessionId` → `ctx.agents.get(sessionId)` yields the live `Agent`.
+ *  - `agent.steer(message)`, `agent.inject(message)`, and `agent.cancel(cause)`
+ *    are public methods; a listener can react but not veto an in-flight step.
  *
  * @module @argszero/cordis-plugin-thinking-loop-guard
  */
@@ -34,19 +45,19 @@ import z from '@deepseek-ai/schemastery';
 /** Plugin configuration. */
 export interface Config {
     /**
-     * Consecutive reasoning-only steps (each at least `minReasoningChars` long,
-     * no text/tool output) before a reaction. Default `3`.
+     * Consecutive reasoning-only model calls (each at least `minReasoningChars`
+     * long, no text/tool output) before a reaction. Default `3`.
      */
     maxThinkingSteps?: number;
     /**
-     * Minimum reasoning text within one step before it counts as a thinking step
+     * Minimum reasoning text within one call before it counts as a thinking step
      * at all; a short burst is normal. Default `2048` chars.
      */
     minReasoningChars?: number;
     /**
-     * Approximate low-entropy repeat detection: the longest single repeated
-     * whitespace-delimited token, as a fraction of total tokens in the step's
-     * reasoning text. A degenerate "好。执行。" loop is near 1.0; coherent
+     * Approximate low-entropy repeat detection: the longest repeated substring's
+     * coverage of the step's reasoning text. Language-agnostic (handles CJK with
+     * no whitespace): a degenerate "好。执行。" loop is near 1.0; coherent
      * exploration is low. Only consulted once `minReasoningChars` is met.
      * Default `0.5`.
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argszero/cordis-plugin-thinking-loop-guard",
-  "description": "Thinking-loop guard for dsh: detects reasoning-only degenerate steps (no text, no tool call) via the agent/assistant-stream event and escalates warn -> steer -> cancel to break the loop.",
-  "version": "0.1.0",
+  "description": "Thinking-loop guard for dsh: detects reasoning-only degenerate calls (no text, no tool call) via the llm/stream waterfall and escalates warn -> steer -> cancel to break the loop. Compatible with dsh 0.1.2-rc.1 and 0.1.5-alpha.1.",
+  "version": "0.1.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -36,11 +36,11 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": ">=0.1.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {