dsh-cursor-subscription 0.6.2 → 0.6.5

package/README.md

@@ -60,7 +60,7 @@ Then add `dsh-cursor-subscription` to the `dsh.profile.bundles` array in `packag
 
 When a tool is required, the agent converts Cursor's tool request into a local DSH tool execution. The result is returned to the model through the conversation history; Cursor's filesystem tools are not used.
 
-The **Runtime settings** card controls the maximum tool rounds in one Cursor run and the HTTP retry policy. Retry count means additional attempts and defaults to `0` (disabled). Cursor's streaming POST protocol cannot prove that a failed attempt was not processed remotely, so enabling retries may repeat model work or usage. Retries occur only before any response output when the initial HTTP status matches the configured list.
+The **Runtime settings** card controls the maximum tool rounds in one Cursor run and the HTTP retry policy. The tool-round cap defaults to `200` (range 1–1000) and ends the run with `TOOL_LIMIT` when exceeded. Retry count means additional attempts and defaults to `0` (disabled). Cursor's streaming POST protocol cannot prove that a failed attempt was not processed remotely, so enabling retries may repeat model work or usage. Retries occur only before any response output when the initial HTTP status matches the configured list.
 
 ## Updating and Removing
 

package/README_zh.md

@@ -71,7 +71,8 @@ pnpm add file:D:/mcp/dsh-cursor-subscription
 需要调用工具时，Agent 会把 Cursor 侧的工具请求转成 DSH 本地工具执行，结果通过
 对话历史回传给模型，全程不经过 Cursor 的文件系统工具。
 
-「运行设置」卡片可以调整单次 Cursor 任务的最大工具轮次和 HTTP 重试策略。重试次数指
+「运行设置」卡片可以调整单次 Cursor 任务的最大工具轮次和 HTTP 重试策略。工具轮次上限
+默认 `200`（范围 1–1000），超过后以 `TOOL_LIMIT` 终止该次运行。重试次数指
 首次请求之外的额外尝试次数，默认 `0`（关闭）。Cursor 的流式 POST 协议无法证明失败请求
 未被远端处理，因此启用重试可能重复模型工作或用量；仅当尚未产生任何输出且初始 HTTP
 状态码匹配列表时才会重试。

package/lib/index.js

@@ -17,7 +17,9 @@ import z from "@deepseek-ai/schemastery";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { ToolCallId, LlmAdapter, LlmError } from "@deepseek-ai/dsh-llm";
 import { createHash, randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { appendFileSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import http2 from "node:http2";
 import http from "node:http";
 import https from "node:https";
@@ -172,7 +174,13 @@ export const STREAM_PROGRESS_TIMEOUT_MS = 60 * 1000;
 /** Retain checkpoints/live tool bridges for inactive DSH sessions. */
 export const SESSION_STATE_TTL_MS = 30 * 60 * 1000;
 /** Stop one Cursor Run before an unconstrained agent can loop forever. */
-export const MAX_TOOL_ROUNDS = 64;
+export const MAX_TOOL_ROUNDS = 200;
+/**
+ * How long a tool-call step keeps reading after `mcpArgs` for the frames that
+ * close the burst (sibling calls, blob writes, checkpoint). Sibling calls of
+ * one burst arrive within ~100 ms of each other.
+ */
+export const TOOL_CALL_SETTLE_MS = 500;
 export const DEFAULT_RETRY_COUNT = 0;
 export const DEFAULT_RETRY_INTERVAL_MS = 1000;
 export const DEFAULT_RETRY_HTTP_STATUS_CODES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
@@ -1156,6 +1164,62 @@ export function decodeAgentServerMessage(bytes) {
 	return { case: "unknown", value: undefined };
 }
 
+/** Field numbers inside one protobuf message; used to describe frames we do not decode. */
+function messageFields(bytes) {
+	const reader = new Reader(bytes);
+	const fields = [];
+	while (!reader.done) {
+		const { field, wireType } = reader.tag();
+		fields.push(field);
+		reader.skip(wireType);
+	}
+	return fields.join(",");
+}
+
+/** Field numbers of a nested message (`wanted` inside `bytes`). */
+function nestedMessageFields(bytes, wanted) {
+	const reader = new Reader(bytes);
+	while (!reader.done) {
+		const { field, wireType } = reader.tag();
+		if (wireType !== 2) {
+			reader.skip(wireType);
+			continue;
+		}
+		const payload = reader.bytes();
+		if (field === wanted) return messageFields(payload);
+	}
+	return "";
+}
+
+/**
+ * One-line description of a server frame for the stall trace. Undecoded
+ * frames report their protobuf field numbers so a server message the adapter
+ * ignores is still visible when a run goes silent.
+ */
+export function describeServerFrame(frame) {
+	if ((frame.flags & CONNECT_END_STREAM_FLAG) !== 0) {
+		return `endstream(${Buffer.from(frame.payload).toString("utf8").replace(/\s+/g, " ").slice(0, 60)})`;
+	}
+	try {
+		const message = decodeAgentServerMessage(frame.payload);
+		if (message.case === "interactionUpdate") {
+			const update = message.value;
+			if (update.type === "textDelta") return `text(${update.text.length})`;
+			if (update.type === "thinkingDelta") return `thinking(${update.text.length})`;
+			if (update.type === "tokenDelta") return `tokens(${update.tokens})`;
+			if (update.type === "partialToolCall") return "partialToolCall";
+			if (update.type === "unknown") return `interaction#${nestedMessageFields(frame.payload, 1)}`;
+			return update.type;
+		}
+		if (message.case === "conversationCheckpointUpdate") return `checkpoint(${message.value.length}B)`;
+		if (message.case === "kvServerMessage") return `kv:${message.value.case}`;
+		if (message.case === "execServerMessage") return `exec:${message.value.case}`;
+		return `message#${messageFields(frame.payload)}`;
+	} catch (error) {
+		return `undecodable(${(error instanceof Error ? error.message : String(error)).slice(0, 40)})`;
+	}
+}
+
 /** InteractionUpdate { text_delta=1, thinking_delta=4, token_delta=8, turn_ended=14, ... } */
 export function decodeInteractionUpdate(bytes) {
 	const reader = new Reader(bytes);
@@ -1410,6 +1474,7 @@ export class ConnectFrameReader {
 		this.frames = [];
 		this.waiters = [];
 		this.ended = false;
+		this.paused = false;
 		this.error = undefined;
 	}
 
@@ -1452,6 +1517,21 @@ export class ConnectFrameReader {
 		for (const waiter of this.waiters.splice(0)) waiter.resolve(undefined);
 	}
 
+	/**
+	 * Stop blocking for new frames without ending the stream: buffered frames
+	 * are still returned, and `resume()` restores normal waiting. A Cursor run
+	 * stays alive across DSH steps, so a reader that is paused to end one step
+	 * must accept frames again when the next step continues the same run.
+	 */
+	pause() {
+		this.paused = true;
+		for (const waiter of this.waiters.splice(0)) waiter.resolve(undefined);
+	}
+
+	resume() {
+		this.paused = false;
+	}
+
 	fail(error) {
 		this.error = error;
 		this.ended = true;
@@ -1460,6 +1540,7 @@ export class ConnectFrameReader {
 
 	async next() {
 		if (this.frames.length > 0) return this.frames.shift();
+		if (this.paused) return undefined;
 		if (this.ended) {
 			if (this.error !== undefined) throw this.error;
 			return undefined;
@@ -2398,6 +2479,9 @@ export class CursorAdapter extends LlmAdapter {
 		this.resolveAttachments = options.resolveAttachments;
 		this.sleep = options.sleep ?? abortableDelay;
 		this.now = options.now ?? Date.now;
+		this.logger = options.logger;
+		this.hangTracePath = options.hangTracePath ?? join(homedir(), ".dsh", "cursor-hang-trace.log");
+		this.toolCallSettleMs = options.toolCallSettleMs ?? TOOL_CALL_SETTLE_MS;
 		this.#modelsCache = { at: 0, models: undefined };
 	}
 
@@ -2501,6 +2585,9 @@ export class CursorAdapter extends LlmAdapter {
 			let blobStore;
 			if (canResume) {
 				run = liveBridge.run;
+				// A previous step paused this reader to stop waiting for frames it
+				// no longer needed; continue the same Run and read again.
+				run.frames?.resume?.();
 				blobStore = persisted.blobs;
 				abortRun = () => run.abort(new Error("Cursor request aborted by caller"));
 				upstream.addEventListener("abort", abortRun, { once: true });
@@ -2560,16 +2647,6 @@ export class CursorAdapter extends LlmAdapter {
 			const started = this.now();
 			let lastActivity = started;
 			let lastProgress = started;
-			const idleCheck = setInterval(() => {
-				const now = this.now();
-				if (now - lastActivity > this.idleTimeoutMs) {
-					run.abort(new Error("Cursor stream idle timeout"));
-				} else if (now - lastProgress > this.progressTimeoutMs) {
-					run.abort(new Error(`Cursor stream progress timeout: no content for ${this.progressTimeoutMs}ms`));
-				}
-			}, this.idleCheckIntervalMs);
-			idleCheck.unref?.();
-
 			let emittedToolCall = false;
 			let toolCallBuffer = undefined;
 			let textOutput = "";
@@ -2579,12 +2656,84 @@ export class CursorAdapter extends LlmAdapter {
 			let toolCallPending = false;
 			let toolRoundCounted = false;
 			const pendingExecs = [];
+			let toolCallSettle;
+			/**
+			 * Stop blocking for more frames without ending the reader, so the same
+			 * Run can be continued by the next DSH step.
+			 */
+			const stopReading = () => {
+				if (typeof run.frames?.pause === "function") run.frames.pause();
+				else if (typeof run.frames?.finish === "function") run.frames.finish();
+			};
+			/**
+			 * Cap how long the loop waits for the frame that closes a tool-call
+			 * burst. Cursor usually follows mcpArgs with blob writes and a
+			 * checkpoint, but it may instead send the checkpoint *before* the burst
+			 * and then nothing at all; waiting for a second checkpoint in that case
+			 * hung the step until the progress watchdog aborted it.
+			 */
+			const armToolCallSettle = () => {
+				toolCallSettle ??= setTimeout(stopReading, this.toolCallSettleMs);
+				toolCallSettle.unref?.();
+			};
+			// Compact trace of the frames this run received, kept for the stall
+			// report so a silent server can be diagnosed from the log alone.
+			const frameTrace = [];
+			const traceFrame = (label) => {
+				const last = frameTrace.at(-1);
+				if (label === "heartbeat" && last?.label === "heartbeat") {
+					last.count++;
+					last.at = this.now();
+					return;
+				}
+				frameTrace.push({ label, at: this.now(), count: 1 });
+				if (frameTrace.length > 120) frameTrace.shift();
+			};
+			const stallReport = (message) => {
+				const lines = [
+					`=== ${new Date().toISOString()} ${message} ===`,
+					`session=${sessionKey ?? "-"} model=${options.model ?? "-"} textChars=${textOutput.length}`
+						+ ` toolCallPending=${toolCallPending} toolRounds=${toolRoundCount}`
+						+ ` checkpoint=${persisted.checkpoint?.length ?? 0}B blobs=${blobStore?.size ?? 0}`,
+					`lastFrame=${Math.round((this.now() - lastActivity) / 1000)}s ago`
+						+ ` lastContent=${Math.round((this.now() - lastProgress) / 1000)}s ago`,
+					...frameTrace.map((entry) => `  ${new Date(entry.at).toISOString()} ${entry.label}${entry.count > 1 ? ` x${entry.count}` : ""}`),
+					"",
+				];
+				try {
+					appendFileSync(this.hangTracePath, lines.join("\n"));
+				} catch {}
+				this.logger?.warn?.(`cursor-subscription: ${message}; trace in ${this.hangTracePath}`);
+			};
+			const handleStall = (message) => {
+				stallReport(message);
+				// The step already delivered something the user can see — answer
+				// text or a tool call — and Cursor stopped sending content without
+				// ending the turn. Stop reading instead of raising a retryable
+				// error: DSH would discard the delivered answer or tool call and
+				// re-run the whole step.
+				if ((textOutput.length > 0 || toolCallPending) && typeof run.frames?.pause === "function") {
+					stopReading();
+					return;
+				}
+				run.abort(new Error(message));
+			};
+			const idleCheck = setInterval(() => {
+				const now = this.now();
+				if (now - lastActivity > this.idleTimeoutMs) {
+					handleStall("Cursor stream idle timeout");
+				} else if (now - lastProgress > this.progressTimeoutMs) {
+					handleStall(`Cursor stream progress timeout: no content for ${this.progressTimeoutMs}ms`);
+				}
+			}, this.idleCheckIntervalMs);
+			idleCheck.unref?.();
 
 			try {
 				for (;;) {
 					const frame = await run.frames.next();
 					if (frame === undefined) break;
 					lastActivity = this.now();
+					traceFrame(describeServerFrame(frame));
 					if ((frame.flags & CONNECT_END_STREAM_FLAG) !== 0) {
 						const end = parseEndStream(frame.payload);
 						if (end !== undefined) {
@@ -2617,8 +2766,11 @@ export class CursorAdapter extends LlmAdapter {
 						// retaining it for a later request.
 						persisted.checkpoint = Uint8Array.from(message.value);
 						if (toolCallPending) {
-							// Cursor emits this checkpoint after mcpArgs. Keep the same Run
-							// alive; the next DSH step resumes it with McpResult field 11.
+							// A checkpoint after mcpArgs closes the tool-call step. Keep the
+							// same Run alive; the next DSH step resumes it with McpResult
+							// field 11. Cursor does not always send this checkpoint after
+							// the burst — the traced hangs have it *before* mcpArgs — so the
+							// wait for it is capped by the settle timer armed below.
 							streamClosed = true;
 							break;
 						}
@@ -2646,6 +2798,18 @@ export class CursorAdapter extends LlmAdapter {
 							}
 						} else if (update.type === "toolCallStarted" || update.type === "toolCallCompleted" || update.type === "toolCallDelta") {
 							emittedToolCall = true;
+						} else if (update.type === "turnEnded") {
+							// Cursor ends every assistant turn with this update, but it does
+							// not reliably close the HTTP/2 stream afterwards: the server can
+							// keep the run alive with heartbeats only. Ignoring the update
+							// therefore left a finished answer waiting until the progress
+							// watchdog aborted the run, and the resulting retryable TIMEOUT
+							// made DSH discard the answer the user had already read and
+							// re-run the whole step. The trailing conversation checkpoint
+							// always arrives before turnEnded, so stopping here keeps
+							// everything a later run needs. A pending MCP tool call still
+							// waits for its checkpoint so the live bridge stays resumable.
+							if (!toolCallPending) break;
 						}
 					} else if (message.case === "kvServerMessage") {
 						const kv = message.value;
@@ -2736,10 +2900,16 @@ export class CursorAdapter extends LlmAdapter {
 							};
 							pendingExecs.push({ id: exec.id, execId: exec.execId, toolCallId: id });
 							toolCallPending = true;
-							// Do not close the Run. Cursor sends blob writes + a checkpoint
-							// immediately after mcpArgs; once captured, return tool-calls to DSH
-							// while preserving this bridge for the result.
+							// Do not close the Run. Cursor usually sends blob writes + a
+							// checkpoint right after mcpArgs, which this loop still wants to
+							// capture for the persisted session, but the ordering is not
+							// guaranteed: traced hangs end with `checkpoint | mcpArgs` and no
+							// further frame, which left the step waiting until the progress
+							// watchdog aborted it and DSH re-ran the whole step instead of
+							// running the tool. Cap the wait; sibling calls of one burst
+							// arrive within ~100 ms of each other.
 							streamClosed = true;
+							armToolCallSettle();
 						} else {
 							const reply = rejectionFor(exec);
 							if (reply !== undefined) {
@@ -2750,6 +2920,7 @@ export class CursorAdapter extends LlmAdapter {
 				}
 			} finally {
 				clearInterval(idleCheck);
+				clearTimeout(toolCallSettle);
 			}
 
 			if (!terminalErrorEmitted && !toolCallPending) {
@@ -2948,7 +3119,7 @@ export function apply(ctx, config = {}) {
 	};
 	const store = new CursorCredentialStore(ctx.credentials, CREDENTIAL_REF);
 	const auth = new CursorAuthService(store, { logger: ctx.logger });
-	const adapter = new CursorAdapter({ auth, settings: readSettings, resolveAttachments: () => ctx.get("attachments") });
+	const adapter = new CursorAdapter({ auth, settings: readSettings, resolveAttachments: () => ctx.get("attachments"), logger: ctx.logger });
 	ctx.llm.registerAdapter([PROVIDER], adapter);
 	const usageReader = new CursorUsageReader(auth, { logger: ctx.logger });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cursor-subscription",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "packageManager": "pnpm@11.19.0",
   "description": "Cursor subscription for DeepSeek Harness with browser login, token refresh, model discovery, and the Cursor Agent chat protocol",
   "type": "module",