@deepseek-ai/dsh-repeat-tool-reminder 0.1.2-rc.1 → 0.1.5-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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: 9b3f176e3c84278b454a138f661e3803d31457e1
-README.zh.md: f2678fe8c3a7a6412681405bb026c21e24c088bd
+README.md: 13035b68e80c9eea3e87bb7c8315fbaf9b84a3c3
+README.zh.md: 330dd22be31cbb128fe7807dd7e370c4ea2e1fe7

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-A model can get stuck calling the same tool with the same arguments — re-running a failing command, re-reading an unchanged file — burning time and tokens without making progress. `dsh-repeat-tool-reminder` notices the pattern and tells the model to stop: at chosen repeat counts it delivers a reminder to analyze the last result and either try a different approach or finish. The reminder is advice, never a block: a legitimate repeated call is delayed by nothing, and the decision to continue, change approach, or stop stays with the model. It tracks each agent separately, so one agent's loop never disturbs another's work, and a new user message clears the count. It ships enabled in the `dsh` base bundle with reminders at 3, 5, and 8 repeats.
+This package helps a model escape loops in which it calls the same tool with identical arguments without making progress. At configured repeat counts, it asks the model to inspect the previous result and change approach or finish. The reminder is advisory: it never blocks or delays a legitimate repeated call. Repeats are tracked separately for each agent and cleared by a new user message. The `dsh` base bundle enables the package with reminders at 3, 5, and 8 repeats.
 
 ## Table of Contents
 
@@ -181,6 +181,6 @@ These limits define when the guard is a poor fit. They are current package const
 
 This Dev Note is working context for maintainers: open questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
 
-The [repeat-tool-guard feature note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md) records the original design and alternatives under the former package name; the [naming ledger](../../../.agents/notes/implemented/architecture/2026-08-11-repository-naming-contract-and-rename-ledger.md) records the rename to `repeat-tool-reminder` and its reason.
+The [repeat-tool-guard feature note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md) records the original design and alternatives under the former package name; the [naming ledger](../../../.agents/notes/archived/architecture/2026-08-11-repository-naming-contract-and-rename-ledger.md) records the rename to `repeat-tool-reminder` and its reason.
 
 </details>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-模型可能会卡在以相同参数调用同一工具上——反复运行失败的命令、反复读取未变化的文件——白白消耗时间和 token 却没有进展。`dsh-repeat-tool-reminder` 会发现这种模式并让模型停下来：在选定的重复次数上，它送出一条提醒，要求模型分析上一次结果并改用其他方法或结束任务。提醒只是建议，绝非阻止：合理的重复调用不会被延迟分毫，是否继续、改变方法或停止仍由模型决定。它分别跟踪每个 agent（智能体），一个 agent 的循环绝不会干扰另一个 agent 的工作，新的用户消息会清零计数。它随 `dsh` base 组合默认启用，在 3、5、8 次重复时提醒。
+本包帮助模型跳出以相同参数反复调用同一工具却没有进展的循环。达到配置的重复次数时，它会要求模型检查上一次结果并改变方法或结束任务。提醒只是建议，绝不会阻止或延迟合理的重复调用。每个 agent 的重复分别跟踪，新的用户消息会清除计数。`dsh` base 组合默认启用本包，并在重复 3、5、8 次时提醒。
 
 ## 目录
 
@@ -181,6 +181,6 @@ The repeated calls are not making progress. Do not call this tool with these exa
 
 本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码和相关 Agent Note 为准。
 
-[repeat-tool-guard Agent Note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md) 以旧包名记录了原始设计与备选方案；[改名台账](../../../.agents/notes/implemented/architecture/2026-08-11-repository-naming-contract-and-rename-ledger.zh.md) 记录了改名为 `repeat-tool-reminder` 及其原因。
+[repeat-tool-guard Agent Note](../../../.agents/notes/archived/feature/2026-07-08-repeat-tool-guard.md) 以旧包名记录了原始设计与备选方案；[改名台账](../../../.agents/notes/archived/architecture/2026-08-11-repository-naming-contract-and-rename-ledger.md) 记录了改名为 `repeat-tool-reminder` 及其原因。
 
 </details>

package/lib/index.js

@@ -495,6 +495,9 @@ function harnessErrorCode(error) {
 }
 //#endregion
 //#region ../../llm/llm/src/content.ts
+function quoted(value) {
+	return JSON.stringify(value);
+}
 /**
 * Stable text shown to a model that cannot accept one durable image reference.
 * @param ref - durable normalized attachment omitted from the request.
@@ -514,6 +517,76 @@ function textOnlyImageText(ref) {
 function contentHasImage(content) {
 	return content.some((block) => block.type === "image" || block.type === "tool-result" && contentHasImage(block.content));
 }
+/**
+* True when typed model content contains a file block, walking nested
+* tool-result content on the same recursion every file policy shares.
+* Reads current content on every call without retaining scan results.
+* @param content - typed model content blocks.
+* @returns whether any nested block is a file.
+*/
+function contentHasFile(content) {
+	for (const block of content) if (block.type === "file" || block.type === "tool-result" && contentHasFile(block.content)) return true;
+	return false;
+}
+/**
+* Stable model-facing handle for one durable file reference: the address of
+* the verbatim stored copy and the instruction to read it on demand. This is
+* the only representation a provider ever receives for a file.
+* @param ref - durable verbatim file reference.
+* @param readonlyPath - execution-world path of the stored copy, when resolvable.
+* @returns deterministic handle text naming the file, its size, and its address.
+*/
+function fileHandleText(ref, readonlyPath) {
+	const digest = String(ref.attachmentId).slice(7, 15);
+	const identity = `File ${quoted(ref.name)} (${ref.bytes} bytes, sha256:${digest})`;
+	if (readonlyPath === void 0) return `[${identity} was uploaded, but the current execution environment cannot access a readable path. Report that limitation if its contents are needed; do not claim to have read it.]`;
+	return `[${identity}: verbatim read-only copy saved at ${quoted(readonlyPath)}. Read that path with your file tools when its contents are needed; copy it to a writable location before modifying it. When delegating file work, include this saved path in the delegation prompt; only subagents sharing this execution environment can read it.]`;
+}
+/** Replace every file occurrence, including nested tool results, with handle text. */
+function replaceFilesWithHandles(blocks, resolvePath) {
+	let next;
+	for (const [index, block] of blocks.entries()) {
+		if (block.type === "file") {
+			next ??= blocks.slice(0, index);
+			next.push({
+				type: "text",
+				text: fileHandleText(block.attachment, resolvePath(block.attachment))
+			});
+			continue;
+		}
+		if (block.type === "tool-result") {
+			const content = replaceFilesWithHandles(block.content, resolvePath);
+			if (content !== block.content) {
+				next ??= blocks.slice(0, index);
+				next.push({
+					...block,
+					content
+				});
+				continue;
+			}
+		}
+		next?.push(block);
+	}
+	return next ?? blocks;
+}
+/**
+* Project durable file history into deterministic handle text for every model
+* route. Unlike images, no provider receives file blocks natively, so this
+* projection is unconditional in request assembly.
+* @param messages - complete request history.
+* @param resolvePath - resolve one reference's current execution-world read path.
+* @returns the original list without files, otherwise shallow message copies with handle text.
+*/
+function projectFilesToText(messages, resolvePath) {
+	if (!messages.some((message) => contentHasFile(message.content))) return messages;
+	return messages.map((message) => {
+		const content = replaceFilesWithHandles(message.content, resolvePath);
+		return content === message.content ? message : {
+			...message,
+			content
+		};
+	});
+}
 /** Replace every image occurrence, including nested tool results, for a text-only model. */
 function replaceImagesForTextModel(blocks) {
 	let next;
@@ -950,6 +1023,15 @@ var LlmError = class extends HarnessError {
 		imageRequestPricing(provider, model) {
 			return this.adapters.get(provider)?.adapter.imageRequestPricing(provider, model);
 		}
+		/**
+		* Resolve the exact text one durable file occurrence contributes to every
+		* provider request in the current execution environment.
+		* @param ref - durable verbatim file reference from model history.
+		* @returns the same deterministic handle text used at adapter dispatch.
+		*/
+		fileRequestText(ref) {
+			return fileHandleText(ref, this.fileReadPath(ref));
+		}
 		/** Detach typed adapter-owned modality metadata. */
 		detachedModalities(modalities) {
 			return modalities === void 0 ? void 0 : [...modalities];
@@ -999,6 +1081,8 @@ var LlmError = class extends HarnessError {
 			const context = resolved.context;
 			if (context !== void 0 && (!Number.isInteger(context.contextWindow) || context.contextWindow <= 0)) throw new LlmError(`adapter returned invalid context metadata for provider "${provider}" model "${model}"`, "INVALID_MODEL_CONTEXT");
 			const inputModalities = this.detachedModalities(resolved.inputModalities);
+			const systemPromptUpdate = resolved.systemPromptUpdate;
+			if (systemPromptUpdate !== void 0 && systemPromptUpdate !== "in-history") throw new LlmError(`adapter returned invalid system prompt update mode for provider "${provider}" model "${model}"`, "INVALID_MODEL_INFO");
 			const defaultMaxTokens = resolved.defaultMaxTokens;
 			if (defaultMaxTokens !== void 0 && (!Number.isSafeInteger(defaultMaxTokens) || defaultMaxTokens <= 0)) throw new LlmError(`adapter returned invalid default maxTokens for provider "${provider}" model "${model}"`, "INVALID_MODEL_MAX_TOKENS");
 			const info = {
@@ -1008,7 +1092,8 @@ var LlmError = class extends HarnessError {
 				...resolved.description === void 0 ? {} : { description: resolved.description },
 				...inputModalities === void 0 ? {} : { inputModalities },
 				...context === void 0 ? {} : { context: { contextWindow: context.contextWindow } },
-				...defaultMaxTokens === void 0 ? {} : { defaultMaxTokens }
+				...defaultMaxTokens === void 0 ? {} : { defaultMaxTokens },
+				...resolved.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: resolved.systemPromptUpdate }
 			};
 			const reasoning = resolved.reasoning;
 			if (reasoning === void 0) return info;
@@ -1102,6 +1187,7 @@ var LlmError = class extends HarnessError {
 				adapterDefaults,
 				...context === void 0 ? {} : { context },
 				...modelInfo.inputModalities === void 0 ? {} : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
+				...modelInfo.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: modelInfo.systemPromptUpdate },
 				stream: (options) => {
 					if (dispatched) throw new LlmError("a prepared LLM call can only be dispatched once", "INVALID_PREPARED_CALL");
 					if (!callConfigEquals(options, resolvedConfig)) throw new LlmError("prepared LLM call config changed before adapter dispatch", "INVALID_PREPARED_CALL");
@@ -1143,6 +1229,20 @@ var LlmError = class extends HarnessError {
 			return Object.isFrozen(options) ? deepFreeze(filtered) : filtered;
 		}
 		/**
+		* Resolve the current execution-world read path of one durable file
+		* reference through the mounted attachment and filesystem providers.
+		*/
+		fileReadPath(ref) {
+			let hostPath;
+			try {
+				hostPath = this.ctx.get("attachments")?.fileHostPath(ref);
+			} catch {
+				return;
+			}
+			if (hostPath === void 0) return void 0;
+			return this.ctx.get("fs")?.processPathFromHostPath(hostPath);
+		}
+		/**
 		* Final adapter boundary. Adapter selection, dispatch, iterator construction,
 		* and iteration failures become one terminal failure chunk. Middleware and
 		* downstream consumer failures remain thrown plugin or consumer errors.
@@ -1173,13 +1273,16 @@ var LlmError = class extends HarnessError {
 					...options,
 					...resolvedConfig
 				};
-				const projectedOptions = modelInfo.inputModalities !== void 0 && !modelInfo.inputModalities.includes("image") && resolvedOptions.messages.some((message) => contentHasImage(message.content)) ? Object.isFrozen(resolvedOptions) ? deepFreeze({
+				let projectedMessages = resolvedOptions.messages;
+				if (projectedMessages.some((message) => contentHasFile(message.content))) projectedMessages = projectFilesToText(projectedMessages, (ref) => this.fileReadPath(ref));
+				if (modelInfo.inputModalities !== void 0 && !modelInfo.inputModalities.includes("image") && projectedMessages.some((message) => contentHasImage(message.content))) projectedMessages = projectImagesForTextModel(projectedMessages);
+				const projectedOptions = projectedMessages === resolvedOptions.messages ? resolvedOptions : Object.isFrozen(resolvedOptions) ? deepFreeze({
 					...resolvedOptions,
-					messages: projectImagesForTextModel(resolvedOptions.messages)
+					messages: projectedMessages
 				}) : {
 					...resolvedOptions,
-					messages: projectImagesForTextModel(resolvedOptions.messages)
-				} : resolvedOptions;
+					messages: projectedMessages
+				};
 				iterator = dispatch(this.forAdapter(projectedOptions, adapter))[Symbol.asyncIterator]();
 			} catch (error) {
 				yield adapterFailureChunk(error, options.signal);

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.1.2-rc.1",
+  "version": "0.1.5-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -30,18 +30,18 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.1"
   }
 }