@goodandready/dsh-goal 0.1.9 → 0.2.0

package/README.md

@@ -18,6 +18,7 @@
 
 <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>
 
@@ -43,6 +44,12 @@ Complex engineering tasks require multi-step autonomy: decomposing high-level ob
 Without an autonomous tracking framework, agents can lose context across turns, stall in passive loops, or fail to notify users when complex workflows stall.
 
 **`@goodandready/dsh-goal`** introduces Goal Mode to DeepSeek Harness:
+* 💡 **Live Steering & Nudge (*Added in v0.2.0*)**: Dynamically clarify, amend, or guide the agent's active objective on the fly without aborting the loop.
+* 🔔 **Native Browser Notifications (*Added in v0.2.0*)**: Zero-dependency desktop push notifications via HTML5 `Notification API` when long-running goals complete or require attention.
+* 📑 **10 Quick Launch Presets (*Added in v0.2.0*)**: Ready-to-use engineering prompt chips (Fix Bug, Refactor YAGNI, Tests & Coverage, Code Review, Security Audit, New Feature, Docs, Upgrade Deps, Dead Code Cleanup, Performance).
+* 🛡️ **Tool-Failure Breaker (*Added in v0.2.0*)**: Configurable consecutive tool error limit (`consecutiveToolFailureLimit`, default: 3) to halt loops upon repetitive tool crashes and prevent token burn.
+* 📌 **Git Checkpoint Snapshot (*Added in v0.2.0*)**: Automatically captures start commit hash (`git rev-parse --short HEAD`) with 1-click `git diff` / rollback command in details modal.
+* 🐙 **GitHub & Gitea PR Comment Export (*Added in v0.2.0*)**: One-click formatted comment generator with collapsible `<details><summary>` milestone cards and token telemetry.
 * 🎯 **Sticky Top Goal Banner**: Pinned header over composer dock with live elapsed timer (`• 2s`, `• 1m 45s`), real-time status badge (`RUNNING`, `PAUSED`, `COMPLETED`), active goal title, and control actions.
 * ⏸️ **Play / Pause / Resume / Cancel**: Instantly pause the autonomous loop or resume execution on demand via buttons or `/goal` command.
 * 📋 **Milestone Breakdown & ETA**: Interactive checklist showing sub-tasks, completion status (`pending`, `in_progress`, `completed`, `failed`), progress bar, and dynamic completion ETA.
@@ -50,6 +57,7 @@ Without an autonomous tracking framework, agents can lose context across turns,
 * 🔘 **Quick Launch Button (*Added in v0.1.8*)**: Fast goal launcher docked above the message input with instant objective prompt modal. Toggleable in settings.
 * 📊 **Token Usage Tracking & Markdown Export (*Added in v0.1.7*)**: Accumulated prompt, completion, and total tokens tracked per session with one-click Markdown summary export.
 * 🤖 **Autonomous Agent Contract**: Provides `goal_set_milestones`, `goal_update_progress`, and `goal_finish` tools directly to the agent.
+* 🔄 **Core DSH Goal Tools Interception (*Added in v0.1.10*)**: Seamless drop-in compatibility for models calling built-in DSH goal tools (`update_goal`, `get_goal`, `create_goal`). Intercepts actions (`complete`, `pause`, `resume`, `edit`, `blocked`), bypasses rigid authority restrictions that caused crashes (`complete and blocked require a direct human turn`), and routes all state updates directly to GoalEngine.
 * 🛡️ **Safety Guardrails**: Configurable `maxIterations` safety limit and Smart Progress Guard to catch and pause idle turns without progress.
 * 🔔 **Web Audio Chimes**: Pleasant synthesized audio feedback on goal completion or failure via Web Audio API.
 
@@ -120,6 +128,7 @@ Handles `/goal` commands and subcommands:
 * Subscribes to `turn/end` for zero-latency turn-to-turn auto-drive using `setImmediate`.
 * Listens to `approval/asked` to automatically pause goal when operator confirmation is needed.
 * Registers agent tools: `goal_set_milestones`, `goal_update_progress`, `goal_finish`.
+* Seamlessly shadows core DSH goal tools: `update_goal`, `get_goal`, `create_goal` with zero collision and full `GOAL_OUTPUT` schema compliance.
 
 ### 4. `lib/client.js` — Frontend Web UI
 * **Sticky Top Banner**: Mounts via slot `conversation.input.dock` with live timer, status badge, pause/resume, and details button.
@@ -191,6 +200,8 @@ dsh-goal:
   autoDrive: true
   enableSound: true
   showQuickLaunchButton: true
+  consecutiveToolFailureLimit: 3
+  enableBrowserNotifications: true
 ```
 
 | Parameter | Type | Default | Description |
@@ -199,6 +210,8 @@ dsh-goal:
 | `autoDrive` | `boolean` | `true` | Keep the autonomous agent loop running between turns |
 | `enableSound` | `boolean` | `true` | Play audio chime when a goal completes or fails |
 | `showQuickLaunchButton` | `boolean` | `true` | Show the quick launch goal button above the composer dock |
+| `consecutiveToolFailureLimit` | `number` | `3` | Auto-pause goal if N consecutive turns hit tool execution errors (0 to disable) |
+| `enableBrowserNotifications` | `boolean` | `true` | Show native desktop push notifications on goal completion or failure |
 
 ---
 

package/{docs/README.ru.md → README.ru.md}

@@ -17,11 +17,21 @@
 </p>
 
 <p align="center">
-  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <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>
 
 ---
@@ -31,10 +41,17 @@
 Решение комплексных инженерных задач требует автономного многошагового выполнения: декомпозиции целей на майлстоуны, непрерывного выполнения итераций без ручного подталкивания пользователя и наглядного отслеживания прогресса.
 
 **`@goodandready/dsh-goal`** внедряет автономный режим достижения целей в DeepSeek Harness через команду `/goal`:
+* 💡 **Живая корректировка цели / Направление агента (*v0.2.0*)**: Возможность вносить точечные правки и уточнения в активную цель на лету без прерывания сессии.
+* 🔔 **Браузерные уведомления (*v0.2.0*)**: Нативные пуш-уведомления через HTML5 `Notification API` по завершении или сбое цели.
+* 📑 **10 инженерных пресетов (*v0.2.0*)**: Готовые кликабельные шаблоны задач (Fix Bug, Refactor YAGNI, Tests, Code Review, Security, Docs, Upgrade Deps, Cleanup, Performance) в окне запуска.
+* 🛡️ **Tool-Failure Breaker (*v0.2.0*)**: Настраиваемый порог ошибок инструментов (`consecutiveToolFailureLimit`, по умолчанию 3) для предотвращения бесконечных сбойных вызовов.
+* 📌 **Git Checkpoint (*v0.2.0*)**: Фиксация коммита старта (`git rev-parse --short HEAD`) и копирование команды `git diff` в 1 клик.
+* 🐙 **Экспорт отчета для GitHub / Gitea PR (*v0.2.0*)**: Генерация отчета со сворачиваемыми спойлерами `<details><summary>` для PR и задач.
 * 🎯 **Плавающий баннер в шапке**: зафиксированный статус-бар над чатом с таймером выполнения (`• 2s`, `• 1m 45s`), заголовком цели и кнопками управления.
 * ⏸️ **Управление циклом (Play / Pause / Cancel)**: мгновенная приостановка автономного цикла агента или его возобновление в любой момент.
 * 📋 **Интерактивная панель майлстоунов**: модальное окно со списком подзадач, прогресс-баром и журналом выполнения.
 * 🤖 **Инструменты агента**: `goal_set_milestones`, `goal_update_progress` и `goal_finish` для самостоятельной работы ИИ.
+* 🔄 **Перехват и замещение инструментов ядра DSH (*Добавлено в v0.1.10*)**: Бесшовная совместимость для моделей, вызывающих стандартные инструменты DSH (`update_goal`, `get_goal`, `create_goal`). Перехватывает действия (`complete`, `pause`, `resume`, `edit`, `blocked`), устраняет падения ядра (`complete and blocked require a direct human turn`) и синхронизирует состояние напрямую с GoalEngine.
 * 🛡️ **Защитные лимиты**: настраиваемое ограничение `maxIterations` для предотвращения бесконечных циклов.
 
 ---

package/README.zh.md

@@ -18,6 +18,7 @@
 
 <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>
 
@@ -50,6 +51,7 @@
 * 🔘 **快速启动按钮（v0.1.8 新增）**：常驻于输入框上方的启动按钮，支持弹窗一键制定目标，可在设置中自由开关。
 * 📊 **Token 消耗统计与 Markdown 导出（v0.1.7 新增）**：实时累计提示词、生成词及总 Token 消耗，支持一键复制完整 Markdown 报告。
 * 🤖 **智能体自主协作工具**：向智能体直接提供 `goal_set_milestones`、`goal_update_progress` 和 `goal_finish` 工具。
+* 🔄 **DSH 核心目标工具无缝拦截与兼容 (*v0.1.10 新增*)**: 为使用原生 DSH 目标控制指令的模型提供完美向下兼容，透明接管 `update_goal`、`get_goal`、`create_goal`。拦截并处理 `complete`、`pause`、`resume`、`edit`、`blocked` 等操作，彻底解决原生工具抛出的 `complete and blocked require a direct human turn` 权限崩溃错误，所有状态直接同步至 GoalEngine。
 * 🛡️ **安全防护机制**：支持自定义最大迭代次数（`maxIterations`）以及智能卡顿检测（Smart Progress Guard）。
 * 🔔 **Web Audio 提示音**：任务完成或失败时，通过 Web Audio API 播放舒缓的合成音效。
 
@@ -191,6 +193,8 @@ dsh-goal:
   autoDrive: true
   enableSound: true
   showQuickLaunchButton: true
+| `consecutiveToolFailureLimit` | `number` | `3` | 连续 N 轮工具错误自动熔断暂停（0 为禁用） |
+| `enableBrowserNotifications` | `boolean` | `true` | 目标完成时发送桌面原生系统通知 |
 ```
 
 | 参数项 | 类型 | 默认值 | 说明 |

package/docs/design/DESIGN.md

@@ -116,3 +116,69 @@
 4. **Экспорт отчета в Markdown (One-click Markdown Export):**
    - Для выполненной цели модальное окно предоставляет кнопку «📋 Скопировать отчёт в Markdown».
    - Генерирует отчет с заголовком, статусом, длительностью, итерациями, расходом токенов, резюме результатов и таблицей вех.
+
+### Решение 10: Бесшовная совместимость и перехват базовых инструментов целей DSH (update_goal, get_goal, create_goal) (v0.1.10)
+
+**Контекст:**
+В GitHub Issue #2 пользователи столкнулись с ошибкой:
+`complete and blocked require a direct human turn or the current goal round`
+при попытке модели завершить или обновить цель вызовом встроенного инструмента `update_goal`.
+Причина: встроенный плагин ядра DSH (`@deepseek-ai/dsh-tool-goal`) накладывает жёсткие проверки происхождения хода (authority checks), которые дают сбой в автономных циклах и при вызовах вне строго размеченного раунда цели.
+
+**Принятые решения:**
+1. **Динамическое замещение инструментов ядра в `ToolRuntime`:**
+   - При инициализации `ctx.inject(['tools'], (tctx) => { ... })` плагин проверяет наличие `update_goal`, `get_goal`, `create_goal` в глобальном слое (`tctx.tools.layers.global.tools.data`), удаляет конфликтующие строгие определения ядра и регистрирует собственные полнофункциональные версии.
+2. **Маршрутизация действий в `GoalEngine`:**
+   - `update_goal` перехватывает все действия модели:
+     - `action: 'complete'` — завершает цель в `engine.completeGoal()`, внедряет заключительный контекст `<goal_complete>` и возвращает статус `complete`;
+     - `action: 'pause'` — переводит цель в паузу через `engine.pause()`;
+     - `action: 'resume'` — возобновляет цель (`engine.resume()`) и перезапускает автодрайв агента;
+     - `action: 'edit'` — обновляет цель (`title`) и лимит раундов (`maxIterations`);
+     - `action: 'blocked'` — фиксирует блокер в `engine.pause()` с возвратом фазы `blocked` и кода причины.
+3. **Строгое соответствие схеме `GOAL_OUTPUT`:**
+   - Все перехваченные инструменты возвращают структуры, валидные по спецификации `GOAL_VALUE_SCHEMA` ядра (`goal: null` при отсутствии активной цели, либо объект цели с `id`, `revision`, `objective`, `phase`, `roundsStarted`, `maxGoalRounds`, `activation`).
+4. **Нейтрализация устаревшего системного промпта ядра:**
+   - Удаляется секция `tool:goal` ядра с ошибочными директивами и заменяется актуальной динамической инструкцией `tool:dsh-goal`.
+
+
+### Решение 11: Живая корректировка цели (Live Steering / Nudge), браузерные уведомления, 10 инженерных пресетов, защита от сбоев инструментов и Git Checkpoints (v0.2.0)
+
+**Контекст:**
+В процессе активной эксплуатации автономного режима Goal Mode пользователям требовались:
+1. Возможность вносить точечные корректировки и уточнения в активную или приостановленную цель без прерывания сессии или перезапуска;
+2. Получение нативных уведомлений операционной системы при завершении длительных фоновых задач;
+3. Быстрый выбор типовых инженерных задач (багфикс, рефакторинг, тесты, код-ревью и др.) без ручного набора стандартных промптов;
+4. Защита от бесконечных повторных вызовов падающих инструментов (Tool-Failure Breaker) с настраиваемым порогом;
+5. Фиксация точки старта в репозитории (Git Checkpoint) для моментального просмотра изменений и отката;
+6. Экспорт структурированного отчета с интерактивными спойлерами для комментариев в GitHub / Gitea PR.
+
+**Принятые решения:**
+1. **Live Steering / Nudge**:
+   - Реализован метод `engine.nudge(text, sid)` и эндпоинт `POST /dsh-goal/action` с `action: 'nudge'`.
+   - Поле ввода в модальном окне деталей позволяет оператору направить агента.
+   - Указание сохраняется в `goal.nudges` и инжектируется в следующий промпт автодрайва как высокоприоритетная директива `🚨 URGENT USER CLARIFICATION / STEERING`.
+2. **Нативные браузерные уведомления (Notification API)**:
+   - При завершении цели (`COMPLETED` или `FAILED`) клиент вызывает системный push через `new Notification(...)` при наличии разрешения.
+   - В карточке настроек добавлен чекбокс `enableBrowserNotifications` с интерактивным запросом прав.
+3. **10 инженерных шаблонов запуска (Quick Launch Presets)**:
+   - В окно быстрого запуска добавлена лента чипов с 10 сценариями на трёх языках (`en`, `ru`, `zh`):
+     1. 🐛 Fix Bug & Verify
+     2. ⚡ Refactor (YAGNI)
+     3. 📝 Tests & Coverage
+     4. 🔍 Code Review
+     5. 🚀 New Feature
+     6. 🛡️ Security Audit
+     7. 📚 Docs & Contract
+     8. 📦 Upgrade Deps
+     9. 🧹 Dead Code Cleanup
+     10. ⚙️ Performance
+4. **Защита от циклических сбоев инструментов (Tool-Failure Breaker)**:
+   - В `GoalEngine` внедрен счетчик последовательных ошибок инструментов (`consecutiveToolFailureLimit`, по умолчанию 3, 0 — отключено).
+   - При превышении порога цель автоматически переводится в `PAUSED` с фиксацией точной причины в журнале.
+   - Порог настраивается через Schemastery карточку в интерфейсе настроек.
+5. **Git Checkpoint Snapshot**:
+   - При старте цели через `node:child_process` фиксируется короткий хеш `git rev-parse --short HEAD` (с таймаутом 1 сек).
+   - В окне деталей отображается бейдж `📌 Git: <commit>` с копированием команды `git diff <commit>` в один клик.
+6. **Экспорт отчета для GitHub / Gitea PR**:
+   - Метод `exportReportGitHubPR(state)` форматирует статус, время, расход токенов, резюме и таблицу вех внутри сворачиваемого блока `<details><summary>`.
+   - В окне деталей добавлена кнопка «🐙 Копировать для GitHub PR».