📦 @goodandready/dsh-dsml-artifact-guard

---

⚡ Problem & Purpose

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:

Response completed successfully.
</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>

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 high-performance runtime guard for DeepSeek Harness that cleans these protocol artifacts in real time before they reach the user interface:

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.

---

📦 Installation

Install into your DeepSeek Harness web profile:

dsh plugin --profile web add @goodandready/dsh-dsml-artifact-guard

Restart your DeepSeek Harness instance.

---

⚙️ Configuration (settings.yaml)

Configure matching rules in settings.yaml or through the Web UI Settings Card:

# settings.yaml
dsh-dsml-artifact-guard:
  mode: sanitize
  modelPattern: "deepseek"
  providers: []
  cleanThinkArtifacts: false

Configuration Parameters

Parameter	Type	Default	Description
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

HTTP Management Endpoints

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

---

🧪 Testing

Run the automated test suite:

npm test
npm run check

---

📄 License

MIT © GooDAnDReaDY