dsh-cursor-subscription 0.6.3 → 0.6.5

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";
@@ -173,6 +175,12 @@ export const STREAM_PROGRESS_TIMEOUT_MS = 60 * 1000;
 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 = 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;
 						}
@@ -2748,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) {
@@ -2762,6 +2920,7 @@ export class CursorAdapter extends LlmAdapter {
 				}
 			} finally {
 				clearInterval(idleCheck);
+				clearTimeout(toolCallSettle);
 			}
 
 			if (!terminalErrorEmitted && !toolCallPending) {
@@ -2960,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.3",
+  "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",