mimo-stable 1.1.0__py3-none-any.whl

mimo_stable-1.1.0.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: mimo-stable
+Version: 1.1.0
+Summary: Record, detect, and apply engineering guardrails for degenerate loops in LLM output and tool calls
+Author: xli498
+License: MIT License
+        
+        Copyright (c) 2026 xli498
+        
+        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.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# LLM Degenerate Loop Guardrails
+
+[English README](README.en.md)
+
+[![Quality Gate](https://github.com/xli498/mimo-stable/actions/workflows/quality.yml/badge.svg)](https://github.com/xli498/mimo-stable/actions/workflows/quality.yml)
+[![Release](https://img.shields.io/github/v/release/xli498/mimo-stable)](https://github.com/xli498/mimo-stable/releases)
+[![License](https://img.shields.io/github/license/xli498/mimo-stable)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+面向国产及其他 LLM 的输出流和工具调用退化循环经验记录与检测工具。
+项目最初来自 MiMo `reasoning=True` 场景的重复输出观察，后来发现类似现象
+也可能出现在 GLM 等其他模型中。这里分享的是识别、止损和复盘方法，不是
+针对任何模型的根治方案。
+
+> [!IMPORTANT]
+> 当前项目的核心能力是**检测与止损**，不是自动修复模型。检测到循环后，
+> 由上层运行器决定停止、切换模型、重试或人工复核。
+
+## 目录
+
+- [30 秒开始](#30-秒开始)
+- [问题描述](#问题描述)
+- [三层防御体系](#三层防御体系)
+- [检测策略](#检测策略)
+- [可复现证据](#可复现证据)
+- [如何记录和分享新案例](#如何记录和分享新案例)
+- [工程侧缓解措施](#工程侧缓解措施不是模型修复)
+- [示例](#示例)
+- [文件结构](#文件结构)
+- [测试](#测试)
+- [安装与集成](#安装与集成)
+- [许可](#许可)
+- [行为契约](#行为契约)
+
+## 30 秒开始
+
+![Guardrails architecture](docs/architecture.svg)
+
+> **核心流程：** 模型输出 → 检测信号 → 保守决策摘要 → 上层运行器处理。
+> 检测器和恢复层都不执行重试、模型切换或工具调用。
+
+```bash
+python3 scripts/detect_loop.py --log fixtures/loop_detected.log
+python3 tests/test_detector.py
+python3 scripts/benchmark_fixtures.py
+```
+
+机器集成使用单份 JSON 摘要和退出码：
+
+```bash
+python3 scripts/detect_loop.py --json --timeout 60 --log fixtures/loop_detected.log
+# 退出码 0 = 未检测到；1 = 检测到；2 = 参数/输入错误
+
+# 将检测摘要转成保守的恢复决策（只输出决策，不执行重试）
+python3 scripts/detect_loop.py --json --timeout 60 --log fixtures/loop_detected.log | \
+  python3 scripts/recovery_policy.py --retryable
+```
+
+典型检测摘要：
+
+```json
+{
+  "loop_detected": true,
+  "details": {
+    "type": "consecutive_identical_output"
+  }
+}
+```
+
+| 退出码 | 含义 |
+| :---: | :--- |
+| `0` | 未检测到循环 |
+| `1` | 检测到循环 |
+| `2` | 参数或输入错误 |
+
+## 问题描述
+
+在特定模型、参数、任务和上游服务条件下，LLM 可能进入退化循环状态：
+
+- **症状**：同一段输出重复，持续时间异常增长
+- **语言切换**：特定中文任务中切换为英文，且无视语言约束
+- **功能停滞**：不执行有进展的工具调用，仅重复输出文本
+- **根因尚未确定**：`reasoning=True`、上下文长度、工具链状态、服务端实现等
+  都可能是相关变量；本项目不把相关性写成因果结论。
+
+类似表现并不等于同一个 bug。MiMo、GLM 或其他国产模型的案例必须分别记录
+模型版本、端点、参数、任务和时间，不能把一个模型的触发概率或规避经验直接
+外推到另一个模型。
+
+## 三层防御体系
+
+### 第一层：工程侧限制（止损，不是修复）
+
+在运行器中设置硬性超时和 Token 限制（具体字段以所用框架官方文档为准）：
+
+```yaml
+# 示例结构；字段名和数值必须按实际框架、模型与任务校准。
+provider:
+  model: <your-model>
+  timeout: <task-specific-limit>
+  max_tokens: <task-specific-limit>
+```
+
+> [!WARNING]
+> **历史案例，不是通用推荐：** 最初 MiMo 案例曾使用
+> `timeoutSeconds=180` 和 `maxTokens=8000` 限制单次资源占用。这些值不是
+> 跨模型配置建议，也不表示能够改变模型进入循环的概率。
+
+作用是限制单次故障的最长资源占用，不改变模型本身的循环概率。
+
+### 第二层：行为检测
+
+运行 `scripts/detect_loop.py` 实时监控模型输出，检测连续重复。
+
+管道输入以空行切分输出块；`--timeout` 的持续时间只在流式输入期间有实际意义，
+离线日志使用日志中的块时间戳。
+
+```bash
+python3 scripts/detect_loop.py --log logs/sample_degenerate_loop.log
+model_output 2>&1 | python3 scripts/detect_loop.py
+python3 scripts/detect_loop.py --json --log logs/sample_degenerate_loop.log
+```
+
+检测规则：
+
+- 连续 3+ 次输出块完全相同或高度相似
+- 连续 3+ 次工具调用参数完全相同
+- 已知副作用工具的重复调用
+- 显式声明中文任务后的英文漂移
+- 可选的持续时间门控
+
+### 第三层：行为规则（AGENTS.md）
+
+在 AGENTS.md 或对应运行器规则中加入检测和处置约束。详见
+[SKILL.md](SKILL.md)。该层是提示和流程规则，不替代运行时检测。
+
+## 检测策略
+
+默认文本重复采用**持续时间门控**：需要达到 `--threshold` 次相似输出，且
+重复窗口达到 `--timeout` 秒。这适合日志后处理，减少短暂重复的误报。
+
+如果上层需要在达到重复次数后立即得到信号，可显式使用：
+
+```bash
+python3 scripts/detect_loop.py --text-mode instant --log fixtures/repeated_but_short.log
+```
+
+工具调用重复和已知副作用工具的重复调用不受文本持续时间门控影响；生产集成仍应
+结合幂等键、调用结果和重试原因做二次判断。
+
+## 可复现证据
+
+> [!NOTE]
+> Fixture 用于稳定回归，历史日志用于记录具体观察；两者的证据性质不同。
+
+`logs/sample_degenerate_loop.log` 是历史观察日志；`logs/fixed_normal_run.log`
+是一次正常运行日志。它们只说明具体案例，不构成模型故障率统计，也不证明
+任何参数能“修复”模型。
+
+当前仓库没有足够实验次数估计任何模型的通用触发概率，因此不提供“某模型
+有 X% 概率出问题”之类的结论。
+
+## 如何记录和分享新案例
+
+建议至少记录以下信息，并在发布前脱敏：
+
+- 模型与精确版本、供应商/端点、调用时间段
+- `reasoning`、temperature、max tokens、上下文规模等实际参数
+- 任务类型、是否多轮、是否涉及工具调用
+- 重复发生前后的输出块摘要或哈希，不公开密钥、隐私和完整敏感工具参数
+- 是否真正发生资源浪费/副作用，检测器是否报警，检测延迟
+- 重试、切换模型或改变参数后的结果
+
+案例记录用于复盘和横向比较，不应写成因果证明。没有原始证据时，使用
+“观察到”“可能相关”“尚未复现”，不要使用“必然”“已证明”“彻底解决”。
+
+## 工程侧缓解措施（不是模型修复）
+
+| 措施 | 作用 | 边界 |
+| :--- | :--- | :--- |
+| `timeoutSeconds=180` | 限制单次资源损失 | 不改变模型行为 |
+| `maxTokens=8000` | 限制输出上限 | 不等于不再循环 |
+| 行为层检测 | 提供停止/切换信号 | 需要上层执行恢复动作 |
+
+## 示例
+
+- [基础文本检测](examples/basic-text-detection.md)
+- [工具调用检测](examples/tool-call-detection.md)
+- [恢复决策接入](examples/recovery-policy-integration.md)
+
+每个示例都只展示输入、检测信号或决策输出；实际停止、重试、切换模型和人工复核
+仍由上层运行器负责。
+
+## 文件结构
+
+```
+mimo-stable/
+├── README.md
+├── SKILL.md
+├── pyproject.toml
+├── CHANGELOG.md
+├── scripts/
+│   ├── detect_loop.py        # 循环检测脚本
+│   ├── benchmark_fixtures.py # 可复现 fixture 基准测试
+│   └── recovery_policy.py    # 保守恢复决策层（不执行副作用）
+├── tests/test_detector.py    # 行为契约测试
+├── examples/                 # 最小集成示例
+├── fixtures/                 # 规范化回归样例
+├── logs/                     # 历史观察日志
+└── references/parameters.md
+```
+
+## 测试
+
+```bash
+python3 -m py_compile scripts/*.py
+bash -n scripts/*.sh
+python3 tests/test_detector.py
+python3 scripts/benchmark_fixtures.py
+# 或使用仓库提供的入口：
+bash scripts/test_short.sh
+bash scripts/test_long.sh
+```
+
+当前 benchmark 覆盖 9 个规范化案例：循环、正常输出、短时重复、近似文本、
+变化参数重试、非连续工具调用、工具 key 顺序、重复副作用工具和中文任务语言漂移。
+
+历史日志在默认 180 秒阈值下可能不报警；复核时使用 `--timeout 60`。生产阈值
+应按业务容忍度评估，不能把测试阈值直接当作生产配置。
+
+## 安装与集成
+
+项目保持零运行时依赖。当前支持源码直接运行和本地 CLI 安装，尚未发布到 PyPI。
+
+### 方式一：直接运行源码
+
+```bash
+git clone https://github.com/xli498/mimo-stable.git
+cd mimo-stable
+python3 scripts/detect_loop.py --log fixtures/loop_detected.log
+```
+
+### 方式二：安装本地 CLI
+
+```bash
+python3 -m pip install --no-deps .
+mimo-loop-detect --json --timeout 60 --log fixtures/loop_detected.log
+```
+
+> [!NOTE]
+> 当前尚未发布公共 PyPI 包，因此不要使用 `pip install mimo-stable` 获取发行包。
+
+上层运行器不应在检测到循环后盲目重试：
+
+1. 保存脱敏后的事件摘要；
+2. 停止当前生成或工具链；
+3. 根据任务是否幂等决定重试；
+4. 必要时切换模型或请求人工复核。
+
+## 许可
+
+MIT
+
+## 行为契约
+
+`fixtures/` 中的规范化样例用于稳定回归，历史日志用于说明观察事实；二者不互相
+替代。执行 `python3 tests/test_detector.py` 可验证检测器行为。

mimo_stable-1.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mimo_stable-1.1.0.dist-info/licenses/LICENSE,sha256=Ie3LloKoBYMu1ugx4D6aUTHmzfmA7R-V23Th1L5U5Jo,1063
+scripts/__init__.py,sha256=FvX-LylRYHIfvaSLKqwEnq9GkV3caaJgpHMmc0_czkk,42
+scripts/benchmark_fixtures.py,sha256=wfbATtAK9Y8iMHEZDez7GIjqv7BnZogWY9CWdT-_11M,1666
+scripts/check_version.py,sha256=NZ-Rkl_dBx4YI5uC-v0BMDyOixMajBOO4qamTM8Wfzo,1050
+scripts/detect_loop.py,sha256=AT4Ex7tLWDF4anDPj7DsHMb68gqFRC-6PW1uYrpwC5U,16994
+scripts/recovery_policy.py,sha256=cm-ktDHDbOv980bvM1dOnlBDuGL8heMqceUQdm7x1OE,3044
+mimo_stable-1.1.0.dist-info/METADATA,sha256=g6wV4EUxPmlga02Kk7TgjKj1mYgHaFZz0hbxXjrbWdY,11325
+mimo_stable-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mimo_stable-1.1.0.dist-info/entry_points.txt,sha256=FMfdVPdqCC1m9WkgWZx34OEPN6AGRtM7iQS7mcf_Bx4,62
+mimo_stable-1.1.0.dist-info/top_level.txt,sha256=rmzd5mewlrJy4sT608KPib7sM7edoY75AeqJeY3SPB4,8
+mimo_stable-1.1.0.dist-info/RECORD,,

mimo_stable-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mimo_stable-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mimo-loop-detect = scripts.detect_loop:main

mimo_stable-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xli498
+
+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.

mimo_stable-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scripts

scripts/__init__.py

@@ -0,0 +1 @@
+"""Executable modules for mimo-stable."""

scripts/benchmark_fixtures.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Run the checked-in fixtures and print a small reproducible benchmark."""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DETECTOR = ROOT / "scripts" / "detect_loop.py"
+
+CASES = [
+    ("loop_detected.log", True),
+    ("normal_output.log", False),
+    ("repeated_but_short.log", False),
+    ("near_duplicate_below_threshold.log", False),
+    ("tool_retry_changed_params.log", False),
+    ("nonconsecutive_tool_calls.log", False),
+    ("tool_key_order_repeat.log", True),
+    ("side_effect_repeat.log", True),
+    ("language_drift_zh.log", True),
+]
+
+
+def run(path: str, expected: bool) -> tuple[bool, str]:
+    args = [sys.executable, str(DETECTOR), "--json", "--timeout", "60"]
+    if path == "language_drift_zh.log":
+        args += ["--expect-language", "zh"]
+    args += ["--log", str(ROOT / "fixtures" / path)]
+    result = subprocess.run(args, capture_output=True, text=True)
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return False, f"invalid JSON: {result.stdout!r}"
+    actual = bool(data.get("loop_detected"))
+    return actual == expected, f"expected={expected} actual={actual} type={data.get('details', {}).get('type')}"
+
+
+def main() -> int:
+    passed = 0
+    for path, expected in CASES:
+        ok, detail = run(path, expected)
+        print(f"{'PASS' if ok else 'FAIL'} {path}: {detail}")
+        passed += ok
+    print(f"\nfixture benchmark: {passed}/{len(CASES)} cases passed")
+    return 0 if passed == len(CASES) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/check_version.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Verify that the package version is represented in the changelog."""
+
+from __future__ import annotations
+
+import re
+import sys
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10 compatibility
+    try:
+        import tomli as tomllib
+    except ModuleNotFoundError as exc:
+        raise SystemExit(
+            "Python 3.10 requires the optional 'tomli' package to run check_version.py"
+        ) from exc
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main() -> int:
+    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+    version = pyproject["project"]["version"]
+    changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
+    if not re.search(rf"^## \[{re.escape(version)}\]", changelog, re.MULTILINE):
+        print(f"CHANGELOG.md has no release heading for version {version}", file=sys.stderr)
+        return 1
+    print(f"version consistency passed: {version}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/detect_loop.py

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""
+LLM Degenerate Loop Guardrails — Detection Script
+
+Detects degenerate loops in model output streams where the model
+repeatedly emits identical or near-identical text blocks.
+
+Detection rules:
+  1. Consecutive identical output blocks (3+ repeats)
+  2. Same tool called 3+ times with identical parameters
+  3. Output duration exceeding threshold without meaningful change
+
+Usage:
+  # From stdin (pipe model output):
+  model_output 2>&1 | python3 detect_loop.py
+
+  # From log file:
+  python3 detect_loop.py --log sample_degenerate_loop.log
+
+  # With custom thresholds:
+  python3 detect_loop.py --threshold 4 --timeout 300 --log sample.log
+
+  # JSON output for integration:
+  python3 detect_loop.py --json --log sample.log
+
+Exit codes:
+  0 — No loop detected
+  1 — Loop detected
+  2 — Invalid arguments
+"""
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import time
+from collections import deque
+from datetime import datetime
+from difflib import SequenceMatcher
+from pathlib import Path
+
+
+# Repeating any external action is riskier than repeating a read-only action.
+# This set is intentionally conservative: unknown tools retain the normal
+# three-repeat rule rather than being guessed as side-effecting.
+SIDE_EFFECT_TOOLS = {
+    "send", "write", "edit", "delete", "remove", "payment", "pay",
+    "purchase", "post", "publish", "create", "submit",
+}
+
+
+class LoopDetector:
+    """Detects degenerate loops in model output streams."""
+
+    def __init__(
+        self,
+        repeat_threshold: int = 3,
+        time_threshold: int = 180,
+        similarity_threshold: float = 0.95,
+        text_mode: str = "duration",
+        json_output: bool = False,
+        expected_language: str | None = None,
+    ):
+        self.repeat_threshold = repeat_threshold
+        self.time_threshold = time_threshold
+        self.similarity_threshold = similarity_threshold
+        self.text_mode = text_mode
+        self.json_output = json_output
+        self.expected_language = expected_language
+
+        # State
+        window_size = max(repeat_threshold + 5, 20)
+        self.blocks: deque = deque(maxlen=window_size)
+        self.tool_calls: deque = deque(maxlen=window_size)
+        self.block_timestamps: deque = deque(maxlen=window_size)
+        self.loop_detected = False
+        self.loop_reason = ""
+        self.loop_details: dict = {}
+
+    def _similarity(self, a: str, b: str) -> float:
+        """Compute similarity ratio between two strings."""
+        return SequenceMatcher(None, a, b).ratio()
+
+    @staticmethod
+    def _params_hash(params: str) -> str:
+        """Return a stable, non-reversible identifier for logging only."""
+        return hashlib.sha256(params.encode("utf-8")).hexdigest()[:16]
+
+    @staticmethod
+    def _looks_english(text: str) -> bool:
+        """Conservative language-drift heuristic for an explicitly Chinese task."""
+        latin = len(re.findall(r"[A-Za-z]", text))
+        cjk = len(re.findall(r"[\u4e00-\u9fff]", text))
+        return latin >= 10 and cjk == 0
+
+    def _extract_tool_calls(self, text: str) -> list[dict]:
+        """Extract tool call signatures from model output text.
+
+        Handles common formats:
+        - JSON tool_call blocks
+        - Function call patterns
+        - Tool use markers
+        """
+        calls = []
+
+        # Pattern: JSON-style tool calls
+        # Match blocks like: {"name": "read", "parameters": {"path": "foo"}}
+        json_tool_pattern = r'\{\s*"name"\s*:\s*"([^"]+)"\s*,\s*"parameters"\s*:\s*(\{[^}]+\})\s*\}'
+        for match in re.finditer(json_tool_pattern, text, re.DOTALL):
+            try:
+                params_str = match.group(2)
+                params = json.loads(params_str)
+                calls.append({
+                    "name": match.group(1),
+                    "params": json.dumps(params, sort_keys=True),
+                })
+            except json.JSONDecodeError:
+                pass
+
+        # Pattern: function-like calls
+        func_pattern = r'(read|write|exec|edit|browser|web_fetch)\s*\(([^)]*)\)'
+        for match in re.finditer(func_pattern, text, re.IGNORECASE):
+            tool = match.group(1).lower()
+            args = match.group(2).strip()
+            if args:
+                calls.append({"name": tool, "params": args})
+
+        return calls
+
+    def _log(self, level: str, message: str):
+        """Output a log message."""
+        timestamp = datetime.now().isoformat()
+        # --json is a machine-readable contract: emit exactly one final summary
+        # document from main(), never interleave event records with it.
+        if self.json_output:
+            return
+        print(f"[{timestamp}] [{level}] {message}", flush=True)
+
+    def process_block(self, text: str, block_time: float | None = None):
+        """Process a single output block from the model.
+
+        Args:
+            text: The model output text for this block
+            block_time: Timestamp when this block was emitted (unix epoch)
+        """
+        if block_time is None:
+            block_time = time.time()
+
+        text = text.strip()
+        if not text:
+            return
+
+        self.blocks.append(text)
+        self.block_timestamps.append(block_time)
+
+        # Tool calls must be consecutive output events. A normal model/result
+        # block between calls is evidence of progress, so do not carry an old
+        # call across it when evaluating a call-loop.
+        tools = self._extract_tool_calls(text)
+        if not tools:
+            self.tool_calls.clear()
+        for t in tools:
+            self.tool_calls.append(t)
+
+        # A configured Chinese task that repeatedly produces English-only
+        # output is an actionable drift signal. It is opt-in because language
+        # cannot be inferred safely from an arbitrary log.
+        if self.expected_language == "zh" and len(self.blocks) >= self.repeat_threshold:
+            recent_blocks = list(self.blocks)[-self.repeat_threshold:]
+            if all(self._looks_english(block) for block in recent_blocks):
+                self.loop_detected = True
+                self.loop_reason = "Detected repeated English-only output in a Chinese task"
+                self.loop_details = {
+                    "type": "language_drift",
+                    "expected_language": "zh",
+                    "repeats": len(recent_blocks),
+                }
+                self._log("LOOP_DETECTED", self.loop_reason)
+                return
+
+        # --- Rule 1: Consecutive identical output blocks ---
+        if len(self.blocks) >= self.repeat_threshold:
+            recent = list(self.blocks)[-self.repeat_threshold:]
+            # Check if all recent blocks are identical or highly similar
+            base = recent[0]
+            identical = all(
+                self._similarity(base, b) >= self.similarity_threshold
+                for b in recent[1:]
+            )
+
+            if identical:
+                duration = block_time - self.block_timestamps[-self.repeat_threshold]
+                # Also check duration threshold (default 3 min)
+                if self.text_mode == "instant" or duration >= self.time_threshold:
+                    self.loop_detected = True
+                    self.loop_reason = (
+                        f"Detected {self.repeat_threshold}+ consecutive identical "
+                        f"output blocks over {duration:.0f}s"
+                    )
+                    self.loop_details = {
+                        "type": "consecutive_identical_output",
+                        "signal": "instant" if self.text_mode == "instant" else "duration_gated",
+                        "repeats": len(recent),
+                        "duration_seconds": duration,
+                        "sample": base[:200] + ("..." if len(base) > 200 else ""),
+                        "block_sizes": [len(b) for b in recent],
+                    }
+                    self._log(
+                        "LOOP_DETECTED",
+                        f"{self.loop_reason}\n  Sample: {self.loop_details['sample']}",
+                    )
+
+        # --- Rule 2: Same tool called 3+ times with identical params ---
+        if len(self.tool_calls) >= self.repeat_threshold:
+            recent_tools = list(self.tool_calls)[-self.repeat_threshold:]
+            tool_sigs = [(t["name"], t["params"]) for t in recent_tools]
+            if len(set(tool_sigs)) == 1:
+                self.loop_detected = True
+                name, params = tool_sigs[0]
+                self.loop_reason = (
+                    f"Detected {len(recent_tools)} consecutive identical "
+                    f"tool calls: {name}"
+                )
+                self.loop_details = {
+                    "type": "identical_tool_calls",
+                    "tool": name,
+                    "params_hash": self._params_hash(params),
+                    "repeats": len(recent_tools),
+                }
+                self._log(
+                    "LOOP_DETECTED",
+                    f"{self.loop_reason}\n  Params hash: {self.loop_details['params_hash']}",
+                )
+
+        # External side effects must not be retried blindly. Two identical
+        # attempts are enough to stop and require a fresh safety review.
+        if len(self.tool_calls) >= 2:
+            previous, current = list(self.tool_calls)[-2:]
+            if (
+                previous["name"] == current["name"]
+                and previous["params"] == current["params"]
+                and current["name"] in SIDE_EFFECT_TOOLS
+            ):
+                self.loop_detected = True
+                self.loop_reason = f"Detected repeated side-effecting tool call: {current['name']}"
+                self.loop_details = {
+                    "type": "repeated_side_effect_tool_call",
+                    "tool": current["name"],
+                    "params_hash": self._params_hash(current["params"]),
+                    "repeats": 2,
+                }
+                self._log("LOOP_DETECTED", self.loop_reason)
+
+    def reset(self):
+        """Reset detector state."""
+        self.blocks.clear()
+        self.tool_calls.clear()
+        self.block_timestamps.clear()
+        self.loop_detected = False
+        self.loop_reason = ""
+        self.loop_details = {}
+
+    def summary(self) -> dict:
+        """Return detection summary."""
+        return {
+            "loop_detected": self.loop_detected,
+            "reason": self.loop_reason,
+            "details": self.loop_details,
+            "blocks_processed": len(self.blocks),
+            "tool_calls_tracked": len(self.tool_calls),
+        }
+
+
+def read_from_file(filepath: str) -> list[tuple[str, float]]:
+    """Read blocks from a log file.
+
+    Each block is separated by a delimiter line like:
+    --- BLOCK N at TIMESTAMP ---
+
+    Returns list of (text, timestamp) tuples.
+    """
+    path = Path(filepath)
+    if not path.exists():
+        print(f"Error: File not found: {filepath}", file=sys.stderr)
+        sys.exit(2)
+
+    content = path.read_text(encoding="utf-8", errors="replace")
+    blocks = []
+    current_block: list[str] = []
+    current_time = time.time()
+
+    for line in content.splitlines():
+        # Match block delimiter
+        match = re.match(r"^--- BLOCK (\d+) at (.+) ---$", line)
+        if match:
+            if current_block:
+                blocks.append(("\n".join(current_block), current_time))
+                current_block = []
+            try:
+                ts = datetime.fromisoformat(match.group(2))
+                current_time = ts.timestamp()
+            except ValueError:
+                pass
+        else:
+            current_block.append(line)
+
+    # Don't forget the last block
+    if current_block:
+        blocks.append(("\n".join(current_block), current_time))
+
+    return blocks
+
+
+def iter_from_stdin():
+    """Yield stdin blocks as they close, preserving their arrival time.
+
+    Processing must happen during iteration. Collecting all of stdin before
+    evaluating blocks would assign nearly identical timestamps and invalidate
+    duration-gated detection for real streamed output.
+    """
+    current_block: list[str] = []
+
+    for line in sys.stdin:
+        if line.strip() == "":
+            if current_block:
+                yield "\n".join(current_block), time.time()
+                current_block = []
+        else:
+            current_block.append(line.rstrip("\n"))
+
+    if current_block:
+        yield "\n".join(current_block), time.time()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="LLM Degenerate Loop Guardrails — Detection",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  model_output 2>&1 | python3 detect_loop.py
+  python3 detect_loop.py --log sample.log
+  python3 detect_loop.py --threshold 4 --timeout 300 --log sample.log
+  python3 detect_loop.py --json --log sample.log --timeout 180
+""",
+    )
+    parser.add_argument(
+        "--log",
+        type=str,
+        help="Path to log file (reads from stdin if not provided)",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=int,
+        default=3,
+        help="Number of consecutive identical blocks to trigger detection (default: 3)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=180,
+        help="Minimum duration in seconds for loop detection (default: 180, i.e. 3 min)",
+    )
+    parser.add_argument(
+        "--text-mode",
+        choices=["duration", "instant"],
+        default="duration",
+        help=(
+            "Text-repeat policy: duration requires --timeout; instant triggers "
+            "after the repeat threshold (default: duration)"
+        ),
+    )
+    parser.add_argument(
+        "--similarity",
+        type=float,
+        default=0.95,
+        help="Similarity threshold for text comparison (default: 0.95)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results in JSON format",
+    )
+    parser.add_argument(
+        "--expect-language",
+        choices=["zh"],
+        help="Enable language-drift detection for an explicitly Chinese task",
+    )
+    args = parser.parse_args()
+
+    if args.threshold < 2:
+        parser.error("--threshold must be at least 2")
+    if args.timeout < 0:
+        parser.error("--timeout must be non-negative")
+    if not 0.0 <= args.similarity <= 1.0:
+        parser.error("--similarity must be between 0 and 1")
+
+    # Create detector
+    detector = LoopDetector(
+        repeat_threshold=args.threshold,
+        time_threshold=args.timeout,
+        similarity_threshold=args.similarity,
+        text_mode=args.text_mode,
+        json_output=args.json,
+        expected_language=args.expect_language,
+    )
+
+    # Read input
+    start_time = time.time()
+    total_blocks = 0
+    if args.log:
+        blocks = read_from_file(args.log)
+        for text, ts in blocks:
+            total_blocks += 1
+            detector.process_block(text, ts)
+            if detector.loop_detected:
+                break
+    else:
+        for text, ts in iter_from_stdin():
+            total_blocks += 1
+            detector.process_block(text, ts)
+            if detector.loop_detected:
+                break
+
+    if total_blocks == 0:
+        print("Warning: No input blocks found", file=sys.stderr)
+        if args.json:
+            print(json.dumps({"error": "no_input"}))
+        sys.exit(2)
+
+    # Output summary
+    summary = detector.summary()
+    summary["elapsed_seconds"] = time.time() - start_time
+    summary["total_blocks"] = total_blocks
+
+    if args.json:
+        print(json.dumps(summary, ensure_ascii=False, indent=2))
+    else:
+        print(f"\n{'=' * 60}")
+        print(f"Loop Detection Summary")
+        print(f"{'=' * 60}")
+        print(f"  Blocks processed: {total_blocks}")
+        print(f"  Loop detected:    {'YES ⚠️' if summary['loop_detected'] else 'NO ✅'}")
+        if summary["loop_detected"]:
+            print(f"  Reason:           {summary['reason']}")
+            details = summary.get("details", {})
+            if details.get("type") == "consecutive_identical_output":
+                print(f"  Repeats:          {details.get('repeats')}")
+                print(f"  Duration:         {details.get('duration_seconds', 0):.0f}s")
+                print(f"  Sample:           {details.get('sample', 'N/A')}")
+            elif details.get("type") == "identical_tool_calls":
+                print(f"  Tool:             {details.get('tool')}")
+                print(f"  Repeats:          {details.get('repeats')}")
+                print(f"  Params hash:      {details.get('params_hash', 'N/A')}")
+            elif details.get("type") == "repeated_side_effect_tool_call":
+                print(f"  Tool:             {details.get('tool', 'N/A')}")
+                print("  Action:           pause and re-check before retrying")
+        print(f"{'=' * 60}")
+
+    sys.exit(1 if summary["loop_detected"] else 0)
+
+
+if __name__ == "__main__":
+    main()

scripts/recovery_policy.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Turn detector output into a conservative, machine-readable next action.
+
+This module deliberately does not execute tools, retry requests, or switch models.
+It only produces a decision so the caller can apply its own permissions and policy.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+def decide(summary: dict[str, Any], *, retryable: bool = False, retry_count: int = 0) -> dict[str, Any]:
+    raw_detected = summary.get("loop_detected", False)
+    if not isinstance(raw_detected, bool):
+        raise ValueError("loop_detected must be a JSON boolean")
+    detected = raw_detected
+    details = summary.get("details") or {}
+    kind = details.get("type")
+
+    if not detected:
+        action = "continue"
+        rationale = "No degenerate-loop signal was detected."
+    elif kind == "repeated_side_effect_tool_call":
+        action = "pause_and_review"
+        rationale = "A repeated side-effecting call requires an idempotency and outcome check before retry."
+    elif retryable and retry_count == 0:
+        action = "stop_and_retry_once"
+        rationale = "Stop the current generation, then allow one controlled retry with a fresh context or strategy."
+    else:
+        action = "stop_and_escalate"
+        rationale = "Stop the current generation; do not blindly retry after a loop or exhausted retry budget."
+
+    return {
+        "action": action,
+        "rationale": rationale,
+        "detector_reason": summary.get("reason", ""),
+        "detector_type": kind,
+        "retryable": retryable,
+        "retry_count": retry_count,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create a conservative recovery decision from detector JSON.")
+    parser.add_argument("--summary", help="Detector JSON file; otherwise read one JSON document from stdin.")
+    parser.add_argument("--retryable", action="store_true", help="Allow one controlled retry when no retry has happened.")
+    parser.add_argument("--retry-count", type=int, default=0)
+    args = parser.parse_args()
+
+    try:
+        if args.summary:
+            with open(args.summary, encoding="utf-8") as handle:
+                raw = handle.read()
+        else:
+            raw = sys.stdin.read()
+        summary = json.loads(raw)
+        if not isinstance(summary, dict):
+            raise ValueError("summary must be a JSON object")
+        if args.retry_count < 0:
+            raise ValueError("retry-count must be non-negative")
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 2
+
+    try:
+        decision = decide(summary, retryable=args.retryable, retry_count=args.retry_count)
+    except ValueError as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 2
+    print(json.dumps(decision, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())