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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 argszero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @argszero/cordis-plugin-thinking-loop-guard
+
+Thinking-loop guard for the DeepSeek Harness (`dsh`). Detects an agent that
+degrades into a **pure-thinking loop** — a step that emits only `reasoning-delta`
+chunks, with **zero `text-delta` and zero `tool-call-delta`** — and reacts to break
+the loop before it burns tokens until a human manually aborts the turn.
+
+## The gap it closes
+
+The in-tree `guard/` family watches two failure modes, both **tool-call-centric**:
+
+| Guard | Hook | Catches |
+|---|---|---|
+| `guard/timeout-policy` | `tools/execute` | a tool call that exceeds a declared `timeoutMs` |
+| `guard/repeat-tool-reminder` | `tools/post-execute` | the model repeating the **same tool call** chain |
+
+Neither fires when the model emits **no tool call at all** — the exact shape of a
+thinking loop. When a model (observed with
+`deepseek-v4.1-flash-expires-on-0910` under `max`/`high` reasoning effort and a
+long context) keeps emitting low-entropy reasoning ("好。执行。好。", repeated
+"Let me / Wait / Actually / Hmm"), the agent-loop `turn()` `while (true)` never
+sets `turnEnds` (`StepEndReason` only carries `completed` / `max-tokens`), so the
+turn never ends until the user aborts it. See
+[deepseek-ai/deepseek-harness discussion #5976](https://github.com/deepseek-ai/deepseek-harness/discussions/5976).
+
+## 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:
+
+- 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`
+  long, counts toward `maxThinkingSteps`.
+
+When the threshold is crossed (or the reasoning text shows an unambiguous
+low-entropy repetition, i.e. `repeatRatio`), it escalates:
+
+1. `escalate: 'warn'` → `agent.inject(...)` a notice into the next pre-step;
+2. `escalate: 'steer'` (default) → `agent.steer(...)` a "stop deliberating and act"
+   steering message into the next step boundary;
+3. `escalate: 'cancel'` → `agent.cancel(cause)` hard-aborts the active turn.
+
+`agent.steer()`, `agent.inject()`, and `agent.cancel()` are all public methods on
+the live `Agent`. A listener can react but cannot veto/rewrite an in-flight step;
+steer and cancel are sufficient to break the loop.
+
+## Install
+
+Load it as an `@deepseek-ai/cordis` plugin in your `dsh` profile, or mount the
+bundle patch:
+
+```yaml
+# cordis.patch.yml (already packaged in this plugin)
+- insert:
+    - id: thinking-loop-guard
+      name: '@argszero/cordis-plugin-thinking-loop-guard'
+```
+
+## Configuration
+
+```ts
+interface Config {
+  /** Consecutive reasoning-only steps (each ≥ minReasoningChars, no output) before reacting. Default 3. */
+  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. */
+  repeatRatio?: number
+  /** Action on the threshold: 'warn' | 'steer' (default) | 'cancel'. */
+  escalate?: 'warn' | 'steer' | 'cancel'
+  /** Cancel cause when escalate is 'cancel'. Default 'thinking-loop'. */
+  cancelCause?: string
+}
+```
+
+## Notes
+
+- The detector is deliberately **conservative**: a step must be long
+  (`minReasoningChars`) and reasoning-only; a short thinking burst or a step with
+  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.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# The @argszero/cordis-plugin-thinking-loop-guard bundle patch: the guard needs no
+# deployment-specific config to mount (its defaults detect reasoning-only steps
+# and steer on the second strike). Tune via a profile layer if desired:
+#
+#   - set:
+#       - id: thinking-loop-guard
+#         config:
+#           maxThinkingSteps: 3
+#           minReasoningChars: 2048
+#           repeatRatio: 0.5
+#           escalate: steer
+#           cancelCause: thinking-loop
+
+- insert:
+    - id: thinking-loop-guard
+      name: '@argszero/cordis-plugin-thinking-loop-guard'

package/lib/index.js

@@ -0,0 +1,151 @@
+/**
+ * Thinking-loop guard for the dsh harness.
+ *
+ * Closes a guard-layer gap the in-tree `guard/` family does not cover.
+ * `guard/timeout-policy` is a per-tool `tools/execute` deadline and
+ * `guard/repeat-tool-reminder` is a same-tool-call chain detector — only a tool
+ * *call* arms either. When a model degrades into a pure-thinking loop
+ * (`deepseek-v4.1-flash-expires-on-0910` under `max`/`high` reasoning effort and
+ * a long context), it emits only `reasoning-delta` chunks — zero `text-delta`,
+ * 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`.
+ *
+ * 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` /
+ *    `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.
+ *
+ * @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';
+export const Config = z.object({
+    maxThinkingSteps: z.number().min(2).default(3),
+    minReasoningChars: z.number().min(256).default(2048),
+    repeatRatio: z.number().min(0).max(1).default(0.5),
+    escalate: z.union(['warn', 'steer', 'cancel']).default('steer'),
+    cancelCause: z.string().default('thinking-loop'),
+});
+export const name = 'thinking-loop-guard';
+const PLUGIN_SOURCE = { kind: 'plugin', plugin: 'thinking-loop-guard' };
+function message(text, form) {
+    return createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { ...PLUGIN_SOURCE, form, summary: 'thinking-loop-guard' },
+    });
+}
+/** Low-entropy ratio: longest repeated whitespace token / total tokens. */
+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);
+    }
+    let best = 1;
+    for (const [, count] of counts)
+        if (count > best)
+            best = count;
+    return best / tokens.length;
+}
+/**
+ * Install the listener. Per-`Agent` state is keyed in a `WeakMap` so a disposed
+ * agent is collected; counters are scoped to one agent lifecycle.
+ */
+export function apply(ctx, config) {
+    const maxThinkingSteps = config.maxThinkingSteps;
+    const minReasoningChars = config.minReasoningChars;
+    const repeatRatioThreshold = config.repeatRatio;
+    const escalate = config.escalate;
+    const cancelCause = config.cancelCause;
+    const states = new WeakMap();
+    function stateFor(agent) {
+        let state = states.get(agent);
+        if (state === undefined) {
+            state = { attempt: null, thinkingSteps: 0, reacted: false };
+            states.set(agent, state);
+        }
+        return state;
+    }
+    function reset(state) {
+        state.thinkingSteps = 0;
+        state.reacted = false;
+    }
+    function react(state, agent) {
+        if (state.reacted)
+            return;
+        state.reacted = true;
+        switch (escalate) {
+            case 'warn':
+                agent.inject(message('The agent has produced several long reasoning-only steps with no output. '
+                    + 'If this continues it will be interrupted.', 'notice'));
+                return;
+            case 'steer':
+                agent.steer(message('You are repeating the same reasoning without acting. Stop deliberating and '
+                    + 'either call a tool or produce a concise answer now.', 'notice'));
+                return;
+            case 'cancel':
+                agent.cancel(cancelCause);
+                return;
+        }
+    }
+    ctx.on('agent/assistant-stream', (payload) => {
+        const { agent, frame } = payload;
+        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;
+            }
+            if (chunk.type === 'text-delta' || chunk.type === 'tool-call-delta') {
+                state.attempt.hasOutput = true;
+            }
+            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

@@ -0,0 +1,72 @@
+/**
+ * Thinking-loop guard for the dsh harness.
+ *
+ * Closes a guard-layer gap the in-tree `guard/` family does not cover.
+ * `guard/timeout-policy` is a per-tool `tools/execute` deadline and
+ * `guard/repeat-tool-reminder` is a same-tool-call chain detector — only a tool
+ * *call* arms either. When a model degrades into a pure-thinking loop
+ * (`deepseek-v4.1-flash-expires-on-0910` under `max`/`high` reasoning effort and
+ * a long context), it emits only `reasoning-delta` chunks — zero `text-delta`,
+ * 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`.
+ *
+ * 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` /
+ *    `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.
+ *
+ * @module @argszero/cordis-plugin-thinking-loop-guard
+ */
+import { Context } from '@deepseek-ai/cordis';
+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`.
+     */
+    maxThinkingSteps?: number;
+    /**
+     * Minimum reasoning text within one step 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
+     * exploration is low. Only consulted once `minReasoningChars` is met.
+     * Default `0.5`.
+     */
+    repeatRatio?: number;
+    /**
+     * Reaction to fire when the threshold is crossed. `warn` injects a notice,
+     * `steer` sends a steering message, `cancel` hard-aborts the turn. Default
+     * `steer`.
+     */
+    escalate?: 'warn' | 'steer' | 'cancel';
+    /** Cancel cause used when `escalate` is `cancel`. Default `'thinking-loop'`. */
+    cancelCause?: string;
+}
+/** Resolved config: every field carries its validated default. */
+type ResolvedConfig = Required<Config>;
+export declare const Config: z<Config>;
+export declare const name = "thinking-loop-guard";
+/**
+ * Install the listener. Per-`Agent` state is keyed in a `WeakMap` so a disposed
+ * agent is collected; counters are scoped to one agent lifecycle.
+ */
+export declare function apply(ctx: Context, config: ResolvedConfig): void;
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "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",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "cordis",
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "guard",
+    "thinking-loop",
+    "reasoning"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.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": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  }
+}