@goodandready/dsh-dsml-artifact-guard 0.1.2 → 0.1.4

package/README.md

@@ -150,3 +150,15 @@ npm run check
 ## 📄 License
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+
+## Changed in v0.1.3
+
+#8: wrap `llm/stream` in `ctx.effect` so unload unsubscribes.
+#9: `cordis.patch.yml` uses `config: {}` — schema defaults (`mode: audit`, provider/model ids) apply unless overridden in host config.
+
+## Changed in v0.1.4
+
+#11: schema `mode` default set to `sanitize` for out-of-the-box protection.
+#11: robust open/close tag balancing in `sanitizeDsmlArtifacts` to handle prior closed blocks in prose.
+#11: repo hygiene with tracked `package-lock.json` and design contract.

package/cordis.patch.yml

@@ -1,8 +1,5 @@
-# Host-only DSH bundle.
+# Host-only DSH bundle. Defaults live in Config schema (mode=sanitize).
 - insert:
     - id: dsh-dsml-artifact-guard
       name: '@goodandready/dsh-dsml-artifact-guard'
-      config:
-        mode: sanitize
-        providerId: opencode-go
-        modelId: deepseek-v4-flash
+      config: {}

package/docs/README.ru.md

@@ -150,3 +150,15 @@ npm run check
 ## 📄 Лицензия
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+
+## Changed in v0.1.3
+
+#8: wrap `llm/stream` in `ctx.effect` so unload unsubscribes.
+#9: `cordis.patch.yml` uses `config: {}` — schema defaults (`mode: audit`, provider/model ids) apply unless overridden in host config.
+
+## Изменения в v0.1.4
+
+#11: значение `mode` по умолчанию в схеме переведено на `sanitize` для защиты «из коробки».
+#11: балансировка открывающих и закрывающих тегов в `sanitizeDsmlArtifacts` при наличии закрытых блоков в прозе.
+#11: гигиена репозитория с отслеживаемым `package-lock.json` и дизайн-контрактом.

package/docs/README.zh.md

@@ -150,3 +150,15 @@ npm run check
 ## 📄 开源许可证
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+
+## Changed in v0.1.3
+
+#8: wrap `llm/stream` in `ctx.effect` so unload unsubscribes.
+#9: `cordis.patch.yml` uses `config: {}` — schema defaults (`mode: audit`, provider/model ids) apply unless overridden in host config.
+
+## v0.1.4 变更说明
+
+#11: 将 schema 中 `mode` 默认值设置为 `sanitize`，实现开箱即用的清理保护。
+#11: 在 `sanitizeDsmlArtifacts` 中实现严格的开闭标签深度平衡，精准处理正文中已闭合标签与末尾泄漏标签。
+#11: 纳入 `package-lock.json` 跟踪并完善设计契约。

package/docs/design/DESIGN.md

@@ -0,0 +1,36 @@
+# Design Contract: dsh-dsml-artifact-guard
+
+## 1. Product Purpose & User Scenarios
+- **Purpose**: Host-only streaming guard for DeepSeek Harness that intercepts assistant stream chunks and strips leaked DSML closing tags (`</｜DSML｜parameter>`, `</｜DSML｜invoke>`, `</｜DSML｜tool_calls>`) emitted by upstream providers before text reaches the user interface.
+- **Primary Scenarios**:
+  - Assistant responds through an upstream gateway exhibiting DSML leakage (e.g. `opencode-go` + `deepseek-v4-flash`). Leaked protocol closing tags at the end of the response are stripped automatically.
+  - User and assistant discuss DSML syntax or generate markdown/code examples with DSML tags. Legitimate open tags and their matching closing tags are preserved intact (fail-open).
+  - Out-of-scope providers/models pass through with zero buffering or regex evaluation.
+
+## 2. User Surfaces
+- **Web UI**: UI отсутствует на текущем этапе (host-only middleware plugin).
+- **DSH Configuration**:
+  - `mode`: `"sanitize"` (default, strips tags), `"audit"` (logs to `ctx.logger.info`), `"disabled"` (bypasses).
+  - `providerId`: target provider (default `"opencode-go"`).
+  - `modelId`: target model (default `"deepseek-v4-flash"`).
+- **Documentation**:
+  - Full trilingual documentation: `README.md` (EN), `docs/README.ru.md` (RU), `docs/README.zh.md` (ZH).
+
+## 3. Streaming & Buffering Contract
+- **Synchronous Hook Contract**: The `llm/stream` listener returns an `AsyncIterable` synchronously. Returning a `Promise` breaks the Cordis event dispatcher.
+- **Sliding Buffer (KEEP = 96)**: Preserves the terminal window across chunk splits.
+- **Tag Balancing**: Tracks opening and closing DSML tags across the stream so that only orphaned closing tags at the terminal tail are sanitized, leaving balanced code blocks untouched.
+
+## 4. Do / Don't
+- **Do**:
+  - Preserve fail-open guarantees for all user prose.
+  - Dispose hook registration with `ctx.effect`.
+  - Pass non-target provider/model streams directly through.
+- **Don't**:
+  - Do not make the stream hook async.
+  - Do not drop legitimate DSML discussion in chat.
+  - Do not add heavy client-side UI for simple host middleware.
+
+## 5. Decisions Log
+- **2026-09-06**: Added `ctx.effect` lifecycle wrapper and switched patch to schema-driven defaults (`#8, #9`).
+- **2026-09-12**: Changed schema default mode to `sanitize` for out-of-the-box protection, implemented robust open/close tag balancing across streaming chunks, and tracked `package-lock.json` (`#11`).

package/lib/index.js

@@ -1 +1,105 @@
-import Schema from '@deepseek-ai/schemastery'; const TAIL=/(?:<\/｜DSML｜parameter>\s*)?(?:<\/｜DSML｜invoke>\s*)?<\/｜DSML｜tool_calls>\s*$/u,OPEN=/<｜DSML｜(?:tool_calls|invoke|parameter)>/u,KEEP=96; export const name='@goodandready/dsh-dsml-artifact-guard',inject=['llm'],Config=Schema.object({mode:Schema.string().default('audit'),providerId:Schema.string().default('opencode-go'),modelId:Schema.string().default('deepseek-v4-flash')}); export function matchesScope(o,c){return (o?.providerId??o?.provider?.id??o?.provider)==c.providerId&&(o?.modelId??o?.model?.id??o?.model?.name??o?.model)==c.modelId} export async function* sanitizeDsmlArtifacts(s,{mode,onArtifact}={}){let p='',i,open=false;const flush=async function*(end){if(!p)return;let text=p;if(end&&!open&&TAIL.test(text)){onArtifact?.({mode,removed:1});if(mode==='sanitize')text=text.replace(TAIL,'')}if(text)yield{type:'text-delta',index:i,text};p='';i=undefined};for await(const c of s){if(c?.type==='text-delta'&&typeof c.text==='string'){if(p&&i!==c.index)yield*flush(false);i=c.index;p+=c.text;open||=OPEN.test(c.text);if(p.length>KEEP){const n=p.length-KEEP;yield{type:'text-delta',index:i,text:p.slice(0,n)};p=p.slice(n)}continue}if(c?.type==='finish'){yield*flush(true);yield c;continue}yield*flush(false);yield c}yield*flush(true)} export function apply(ctx,c={}){const e=Config(c)??{};ctx.on('llm/stream',(o,next)=>{const s=next(o);return e.mode==='disabled'||!matchesScope(o,e)?s:sanitizeDsmlArtifacts(s,{mode:e.mode,onArtifact:x=>ctx.logger?.info?.('DSML closing-tag artifact detected',x)})})}
+import Schema from '@deepseek-ai/schemastery';
+
+const TAIL = /(?:<\/｜DSML｜parameter>\s*)?(?:<\/｜DSML｜invoke>\s*)?<\/｜DSML｜tool_calls>\s*$/u;
+const OPEN_TAG = /<｜DSML｜(?:tool_calls|invoke|parameter)[^>]*>/gu;
+const CLOSE_TAG = /<\/｜DSML｜(?:tool_calls|invoke|parameter)>/gu;
+const KEEP = 96;
+const SCAN_BUFFER_SAFE = 64;
+
+export const name = '@goodandready/dsh-dsml-artifact-guard';
+export const inject = ['llm'];
+
+export const Config = Schema.object({
+  mode: Schema.string().default('sanitize'),
+  providerId: Schema.string().default('opencode-go'),
+  modelId: Schema.string().default('deepseek-v4-flash'),
+});
+
+export function matchesScope(o, c) {
+  return (o?.providerId ?? o?.provider?.id ?? o?.provider) == c.providerId
+    && (o?.modelId ?? o?.model?.id ?? o?.model?.name ?? o?.model) == c.modelId;
+}
+
+export async function* sanitizeDsmlArtifacts(s, { mode = 'sanitize', onArtifact } = {}) {
+  let p = '';
+  let i;
+  let scanBuffer = '';
+  let totalOpen = 0;
+  let totalClose = 0;
+
+  const countTags = (str) => {
+    if (!str) return;
+    const opens = str.match(OPEN_TAG);
+    if (opens) totalOpen += opens.length;
+    const closes = str.match(CLOSE_TAG);
+    if (closes) totalClose += closes.length;
+  };
+
+  const flush = async function* (end) {
+    if (!p) return;
+    let text = p;
+    if (end) {
+      if (scanBuffer) {
+        countTags(scanBuffer);
+        scanBuffer = '';
+      }
+      if (TAIL.test(text)) {
+        const tailMatch = text.match(TAIL);
+        const tailCloseCount = tailMatch ? (tailMatch[0].match(CLOSE_TAG) || []).length : 0;
+        const closedBeforeTail = totalClose - tailCloseCount;
+        const unclosedBeforeTail = totalOpen - closedBeforeTail;
+        if (unclosedBeforeTail <= 0) {
+          onArtifact?.({ mode, removed: 1 });
+          if (mode === 'sanitize') text = text.replace(TAIL, '');
+        }
+      }
+    }
+    if (text) yield { type: 'text-delta', index: i, text };
+    p = '';
+    i = undefined;
+  };
+
+  for await (const c of s) {
+    if (c?.type === 'text-delta' && typeof c.text === 'string') {
+      if (p && i !== c.index) yield* flush(false);
+      i = c.index;
+      p += c.text;
+
+      scanBuffer += c.text;
+      if (scanBuffer.length > SCAN_BUFFER_SAFE) {
+        const safe = scanBuffer.slice(0, scanBuffer.length - SCAN_BUFFER_SAFE);
+        scanBuffer = scanBuffer.slice(scanBuffer.length - SCAN_BUFFER_SAFE);
+        countTags(safe);
+      }
+
+      if (p.length > KEEP) {
+        const n = p.length - KEEP;
+        yield { type: 'text-delta', index: i, text: p.slice(0, n) };
+        p = p.slice(n);
+      }
+      continue;
+    }
+    if (c?.type === 'finish') {
+      yield* flush(true);
+      yield c;
+      continue;
+    }
+    yield* flush(false);
+    yield c;
+  }
+  yield* flush(true);
+}
+
+export function apply(ctx, c = {}) {
+  const e = Config(c) ?? {};
+  // #8: dispose with ctx.effect so unload unsubscribes llm/stream
+  ctx.effect(() => ctx.on('llm/stream', (o, next) => {
+    const s = next(o);
+    return e.mode === 'disabled' || !matchesScope(o, e)
+      ? s
+      : sanitizeDsmlArtifacts(s, {
+        mode: e.mode,
+        onArtifact: (x) => ctx.logger?.info?.('DSML closing-tag artifact detected', x),
+      });
+  }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-dsml-artifact-guard",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Sanitizes leaked DeepSeek DSML closing tags from model text streams",
   "type": "module",
   "main": "lib/index.js",