From 9d3a2528bcdee7252aa4bbe7d1427c084e971873 Mon Sep 17 00:00:00 2001 From: Andrew Munsell Date: Fri, 10 Jul 2026 15:04:51 -0700 Subject: [PATCH] fix(cursor): use Agent CLI build id for x-cursor-client-version (#6795) * fix(cursor): use Agent CLI build id for x-cursor-client-version Reconstructed onto release/v3.8.47 to drop unrelated main-drift (deps/electron/proxy files belong to #6620, not this PR); the author's .env.example/docs deltas were re-applied cleanly onto the release tip. Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com> * chore(changelog): re-sync CHANGELOG.md to release tip (restore #6701 bullet) Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com> --------- Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com> --- .env.example | 11 +- .../6795-cursor-client-version-build-id.md | 1 + docs/reference/ENVIRONMENT.md | 4 +- open-sse/executors/cursor.ts | 7 +- open-sse/utils/cursorAgentCliVersion.ts | 124 +++++++++++++ scripts/ad-hoc/cursor-tap.cjs | 2 +- tests/unit/cursor-agent-cli-version.test.ts | 165 ++++++++++++++++++ 7 files changed, 309 insertions(+), 5 deletions(-) create mode 100644 changelog.d/fixes/6795-cursor-client-version-build-id.md create mode 100644 open-sse/utils/cursorAgentCliVersion.ts create mode 100644 tests/unit/cursor-agent-cli-version.test.ts diff --git a/.env.example b/.env.example index 31fe954c12..8f3a700dde 100644 --- a/.env.example +++ b/.env.example @@ -1647,10 +1647,19 @@ APP_LOG_TO_FILE=true # Used by: open-sse/utils/cursorImages.ts. # CURSOR_IMAGE_FETCH_TIMEOUT_MS=15000 -# Cursor state DB path override (for cursor version detection). +# Cursor state DB path override (for IDE cursor version detection). # Used by: open-sse/utils/cursorVersionDetector.ts. Default: probed automatically. # CURSOR_STATE_DB_PATH= +# Cursor Agent CLI build id for AgentService/Run impersonation (YYYY.MM.DD-). +# Used by: open-sse/utils/cursorAgentCliVersion.ts. Default: detect local install, else pin. +# CURSOR_AGENT_CLI_VERSION=2026.07.08-0c04a8a + +# Cursor Agent CLI data directory override (versions live under /versions/). +# Used by: open-sse/utils/cursorAgentCliVersion.ts. Default: ~/.local/share/cursor-agent (unix) +# or %LOCALAPPDATA%\cursor-agent (win32). Official agent CLI also honors this var. +# CURSOR_DATA_DIR= + # Direct Cursor bearer token used by scripts/ad-hoc/cursor-tap.cjs (developer tooling). # CURSOR_TOKEN= diff --git a/changelog.d/fixes/6795-cursor-client-version-build-id.md b/changelog.d/fixes/6795-cursor-client-version-build-id.md new file mode 100644 index 0000000000..b82f2fbba2 --- /dev/null +++ b/changelog.d/fixes/6795-cursor-client-version-build-id.md @@ -0,0 +1 @@ +- **fix(cursor):** send the Agent CLI build id as `x-cursor-client-version` so Cursor upstream accepts requests from the current CLI build instead of a stale hardcoded version (#6795 — thanks @andrewmunsell). diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md index 3bc0371570..1963c24302 100644 --- a/docs/reference/ENVIRONMENT.md +++ b/docs/reference/ENVIRONMENT.md @@ -894,7 +894,9 @@ changing them requires a code edit, not an env var: | `CURSOR_STREAM_TIMEOUT_MS` | `300000` | `open-sse/executors/cursor.ts` | Stream idle timeout (ms) for the Cursor executor. | | `CURSOR_TOOL_DIRECTIVE` | enabled (`!== "0"`) | `open-sse/executors/cursor.ts` | Tool-commit directive that makes composer-2.5 reliably issue tool calls. Set `0` to disable. | | `CURSOR_IMAGE_FETCH_TIMEOUT_MS` | `15000` | `open-sse/utils/cursorImages.ts` | Per-image fetch timeout (ms) for remote `image_url` vision input. | -| `CURSOR_STATE_DB_PATH` | _(probed)_ | `open-sse/utils/cursorVersionDetector.ts` | Override the Cursor state DB lookup used for version detection. | +| `CURSOR_STATE_DB_PATH` | _(probed)_ | `open-sse/utils/cursorVersionDetector.ts` | Override the Cursor IDE state DB lookup used for IDE version detection. | +| `CURSOR_AGENT_CLI_VERSION` | _(detect / pin)_ | `open-sse/utils/cursorAgentCliVersion.ts` | Agent CLI build id (`YYYY.MM.DD-`) for `x-cursor-client-version: cli-…` on Agent Run. | +| `CURSOR_DATA_DIR` | _(probed)_ | `open-sse/utils/cursorAgentCliVersion.ts` | Override Cursor Agent CLI data dir (`…/versions/`); same var the official agent uses. | | `CURSOR_TOKEN` | _(unset)_ | `scripts/ad-hoc/cursor-tap.cjs` | Direct Cursor bearer token used by developer tooling. | | `OMNIROUTE_LOG_REQUEST_SHAPE` | enabled (`!== "0"`) | `src/app/api/v1/chat/completions/route.ts` | Log content-type/length markers for large chat payloads. Set `"0"` to silence. | | `DEBUG_RESPONSES_SSE_TO_JSON` | _(unset)_ | `open-sse/handlers/responseTranslator.ts` | Set `true` to log Responses API SSE→JSON translation details. | diff --git a/open-sse/executors/cursor.ts b/open-sse/executors/cursor.ts index ad7a9b68a6..d05d3b5ee5 100644 --- a/open-sse/executors/cursor.ts +++ b/open-sse/executors/cursor.ts @@ -44,7 +44,10 @@ import { estimateOutputTokens, addBufferToUsage, } from "../utils/usageTracking.ts"; -import { getCursorVersion } from "../utils/cursorVersionDetector.ts"; +import { + formatCursorAgentClientVersion, + getCursorAgentCliVersion, +} from "../utils/cursorAgentCliVersion.ts"; import { sanitizeErrorMessage } from "../utils/error.ts"; import { generateToolCallId } from "../translator/helpers/toolCallHelper.ts"; import { @@ -647,7 +650,7 @@ export class CursorExecutor extends BaseExecutor { traceparent: traceParent, "user-agent": "connect-es/1.6.1", "x-cursor-client-type": "cli", - "x-cursor-client-version": `cli-${getCursorVersion()}`, + "x-cursor-client-version": formatCursorAgentClientVersion(getCursorAgentCliVersion()), "x-ghost-mode": ghostMode ? "true" : "false", "x-original-request-id": requestId, "x-request-id": requestId, diff --git a/open-sse/utils/cursorAgentCliVersion.ts b/open-sse/utils/cursorAgentCliVersion.ts new file mode 100644 index 0000000000..2a65df051b --- /dev/null +++ b/open-sse/utils/cursorAgentCliVersion.ts @@ -0,0 +1,124 @@ +/** + * Cursor Agent CLI version for AgentService/Run impersonation. + * + * Wire header: `x-cursor-client-version: cli-${id}` where `id` is a dated + * build like `2026.07.08-0c04a8a` (not the IDE `3.x` semver). + * + * Resolution: CURSOR_AGENT_CLI_VERSION env → local install detect → pin. + */ + +import { existsSync, lstatSync, readdirSync, realpathSync } from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; + +/** + * Pinned Agent CLI build id used when no local install is found (typical + * headless OmniRoute). Bump when refreshing Cursor CLI impersonation. + */ +export const CURSOR_AGENT_CLI_VERSION = "2026.07.08-0c04a8a"; + +const VERSION_ID_RE = /^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/; +const CACHE_TTL_MS = 60 * 60 * 1000; + +let cachedVersion: string | null = null; +let cachedAt = 0; + +export function isCursorAgentCliVersionId(value: string): boolean { + return VERSION_ID_RE.test(value); +} + +export function formatCursorAgentClientVersion(id: string): string { + return `cli-${id}`; +} + +/** Extract `versions/` from a resolved agent binary path. */ +export function extractVersionIdFromResolvedPath(resolvedPath: string): string | null { + const parts = resolvedPath.split(/[/\\]/); + const versionsIdx = parts.lastIndexOf("versions"); + if (versionsIdx < 0 || versionsIdx + 1 >= parts.length) return null; + const id = parts[versionsIdx + 1]; + return isCursorAgentCliVersionId(id) ? id : null; +} + +export function newestVersionInDir(versionsDir: string): string | null { + try { + if (!existsSync(versionsDir)) return null; + const matches = readdirSync(versionsDir) + .filter((name) => { + if (!isCursorAgentCliVersionId(name)) return false; + try { + return lstatSync(join(versionsDir, name)).isDirectory(); + } catch { + return false; + } + }) + .sort(); + return matches.length > 0 ? matches[matches.length - 1] : null; + } catch { + return null; + } +} + +function versionFromShim(shimPath: string): string | null { + try { + if (!existsSync(shimPath)) return null; + const resolved = realpathSync(shimPath); + return extractVersionIdFromResolvedPath(resolved); + } catch { + return null; + } +} + +function defaultVersionsDir(home: string): string { + if (process.platform === "win32") { + const localAppData = process.env.LOCALAPPDATA || join(home, "AppData", "Local"); + return join(localAppData, "cursor-agent", "versions"); + } + return join(home, ".local", "share", "cursor-agent", "versions"); +} + +/** + * Detect an installed Agent CLI build id from the filesystem. + * @param home - injectable home for tests (defaults to os.homedir()) + */ +export function detectCursorAgentCliVersionFromFs(home: string = homedir()): string | null { + const localBin = join(home, ".local", "bin"); + for (const name of ["agent", "cursor-agent"]) { + const fromShim = versionFromShim(join(localBin, name)); + if (fromShim) return fromShim; + } + + const dataDir = process.env.CURSOR_DATA_DIR; + const versionsDir = dataDir ? join(dataDir, "versions") : defaultVersionsDir(home); + return newestVersionInDir(versionsDir); +} + +export function getCursorAgentCliVersion(): string { + const now = Date.now(); + if (cachedVersion && now - cachedAt < CACHE_TTL_MS) { + return cachedVersion; + } + + const fromEnv = process.env.CURSOR_AGENT_CLI_VERSION?.trim(); + if (fromEnv && isCursorAgentCliVersionId(fromEnv)) { + cachedVersion = fromEnv; + cachedAt = now; + return cachedVersion; + } + + const home = process.env.HOME || process.env.USERPROFILE || homedir(); + const fromFs = detectCursorAgentCliVersionFromFs(home); + if (fromFs) { + cachedVersion = fromFs; + cachedAt = now; + return cachedVersion; + } + + return CURSOR_AGENT_CLI_VERSION; +} + +/** Exposed for testing: reset the in-memory cache. */ +export function resetCursorAgentCliVersionCache(): void { + cachedVersion = null; + cachedAt = 0; +} diff --git a/scripts/ad-hoc/cursor-tap.cjs b/scripts/ad-hoc/cursor-tap.cjs index 0145d6162c..3bb3f94ae4 100644 --- a/scripts/ad-hoc/cursor-tap.cjs +++ b/scripts/ad-hoc/cursor-tap.cjs @@ -130,7 +130,7 @@ const req = client.request({ traceparent: traceParent, "user-agent": "connect-es/1.6.1", "x-cursor-client-type": "cli", - "x-cursor-client-version": "cli-2025.10.21-b2dfaef", + "x-cursor-client-version": "cli-2026.07.08-0c04a8a", "x-ghost-mode": "true", "x-original-request-id": requestId, "x-request-id": requestId, diff --git a/tests/unit/cursor-agent-cli-version.test.ts b/tests/unit/cursor-agent-cli-version.test.ts new file mode 100644 index 0000000000..85bb4e9ecf --- /dev/null +++ b/tests/unit/cursor-agent-cli-version.test.ts @@ -0,0 +1,165 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +const { + CURSOR_AGENT_CLI_VERSION, + detectCursorAgentCliVersionFromFs, + extractVersionIdFromResolvedPath, + formatCursorAgentClientVersion, + getCursorAgentCliVersion, + newestVersionInDir, + resetCursorAgentCliVersionCache, +} = await import("../../open-sse/utils/cursorAgentCliVersion.ts"); + +function withEnv(vars: Record, fn: () => void) { + const saved: Record = {}; + for (const key of Object.keys(vars)) { + saved[key] = process.env[key]; + const next = vars[key]; + if (next === undefined) delete process.env[key]; + else process.env[key] = next; + } + try { + fn(); + } finally { + for (const key of Object.keys(saved)) { + if (saved[key] === undefined) delete process.env[key]; + else process.env[key] = saved[key]; + } + } +} + +test("formatCursorAgentClientVersion prefixes cli-", () => { + assert.equal(formatCursorAgentClientVersion("2026.07.08-0c04a8a"), "cli-2026.07.08-0c04a8a"); +}); + +test("extractVersionIdFromResolvedPath reads versions/", () => { + assert.equal( + extractVersionIdFromResolvedPath( + "/home/u/.local/share/cursor-agent/versions/2026.07.08-0c04a8a/cursor-agent" + ), + "2026.07.08-0c04a8a" + ); + assert.equal(extractVersionIdFromResolvedPath("/tmp/not-an-agent"), null); +}); + +test("newestVersionInDir picks lexicographically newest matching child", () => { + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-ver-dir-")); + try { + fs.mkdirSync(path.join(tmp, "2026.05.24-dda726e")); + fs.mkdirSync(path.join(tmp, "2026.07.08-0c04a8a")); + fs.writeFileSync(path.join(tmp, "not-a-version"), "x"); + fs.mkdirSync(path.join(tmp, "3.9.0")); + assert.equal(newestVersionInDir(tmp), "2026.07.08-0c04a8a"); + } finally { + fs.rmSync(tmp, { recursive: true, force: true }); + } +}); + +test("detectCursorAgentCliVersionFromFs uses shim realpath under versions/", () => { + const home = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-home-shim-")); + try { + const id = "2026.06.01-abcdef0"; + const versionDir = path.join(home, ".local", "share", "cursor-agent", "versions", id); + fs.mkdirSync(versionDir, { recursive: true }); + const binary = path.join(versionDir, "cursor-agent"); + fs.writeFileSync(binary, "#!/bin/sh\n"); + const binDir = path.join(home, ".local", "bin"); + fs.mkdirSync(binDir, { recursive: true }); + fs.symlinkSync(binary, path.join(binDir, "agent")); + + withEnv({ CURSOR_DATA_DIR: undefined, CURSOR_AGENT_CLI_VERSION: undefined }, () => { + assert.equal(detectCursorAgentCliVersionFromFs(home), id); + }); + } finally { + fs.rmSync(home, { recursive: true, force: true }); + } +}); + +test("detectCursorAgentCliVersionFromFs uses CURSOR_DATA_DIR versions when no shim", () => { + const home = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-home-empty-")); + const data = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-data-")); + try { + const id = "2026.04.01-deadbeef"; + fs.mkdirSync(path.join(data, "versions", id), { recursive: true }); + withEnv({ CURSOR_DATA_DIR: data }, () => { + assert.equal(detectCursorAgentCliVersionFromFs(home), id); + }); + } finally { + fs.rmSync(home, { recursive: true, force: true }); + fs.rmSync(data, { recursive: true, force: true }); + } +}); + +test("getCursorAgentCliVersion env override wins", () => { + withEnv({ CURSOR_AGENT_CLI_VERSION: "2026.01.02-abc1234" }, () => { + resetCursorAgentCliVersionCache(); + assert.equal(getCursorAgentCliVersion(), "2026.01.02-abc1234"); + }); + resetCursorAgentCliVersionCache(); +}); + +test("getCursorAgentCliVersion ignores invalid env and uses pin when FS empty", () => { + const home = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-home-pin-")); + try { + withEnv( + { + HOME: home, + USERPROFILE: home, + CURSOR_AGENT_CLI_VERSION: "3.9", + CURSOR_DATA_DIR: undefined, + }, + () => { + resetCursorAgentCliVersionCache(); + assert.equal(getCursorAgentCliVersion(), CURSOR_AGENT_CLI_VERSION); + } + ); + } finally { + resetCursorAgentCliVersionCache(); + fs.rmSync(home, { recursive: true, force: true }); + } +}); + +test("getCursorAgentCliVersion caches until reset", () => { + withEnv({ CURSOR_AGENT_CLI_VERSION: "2026.02.03-111aaaa" }, () => { + resetCursorAgentCliVersionCache(); + assert.equal(getCursorAgentCliVersion(), "2026.02.03-111aaaa"); + process.env.CURSOR_AGENT_CLI_VERSION = "2026.02.03-222bbbb"; + assert.equal(getCursorAgentCliVersion(), "2026.02.03-111aaaa", "cached"); + resetCursorAgentCliVersionCache(); + assert.equal(getCursorAgentCliVersion(), "2026.02.03-222bbbb"); + }); + resetCursorAgentCliVersionCache(); +}); + +test("getCursorAgentCliVersion reads CURSOR_DATA_DIR via isolated HOME", () => { + const home = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-home-get-")); + const data = fs.mkdtempSync(path.join(os.tmpdir(), "cursor-cli-data-get-")); + try { + const id = "2026.03.15-cafebabe"; + fs.mkdirSync(path.join(data, "versions", id), { recursive: true }); + withEnv( + { + HOME: home, + USERPROFILE: home, + CURSOR_DATA_DIR: data, + CURSOR_AGENT_CLI_VERSION: undefined, + }, + () => { + resetCursorAgentCliVersionCache(); + assert.equal(getCursorAgentCliVersion(), id); + assert.equal( + formatCursorAgentClientVersion(getCursorAgentCliVersion()), + `cli-${id}` + ); + } + ); + } finally { + resetCursorAgentCliVersionCache(); + fs.rmSync(home, { recursive: true, force: true }); + fs.rmSync(data, { recursive: true, force: true }); + } +});