npm - @goodandready/dsh-dsml-artifact-guard - Versions diffs - 0.2.12 → 0.2.14 - Mend

@goodandready/dsh-dsml-artifact-guard 0.2.12 → 0.2.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ---
+## [0.2.14] - 2026-11-05
+### Added
+- **Live Intercept Telemetry & Stats**: in `lib/telemetry.js`, implemented in-memory telemetry gathering `totalCleaned`, `sessionsGuarded`, `lastCleanedAt`, `lastModel`, `lastProvider`, and an in-memory ring buffer of recent incidents (#68).
+- **Telemetry Web Endpoint**: mounted `/api/dsh-dsml-artifact-guard/stats` (GET for telemetry payload, POST with loopback/same-origin validation to reset counters) (#68).
+- **Settings Card Telemetry Dashboard**: in `lib/client.js`, added a responsive telemetry block displaying live counters, a reset button, and an expandable recent incidents log (#68).
+- **Reasoning Think Artifact Cleaning**: in `lib/index.js`, added `cleanThinkArtifacts` configuration option to strip orphan `</think>` tags, trailing reasoning markers (`<｜end of sentence｜>`, `<｜thought｜>`), and auto-heal unclosed reasoning blocks at stream finish (#69).
+- **Incomplete Trailing DSML Sanitization**: in `lib/index.js`, added detection and stripping of incomplete trailing DSML closing tag tokens (`</｜DSML｜...`) at stream finish when balanced tags precede it (#69).
+## [0.2.13] - 2026-10-21
+### Fixed
+- **Desktop Profile Auto-Detection**: in `lib/updater.js`, updated `runtime()` to detect profile from `process.cwd()` when `cordis.yml` or `cordis.patch.yml` exists, properly resolving the `desktop` profile in DSH Desktop without requiring `DSH_PROFILE_DIR` (#66).
+- **DSH Desktop Origin Trust**: in `lib/updater.js`, updated `isTrustedUpdateRequest()` to accept loopback requests from Electron UI origin `dsh-app://app` (#66).
 ## [0.2.12] - 2026-10-15
 ### Fixed
@@ -31,121 +46,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.2.9] - 2026-10-07
 ### Fixed
-- **Settings Card Locale Snapshot Extraction**: safely extract active locale string from `LocaleSnapshot` object (`snap?.active`) returned by `ctx.locale.getLocale()` / `getSnapshot()`, eliminating fatal `TypeError: rawLang.startsWith is not a function` during settings card mount (#50, #57).
-- **Russian Language Registration & Ownership**: removed embedded `ru` dictionary from the plugin bundle to prevent `(namespace, 'ru')` duplicate registration collisions in core; delegate Russian translations to `dsh-russian-lang` via `props.t` and `ctx.locale.bind(NS)` (#58).
-- **Volatile Per-Field Settings Schema**: marked configuration fields volatile individually, enabling DSH to discover and generate settings form controls (#52).
+- **Safe Locale Extraction**: safely extracted active language string from `LocaleSnapshot` object (`snap?.active`), resolving fatal `TypeError: rawLang.startsWith is not a function` on settings card render (#50, #57).
+- **Locale Dictionary Isolation**: removed embedded `ru` dictionary from the plugin bundle to avoid `(namespace, 'ru')` collision in DSH core with `dsh-russian-lang` (#58).
+- **Fallback Translator Binding**: bound fallback translator to `ctx.locale.bind(NS)` inside `PluginCard` for clean localization rendering.
 ## [0.2.8] - 2026-09-26
 ### Added
-- **Universal DeepSeek Model Matching**: replaced strict single `providerId`/`modelId` pair with case-insensitive `modelPattern` RegExp (default: `deepseek`), automatically protecting all DeepSeek models regardless of provider gateway or vendor prefix (#48).
-- **Target Providers Filter**: added optional `providers` array filter (empty = all providers) (#48).
-- **Russian Localization**: added native `ru` translations in the Web UI settings card alongside English and Chinese (#48).
-### Changed
-- **De-identification**: removed proprietary `opencode-go` default in public package configuration.
-- **Backward Compatibility**: user configs with legacy `providerId` and `modelId` continue to work as an additional exact rule, with a deprecation notice and one-click clear button in the Web UI settings card.
-- **Documentation**: added dedicated section explaining lack of DSML processing in core DSH 0.1.7-rc.2.
+- **Global Model Regex Scoping**: replaced rigid single `providerId`/`modelId` requirements with universal case-insensitive `modelPattern` RegExp (default `deepseek`), automatically protecting all DeepSeek models across all providers (#48).
+- **Whitelist Provider Filtering**: added optional `providers` array parameter to restrict protection to specified provider IDs while allowing empty array to guard all providers (#48).
+- **Backward-Compatible Legacy Scope**: added automatic backward compatibility for existing user configs with legacy `providerId`/`modelId`, displaying an informational notice and clean action in the settings card (#48).
+- **De-identified Defaults**: removed proprietary `opencode-go` default from public package distribution (#48).
 ## [0.2.7] - 2026-09-25
 ### Fixed
-- **Volatile Config Unwrapping**: introduced `unwrapConfig` helper to gracefully handle pre-resolved volatile schema references passed by Cordis to `apply` and `ctx.on('config')`, avoiding TypeError on functions inside volatile schemas (#47).
-## [0.2.6] - 2026-09-25
-### Fixed
-- **SettingsForms Migration (DSH 0.1.7)**: marked Config schema as volatile and configured settings policy (`auto: false`) to suppress generic auto-generated form duplicates, while resolving row ID `dsh-dsml-artifact-guard` via client `configForms` with live subscription support (#17).
-- **Client Locale Lifecycle**: wrapped client locale registration in `ctx.effect` to ensure clean namespace disposal on HMR and avoid collision on module reload (#44).
-## [0.2.5] - 2026-09-24
-### Fixed
-- **Preflight & Locale Contract**: eliminated nonexistent `locale.get()` call in `lib/client.js`, using injected `props.t` with canonical `ctx.locale.bind(NS)` fallback (#36).
-- **Streaming Buffer & Tag Balancing**: replaced fixed 64-character buffer slicing with delimiter-based tag boundary scanning (`<` and `>`), ensuring DSML parameter tags of arbitrary length preserve open/close tag balance without premature truncation (#37).
-- **One-Click Updater LAN Support**: updated `isTrustedUpdateRequest` to allow same-origin requests matching Host/Origin, enabling one-click updates from LAN and reverse-proxy Web UIs while retaining strict loopback verification for local endpoints (#38).
-- **Dead Code Elimination**: connected `checkRequestMethod` helper to updater POST handler (#39).
-## [0.2.4] - 2026-09-22
-### Fixed
-- The settings card no longer waits for the removed `settingsScope` service. It uses `configForms` on current DeepSeek Harness (#41).
-## [0.2.3] - 2026-09-19
-### Fixed
-- **Settings reachable again on the plugin's own page**: the card registered into
-  `settings.plugin.item` / `plugins.row.config`, and the current DSH core
-  (0.1.6-alpha.2) only renders a plugin's configuration page for entries registered
-  in the plugin list seat `plugins.item` — that is how `dsh-agentrouter` and
-  `dsh-agent-orchestrator` show their settings. The view-aware `PluginItem` is now
-  registered there as well (`id: 'dsh-dsml-artifact-guard'`, order 95, static label),
-  with the row seat and the legacy card kept as fallbacks.
-- The render path was hardened on the way: `PluginCard` is wrapped in its own error
-  boundary so a throw inside this card cannot take the whole client batch down.
-## [0.2.2] - 2026-09-18
-### Fixed
-- **Settings reachable again (`lib/client.js`)**: the settings card registered into `settings.plugin.item`, a slot the current DSH core no longer renders, so the plugin's settings were unreachable. The surface now registers into the Plugins page row seat `plugins.row.config`, keyed `@goodandready/dsh-dsml-artifact-guard#dsh-dsml-artifact-guard`: the plugin's row gains a configure control whose page is the settings form (`view: 'page'`, rendered bare — `PluginCard` accepts `bare` and drops the card wrapper because the host page draws the title, icon, crumb and padding) plus a one-line state under the title (`view: 'summary'`). The legacy seat stays registered as a fallback for older cores ([#31](http://192.168.1.111:3005/goodandready/dsh-dsml-artifact-guard/issues/31)).
-- **Row-seat guard (`test/row-config-seat.test.js`)**: asserts the row key, the seat order (row seat first, legacy seat kept) and the bare page render.
----
-## [0.2.1] - 2026-09-18
-### Fixed
-- **Theme Semantic Standardization (`lib/client.js`)**: Eliminated all 42 hardcoded hex/rgba color literals in favor of canonical DeepSeek Harness theme CSS custom properties (`--dsw-alias-...`) and `color-mix()` tints, guaranteeing high contrast and legibility across Dark and Light modes ([#26](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/26)).
-- **Theme Regression Test Guard (`test/theme.test.js`)**: Added automated regression test asserting zero hardcoded hex and rgba color literals in client surfaces.
-- **Repository Hygiene**: Fixed `.gitignore` whitespace rule for `AGENTS.md` and untracked `package-lock.json` in alignment with zero-dependency architecture.
+- **Client Locale Lifecycle**: bound client locale registration lifecycle via `ctx.effect` to ensure clean unregistration on HMR and card reload (#44).
+- **DSH 0.1.7 SettingsForms Discovery**: marked each user-editable schema field volatile and registered fiber-attributed settings policy with `auto: false` (#17).
----
-## [0.2.0] - 2026-09-17
-### Added
-- **Native Settings Card (`lib/client.js`)**: Registered UI card in slot `settings.plugin.item` with snapshot status check, configuration inputs, and disabled warning indicator ([#17](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/17)).
-- **One-Click In-Place Updater (`lib/updater.js`)**: Standard HTTP endpoint `/api/dsh-dsml-artifact-guard/update` with SemVer comparison, loopback/same-origin protection, and update execution ([#18](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/18)).
-- **Core Primitive Chevron**: Requested `IconChevronDownOutline14` with SVG fallback.
-### Fixed
-- **Package Hygiene**: Deduplicated multilingual READMEs in `docs/` and restricted `package.json#files` allowlist, reducing package size by ~40% ([#20](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/20)).
-- **Repository Cleanliness**: Removed `AGENTS.md` from git tracking ([#19](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/19)) and eliminated legacy `.tgz` archives from source tree ([#21](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/21)).
----
-## [0.1.5] - 2026-09-17
-### Documentation
-- Fixed Mermaid diagram edge label syntax on GitHub and added standard community support block ([#15](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/15)).
----
-## [0.1.4] - 2026-09-12
-### Changed
-- Schema `mode` default set to `sanitize` for out-of-the-box protection ([#11](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/11)).
-- Added robust open/close tag balancing in `sanitizeDsmlArtifacts` to handle prior closed blocks in prose ([#11](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/11)).
-- Updated design contract documentation and verified package hygiene ([#11](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/11)).
----
-## [0.1.3] - 2026-09-06
-### Changed
-- Wrapped `llm/stream` handler in `ctx.effect` for clean lifecycle unmount ([#8](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/8)).
-- Updated `cordis.patch.yml` to use `config: {}`, allowing schema defaults to apply automatically unless overridden ([#9](https://github.com/GooDAnDReaDY/dsh-dsml-artifact-guard/issues/9)).
----
-## [0.1.2] - 2026-09-02
+## [0.2.6] - 2026-09-24
 ### Fixed
-- Packaging and runtime compatibility adjustments for DSH profile loader.
----
-## [0.1.1] - 2026-08-30
-### Added
-- Initial release: synchronous, fail-open DSML protocol closing tag sanitizer for DeepSeek Harness model streams.
+- **Deep Audit Resolution**: removed nonexistent `ctx.locale.get()` calls in favor of injected `props.t` with `ctx.locale.bind(NS)` fallback (#36).
+- **Arbitrary Tag Length Buffer Scanning**: upgraded stream buffer scanning to delimiter-based boundary tracking supporting DSML tags of arbitrary length without buffer truncation (#37).
+- **LAN Same-Origin Security**: allowed same-origin update requests from LAN/reverse-proxy UIs while enforcing strict Host/Origin match and loopback origin security (#38).
+- **Request Method Verification Integration**: integrated `checkRequestMethod` helper into updater POST handler, eliminating dead export (#39).

package/README.md CHANGED Viewed

@@ -2,7 +2,7 @@
 <div align="center">
-<h3>Fail-Open Stream Sanitizer for Leaked Protocol DSML Closing Tags in DeepSeek Harness</h3>
+<h3>Zero-dependency streaming guard and sanitizer for leaked DeepSeek DSML protocol tags and reasoning artifacts</h3>
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-dsml-artifact-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -24,9 +24,9 @@
 <table align="center">
   <tr>
     <td align="center">
-      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      ⭐ <strong>If you find this plugin helpful, please star it on GitHub</strong> — your support helps maintain and develop the project.
       <br><br>
-      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+      🐛 <strong>Found a bug or have a feature idea?</strong> Feel free to open an issue on GitHub in any language.
     </td>
   </tr>
 </table>
@@ -35,103 +35,25 @@
 ---
-## ⚡ Overview & The Problem
+## ⚡ Problem & Purpose
-When interacting with certain upstream model providers or API gateways, raw DSML (DeepSeek Markup Language) tool-invocation protocol tags can leak into the assistant's visible text stream. Users frequently see trailing protocol clutter like:
+When streaming responses from DeepSeek models via third-party proxies, gateways, or incompatible providers, protocol closing tags for tool invocations (DSML — DeepSeek Markup Language) occasionally leak into the visible text channel. Users observe raw markup at the end of their conversation:
 ```text
-Done. All tests have passed.
+Response completed successfully.
 </｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>
 ```
-These leaked closing tags visually pollute the chat bubble, cause Markdown rendering glitches, and can confuse downstream agents or clipboard exports.
+Additionally, reasoning models (such as DeepSeek-R1 / V3) or interrupted network streams can leave orphan `</think>` tags, dangling tokens (`<｜end of sentence｜>`), or unclosed thinking blocks that corrupt markdown rendering.
-**`@goodandready/dsh-dsml-artifact-guard`** is a lightweight, host-only runtime stream interceptor for DeepSeek Harness that cleans up these terminal artifacts in real time before they reach the user interface:
+**`@goodandready/dsh-dsml-artifact-guard`** is a high-performance runtime guard for DeepSeek Harness that cleans these protocol artifacts in real time before they reach the user interface:
-1. **Synchronous Stream Contract Preservation**: Cordis requires stream interceptors to return an `AsyncIterable` synchronously. Making interceptors `async` returns a `Promise` that crashes the harness turn with `stream is not async iterable`. This guard adheres strictly to the synchronous hook contract.
-2. **Split Chunk Buffer Pipeline**: Protocol tags often arrive split across multiple TCP or WebSocket text deltas. The guard maintains a small sliding buffer (`KEEP = 96` bytes) to reliably match and strip multi-chunk tails.
-3. **100% Fail-Open Safety**: Never drops legitimate user or assistant text. Legitimate discussions about DSML syntax or internal tool calls are preserved intact.
-4. **Targeted Provider & Model Scoping**: Restricts processing specifically to the provider and model configurations that exhibit tag leakage, passing other model traffic through with zero overhead.
----
-## 💡 Why Not in DSH Core?
-As of DeepSeek Harness **0.1.7-rc.2**, the core upstream stream pipeline (`dsh-llm-pi-ai`, `dsh-llm-deepseek*`, etc.) does not perform terminal DSML protocol cleanup — there is zero mention or handling of `｜DSML｜` anywhere in the core engine. When upstream gateways (e.g. `commandcode`, `deepseek-official`, or custom proxies) leak protocol closing tags at the conclusion of an assistant turn, DSH forwards them directly to the frontend.
-`dsh-dsml-artifact-guard` serves as the universal runtime guard across all DeepSeek models regardless of provider gateway or routing configuration.
----
-## 🏗️ Architecture
-```mermaid
-graph TD
-    subgraph DSH ["DeepSeek Harness Runtime"]
-        Turn["Agent Turn Execution<br/>(LLM Stream Request)"]
-        ChatUI["Chat UI Stream Consumer<br/>(Renders clean markdown text)"]
-    end
-    subgraph Guard ["@goodandready/dsh-dsml-artifact-guard"]
-        Hook["Synchronous llm/stream Hook<br/>(Returns AsyncIterable synchronously)"]
-        ScopeCheck{"Scope Match?<br/>(providerId & modelId)"}
-        PassThrough["Raw Stream Pass-Through<br/>(Zero overhead for other models)"]
-        Buffer["Sliding Tail Buffer<br/>(Preserves trailing 96 bytes across deltas)"]
-        Detector{"Terminal Artifact?<br/>(Matches leaked DSML tail at finish)"}
-        Sanitize["Sanitize Mode<br/>(Strips leaked closing tags)"]
-        Audit["Audit Mode<br/>(Emits ctx.logger warning only)"]
-    end
-    Turn -->|llm/stream hook| Hook
-    Hook --> ScopeCheck
-    ScopeCheck -->|No| PassThrough
-    ScopeCheck -->|Yes| Buffer
-    PassThrough --> ChatUI
-    Buffer --> Detector
-    Detector -->|No Artifact| ChatUI
-    Detector -->|Artifact detected: sanitize| Sanitize --> ChatUI
-    Detector -->|Artifact detected: audit| Audit --> ChatUI
-```
----
-## ✨ Features & Capabilities
-### 1. Synchronous Hook Guarantee
-Under Cordis and DSH service lifecycles, event listeners on `llm/stream` must return the transformed stream synchronously. An asynchronous hook wrapper will return a `Promise<AsyncIterable>`, causing the runtime dispatcher to immediately throw `TypeError: stream is not async iterable`. `dsh-dsml-artifact-guard` wraps the stream generator in a pure synchronous registration.
-### 2. Multi-Chunk Tail Buffering
-In real-world streaming, the artifact `</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>` is frequently fractured into fragments:
-* Chunk 1: `All tasks complete. </｜DSML｜pa`
-* Chunk 2: `rameter> </｜DSML｜invoke> `
-* Chunk 3: `</｜DSML｜tool_calls>`
-The guard retains a minimal 96-byte window until the next chunk or `finish` event arrives, ensuring fractured tags are seamlessly detected and sanitized as a single terminal artifact.
-### 3. Fail-Open Architecture
-* If the text contains genuine prose about DSML (e.g. `<｜DSML｜tool_calls>example</｜DSML｜tool_calls>`), it is **never** removed.
-* Non-text chunks (`tool-call-delta`, `usage`, `finish`) are forwarded immediately without delay.
-* Any malformed chunk structure passes through transparently to preserve session stability.
-### 4. Flexible Operating Modes
-* **`sanitize`** *(default)*: Strips terminal DSML closing tags and logs a warning with the count of removed artifacts.
-* **`audit`**: Emits diagnostic logs with `ctx.logger.info(...)` without modifying the user-visible stream.
-* **`disabled`**: Bypasses processing entirely.
-### 5. Native Web UI Settings Card
-Registered directly in DeepSeek Harness `plugins.row.config` and `plugins.item` slots (`lib/client.js`):
-* **Reactive Configuration**: Adjust `mode`, `providers`, and `modelPattern` on the fly without restarting the harness.
-* **Snapshot State Awareness**: Gracefully handles snapshot loading, ready, and unavailable states.
-* **Protection Bypass Warning**: Displays a prominent `OFF` badge and warning banner when the guard is set to `disabled`.
-### 6. One-Click In-Place Auto-Updater
-A canonical HTTP management route (`/api/dsh-dsml-artifact-guard/update`) mounted via `lib/updater.js`:
-* **SemVer Inspection**: Queries the registry and compares versions with full pre-release support.
-* **Loopback & Same-Origin Protection**: Write mutations (`POST`) are strictly restricted to local loopback connections with valid origin headers.
-* **Clean Invocation**: Executes package updates safely without risky CLI bypass flags.
-### 7. Full Dark & Light Theme Compliance
-All client UI styles are strictly tokenized via DeepSeek Harness `--dsw-alias-...` CSS custom properties and `color-mix()` functions with zero hardcoded hex or rgba color literals. High contrast and accessibility are guaranteed in both Dark and Light themes, guarded by automated regression tests (`test/theme.test.js`).
+1. **Strict Synchronous Hook Contract**: Implements the Cordis `llm/stream` hook synchronously, returning an `AsyncIterable` directly to preserve runtime integrity and avoid fatal `TypeError: stream is not async iterable` errors.
+2. **Chunk Boundary Buffer**: Uses a 96-byte sliding window to reliably intercept closing tags fragmented across network packet boundaries.
+3. **Incomplete Token Recovery at Finish**: Detects and strips truncated protocol closing prefixes (`</｜DSML｜...`) when connections terminate abruptly.
+4. **Reasoning Artifact Protection (`cleanThinkArtifacts`)**: Strips orphan `</think>` tags, removes trailing reasoning markers, and heals unclosed `<think>` blocks at stream finish.
+5. **Fail-Open Tag Balancing**: Tracks open and closed tags to guarantee that legitimate technical discussions containing DSML or think examples are never altered.
+6. **Live Telemetry & Metrics Dashboard**: Real-time in-memory counters (guarded sessions, stripped tags, last incident time, and recent events log) available directly in the native Web UI card.
 ---
@@ -149,14 +71,15 @@ Restart your DeepSeek Harness instance.
 ## ⚙️ Configuration (`settings.yaml`)
-Configure model matching and provider targets in `settings.yaml` or through the Web UI:
+Configure matching rules in `settings.yaml` or through the Web UI Settings Card:
 ```yaml
 # settings.yaml
 dsh-dsml-artifact-guard:
   mode: sanitize
-  modelPattern: "deepseek"   # Case-insensitive RegExp matching all DeepSeek models
-  providers: []             # Empty = guard all providers; or e.g. ["commandcode", "deepseek-official"]
+  modelPattern: "deepseek"
+  providers: []
+  cleanThinkArtifacts: false
 ```
 ### Configuration Parameters
@@ -166,6 +89,7 @@ dsh-dsml-artifact-guard:
 | `mode` | `string` | `"sanitize"` | Operation mode: `"sanitize"` (strip tags), `"audit"` (log only), or `"disabled"` |
 | `modelPattern` | `string` | `"deepseek"` | Case-insensitive RegExp matched against model IDs (e.g. `deepseek`, `deepseek-v4.*`, `deepseek/.*`) |
 | `providers` | `string[]` | `[]` | Optional list of provider IDs. When empty, guards all providers |
+| `cleanThinkArtifacts` | `boolean` | `false` | Strips orphan `</think>` tags, removes trailing reasoning markers, and heals unclosed reasoning blocks |
 | `providerId` | `string` | `undefined` | *(Deprecated)* Legacy exact provider identifier; maintained for backward compatibility |
 | `modelId` | `string` | `undefined` | *(Deprecated)* Legacy exact model identifier; maintained for backward compatibility |
@@ -173,6 +97,8 @@ dsh-dsml-artifact-guard:
 | Method | Endpoint | Access | Description |
 |:---|:---|:---|:---|
+| `GET` | `/api/dsh-dsml-artifact-guard/stats` | Web UI / Localhost | Retrieves live in-memory telemetry and recent incident history |
+| `POST` | `/api/dsh-dsml-artifact-guard/stats` | Loopback & Same-Origin | Resets telemetry counters and clears the recent incident log |
 | `GET` | `/api/dsh-dsml-artifact-guard/update` | Web UI / Localhost | Retrieves current version, latest registry version, and update status |
 | `POST` | `/api/dsh-dsml-artifact-guard/update` | Loopback & Same-Origin | Triggers in-place package update via DSH CLI |
@@ -180,7 +106,7 @@ dsh-dsml-artifact-guard:
 ## 🧪 Testing
-Run the automated test suite covering split chunks, audit vs sanitize modes, scope matching, and synchronous hook contracts:
+Run the automated test suite:
 ```bash
 npm test
@@ -192,7 +118,3 @@ npm run check
 ## 📄 License
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
----
-For a complete release history and version migration notes, see [CHANGELOG.md](CHANGELOG.md).

package/README.ru.md CHANGED Viewed

@@ -2,7 +2,7 @@
 <div align="center">
-<h3>Предохранитель и потоковый очиститель от артефактов закрывающих тегов протокола DSML в DeepSeek Harness</h3>
+<h3>Предохранитель и потоковый очиститель от артефактов закрывающих тегов DSML и reasoning-разметки в DeepSeek Harness</h3>
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-dsml-artifact-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -44,79 +44,16 @@
 </｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>
 ```
-Такие теги загрязняют чат, ломают рендеринг Markdown и сбивают парсинг при копировании или передаче ответов другим агентам.
+Кроме того, reasoning-модели (например, DeepSeek-R1 / V3) или обрывы сетевых сессий могут оставлять сиротливые теги `</think>`, концевые маркеры (`<｜end of sentence｜>`) или незакрытые блоки размышлений, ломающие вёрстку Markdown.
-**`@goodandready/dsh-dsml-artifact-guard`** — легковесный плагин времени выполнения (host-only) для DeepSeek Harness, перехватывающий и удаляющий эти паразитные терминальные артефакты в реальном времени до того, как текст попадёт в интерфейс:
+**`@goodandready/dsh-dsml-artifact-guard`** — легковесный плагин времени выполнения для DeepSeek Harness, перехватывающий и удаляющий эти паразитные терминальные артефакты в реальном времени до того, как текст попадёт в интерфейс:
-1. **Строго синхронный контракт хука**: в среде Cordis обработчик события `llm/stream` обязан синхронно возвращать итератор `AsyncIterable`. Сделать обработчик асинхронным (`async`) означает вернуть `Promise`, что неизбежно приводит к падению среды выполнения с ошибкой `stream is not async iterable`. Плагин строго соблюдает синхронный контракт.
-2. **Буферизация фрагментированного хвоста**: сетевые чанки часто разрезают закрывающие теги на части. Плагин использует скользящее окно размером 96 байт (`KEEP = 96`), гарантируя надёжный захват и вырезание артефакта, даже если он разделен между пакетами.
-3. **100% Fail-Open архитектура**: плагин никогда не удаляет полезный пользовательский текст или легитимные обсуждения синтаксиса DSML.
-4. **Адресный скоупинг (Provider & Model)**: фильтрация применяется только к целевым провайдерам и моделям, у которых наблюдается утечка протокольных тегов. Трафик остальных моделей проходит без задержек и оверхеда.
----
-## 💡 Почему этого нет в ядре DSH?
-По состоянию на DeepSeek Harness **0.1.7-rc.2**, ядро системы (`dsh-llm-pi-ai`, `dsh-llm-deepseek*` и др.) вообще не выполняет очистку завершающих тегов DSML — в ядровом коде нет ни единого упоминания `｜DSML｜`. Когда вышестоящие провайдеры (например, `commandcode`, `deepseek-official` или внешние шлюзы) отдают в потоке закрывающие теги протокола, DSH пропускает их прямо в интерфейс чата.
-Плагин `dsh-dsml-artifact-guard` обеспечивает универсальную защиту для всех моделей DeepSeek независимо от конкретного шлюза или маршрутизатора.
----
-## 🏗️ Архитектура работы
-```mermaid
-graph TD
-    subgraph DSH ["Среда DeepSeek Harness"]
-        Turn["Ход выполнения агента<br/>(Запрос к потоку модели)"]
-        ChatUI["Отображение в чате<br/>(Чистый текст без паразитных тегов)"]
-    end
-    subgraph Guard ["@goodandready/dsh-dsml-artifact-guard"]
-        Hook["Синхронный хук llm/stream<br/>(Возвращает AsyncIterable синхронно)"]
-        ScopeCheck{"Совпадает скоуп?<br/>(providerId и modelId)"}
-        PassThrough["Сквозной пропуск потока<br/>(Нулевой оверхед для других моделей)"]
-        Buffer["Буфер скользящего хвоста<br/>(Сохраняет последние 96 байт)"]
-        Detector{"Терминальный артефакт?<br/>(Поиск хвоста DSML при finish)"}
-        Sanitize["Режим Sanitize<br/>(Вырезание закрывающих тегов)"]
-        Audit["Режим Audit<br/>(Логирование через ctx.logger)"]
-    end
-    Turn -->|Хук llm/stream| Hook
-    Hook --> ScopeCheck
-    ScopeCheck -->|Нет| PassThrough
-    ScopeCheck -->|Да| Buffer
-    PassThrough --> ChatUI
-    Buffer --> Detector
-    Detector -->|Нет артефакта| ChatUI
-    Detector -->|Артефакт найден: sanitize| Sanitize --> ChatUI
-    Detector -->|Артефакт найден: audit| Audit --> ChatUI
-```
----
-## ✨ Подробный разбор возможностей
-### 1. Защита синхронного контракта Cordis
-В архитектуре Cordis вызов `ctx.on('llm/stream', (o, next) => ...)` ожидает немедленный возврат асинхронного генератора. Если функция хука объявлена как `async`, JavaScript оборачивает возвращаемое значение в `Promise`. В результате потребители стрима падают с фатальной ошибкой `TypeError: stream is not async iterable`. `dsh-dsml-artifact-guard` оборачивает поток синхронно, сохраняя целостность рантайма.
-### 2. Захват разорванных сетевых чанков
-В реальном сетевом потоке завершающая последовательность тегов может приходить отдельными фрагментами:
-* Чанк 1: `Задача выполнена. </｜DSML｜pa`
-* Чанк 2: `rameter> </｜DSML｜invoke> `
-* Чанк 3: `</｜DSML｜tool_calls>`
-Буфер скользящего хвоста удерживает последние 96 байт до получения следующего текстового блока или сигнала завершения `finish`, точно сопоставляя полный шаблон и удаляя его как единое целое.
-### 3. Гарантия сохранности данных (Fail-Open)
-* Если в ответе содержится обычный текст с упоминанием тегов (например, руководство по написанию `<｜DSML｜tool_calls>`), текст **никогда** не удаляется.
-* Нетекстовые чанки (`tool-call-delta`, `usage`, `finish`) пробрасываются немедленно без задержек.
-* При любых непредвиденных ошибках или нестандартных форматах чанков поток не прерывается, а беспрепятственно передаётся дальше.
-### 4. Режимы работы
-* **`sanitize`** *(по умолчанию)*: вырезает паразитные закрывающие теги и фиксирует событие в журнале с указанием числа удалённых артефактов.
-* **`audit`**: только логирует обнаружение артефактов через `ctx.logger.info(...)`, не модифицируя текст в чате.
-* **`disabled`**: полностью отключает обработку.
+1. **Строго синхронный контракт хука**: в среде Cordis обработчик события `llm/stream` возвращает `AsyncIterable` синхронно без Promise-обёрток.
+2. **Буферизация фрагментированного хвоста**: скользящее окно размером 96 байт захватывает закрывающие теги, даже если они разрезаны между сетевыми чанками.
+3. **Очистка неполных префиксов тегов при обрыве связи**: при получении сигнала `finish` срезает оборванные терминальные остатки (`</｜DSML｜...`).
+4. **Защита от reasoning-артефактов (`cleanThinkArtifacts`)**: очищает сиротливые `</think>`, терминальные спецтокены шлюзов и закрывает аварийно оборванные `<think>`.
+5. **100% Fail-Open архитектура**: плагин отслеживает баланс тегов и никогда не удаляет полезный пользовательский текст или обсуждения разметки.
+6. **Панель телеметрии и статистики в UI**: отображение числа защищённых сессий, срезанных тегов, времени последней активности и журнала недавних перехватов с кнопкой сброса.
 ---
@@ -134,14 +71,15 @@ dsh plugin --profile web add @goodandready/dsh-dsml-artifact-guard
 ## ⚙️ Конфигурация (`settings.yaml`)
-Настройка провайдера и модели в `settings.yaml` или через веб-панель управления:
+Настройка параметров в `settings.yaml` или через веб-панель управления:
 ```yaml
 # settings.yaml
 dsh-dsml-artifact-guard:
   mode: sanitize
-  providerId: "your-provider-id"
-  modelId: "your-model-id"
+  modelPattern: "deepseek"
+  providers: []
+  cleanThinkArtifacts: false
 ```
 ### Таблица параметров конфигурации
@@ -149,8 +87,20 @@ dsh-dsml-artifact-guard:
 | Параметр | Тип | По умолчанию | Описание |
 |:---|:---|:---|:---|
 | `mode` | `string` | `"sanitize"` | Режим работы: `"sanitize"` (удалять теги), `"audit"` (только логировать) или `"disabled"` |
-| `providerId` | `string` | `"opencode-go"` | Идентификатор целевого провайдера, отдающего паразитные теги |
-| `modelId` | `string` | `"deepseek-v4-flash"` | Идентификатор целевой модели с артефактами |
+| `modelPattern` | `string` | `"deepseek"` | Case-insensitive регулярное выражение для фильтрации моделей (например, `deepseek`, `deepseek-v4.*`) |
+| `providers` | `string[]` | `[]` | Список разрешённых ID провайдеров. Если пуст — фильтруются все провайдеры |
+| `cleanThinkArtifacts` | `boolean` | `false` | Очистка сиротливых `</think>`, концевых маркеров reasoning и починка незакрытых блоков |
+| `providerId` | `string` | `undefined` | *(Устарело)* Идентификатор целевого провайдера; сохранено для обратной совместимости |
+| `modelId` | `string` | `undefined` | *(Устарело)* Идентификатор целевой модели; сохранено для обратной совместимости |
+### HTTP-эндпоинты управления
+| Метод | Эндпоинт | Доступ | Назначение |
+|:---|:---|:---|:---|
+| `GET` | `/api/dsh-dsml-artifact-guard/stats` | Web UI / Localhost | Возвращает live-телеметрию и последние перехваченные инциденты |
+| `POST` | `/api/dsh-dsml-artifact-guard/stats` | Loopback & Same-Origin | Сбрасывает счётчики телеметрии и очищает журнал инцидентов |
+| `GET` | `/api/dsh-dsml-artifact-guard/update` | Web UI / Localhost | Получение статуса версии и проверки обновлений |
+| `POST` | `/api/dsh-dsml-artifact-guard/update` | Loopback & Same-Origin | Запуск автоматического обновления пакета через DSH CLI |
 ---
@@ -168,7 +118,3 @@ npm run check
 ## 📄 Лицензия
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
----
-Полная история версий и изменений доступна в файле [CHANGELOG.md](CHANGELOG.md).