pi-provider-cursor-ask 0.1.0

package/src/client/cursor-wire.ts

@@ -0,0 +1,213 @@
+export interface CursorModelParameter {
+  id: string;
+  value: string;
+}
+
+export interface CursorParameterizedVariant {
+  parameters: CursorModelParameter[];
+  isMaxMode: boolean;
+  isDefaultMaxConfig?: boolean;
+  isDefaultNonMaxConfig?: boolean;
+  displayName?: string;
+  displayNameOutsidePicker?: string;
+  variantStringRepresentation?: string;
+}
+
+export interface CursorParameterizedModel {
+  name: string;
+  clientDisplayName?: string;
+  serverModelName?: string;
+  supportsMaxMode?: boolean;
+  supportsNonMaxMode?: boolean;
+  supportsImages?: boolean;
+  contextTokenLimit?: number;
+  contextTokenLimitForMaxMode?: number;
+  variants: CursorParameterizedVariant[];
+}
+
+function encodeVarint(value: number): number[] {
+  const out: number[] = [];
+  let v = value >>> 0;
+  while (v >= 0x80) {
+    out.push((v & 0x7f) | 0x80);
+    v >>>= 7;
+  }
+  out.push(v);
+  return out;
+}
+
+function encodeBoolField(fieldNo: number, value: boolean): number[] {
+  return [...encodeVarint(fieldNo << 3), value ? 1 : 0];
+}
+
+export function encodeAvailableModelsRequest(): Uint8Array {
+  // aiserver.v1.AvailableModelsRequest {
+  //   optional bool use_model_parameters = 5;
+  //   optional bool do_not_use_markdown = 7;
+  // }
+  return new Uint8Array([...encodeBoolField(5, true), ...encodeBoolField(7, true)]);
+}
+
+interface WireReader {
+  bytes: Uint8Array;
+  offset: number;
+}
+
+function readVarint(reader: WireReader): number {
+  let result = 0;
+  let shift = 0;
+  while (reader.offset < reader.bytes.length) {
+    const byte = reader.bytes[reader.offset++]!;
+    // Avoid JS bitwise operators here: they truncate to 32 bits, but protobuf
+    // varints can legally carry 64-bit values on fields we merely skip.
+    if (shift < 53) result += (byte & 0x7f) * 2 ** shift;
+    if ((byte & 0x80) === 0) return result;
+    shift += 7;
+    if (shift >= 70) throw new Error("varint too long");
+  }
+  throw new Error("unexpected EOF while reading varint");
+}
+
+function readLengthDelimited(reader: WireReader): Uint8Array {
+  const length = readVarint(reader);
+  if (!Number.isSafeInteger(length)) throw new Error("length-delimited size is too large");
+  const end = reader.offset + length;
+  if (end > reader.bytes.length) throw new Error("length-delimited field exceeds buffer");
+  const value = reader.bytes.subarray(reader.offset, end);
+  reader.offset = end;
+  return value;
+}
+
+function skipBytes(reader: WireReader, length: number): void {
+  const end = reader.offset + length;
+  if (end > reader.bytes.length) throw new Error("fixed-width field exceeds buffer");
+  reader.offset = end;
+}
+
+function skipWireField(reader: WireReader, wireType: number): void {
+  switch (wireType) {
+    case 0:
+      readVarint(reader);
+      return;
+    case 1:
+      skipBytes(reader, 8);
+      return;
+    case 2:
+      readLengthDelimited(reader);
+      return;
+    case 5:
+      skipBytes(reader, 4);
+      return;
+    default:
+      throw new Error(`unsupported wire type ${wireType}`);
+  }
+}
+
+function decodeString(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function decodeModelParameter(bytes: Uint8Array): CursorModelParameter {
+  const reader: WireReader = { bytes, offset: 0 };
+  const parameter: CursorModelParameter = { id: "", value: "" };
+  while (reader.offset < bytes.length) {
+    const tag = readVarint(reader);
+    const fieldNo = tag >>> 3;
+    const wireType = tag & 0x7;
+    if (fieldNo === 1 && wireType === 2) parameter.id = decodeString(readLengthDelimited(reader));
+    else if (fieldNo === 2 && wireType === 2)
+      parameter.value = decodeString(readLengthDelimited(reader));
+    else skipWireField(reader, wireType);
+  }
+  return parameter;
+}
+
+function decodeParameterizedVariant(bytes: Uint8Array): CursorParameterizedVariant {
+  const reader: WireReader = { bytes, offset: 0 };
+  const variant: CursorParameterizedVariant = { parameters: [], isMaxMode: false };
+  while (reader.offset < bytes.length) {
+    const tag = readVarint(reader);
+    const fieldNo = tag >>> 3;
+    const wireType = tag & 0x7;
+    if (fieldNo === 1 && wireType === 2)
+      variant.parameters.push(decodeModelParameter(readLengthDelimited(reader)));
+    else if (fieldNo === 2 && wireType === 2)
+      variant.displayName = decodeString(readLengthDelimited(reader));
+    else if (fieldNo === 8 && wireType === 2)
+      variant.displayNameOutsidePicker = decodeString(readLengthDelimited(reader));
+    else if (fieldNo === 3 && wireType === 0) variant.isMaxMode = readVarint(reader) !== 0;
+    else if (fieldNo === 4 && wireType === 0) variant.isDefaultMaxConfig = readVarint(reader) !== 0;
+    else if (fieldNo === 5 && wireType === 0)
+      variant.isDefaultNonMaxConfig = readVarint(reader) !== 0;
+    else if (fieldNo === 9 && wireType === 2)
+      variant.variantStringRepresentation = decodeString(readLengthDelimited(reader));
+    else skipWireField(reader, wireType);
+  }
+  return variant;
+}
+
+function decodeParameterizedModel(bytes: Uint8Array): CursorParameterizedModel {
+  const reader: WireReader = { bytes, offset: 0 };
+  const model: CursorParameterizedModel = { name: "", variants: [] };
+  while (reader.offset < bytes.length) {
+    const tag = readVarint(reader);
+    const fieldNo = tag >>> 3;
+    const wireType = tag & 0x7;
+    if (fieldNo === 1 && wireType === 2) model.name = decodeString(readLengthDelimited(reader));
+    else if (fieldNo === 10 && wireType === 0) model.supportsImages = readVarint(reader) !== 0;
+    else if (fieldNo === 14 && wireType === 0) model.supportsMaxMode = readVarint(reader) !== 0;
+    else if (fieldNo === 19 && wireType === 0) model.supportsNonMaxMode = readVarint(reader) !== 0;
+    else if (fieldNo === 15 && wireType === 0) model.contextTokenLimit = readVarint(reader);
+    else if (fieldNo === 16 && wireType === 0)
+      model.contextTokenLimitForMaxMode = readVarint(reader);
+    else if (fieldNo === 17 && wireType === 2)
+      model.clientDisplayName = decodeString(readLengthDelimited(reader));
+    else if (fieldNo === 18 && wireType === 2)
+      model.serverModelName = decodeString(readLengthDelimited(reader));
+    else if (fieldNo === 30 && wireType === 2)
+      model.variants.push(decodeParameterizedVariant(readLengthDelimited(reader)));
+    else skipWireField(reader, wireType);
+  }
+  return model;
+}
+
+export function decodeAvailableModelsResponse(bytes: Uint8Array): CursorParameterizedModel[] {
+  const reader: WireReader = { bytes, offset: 0 };
+  const models: CursorParameterizedModel[] = [];
+  while (reader.offset < bytes.length) {
+    const tag = readVarint(reader);
+    const fieldNo = tag >>> 3;
+    const wireType = tag & 0x7;
+    if (fieldNo === 2 && wireType === 2) {
+      const model = decodeParameterizedModel(readLengthDelimited(reader));
+      if (model.name) models.push(model);
+    } else {
+      skipWireField(reader, wireType);
+    }
+  }
+  return models;
+}
+
+// No generated schema for selectedContextBlob; emit raw wire format for the two
+// fields Cursor actually reads: field 1 (repeated bytes) rootPromptMessagesJson
+// refs, field 22 (string) clientName. Lengths are varint-encoded so this stays
+// correct even if a caller ever passes a value >=128 bytes.
+export function buildSelectedContextBlob(
+  rootPromptBlobIds: Uint8Array[],
+  clientName: string,
+): Uint8Array {
+  const parts: Uint8Array[] = [];
+  for (const blobId of rootPromptBlobIds) {
+    parts.push(new Uint8Array([0x0a, ...encodeVarint(blobId.length), ...blobId]));
+  }
+  const clientBytes = new TextEncoder().encode(clientName);
+  parts.push(new Uint8Array([0xb2, 0x01, ...encodeVarint(clientBytes.length), ...clientBytes]));
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    result.set(p, offset);
+    offset += p.length;
+  }
+  return result;
+}

package/src/client/h2-unary.ts

@@ -0,0 +1,142 @@
+/**
+ * Node-only in-process HTTP/2 transport for Cursor unary Connect RPCs.
+ *
+ * `fetch` is not an option: Cursor's agent hosts speak HTTP/2 and undici does
+ * not provide the required HTTP/2 client transport.
+ */
+import http2 from "node:http2";
+import { randomUUID } from "node:crypto";
+
+import { getCursorClientVersion } from "../config/index.js";
+
+const CURSOR_API_URL = "https://api2.cursor.sh";
+export const MAX_UNARY_RESPONSE_BYTES = 16 * 1024 * 1024;
+
+export interface UnaryH2Options {
+  accessToken: string;
+  rpcPath: string;
+  requestBody: Uint8Array;
+  url?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface UnaryH2Result {
+  status: number;
+  body: Buffer;
+}
+
+export class UnaryH2TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnaryH2TimeoutError";
+  }
+}
+
+/** Perform one unary Connect RPC over an in-process Node HTTP/2 session. */
+export function callUnaryOverH2(options: UnaryH2Options): Promise<UnaryH2Result> {
+  const origin = options.url ?? CURSOR_API_URL;
+  const timeoutMs = options.timeoutMs ?? 15_000;
+
+  return new Promise<UnaryH2Result>((resolve, reject) => {
+    let settled = false;
+    let session: http2.ClientHttp2Session | undefined;
+    let request: http2.ClientHttp2Stream | undefined;
+    let timer: NodeJS.Timeout | undefined;
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      try {
+        session?.close();
+      } catch {
+        // Session may already be torn down by the event that settled the RPC.
+      }
+    };
+
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      try {
+        request?.close(http2.constants.NGHTTP2_CANCEL);
+        session?.destroy();
+      } catch {
+        // Destruction is best effort; the session is abandoned either way.
+      }
+      reject(error);
+    };
+
+    const succeed = (result: UnaryH2Result) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    function onAbort() {
+      fail(new UnaryH2TimeoutError("Cursor unary RPC aborted"));
+    }
+
+    if (options.signal?.aborted) {
+      reject(new UnaryH2TimeoutError("Cursor unary RPC aborted"));
+      return;
+    }
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(
+        () => fail(new UnaryH2TimeoutError(`Cursor unary RPC timed out after ${timeoutMs}ms`)),
+        timeoutMs,
+      );
+      timer.unref?.();
+    }
+
+    try {
+      session = http2.connect(origin);
+    } catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)));
+      return;
+    }
+
+    session.on("error", (error) => fail(error));
+
+    try {
+      request = session.request({
+        ":method": "POST",
+        ":path": options.rpcPath,
+        "content-type": "application/proto",
+        "connect-protocol-version": "1",
+        te: "trailers",
+        authorization: `Bearer ${options.accessToken}`,
+        "x-ghost-mode": "true",
+        "x-cursor-client-version": getCursorClientVersion(),
+        "x-cursor-client-type": "cli",
+        "x-request-id": randomUUID(),
+      });
+    } catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)));
+      return;
+    }
+
+    const chunks: Buffer[] = [];
+    let responseBytes = 0;
+    let status = 0;
+
+    request.on("response", (headers) => {
+      status = Number(headers[":status"] ?? 0);
+    });
+    request.on("data", (chunk: Buffer) => {
+      responseBytes += chunk.byteLength;
+      if (responseBytes > MAX_UNARY_RESPONSE_BYTES) {
+        fail(new Error(`Cursor unary response exceeds ${MAX_UNARY_RESPONSE_BYTES} bytes`));
+        return;
+      }
+      chunks.push(Buffer.from(chunk));
+    });
+    request.on("error", (error) => fail(error));
+    request.on("end", () => succeed({ status, body: Buffer.concat(chunks) }));
+
+    request.end(Buffer.from(options.requestBody));
+  });
+}

package/src/client/index.ts

@@ -0,0 +1,18 @@
+export {
+  createBridge,
+  createConnectFrameParser,
+  frameConnectMessage,
+  parseConnectEndStream,
+  type BridgeHandle,
+  type BridgeFactory,
+  type CreateBridgeOptions,
+} from "./bridge.js";
+export {
+  encodeAvailableModelsRequest,
+  decodeAvailableModelsResponse,
+  buildSelectedContextBlob,
+  type CursorModelParameter,
+  type CursorParameterizedModel,
+  type CursorParameterizedVariant,
+} from "./cursor-wire.js";
+export { getCursorAgentUrl, getCursorClientVersion } from "../config/index.js";

package/src/config/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Cursor agent URL and client version resolution (env → CLI config → default).
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { assertSafeCursorBaseUrl } from "../utils/security.js";
+
+export const DEFAULT_CURSOR_AGENT_URL = "https://agentn.us.api5.cursor.sh";
+export const DEFAULT_CURSOR_CLIENT_VERSION = "cli-2026.05.01-eea359f";
+
+let cachedCursorAgentUrl: string | undefined;
+
+export function normalizeCursorUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+export function readCursorCliAgentUrl(): string | undefined {
+  const configDir = process.env.CURSOR_CONFIG_DIR?.trim() || pathJoin(homedir(), ".cursor");
+  try {
+    const config = JSON.parse(readFileSync(pathJoin(configDir, "cli-config.json"), "utf8")) as {
+      serverConfigCache?: {
+        agentUrlConfig?: { agentnUrl?: unknown; agentUrl?: unknown };
+      };
+    };
+    return (
+      normalizeCursorUrl(config.serverConfigCache?.agentUrlConfig?.agentnUrl) ??
+      normalizeCursorUrl(config.serverConfigCache?.agentUrlConfig?.agentUrl)
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function getCursorClientVersion(): string {
+  return process.env.PI_CURSOR_CLIENT_VERSION?.trim() || DEFAULT_CURSOR_CLIENT_VERSION;
+}
+
+/** Resolve the agent base URL, validating host against the allowlist. */
+export function getCursorAgentUrl(): string {
+  const envUrl =
+    normalizeCursorUrl(process.env.PI_CURSOR_AGENT_URL) ??
+    normalizeCursorUrl(process.env.CURSOR_AGENT_URL);
+  if (envUrl) {
+    cachedCursorAgentUrl = assertSafeCursorBaseUrl(envUrl);
+    return cachedCursorAgentUrl;
+  }
+  if (cachedCursorAgentUrl) return cachedCursorAgentUrl;
+  const resolved = readCursorCliAgentUrl() ?? DEFAULT_CURSOR_AGENT_URL;
+  cachedCursorAgentUrl = assertSafeCursorBaseUrl(resolved);
+  return cachedCursorAgentUrl;
+}
+
+/** Test helper: clear cached URL between cases. */
+export function resetCursorAgentUrlCacheForTests(): void {
+  cachedCursorAgentUrl = undefined;
+}

package/src/diagnostics/diagnostics.ts

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { redactSecrets } from "../utils/security.js";
+
+export type DiagnosticsSnapshot = {
+  status?: number;
+  endpoint?: string;
+  error?: string;
+  projectId?: string;
+  resolvedRuntimeModel?: string;
+  availableModels?: string;
+  matchedModelDebug?: string;
+  lastRpc?: string;
+  tokenSource?: string;
+  clientVersion?: string;
+  lastRecoverySkipReason?: string;
+  systemCredentials?: string;
+  /** ISO timestamp of the most recent stream idle timeout. */
+  lastIdleTimeoutAt?: string;
+  /** Configured idle timeout (ms) that fired. */
+  lastIdleTimeoutMs?: number;
+  /** Attempt number when the idle timeout fired. */
+  lastIdleAttempt?: number;
+  /** Short event name for the latest stream lifecycle signal. */
+  lastStreamEvent?: string;
+  /** Most recent wire-protocol drift observation (`kind:detail`). */
+  lastDriftSignal?: string;
+  /** Compact request-size breakdown from the latest stream start. */
+  lastRequestSize?: string;
+};
+
+const storage = new AsyncLocalStorage<DiagnosticsSnapshot>();
+let lastSnapshot: DiagnosticsSnapshot = {};
+
+function currentBag(): DiagnosticsSnapshot {
+  return storage.getStore() ?? lastSnapshot;
+}
+
+export async function runWithDiagnostics<T>(fn: () => Promise<T>): Promise<T> {
+  const bag: DiagnosticsSnapshot = {};
+  return storage.run(bag, async () => {
+    try {
+      return await fn();
+    } finally {
+      lastSnapshot = { ...bag };
+    }
+  });
+}
+
+export function getLastDiagnostics(): Readonly<DiagnosticsSnapshot> {
+  return lastSnapshot;
+}
+
+export function setLastStatus(status: number | undefined): void {
+  currentBag().status = status;
+}
+export function setLastEndpoint(endpoint: string | undefined): void {
+  currentBag().endpoint = endpoint;
+}
+export function setLastError(error: string | undefined): void {
+  currentBag().error = error === undefined ? undefined : redactSecrets(error).slice(0, 800);
+}
+export function setLastResolvedRuntimeModel(model: string | undefined): void {
+  currentBag().resolvedRuntimeModel = model;
+}
+export function setLastAvailableModels(models: string | undefined): void {
+  currentBag().availableModels = models;
+}
+export function setLastRpc(rpc: string | undefined): void {
+  currentBag().lastRpc = rpc;
+}
+export function setLastMatchedModelDebug(debug: string | undefined): void {
+  currentBag().matchedModelDebug =
+    debug === undefined ? undefined : redactSecrets(debug).slice(0, 1200);
+}
+export function setLastTokenSource(source: string | undefined): void {
+  currentBag().tokenSource = source;
+}
+export function setLastClientVersion(version: string | undefined): void {
+  currentBag().clientVersion = version;
+}
+export function setLastRecoverySkipReason(reason: string | undefined): void {
+  currentBag().lastRecoverySkipReason =
+    reason === undefined ? undefined : redactSecrets(reason).slice(0, 200);
+}
+export function setSystemCredentialsPolicy(policy: string | undefined): void {
+  currentBag().systemCredentials = policy;
+}
+export function setLastStreamEvent(event: string | undefined): void {
+  currentBag().lastStreamEvent =
+    event === undefined ? undefined : redactSecrets(event).slice(0, 200);
+}
+export function setLastDriftSignal(signal: string | undefined): void {
+  currentBag().lastDriftSignal =
+    signal === undefined ? undefined : redactSecrets(signal).slice(0, 200);
+}
+export function setLastRequestSize(summary: string | undefined): void {
+  currentBag().lastRequestSize =
+    summary === undefined ? undefined : redactSecrets(summary).slice(0, 400);
+}
+export function setLastIdleTimeout(info: {
+  timeoutMs: number;
+  attempt: number;
+  event?: string;
+}): void {
+  const bag = currentBag();
+  bag.lastIdleTimeoutAt = new Date().toISOString();
+  bag.lastIdleTimeoutMs = info.timeoutMs;
+  bag.lastIdleAttempt = info.attempt;
+  if (info.event) {
+    bag.lastStreamEvent = redactSecrets(info.event).slice(0, 200);
+  }
+}
+
+export function resetDiagnosticsForTests(): void {
+  lastSnapshot = {};
+}

package/src/diagnostics/index.ts

@@ -0,0 +1 @@
+export * from "./diagnostics.js";

package/src/extension/auth.ts

@@ -0,0 +1,99 @@
+/**
+ * Extension authentication and startup token resolution.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir, readStoredCredential } from "@earendil-works/pi-coding-agent";
+import {
+  getCursorAccessTokenFromEnv,
+  getTokenExpiry,
+  refreshCursorToken,
+  type CursorCredentials,
+} from "../auth/oauth.js";
+import { resolveSystemCursorAccessToken } from "../auth/cli-credentials.js";
+import { CredentialSource, ProviderConstant } from "../types/enums.js";
+
+export interface ResolvedAccessToken {
+  accessToken: string;
+  source: CredentialSource;
+}
+
+function isUsableAccessToken(token: string): boolean {
+  try {
+    return Date.now() < getTokenExpiry(token);
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort write of a rotated OAuth pair back into Pi's auth.json. */
+export function persistRefreshedPiOAuth(credentials: CursorCredentials): void {
+  try {
+    const authPath = join(getAgentDir(), "auth.json");
+    const parsed: unknown = JSON.parse(readFileSync(authPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    const data = parsed as Record<string, unknown>;
+    const existing = data[ProviderConstant.ProviderId];
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) return;
+    data[ProviderConstant.ProviderId] = {
+      ...(existing as Record<string, unknown>),
+      type: "oauth",
+      access: credentials.access,
+      refresh: credentials.refresh,
+      expires: credentials.expires,
+    };
+    writeFileSync(authPath, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  } catch {
+    // The process still has a usable access token; next launch may need /login.
+  }
+}
+
+export async function getStoredCursorOAuthAccessToken(options?: {
+  forceRefresh?: boolean;
+}): Promise<ResolvedAccessToken | undefined> {
+  const credential = readStoredCredential(ProviderConstant.ProviderId);
+  if (!credential || credential.type !== "oauth") return undefined;
+
+  if (!options?.forceRefresh && credential.access && Date.now() < credential.expires) {
+    return { accessToken: credential.access, source: CredentialSource.PiOAuth };
+  }
+
+  if (credential.refresh) {
+    try {
+      const refreshed = await refreshCursorToken(credential.refresh);
+      persistRefreshedPiOAuth(refreshed);
+      return { accessToken: refreshed.access, source: CredentialSource.PiOAuthRefresh };
+    } catch {
+      if (credential.access && Date.now() < credential.expires) {
+        return { accessToken: credential.access, source: CredentialSource.PiOAuth };
+      }
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+export async function getStartupCursorAccessToken(options?: {
+  forceRefresh?: boolean;
+}): Promise<ResolvedAccessToken | undefined> {
+  const envToken = getCursorAccessTokenFromEnv();
+  if (envToken && (!options?.forceRefresh || isUsableAccessToken(envToken))) {
+    return { accessToken: envToken, source: CredentialSource.Env };
+  }
+
+  // Explicit `/login cursor` must win over IDE/CLI harvest so the user is not
+  // silently billed to a different Cursor account.
+  const oauth = await getStoredCursorOAuthAccessToken(options);
+  if (oauth) return oauth;
+
+  return resolveSystemCursorAccessToken(options);
+}
+
+export function isTokenNearExpiry(token: string, skewMs = 60_000): boolean {
+  try {
+    return Date.now() >= getTokenExpiry(token) - skewMs;
+  } catch {
+    return true;
+  }
+}