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

@@ -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-<hash>).
+# 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 <dir>/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=
 

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).

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-<hash>`) 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/<id>`); 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.                                |

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,

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/<id>` 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;
+}

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,

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<string, string | undefined>, fn: () => void) {
+  const saved: Record<string, string | undefined> = {};
+  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/<id>", () => {
+  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/<id>", () => {
+  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 });
+  }
+});