# 📦 @goodandready/dsh-agent-loop-guard

<div align="center">

<h3>Аварийный предохранитель от зацикливания вызовов инструментов и текстового потока агента для DeepSeek Harness</h3>

<p align="center">
  <a href="https://www.npmjs.com/package/@goodandready/dsh-agent-loop-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-agent-loop-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-agent-loop-guard.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
</p>

<p align="center">
  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
</p>

<p align="center">
  <a href="README.md"><b>🇬🇧 English</b></a> •
  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
</p>

<table align="center">
  <tr>
    <td align="center">
      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
      <br><br>
      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
    </td>
  </tr>
</table>

</div>

---

## ⚡ Назначение и решаемая проблема

При выполнении многоэтапных задач автономные ИИ-агенты могут попадать в петли повторных попыток: бесконечно перечитывать один и тот же файл без изменений, раз за разом безуспешно вызывать инструмент с одними и теми же параметрами или повторять одинаковые строки в потоковом ответе. Такие зацикливания приводят к мгновенному исчерпанию контекста и токенов, заморозке интерфейса и бесполезной трате бюджета.

**`@goodandready/dsh-agent-loop-guard`** — нативный плагин для среды выполнения DeepSeek Harness, предотвращающий зацикливание агента на уровне хоста без вмешательства в ядро DSH:

1. **Контроль прогресса инструментов (Progress-Aware Epochs)**: повторные вызовы инструментов блокируются *только тогда*, когда с прошлой попытки не изменилось состояние системы или результат. Легитимные продуктивные циклы (например, `чтение` ➔ `правка` ➔ `чтение` ➔ `правка`) выполняются абсолютно свободно.
2. **Предохранитель генерации текста (Assistant Output Loop Guard)**: отслеживает повторение отдельных строк и целых многострочных абзацев между шагами и ходами, выполняя мягкую отмену генерации без потери истории диалога.
3. **Безопасный переход в режим ответа (Answer-Only Mode)**: при фиксации зацикливания инструмент не просто падает с ошибкой, а возвращает структурированный отказ, обязывающий модель сформулировать текстовый ответ пользователю с объяснением проблемы.
4. **Маскирование секретов в журналах**: любые ключи доступа, токены и пароли автоматически заменяются на `[redacted]` в диагностических логах.

---

## 🏗️ Архитектура работы

```mermaid
graph TD
    subgraph DSH ["Среда выполнения DeepSeek Harness"]
        Turn["Ход выполнения агента<br/>(Рассуждение LLM и вызовы инструментов)"]
        Stream["Поток генерации ассистента<br/>(text-delta и block-end)"]
        UserStop["Анализ сообщений пользователя<br/>(Стоп-слова: стоп, хватит, прекрати, петля)"]
    end

    subgraph LoopGuard ["@goodandready/dsh-agent-loop-guard"]
        ToolInterceptor["Перехватчик ctx.tools.guard<br/>(Проверка denyReason перед запуском)"]
        ProgressEpoch["Трекер эпох прогресса<br/>(Хэширование аргументов и результатов)"]
        OutputState["AssistantOutputGuardState<br/>(Анализ повторов строк и блоков)"]
        SafeLogger["Санитизация журналов<br/>(Маскирование Bearer/API токенов)"]
    end

    subgraph Actions ["Действия защиты"]
        Allow["Разрешить выполнение инструмента<br/>(Новый результат / зафиксирован прогресс)"]
        Deny["Отказ с переходом в режим ответа<br/>(Требование текстового резюме от агента)"]
        Cancel["Мягкая отмена сессии<br/>(keepInbox: false при зацикливании текста)"]
    end

    Turn -->|agent/pre-step и вызов инструмента| ToolInterceptor
    ToolInterceptor --> ProgressEpoch
    ProgressEpoch -->|Изменение состояния подтверждено| Allow
    ProgressEpoch -->|Дубликат или превышен лимит| Deny
    Stream --> OutputState
    OutputState -->|Превышен лимит повторов текста| Cancel
    UserStop -->|Мгновенная фиксация остановки| Deny
    Deny -.-> SafeLogger
    Cancel -.-> SafeLogger
```

---

## ✨ Подробный разбор возможностей

### 1. Эпохи прогресса и дифференциация вызовов

В отличие от примитивных счётчиков, плагин анализирует реальную полезность действий агента:

* **Детерминированные отпечатки**: строит стабильные сигнатуры аргументов (`callFingerprint`) и результатов вызовов (`resultFingerprint`).
* **Эпохи полезного действия**: как только вызов приводит к новому результату (изменился файл, вернулся новый diff или токен прогресса), счётчик холостых попыток обнуляется.
* **Изоляция сетевых операций**: различные методы и эндпоинты (например, разные API-запросы Gitea или curl) не склеиваются по общему базовому URL.
* **Белый список инструментов отслеживания задач**: инструменты ведения списков задач (`todo_write`) обладают собственным независимым бюджетом, предотвращая ложные срабатывания при обновлении чек-листов.

### 2. Коды нарушений и реакции предохранителя

| Код защиты | Условие срабатывания | Лимит по умолчанию | Действие плагина |
|:---|:---|:---|:---|
| `LOOP_GUARD_STOP` | Пользователь отправил команду остановки (`стоп`, `хватит`, `прекрати`, `ответь`, `петля`, `stop`, `halt`, `cancel`) | Мгновенно | Блокирует вызовы инструментов; требует немедленный текстовый ответ |
| `LOOP_GUARD_DUPLICATE` | Повторный вызов с идентичными аргументами и неизменным результатом | 1 повтор | Пресекает топтание на месте; требует сменить подход |
| `LOOP_GUARD_REPEAT` | Череда вызовов инструментов одной группы без изменения состояния | `maxCallsPerRepeatGroup` (5) | Останавливает монотонные повторы |
| `LOOP_GUARD_LIMIT` | Суммарное число бесплодных попыток за текущий ход | `maxToolAttemptsPerTurn` (64) | Ограничивает общий бюджет холостых действий |
| `LOOP_GUARD_PROGRESS_LIMIT` | Повторные вызовы progress-инструментов без реального продвижения | `maxProgressToolCallsPerTurn` (16) | Блокирует бесконечную перезапись todo |
| `LOOP_GUARD_OUTPUT` | Модель генерирует одинаковые строки или блоки текста | `maxRepeatedAssistantLines` (5) | Мягко прерывает сессию через `agent.cancel()` |

### 3. Предотвращение зацикливания текстового вывода

Иногда модель зацикливается не на инструментах, а на генерации текста (повторяет одну фразу в цикле streaming):

* **Нормализация строк**: очищает невидимые символы переноса и множественные пробелы.
* **Детекция абзацев**: хэширует блоки текста до `maxAssistantBlockChars` (16 384 байт).
* **Иммунитет во время выполнения инструментов**: пока агент ждёт завершения длительной команды, отмена текста временно блокируется.
* **Чистый сброс**: при отправке нового сообщения пользователем состояние детектора полностью очищается.

### 4. Санитизация журналов и защита приватности

Все предупреждающие записи журнала автоматически маскируют чувствительные учетные данные:
* Токены Bearer, пароли, cookie и секреты в query-параметрах (`token=`, `api-key=`, `secret=`) заменяются на `[redacted]` до записи в лог.
* Ограничена глубина вложенности деревьев аргументов для предотвращения утечек памяти при разборе крупных JSON-структур.

### 5. Веб-интерфейс, живая телеметрия и обновление в один клик

* **Интегрированная карточка настроек**: нативно встроена во вкладку *«Настройки → Плагины → Настройки плагинов»* (`settings.plugin.item`, order 95).
* **Дизайн-система DSH**: построена строго на системных переменных DSH (`--dsw-alias-*`), доступных связках `<label>`/`<input>` (`htmlFor`/`id`) и нативном шевроне с плавной анимацией без тяжёлых сторонних UI-библиотек.
* **Телеметрия инцидентов**: живые счётчики заблокированных петель (`LOOP_GUARD_DUPLICATE`, `LOOP_GUARD_REPEAT`, `LOOP_GUARD_LIMIT`, `LOOP_GUARD_OUTPUT`) с возможностью мгновенного сброса через защищённый маршрут `/api/@goodandready/dsh-agent-loop-guard/telemetry`.
* **One-Click Updater**: проверка актуальных версий в реестре npm и обновление плагина в один клик через защищённый loopback API (`/api/@goodandready/dsh-agent-loop-guard/update`).

---

## 📦 Установка

Установка через командную строку DeepSeek Harness:

```bash
dsh plugin --profile web add @goodandready/dsh-agent-loop-guard
```

Перезапустите DSH и обновите вкладку браузера.

---

## ⚙️ Конфигурация

Настройка через файл `config.yaml` или панель управления DSH:

```yaml
# config.yaml
dsh-agent-loop-guard:
  maxToolAttemptsPerTurn: 64
  maxProgressToolCallsPerTurn: 16
  progressToolNames:
    - todo_write
  maxCallsPerRepeatGroup: 5
  blockExactDuplicates: true
  assistantOutputGuard: true
  maxRepeatedAssistantLines: 5
  maxRepeatedAssistantBlocks: 5
  maxAssistantBlockChars: 16384
```

### Таблица параметров конфигурации

| Параметр | Тип | По умолчанию | Описание |
|:---|:---|:---|:---|
| `maxToolAttemptsPerTurn` | `number` | `64` | Максимум холостых вызовов за ход. Значение `0` отключает суммарный бюджет. |
| `maxProgressToolCallsPerTurn` | `number` | `16` | Максимум вызовов progress-инструментов (`todo_write`) подряд без изменений. |
| `progressToolNames` | `array` | `["todo_write"]` | Список имён инструментов, маркирующих прогресс задач. |
| `maxCallsPerRepeatGroup` | `number` | `5` | Максимум повторений инструментов одной группы без смены результата. |
| `maxCallsPerToolPerTurn` | `number` | `5` | *(Устарело)* Устаревший алиас для `maxCallsPerRepeatGroup`. При указании обоих параметров приоритет имеет `maxCallsPerRepeatGroup`. В UI-карточке опущен во избежание дублирования. |
| `strictTools` | `array` | `[]` | Список имён инструментов с пониженным лимитом повторов (например, изменяющие файлы/состояние). |
| `strictToolLimit` | `number` | `3` | Максимальный лимит повторов для инструментов из списка `strictTools`. |
| `blockExactDuplicates` | `boolean` | `true` | Немедленно блокировать повторные идентичные вызовы без изменения состояния. |
| `dryRunMode` | `boolean` | `false` | Режим аудита: фиксация нарушений в логах и телеметрии без принудительной остановки вызовов. |
| `assistantOutputGuard` | `boolean` | `true` | Включить мониторинг зацикливания текстового потока модели. |
| `maxRepeatedAssistantLines` | `number` | `5` | Порог повторяющихся одинаковых строк текста для прерывания генерации. |
| `maxRepeatedAssistantBlocks` | `number` | `5` | Порог повторяющихся многострочных блоков до отмены хода. |
| `maxAssistantBlockChars` | `number` | `16384` | Максимальный размер текстового блока для хэширования (в байтах). |

---

## 🧪 Тестирование
 
Запуск полного набора из 51 автоматизированного теста и статической проверки:
 
```bash
npm test
npm run check
```
 
---
 
## 📄 Лицензия
 
* **Лицензия**: MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
* **История изменений**: Подробная хронология всех релизов и миграций ведётся в [CHANGELOG.md](CHANGELOG.md).