@deepseek-ai/dsh-repeat-tool-reminder 0.0.1-rc.3

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/guard/repeat-tool-reminder/README.md
+README.md: cfece8150dce8e2fe45b4e942bf7188f46836551
+README.zh.md: 439480d876ad07d8bc095b2534a5a2ce732bfc9b

package/README.md

@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-repeat-tool-reminder
+
+English | [中文](README.zh.md)
+
+An advisory loop-breaker, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The decision (retry differently, gather more evidence, or finish) stays entirely with the model: a legitimately repeated call is delayed by nothing and blocked by nothing. Decision record: [the repeat-tool-reminder Agent Note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md).
+
+## Config
+
+```yaml
+- id: repeat-tool-reminder
+  name: '@deepseek-ai/dsh-repeat-tool-reminder'
+  config:
+    thresholds: [3, 5, 8]        # default; consecutive counts that trigger a reminder
+    include: []                  # tool-name patterns to track; empty ⇒ all tools
+    exclude: [todo_write]        # tool-name patterns transparent to the chain
+    argumentsPreviewChars: 500   # default; cap on arguments quoted in the detailed reminder
+```
+
+`thresholds` fails loud at plugin load: an empty list, a non-integer, a value below 2, or a duplicate throws, never a silent fall-back to defaults; `argumentsPreviewChars` equally rejects anything but an integer >= 1. The list is normalized to ascending order; the FIRST threshold delivers a short generic nudge, every later threshold delivers the detailed form naming the tool, the run length, and the canonical arguments — head-truncated at `argumentsPreviewChars` with an omitted-count marker, so a looping `write`/`edit` payload cannot ride into the next request unbounded (the chain key always compares the FULL canonical string; the cap bounds the reminder, never the detection).
+
+`include`/`exclude` entries support `*` wildcards and are predicates over whatever tools exist at call time, not references to registry entries — a pattern matching no currently registered tool is NOT an error (`exclude: [mcp_*]` stays valid in a deployment that loads no MCP tools), unlike `toolOrder`'s referent check.
+
+## Chain semantics
+
+The chain key is `(tool name, canonical arguments)` — canonicalization is a deep key-sort plus `JSON.stringify`, so argument objects differing only in property order count as identical. A call identical to the previous tracked call increments the agent's consecutive counter; a different tracked call resets it to 1.
+
+- **Untracked calls are transparent to the chain.** A call excluded by `include`/`exclude` neither increments nor resets the counter, so `grep X → todo_write → grep X` still counts as two consecutive `grep X` when `todo_write` is excluded. This is what makes exclusion useful: bookkeeping tools interleaved into a loop must not launder it.
+- **Denied calls count.** Detection sits on `tools/post-execute`, which also runs for calls a `tools/pre-execute` listener denied — a model hammering a denied call is exactly the loop worth breaking.
+- **Calls without an agent are ignored.** A direct `ctx.tools.execute()` caller has no model to remind and no live agent object to key on.
+- **Per-agent keying.** The tool registry is context-level and subagents interleave through the same waterfall, so a `WeakMap<Agent, Chain>` keys each chain by the live agent object; one agent's repetition never trips another's reminder. A user prompt (`agent/pre-step`) resets the submitting agent's chain, and object lifetime bounds the weak entry without a disposal listener.
+- **In-memory only.** A session resumed from persistence starts with a fresh chain — the guard is a heuristic nudge, not a logged invariant, later reminders are the accepted cost.
+
+## Reminder delivery
+
+Reminders ride the post-execute decision's `additionalContexts` (source `{kind: 'plugin', plugin: 'repeat-tool-reminder'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as an injected `user/message` after the step's tool results, which the session renders as a plain synthetic user message — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and prepends its reminder to the downstream decision's context array (both variants — a blocked call still gets the nudge); every entry retains its own source and metadata.
+
+## Model Experience
+
+### First-threshold context message
+
+#### What the model sees
+
+At the first configured consecutive-repeat threshold, that agent receives the reminder below. No tool schema or normal-call text is added.
+
+##### First-threshold reminder
+
+```markdown
+You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call.
+```
+
+#### Token effect
+
+Zero tokens before the threshold. The reminder is retained history for that agent.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Later-threshold context message
+
+#### What the model sees
+
+A later threshold receives the detailed reminder template below. A capped argument preview ends exactly `… (+<omitted> more chars)`.
+
+##### Later-threshold reminder
+
+```markdown
+Repeated tool call detected:
+- tool: <toolName>
+- consecutive_calls: <count>
+- arguments: <canonicalArguments>
+The repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered.
+```
+
+#### Token effect
+
+Each reminder is retained history; `argumentsPreviewChars` bounds its data-dependent argument text, while agents keep independent counters.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Exact-match detection only** — canonicalization is a deep key-sort, so near-identical variants (a tweaked path, extra whitespace inside a value) evade the chain; fuzzy matching is rejected pending evidence of need.
+- **Compaction does not reset chains** — a chain spanning a compaction checkpoint keeps counting.
+- **Advisory only** — escalating to `block` at a high threshold is not implemented, though `PostToolDecision` already supports blocking.
+- **No subagent chain-sharing** — chains stay isolated per agent; a parent and its subagent repeating the same call never combine.
+- **Legitimate idempotent polling still draws nudges** past the thresholds — the pressure valves are `thresholds`/`exclude` config.
+- **Past the highest threshold a chain goes silent** — reminders fire only at exact configured counts, never beyond them.

package/README.zh.md

@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-repeat-tool-reminder
+
+[English](README.md) | 中文
+
+这是一个仅提供建议的循环中断器，而非面向模型的工具：它不会出现在工具列表中，不会否决或改写调用，只增加一种行为。它监视每个 agent（智能体）的工具调用流，统计以完全相同的规范化参数连续调用同一工具的次数；达到所配置的连续次数时，它会注入逐级增强的提示，要求模型停止重复、重新阅读上一次结果，并改用其他方案或结束任务。究竟是换一种方式重试、收集更多证据还是完成任务，仍完全由模型决定：合理的重复调用既不会延迟，也不会受阻。决策记录见 [repeat-tool-reminder Agent Note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md)。
+
+## 配置
+
+```yaml
+- id: repeat-tool-reminder
+  name: '@deepseek-ai/dsh-repeat-tool-reminder'
+  config:
+    thresholds: [3, 5, 8]        # default; consecutive counts that trigger a reminder
+    include: []                  # tool-name patterns to track; empty ⇒ all tools
+    exclude: [todo_write]        # tool-name patterns transparent to the chain
+    argumentsPreviewChars: 500   # default; cap on arguments quoted in the detailed reminder
+```
+
+插件加载时，`thresholds` 会对错误配置快速失败：空列表、非整数、小于 2 的值或重复值都会抛出错误，绝不静默回退到默认值；`argumentsPreviewChars` 同样只接受大于等于 1 的整数。系统会将列表按升序规范化；第一个阈值只发送简短的通用提醒，后续每个阈值都会发送详细版本，列出工具、连续次数和规范参数。参数内容截取前 `argumentsPreviewChars` 个字符，并附带省略字符数标记，避免循环中的 `write`／`edit` 载荷无限制进入下一次请求（链键始终比较完整的规范字符串；此上限只约束提醒，不影响检测）。
+
+`include`／`exclude` 条目支持 `*` 通配符，并针对调用时实际存在的工具执行谓词判断，而不是引用注册表条目。因此，与当前任何已注册工具都不匹配的模式并非错误（未加载 MCP 工具的部署中，`exclude: [mcp_*]` 仍然有效）；这与 `toolOrder` 的引用目标检查不同。
+
+## 链语义
+
+链键为「`(tool name, canonical arguments)`」：规范化过程会对键进行深度排序，然后执行 `JSON.stringify`，因此仅属性顺序不同的参数对象会视为相同。若某次调用与上一条受跟踪调用相同，该 agent 的连续计数器递增；换成另一条受跟踪调用则重置为 1。
+
+- **不受跟踪的调用对链透明。** 被 `include`／`exclude` 排除的调用既不递增计数器，也不重置计数器；因此，`grep X → todo_write → grep X` 仍算作连续两次 `grep X`，即使 `todo_write` 已被排除。这正是排除机制的价值：循环中穿插的记录类工具不能掩盖循环。
+- **被拒绝的调用也计数。** 检测位于 `tools/post-execute`；即便调用被 `tools/pre-execute` 监听器拒绝，该事件也会运行。模型反复尝试被拒绝的调用，恰恰是需要打断的循环。
+- **忽略没有 agent 的调用。** 直接调用 `ctx.tools.execute()` 的调用方没有需要提醒的模型，也没有可作为键的活跃 agent 对象。
+- **按 agent 分键。** 工具注册表位于上下文层级，subagent 会交错通过同一个 waterfall（瀑布式事件），因此每条链使用 `WeakMap<Agent, Chain>`，以活跃 agent 对象为键。一个 agent 的重复调用绝不会触发另一个 agent 的提醒。用户提示词（`agent/pre-step`）会重置提交该提示词的 agent 链；对象生命周期会自然限制弱引用条目的寿命，无需 dispose（资源释放）监听器。
+- **仅驻留内存。** 从持久化恢复的会话会从一条全新的链开始：guard 是启发式提醒，并非有日志记录的不变量；提醒会延后，这是可接受的代价。
+
+## 提醒传递
+
+提醒通过 post-execute 决策中的 `additionalContexts`（来源为 `{kind: 'plugin', plugin: 'repeat-tool-reminder'}`）传递，绝不替换 `content`；用于审计的 `tool/result` 事件仍保留工具自己的输出。循环会缓冲这段上下文，并在该步骤的工具结果之后将其作为注入的 `user/message` 追加；会话会将它渲染为普通的合成用户消息。因此，提醒对模型可见、带有来源归属，并且无需增加会话事件即可从会话日志重建。guard 始终通过 `next()` 委派，并将自己的提醒放在下游决策的上下文数组之前（两种结果都适用：被阻止的调用也会收到提醒）；每个条目保留自己的来源和元数据。
+
+## 模型体验
+
+### 首个阈值的上下文消息
+
+#### 模型看到的内容
+
+达到第一个配置的连续重复阈值时，对应 agent 会收到以下提醒。系统不会添加工具 schema 或正常调用文本。
+
+##### 首个阈值提醒
+
+```markdown
+You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call.
+```
+
+#### Token 影响
+
+达到阈值前为零 token。提醒会作为该 agent 的历史记录保留。
+
+#### KV Cache 影响
+
+仅追加；新出现的内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 后续阈值的上下文消息
+
+#### 模型看到的内容
+
+达到后续阈值时，agent 会收到以下详细提醒模板。受上限约束的参数预览严格以 `… (+<omitted> more chars)` 结尾。
+
+##### 后续阈值提醒
+
+```markdown
+Repeated tool call detected:
+- tool: <toolName>
+- consecutive_calls: <count>
+- arguments: <canonicalArguments>
+The repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered.
+```
+
+#### Token 影响
+
+每条提醒都会作为历史记录保留；`argumentsPreviewChars` 会限制随数据变化的参数文本长度，而各 agent 仍使用独立计数器。
+
+#### KV Cache 影响
+
+仅追加；新出现的内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **仅检测精确匹配**：规范化过程会对键进行深度排序，因此近似变体（稍作修改的路径、值内增加的空白）可以绕过链；在没有需求证据前，不采用模糊匹配。
+- **压缩（compaction）不会重置链**：跨越压缩检查点的链会继续计数。
+- **仅提供建议**：尚未实现达到较高阈值后升级为 `block`，但 `PostToolDecision` 已支持阻止调用。
+- **subagent 之间不共享链**：链始终按 agent 隔离；即使父 agent 与其 subagent 重复相同调用，也不会合并计数。
+- **合理的幂等轮询超过阈值后仍会收到提醒**：可通过 `thresholds`／`exclude` 配置释放压力。
+- **超过最高阈值后链不再提醒**：提醒只在精确达到所配置的次数时触发，超过后不会继续发送。

package/lib/index.js

@@ -0,0 +1,323 @@
+import { createRequire } from "node:module";
+import z from "@deepseek-ai/schemastery";
+import "@deepseek-ai/cordis";
+//#region ../../llm/llm/src/brand.ts
+/**
+* Brand a message identifier.
+* @param id - the opaque message identifier.
+* @returns the same string, branded; no validation is performed.
+*/
+function MessageId(id) {
+	return id;
+}
+//#endregion
+//#region ../../llm/llm/src/call-config.ts
+/**
+* Deep-freeze a value in place with an iterative traversal, guarding cycles,
+* so later mutation throws without imposing a JavaScript call-stack depth cap.
+* {@link AbortSignal} objects are deliberately skipped because they are the
+* request's live cancellation channel and freezing them breaks abort.
+* @param value - the value to freeze in place.
+* @returns the same value, frozen.
+*/
+function deepFreeze(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const pending = [{
+		kind: "visit",
+		node: value
+	}];
+	while (pending.length > 0) {
+		const task = pending.pop();
+		/* v8 ignore next -- the loop condition guarantees one pending task. */
+		if (task === void 0) continue;
+		if (task.kind === "property") {
+			pending.push({
+				kind: "visit",
+				node: task.source[task.key]
+			});
+			continue;
+		}
+		const node = task.node;
+		if (node === null || typeof node !== "object") continue;
+		if (node instanceof AbortSignal) continue;
+		if (seen.has(node)) continue;
+		seen.add(node);
+		Object.freeze(node);
+		const keys = Object.keys(node);
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) continue;
+			pending.push({
+				kind: "property",
+				source: node,
+				key
+			});
+		}
+	}
+	return value;
+}
+//#endregion
+//#region ../../llm/llm/src/message.ts
+/** Message value types, identity, and immutable construction helpers. */
+/**
+* Detach and deep-freeze a message whose identity already exists.
+* @param message - complete message, including its stable identity.
+* @returns an immutable snapshot that preserves the identity.
+*/
+function freezeMessage(message) {
+	return deepFreeze(structuredClone(message));
+}
+/**
+* Create one identified message and freeze it before publication.
+* @param input - complete role, content, and source for a new message.
+* @returns an immutable message with a fresh stable identity.
+*/
+function createMessage(input) {
+	return freezeMessage({
+		...input,
+		id: MessageId(crypto.randomUUID())
+	});
+}
+/**
+* Create one identified user-role message and freeze it before publication.
+* @param input - complete content and source for a new user message.
+* @returns an immutable user message with a fresh stable identity.
+*/
+function createUserMessage(input) {
+	return createMessage({
+		...input,
+		role: "user"
+	});
+}
+//#endregion
+//#region ../../util/timeout/src/index.ts
+/** Largest delay Node schedules without clamping it to one millisecond. */
+const MAX_TIMER_DELAY_MS = 2147483647;
+//#endregion
+//#region ../../llm/llm/src/error.ts
+/**
+* Canonical provider-neutral code for a response that completed normally but
+* carried no content blocks at all. Providers occasionally emit a degenerate
+* completion (a terminal stop with zero output); adapters classify it as this
+* failure instead of yielding an empty assistant message, because an empty
+* message silently ends the turn with nothing for the user or the loop to act
+* on. The attempt produced nothing durable, so retry policy treats it as safe
+* to repeat.
+*/
+const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
+new RegExp(String.raw`(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]` + String.raw`(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, "i");
+new RegExp(String.raw`\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?` + String.raw`too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?` + String.raw`(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, "i");
+new RegExp(String.raw`\b(?:input|prompt|request|messages?)\b.{0,40}` + String.raw`\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}` + String.raw`\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, "i");
+//#endregion
+//#region ../../llm/llm/src/retry-policy.ts
+/**
+* Provider-owned request-retry policy configuration and resolution.
+*
+* Adapters expose one resolved policy per registered provider route; the
+* optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
+*
+* @module @deepseek-ai/dsh-llm/retry-policy
+*/
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_INITIAL_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 1e4;
+const DEFAULT_JITTER_RATIO = .1;
+const DEFAULT_RETRYABLE_CODES = Object.freeze([
+	EMPTY_RESPONSE_CODE,
+	"RATE_LIMIT",
+	"SERVER",
+	"TIMEOUT",
+	"TRANSPORT"
+]);
+const backoffSchema = z.object({
+	initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
+	maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
+	jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO)
+});
+const normalPolicySchema = z.object({
+	mode: z.const("normal").required(),
+	maxRetries: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
+	retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
+	backoff: backoffSchema
+});
+const alwaysPolicySchema = z.object({
+	mode: z.const("always").required(),
+	backoff: backoffSchema
+});
+z.union([normalPolicySchema, alwaysPolicySchema]);
+//#endregion
+//#region ../../llm/llm/src/attribution.ts
+/**
+* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
+* adapters from drifting. See
+* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+*
+* App-attribution vocabulary for provider requests.
+* @module @deepseek-ai/dsh-llm/attribution
+*/
+const { version } = createRequire(import.meta.url)("../package.json");
+//#endregion
+//#region lib/types/index.js
+/**
+* Advisory per-agent repeat-call detector. It enriches post-execute decisions
+* with logged model context without vetoing or rewriting calls. Configuration
+* and chain semantics live in the package README; rationale lives in the
+* repeat-tool-reminder Agent Note.
+* @module @deepseek-ai/dsh-repeat-tool-reminder
+*/
+const name = "repeat-tool-reminder";
+const Config = z.object({
+	thresholds: z.array(z.number()).default([
+		3,
+		5,
+		8
+	]),
+	include: z.array(z.string()).default([]),
+	exclude: z.array(z.string()).default([]),
+	argumentsPreviewChars: z.number().default(500)
+});
+/**
+* The `{kind:'plugin'}` source stamped on every reminder this guard injects —
+* the label is load-bearing (an unlabeled context would render as a user
+* prompt in derived history).
+*/
+const PLUGIN_SOURCE = {
+	kind: "plugin",
+	plugin: "repeat-tool-reminder"
+};
+/**
+* The gentle first-threshold reminder. Keyed to `thresholds[0]`, not a literal
+* count, so a custom first threshold keeps the gentle-then-detailed escalation.
+*/
+const GENTLE_REMINDER = "You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call.";
+/** The detailed later-threshold reminder naming the tool, the run length, and the canonical arguments. */
+function detailedReminder(toolName, count, canonicalArguments) {
+	return `Repeated tool call detected:
+- tool: ${toolName}\n- consecutive_calls: ${count}\n- arguments: ${canonicalArguments}\nThe repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered.`;
+}
+/**
+* Deep key-sort of a parsed-JSON value so two argument objects that differ
+* only in property order canonicalize identically. Arguments reach the guard
+* as the loop's `JSON.parse` output (or its raw-string fallback for malformed
+* argument JSON), so JSON's value domain is the whole input domain — no
+* bigint, cycle, or `undefined` handling exists because no input path can
+* produce them.
+*/
+function sortJsonValue(value) {
+	if (Array.isArray(value)) return value.map(sortJsonValue);
+	if (value !== null && typeof value === "object") {
+		const record = value;
+		const sorted = {};
+		for (const key of Object.keys(record).sort()) sorted[key] = sortJsonValue(record[key]);
+		return sorted;
+	}
+	return value;
+}
+/** Canonical string form of a call's arguments: deep key-sort, then stringify. */
+function canonicalize(argumentsValue) {
+	return JSON.stringify(sortJsonValue(argumentsValue));
+}
+/** Compile one `*`-wildcard pattern to an anchored RegExp (every other regex metacharacter is matched literally). */
+function wildcardToRegExp(pattern) {
+	const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, String.raw`\$&`);
+	return new RegExp(`^${escaped.replaceAll("*", ".*")}$`);
+}
+/**
+* Head-truncate the canonical arguments for quoting in the detailed reminder,
+* marking how much was omitted. Bounds only the model-visible text — the
+* chain key always uses the full canonical string.
+*/
+function previewArguments(canonical, cap) {
+	if (canonical.length <= cap) return canonical;
+	return `${canonical.slice(0, cap)}… (+${canonical.length - cap} more chars)`;
+}
+/**
+* Validate `thresholds` per the fail-loud contract and return them sorted
+* ascending (the escalation rule reads `thresholds[0]` as the gentle tier, so
+* order is normalized here, once).
+*/
+function validateThresholds(values) {
+	if (values.length === 0) throw new Error("repeat-tool-reminder: `thresholds` must not be empty");
+	for (const value of values) if (!Number.isInteger(value) || value < 2) throw new Error(`repeat-tool-reminder: invalid threshold ${value} — every threshold must be an integer >= 2`);
+	if (new Set(values).size !== values.length) throw new Error("repeat-tool-reminder: `thresholds` must not contain duplicates");
+	return [...values].sort((a, b) => a - b);
+}
+/**
+* Prepend the guard's reminder while preserving every downstream context's
+* source and metadata.
+*/
+function prependContext(ours, theirs) {
+	return [ours, ...theirs ?? []];
+}
+/**
+* Install the guard's listeners.
+* @param ctx - plugin context; listeners are scoped to it and disposed with it.
+* @param config - validated {@link Config}; `thresholds` is re-checked fail-loud here.
+*/
+function apply(ctx, config) {
+	const thresholds = validateThresholds(config.thresholds);
+	const thresholdSet = new Set(thresholds);
+	const includePatterns = config.include.map(wildcardToRegExp);
+	const excludePatterns = config.exclude.map(wildcardToRegExp);
+	const argumentsPreviewChars = config.argumentsPreviewChars;
+	if (!Number.isInteger(argumentsPreviewChars) || argumentsPreviewChars < 1) throw new Error(`repeat-tool-reminder: invalid argumentsPreviewChars ${argumentsPreviewChars} — must be an integer >= 1`);
+	const chains = /* @__PURE__ */ new WeakMap();
+	/** Whether a tool participates in the chain (untracked calls are transparent: they neither count nor reset). */
+	function tracked(toolName) {
+		if (includePatterns.length > 0 && !includePatterns.some((pattern) => pattern.test(toolName))) return false;
+		return !excludePatterns.some((pattern) => pattern.test(toolName));
+	}
+	/**
+	* Advance the calling agent's chain for one attempt and return the reminder
+	* to deliver, if this attempt's run length hits a configured threshold.
+	* Counting happens here — in post-execute — because denied calls also flow
+	* through this waterfall (`ToolRuntime.execute` routes a deny through the
+	* same pipeline), and a model hammering a denied call is exactly the loop
+	* worth breaking.
+	*/
+	function observe(exec) {
+		if (!exec.agent) return void 0;
+		if (!tracked(exec.name)) return void 0;
+		const canonical = canonicalize(exec.arguments);
+		const key = JSON.stringify([exec.name, canonical]);
+		const chain = chains.get(exec.agent);
+		const count = chain !== void 0 && chain.key === key ? chain.count + 1 : 1;
+		chains.set(exec.agent, {
+			key,
+			count
+		});
+		if (!thresholdSet.has(count)) return void 0;
+		return createUserMessage({
+			content: [{
+				type: "text",
+				text: count === thresholds[0] ? GENTLE_REMINDER : detailedReminder(exec.name, count, previewArguments(canonical, argumentsPreviewChars))
+			}],
+			source: {
+				...PLUGIN_SOURCE,
+				form: "notice",
+				summary: `${exec.name} × ${count}`
+			}
+		});
+	}
+	ctx.on("tools/post-execute", async (exec, _result, next) => {
+		const reminder = observe(exec);
+		const downstream = await next();
+		if (!reminder) return downstream;
+		if (downstream.kind === "block") return {
+			kind: "block",
+			feedback: downstream.feedback,
+			additionalContexts: prependContext(reminder, downstream.additionalContexts)
+		};
+		return {
+			...downstream,
+			additionalContexts: prependContext(reminder, downstream.additionalContexts)
+		};
+	});
+	ctx.on("agent/pre-step", ({ agent, messages }, next) => {
+		if (messages.some((message) => message.source.kind === "user")) chains.delete(agent);
+		return next();
+	});
+}
+//#endregion
+export { Config, apply, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-repeat-tool-reminder`.
+* @module @deepseek-ai/dsh-repeat-tool-reminder/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-repeat-tool-reminder";
+/** Cordis companion plugin name. */
+const name = "repeat-tool-reminder-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the repeat chain is private to one post-execute listener and exposes no
+* package-owned event or snapshot that an independent companion can observe.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Advisory per-agent repeat-call detector. It enriches post-execute decisions
+ * with logged model context without vetoing or rewriting calls. Configuration
+ * and chain semantics live in the package README; rationale lives in the
+ * repeat-tool-reminder Agent Note.
+ * @module @deepseek-ai/dsh-repeat-tool-reminder
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "repeat-tool-reminder";
+/**
+ * Plugin config, validated by the same-named schemastery schema plus the
+ * load-time checks in `apply` (misconfiguration fails loud: an empty
+ * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at
+ * plugin load, never a silent fall-back). `include`/`exclude` entries are
+ * `*`-wildcard predicates over tool names at call time, not references to
+ * registry entries — a pattern matching no currently registered tool is valid
+ * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools).
+ */
+export interface Config {
+    /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */
+    thresholds?: number[];
+    /** Tool-name patterns to track; empty means every tool is tracked. */
+    include?: string[];
+    /** Tool-name patterns transparent to the chain (neither count nor reset). */
+    exclude?: string[];
+    /**
+     * Maximum characters of canonical arguments quoted in the DETAILED reminder
+     * (default 500). Large payloads (a `write` body, a long command) would
+     * otherwise ride into the next request unbounded — precisely in a loop
+     * scenario; the cap bounds the reminder, never the detection (the chain key
+     * always compares the FULL canonical string).
+     */
+    argumentsPreviewChars?: number;
+}
+export declare const Config: z<Config>;
+/**
+ * Install the guard's listeners.
+ * @param ctx - plugin context; listeners are scoped to it and disposed with it.
+ * @param config - validated {@link Config}; `thresholds` is re-checked fail-loud here.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-repeat-tool-reminder`.
+ * @module @deepseek-ai/dsh-repeat-tool-reminder/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "repeat-tool-reminder-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-repeat-tool-reminder",
+  "description": "Repeat-tool-call guard plugin: advisory reminders when an agent loops on identical tool calls",
+  "version": "0.0.1-rc.3",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/guard/repeat-tool-reminder"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}