dsh-dsml-rescue 0.1.0 → 0.2.1

package/README.md

@@ -5,15 +5,16 @@
 <h1 align="center">dsh-dsml-rescue</h1>
 
 <div align="center">
-  <p><strong>Continue the turn a model stalled by writing tool-call markup into its reasoning</strong></p>
-  <p><em>把"思考里写了工具调用标记、于是什么都没发生"的那一回合续上</em></p>
+  <p><strong>A stalled turn gets another one</strong></p>
+  <p><em>空转的轮次，替你续上</em></p>
 
   <p>
-    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat&logo=deepseek&logoColor=white" alt="powered by dsh"></a>
+    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered by dsh"></a>
   </p>
 
   <p>
     <a href="https://github.com/dsh-plugin-lab/dsh-dsml-rescue/actions/workflows/ci.yml"><img src="https://github.com/dsh-plugin-lab/dsh-dsml-rescue/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://www.npmjs.com/package/dsh-dsml-rescue"><img src="https://img.shields.io/npm/v/dsh-dsml-rescue.svg?style=flat" alt="npm"></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat" alt="MIT License"></a>
   </p>
 
@@ -28,51 +29,60 @@
 
 ---
 
-Some provider routes deliver a model's tool call as **reasoning text carrying the call's own markup**
-instead of a structured call. The call never happens, the turn closes having produced nothing, and
-the conversation waits for someone to type "continue". This plugin types it for you.
+## Does this look familiar?
 
-## What it does
+You asked for something. The model reasoned for a while. Then the turn simply ended — no answer, no
+tool call, nothing. The reasoning output ended with lines like these:
+
+```
+</｜｜DSML｜｜ parameter>
+</｜｜DSML｜｜ invoke>
+</｜｜DSML｜｜ calls>
+```
+
+DSML (DeepSeek Markup Language) is how DeepSeek formats a tool call. Some provider routes hand that
+markup back as **ordinary reasoning text** instead of an actual call, so the call never happens, the
+turn closes with no output, and everything waits for someone to type "continue".
 
-- Continues a turn that closed with leaked protocol markup and **nothing else**.
-- Sends one neutral sentence: take the next step, or close out with a summary.
-- Waits for you — if you are already typing, it stays out of the way.
-- Stops after a few attempts instead of spending requests forever.
-- Covers child agents too, so a delegated run is not reported finished while it is stuck.
+This plugin types it.
 
-## Getting started
+## What it does
 
-**Prerequisites**: DSH on its current RC line; Node `>= 20`. The only source for the compatible range
-is `engines.dsh` in [package.json](package.json).
+- Continues a stalled turn: DSML markup at the end of the reasoning, and nothing else produced.
+- Sends one short, neutral line — carry on, or wrap up if the work is done.
+- Backs off while you are typing.
+- Gives up after a few attempts instead of burning requests.
+- Covers subagents too, so a delegated task is not falsely reported as completed while it is stuck.
+
+## Install
 
 ```bash
 dsh plugin --profile web add dsh-dsml-rescue
 ```
 
-Restart `dsh --profile web`. Nothing to configure: the defaults are the intended behaviour.
+Then restart `dsh --profile web`. There is nothing to configure — the defaults are the intended
+behaviour.
 
-From source: `git clone`, then `pnpm install && pnpm run build`, then
+Working from source: clone, `pnpm install && pnpm run build`, then
 `dsh plugin --profile web add "$PWD"`.
 
 ## What it will not do
 
-- **It does not fix the cause.** The leak happens below the model, so no prompt prevents it; this
-  plugin only shortens the pause that follows.
-- **It does not rescue turns that ended empty for other reasons.** No markup, no rescue — a
-  cancellation, a failure, or a step cut off at its output ceiling all stay untouched.
-- **It does not touch your conversation.** Nothing is rewritten or re-sent; it adds one message and
-  lets the host run.
-
-## Configuration
-
-Three keys, all optional: `enabled`, `maxConsecutive`, `applyToSubagents`. Defaults, and what moving
-each one changes → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#configuration).
-
-## Under the hood
-
-How a stall is recognized, why the continuation is queued where it is, and what must not change →
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
-What each check establishes, and a repeatable end-to-end run → [docs/VERIFICATION.md](docs/VERIFICATION.md).
+- **It does not fix the cause.** The markup leaks below the model, out of reach of any prompt. What
+  it buys you is the wait, shortened.
+- **It does not rescue other empty turns.** No DSML markup, no rescue: a cancellation, a failed
+  request, or a reply cut off at the output limit is left alone on purpose.
+- **It does not touch your conversation.** Nothing is rewritten or replayed; it adds one message and
+  lets the host carry on.
+
+## Going deeper
+
+- Which three settings exist and what each one changes →
+  [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#configuration)
+- How a stalled turn is recognised, and the rules that must not be broken →
+  [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- What the tests prove, and how to reproduce the whole thing locally →
+  [docs/VERIFICATION.md](docs/VERIFICATION.md)
 
 ## License
 

package/README_zh.md

@@ -5,15 +5,16 @@
 <h1 align="center">dsh-dsml-rescue</h1>
 
 <div align="center">
-  <p><strong>把"思考里写了工具调用标记、于是什么都没发生"的那一回合续上</strong></p>
-  <p><em>Continue the turn a model stalled by writing tool-call markup into its reasoning</em></p>
+  <p><strong>空转的轮次，替你续上</strong></p>
+  <p><em>A stalled turn gets another one</em></p>
 
   <p>
-    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat&logo=deepseek&logoColor=white" alt="powered by dsh"></a>
+    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered by dsh"></a>
   </p>
 
   <p>
     <a href="https://github.com/dsh-plugin-lab/dsh-dsml-rescue/actions/workflows/ci.yml"><img src="https://github.com/dsh-plugin-lab/dsh-dsml-rescue/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://www.npmjs.com/package/dsh-dsml-rescue"><img src="https://img.shields.io/npm/v/dsh-dsml-rescue.svg?style=flat" alt="npm"></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat" alt="MIT License"></a>
   </p>
 
@@ -28,44 +29,49 @@
 
 ---
 
-有些 provider 路由会把模型的工具调用当成**普通思考文本**吐回来，里面夹着调用本身的协议标记。于是调用没有发生，回合以"什么都没产出"结束，会话就停在那儿等人敲一句"继续"。这个插件替你敲。
+## 这场景眼熟吗
 
-## 它做什么
+你提了要求，模型推理了一会儿，然后这一轮就这么结束了——没有回复、没有工具调用，什么都没有。推理过程的最后几行是这样：
 
-- 只续一种回合：以泄漏的协议标记结束、且**没有产出任何别的**内容的回合。
-- 只发一句中性的话：要么执行下一步，要么收尾给结论。
-- 让着你：你已经在打字时它不插话。
-- 续几次就停，不会无限花请求。
-- 子 agent 也管，被派出去的活儿不会"卡着却被告知已结束"。
+```
+</｜｜DSML｜｜ parameter>
+</｜｜DSML｜｜ invoke>
+</｜｜DSML｜｜ calls>
+```
 
-## 开始用
+DSML（DeepSeek Markup Language）是 DeepSeek 表示工具调用的协议标记。某些 provider 路由会把这段标记当成**普通推理文本**返回，而不是真的发出调用；于是调用没有发生，这一轮空着结束，所有人都在等一句「继续」。
 
-**前置**：DSH 当前 RC 线；Node `>= 20`。兼容区间的唯一来源是 [package.json](package.json) 里的 `engines.dsh`。
+这个插件替你把这句「继续」发出去。
+
+## 它做什么
+
+- 只救空转的轮次：推理过程末尾带着 DSML 标记，而且没有产出任何别的内容。
+- 发一句很短、很中性的话：接着做，或者已经做完就收尾。
+- 你正在打字时它让开。
+- 连着几次没救回来就收手，不会一直烧请求。
+- 子代理也管：被派出去的任务不会在卡住时被误报为已完成。
+
+## 安装
 
 ```bash
 dsh plugin --profile web add dsh-dsml-rescue
 ```
 
-重启 `dsh --profile web` 即可。不需要配置，默认值就是预期行为。
-
-从源码装：`git clone` 后 `pnpm install && pnpm run build`，再 `dsh plugin --profile web add "$PWD"`。
-
-## 它不做什么
+然后重启 `dsh --profile web`。不需要配置，默认值就是预期行为。
 
-- **不修根因。** 泄漏发生在模型之下，任何提示词都规避不了；本插件只把随之而来的停顿缩短。
-- **不救其他空转。** 没有标记就不救——用户主动取消、请求失败、以及输出被长度截断后停在原地的回合，都不碰。
-- **不动你的对话。** 不改写、不重发；只多加一条消息，然后交给宿主继续跑。
+从源码装：先 clone，`pnpm install && pnpm run build`，再 `dsh plugin --profile web add "$PWD"`。
 
-## 配置
+## 它不会做什么
 
-三个键，都可选：`enabled`、`maxConsecutive`、`applyToSubagents`。默认值以及改动各自的影响 →
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#configuration)。
+- **不修根因。** 标记泄漏发生在模型之下，提示词够不着。它换来的只有那段等待被缩短。
+- **不救别的空转轮次。** 没有 DSML 标记就不出手：你主动取消、请求失败、回复被输出上限截断，这些都刻意不碰。
+- **不动你的对话。** 不改写、不重放历史，只多加一条消息，剩下的交给宿主。
 
-## 内部实现
+## 想了解更多
 
-怎么认定一次空转、续跑消息为什么排在那个位置、哪些约束不能破 →
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
-每项检查能证明什么、以及可复现的端到端验法 → [docs/VERIFICATION.md](docs/VERIFICATION.md)。
+- 有哪三个配置项、各自会改变什么 → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#configuration)
+- 怎么认定一个空转轮次、哪些规则不能破 → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- 测试能证明什么、怎么在本机完整复现 → [docs/VERIFICATION.md](docs/VERIFICATION.md)
 
 ## 许可
 

package/lib/index.d.ts

@@ -4,6 +4,10 @@ import { Context } from "@deepseek-ai/cordis";
 declare const name = "dsh-dsml-rescue";
 /** The agent registry, needed to map a session back to its live agent. */
 declare const inject: string[];
+/** Rescues allowed in a row before an agent is left alone. */
+declare const DEFAULT_MAX_CONSECUTIVE = 3;
+/** Whether child agents are rescued by default. */
+declare const DEFAULT_APPLY_TO_SUBAGENTS = true;
 /** Validated configuration; the defaults are the documented behaviour. */
 interface Config {
   /** Whether the plugin acts at all. Turn it off without uninstalling. */
@@ -23,7 +27,7 @@ declare const Config: z<Config>;
 /**
  * Mount the plugin.
  * @param ctx - host context.
- * @param config - validated configuration.
+ * @param config - validated configuration; the schema fills in every default.
  */
 declare function apply(ctx: Context, config: Config): void;
-export { Config, apply, inject, name };
+export { Config, DEFAULT_APPLY_TO_SUBAGENTS, DEFAULT_MAX_CONSECUTIVE, apply, inject, name };

package/lib/index.js

@@ -60,7 +60,7 @@ function hasLeakedProtocolTail(reasoning) {
 /**
 * The one judgment this plugin makes: does a finished turn deserve a rescue?
 *
-* A turn deserves one when it ended normally yet produced nothing the loop or
+* It deserves one when the turn ended normally yet produced nothing the loop or
 * the user can act on, and its reasoning ends in leaked protocol markup. Both
 * halves are required — a turn that produced nothing for another reason stays
 * untouched, because rescuing it would paper over an unrelated failure.
@@ -70,21 +70,20 @@ function hasLeakedProtocolTail(reasoning) {
 *
 * @module dsh-dsml-rescue/detect
 */
-/** Whether a text block carries anything other than whitespace. */
-function carriesText(block) {
-	return block.type === "text" && block.text !== void 0 && /\S/.test(block.text);
-}
 /**
-* Whether the turn produced anything a caller could act on.
+* Whether one block produced something a caller could act on.
 *
-* An unknown block type counts as actionable on purpose: a provider that adds
-* a content kind this plugin has never seen is far more likely to have produced
+* Reasoning never counts — that is where the leak lives, not where the work
+* lands. An unknown block type does count, on purpose: a provider that adds a
+* content kind this plugin has never seen is far likelier to have produced
 * output than to have produced nothing, and a false rescue costs a request.
-* @param blocks - the turn's closing content blocks.
-* @returns whether any block is visible text, a tool call, or an unknown kind.
+* @param block - one content block of the closing message.
+* @returns whether the block is visible text, a tool call, or an unknown kind.
 */
-function hasActionableContent(blocks) {
-	return blocks.some((block) => block.type === "reasoning" ? false : block.type === "text" ? carriesText(block) : true);
+function isActionable(block) {
+	if (block.type === "reasoning") return false;
+	if (block.type !== "text") return true;
+	return block.text !== void 0 && /\S/.test(block.text);
 }
 /**
 * Concatenate every reasoning block of a message.
@@ -92,7 +91,7 @@ function hasActionableContent(blocks) {
 * @returns the joined reasoning text, or the empty string when there is none.
 */
 function joinReasoning(blocks) {
-	return blocks.flatMap((block) => block.type === "reasoning" && block.text !== void 0 ? [block.text] : []).join("\n");
+	return blocks.filter((block) => block.type === "reasoning" && block.text !== void 0).map((block) => block.text ?? "").join("\n");
 }
 /**
 * Decide whether one finished turn is a leaking stall.
@@ -102,7 +101,7 @@ function joinReasoning(blocks) {
 */
 function isRescueCandidate(observation) {
 	if (!observation.completed) return false;
-	if (hasActionableContent(observation.blocks)) return false;
+	if (observation.blocks.some(isActionable)) return false;
 	return hasLeakedProtocolTail(joinReasoning(observation.blocks));
 }
 // src/policy.ts
@@ -147,8 +146,33 @@ function evaluate(input) {
 const INITIAL_STATE = {
 	consecutive: 0,
 	turn: void 0,
-	blocks: []
+	blocks: [],
+	outputTokens: void 0
 };
+/** Nothing to do, with the state unchanged. */
+function nothing(state) {
+	return {
+		state,
+		decision: "ignore",
+		round: 0
+	};
+}
+/**
+* Whether the step being closed spent its whole output budget.
+*
+* Reads as exhausted only when both numbers are known: an unknown ceiling or a
+* missing count reports "not exhausted" on purpose, because a wrong `true`
+* would silence the rescue this plugin exists for, while a wrong `false` only
+* costs the streak one attempt.
+* @param state - state carrying the closing message's output tokens.
+* @param ceiling - the ceiling the request was sent under, when known.
+* @returns whether the model was cut off rather than finished.
+*/
+function spentBudget(state, ceiling) {
+	if (state.outputTokens === void 0) return false;
+	if (ceiling === void 0 || ceiling <= 0) return false;
+	return state.outputTokens >= ceiling;
+}
 /**
 * Advance one agent's machine by one event.
 *
@@ -162,41 +186,25 @@ const INITIAL_STATE = {
 */
 function reduce(state, event, limits) {
 	switch (event.kind) {
-		case "assistant-message": return {
-			state: {
-				...state,
-				turn: event.turn,
-				blocks: event.blocks
-			},
-			decision: "ignore",
-			round: 0
-		};
-		case "human-message": return {
-			state: {
-				...state,
-				consecutive: 0
-			},
-			decision: "ignore",
-			round: 0
-		};
-		case "turn-end": return event.completed ? {
-			state,
-			decision: "ignore",
-			round: 0
-		} : {
-			state: {
-				...state,
-				consecutive: 0
-			},
-			decision: "ignore",
-			round: 0
-		};
+		case "assistant-message": return nothing({
+			...state,
+			turn: event.turn,
+			blocks: event.blocks,
+			outputTokens: event.outputTokens
+		});
+		case "human-message": return nothing({
+			...state,
+			consecutive: 0
+		});
+		case "turn-end": return event.completed ? nothing(state) : nothing({
+			...state,
+			consecutive: 0
+		});
 		case "turn-stopping": {
-			const blocks = state.turn === event.turn ? state.blocks : [];
 			const outcome = evaluate({
-				candidate: !event.outputExhausted && isRescueCandidate({
+				candidate: isRescueCandidate({
 					completed: true,
-					blocks
+					blocks: state.turn === event.turn && !spentBudget(state, event.outputCeiling) ? state.blocks : []
 				}),
 				consecutive: state.consecutive,
 				maxConsecutive: limits.maxConsecutive,
@@ -253,38 +261,12 @@ function humanPending(agent) {
 	return agent.inbox.nextTurn.some((message) => message.source.kind === "user") || agent.inbox.nextStep.some((message) => message.source.kind === "user");
 }
 /**
-* Whether the step being closed spent its whole output budget.
-*
-* The seam carries no stop reason, so this compares the closing message's
-* output-token count with the ceiling the request was sent under. Both numbers
-* are the caller's own accounting — the count is what the provider reported and
-* the ceiling is what this session last requested — so equality means the model
-* was cut off, not that it chose to stop.
-*
-* The comparison is deliberately one-sided: an unknown ceiling or a missing
-* count reports "not exhausted", because a wrong `true` would silence the
-* rescue this plugin exists for, while a wrong `false` only costs the rescue
-* one attempt of the streak.
-* @param agent - the agent whose turn is closing.
-* @param turn - the turn being closed.
-* @param usage - the closing message's token accounting, when the host logged it.
-* @returns whether the output budget is spent.
-*/
-function outputExhausted(agent, usage) {
-	if (usage === void 0) return false;
-	const ceiling = agent.session.requestHeader()?.config.maxTokens;
-	if (ceiling === void 0 || ceiling <= 0) return false;
-	return usage.outputTokens >= ceiling;
-}
-/**
 * Install the turn watcher and its continuation side effect.
 * @param ctx - plugin context; listeners are disposed with it.
 * @param config - validated limits.
 */
 function install(ctx, config) {
 	const states = /* @__PURE__ */ new Map();
-	/** Output accounting of the last assistant message, per agent. */
-	const usageByAgent = /* @__PURE__ */ new Map();
 	/** Apply one reducer event and store the result. */
 	function advance(agent, event) {
 		const step = reduce(states.get(agent) ?? INITIAL_STATE, event, { maxConsecutive: config.maxConsecutive });
@@ -303,9 +285,9 @@ function install(ctx, config) {
 				advance(agent, {
 					kind: "assistant-message",
 					turn: event.data.turn,
-					blocks: event.data.message.content
+					blocks: event.data.message.content,
+					outputTokens: event.data.usage?.outputTokens
 				});
-				usageByAgent.set(agent, event.data.usage);
 				return;
 			case "user/message":
 				if (event.data.source.kind === "user") advance(agent, { kind: "human-message" });
@@ -326,7 +308,7 @@ function install(ctx, config) {
 			kind: "turn-stopping",
 			turn,
 			humanPending: humanPending(agent),
-			outputExhausted: outputExhausted(agent, usageByAgent.get(agent))
+			outputCeiling: agent.session.requestHeader()?.config.maxTokens
 		});
 		if (step.decision === "give-up") {
 			ctx.logger.warn(`dsml-rescue: agent "${agent.id}" stalled ${config.maxConsecutive} times in a row; stopped continuing it`);
@@ -345,7 +327,6 @@ function install(ctx, config) {
 	});
 	ctx.on("agent/disposed", ({ agent }) => {
 		states.delete(agent);
-		usageByAgent.delete(agent);
 	});
 }
 // src/index.ts
@@ -353,6 +334,10 @@ function install(ctx, config) {
 const name = "dsh-dsml-rescue";
 /** The agent registry, needed to map a session back to its live agent. */
 const inject = ["agents"];
+/** Rescues allowed in a row before an agent is left alone. */
+const DEFAULT_MAX_CONSECUTIVE = 3;
+/** Whether child agents are rescued by default. */
+const DEFAULT_APPLY_TO_SUBAGENTS = true;
 const Config = z.object({
 	enabled: z.boolean().default(true),
 	maxConsecutive: z.natural().min(1).default(3),
@@ -361,7 +346,7 @@ const Config = z.object({
 /**
 * Mount the plugin.
 * @param ctx - host context.
-* @param config - validated configuration.
+* @param config - validated configuration; the schema fills in every default.
 */
 function apply(ctx, config) {
 	if (config.enabled === false) return;
@@ -370,4 +355,4 @@ function apply(ctx, config) {
 		applyToSubagents: config.applyToSubagents ?? true
 	});
 }
-export { Config, apply, inject, name };
+export { Config, DEFAULT_APPLY_TO_SUBAGENTS, DEFAULT_MAX_CONSECUTIVE, apply, inject, name };

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "DSML Rescue",
-    "description": "Continues the turn a model stalled by writing tool-call markup into its reasoning instead of calling a tool."
+    "description": "Auto-continues turns stalled by DSML tool-call markup leaking into reasoning."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "DSML Rescue",
-    "description": "模型把工具调用协议标记写进思考、导致回合空转时，自动补发一条中性指令把回合续上。"
+    "description": "当 DSML 工具调用标记泄漏进推理过程导致回合停滞时，自动续跑。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-dsml-rescue",
-  "version": "0.1.0",
-  "description": "Continue the turn a model stalled by writing tool-call markup into its reasoning",
+  "version": "0.2.1",
+  "description": "Auto-continues turns stalled by DSML tool-call markup leaking into reasoning.",
   "keywords": [
     "dsh",
     "deepseek-harness",
@@ -50,17 +50,6 @@
       "patch": "./cordis.patch.yml"
     }
   },
-  "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint .",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "check:release": "node scripts/check-release.mjs",
-    "check": "pnpm run typecheck && pnpm run build && pnpm run test && pnpm run check:release"
-  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
     "@deepseek-ai/dsh-llm": "^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
@@ -83,5 +72,16 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.70.1",
     "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check:release": "node scripts/check-release.mjs",
+    "check": "pnpm run typecheck && pnpm run build && pnpm run test && pnpm run check:release"
   }
-}
+}