@evanovation/open-cursor 2.4.15

package/src/usage.ts

@@ -0,0 +1,112 @@
+import type { StreamJsonResultEvent } from "./streaming/types.js";
+
+export type CursorUsageMetrics = {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  cost?: number;
+};
+
+export type OpenAiUsage = {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  prompt_tokens_details: {
+    cached_tokens: number;
+    cache_write_tokens: number;
+  };
+  completion_tokens_details: {
+    reasoning_tokens: number;
+  };
+  cost?: number;
+};
+
+function readTokenCount(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return Math.floor(value);
+}
+
+function readOptionalCost(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+  return value;
+}
+
+export function normalizeCursorUsage(value: unknown): CursorUsageMetrics | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+
+  const usage = value as Record<string, unknown>;
+  const metrics: CursorUsageMetrics = {
+    inputTokens: readTokenCount(usage.inputTokens ?? usage.input_tokens ?? usage.prompt_tokens),
+    outputTokens: readTokenCount(usage.outputTokens ?? usage.output_tokens ?? usage.completion_tokens),
+    reasoningTokens: readTokenCount(usage.reasoningTokens ?? usage.reasoning_tokens),
+    cacheReadTokens: readTokenCount(usage.cacheReadTokens ?? usage.cache_read_tokens),
+    cacheWriteTokens: readTokenCount(usage.cacheWriteTokens ?? usage.cache_write_tokens),
+  };
+
+  const cost = readOptionalCost(usage.cost ?? usage.totalCost ?? usage.total_cost);
+  if (cost !== undefined) {
+    metrics.cost = cost;
+  }
+
+  const hasUsage =
+    metrics.inputTokens > 0
+    || metrics.outputTokens > 0
+    || metrics.reasoningTokens > 0
+    || metrics.cacheReadTokens > 0
+    || metrics.cacheWriteTokens > 0
+    || cost !== undefined;
+
+  return hasUsage ? metrics : undefined;
+}
+
+export function createOpenAiUsage(metrics: CursorUsageMetrics): OpenAiUsage {
+  const promptTokens = metrics.inputTokens + metrics.cacheReadTokens + metrics.cacheWriteTokens;
+  const totalTokens = promptTokens + metrics.outputTokens + metrics.reasoningTokens;
+  const usage: OpenAiUsage = {
+    prompt_tokens: promptTokens,
+    completion_tokens: metrics.outputTokens,
+    total_tokens: totalTokens,
+    prompt_tokens_details: {
+      cached_tokens: metrics.cacheReadTokens,
+      cache_write_tokens: metrics.cacheWriteTokens,
+    },
+    completion_tokens_details: {
+      reasoning_tokens: metrics.reasoningTokens,
+    },
+  };
+
+  if (metrics.cost !== undefined) {
+    usage.cost = metrics.cost;
+  }
+
+  return usage;
+}
+
+export function extractOpenAiUsageFromResult(event: StreamJsonResultEvent): OpenAiUsage | undefined {
+  const metrics = normalizeCursorUsage(event.usage);
+  return metrics ? createOpenAiUsage(metrics) : undefined;
+}
+
+export function createChatCompletionUsageChunk(
+  id: string,
+  created: number,
+  model: string,
+  usage: OpenAiUsage,
+) {
+  return {
+    id,
+    object: "chat.completion.chunk",
+    created,
+    model,
+    choices: [],
+    usage,
+  };
+}

package/src/utils/binary.ts

@@ -0,0 +1,71 @@
+// src/utils/binary.ts
+//
+// Resolves the cursor-agent executable path. On Windows the binary is a `.cmd`
+// shim, which Node's spawn cannot execute directly without `shell: true` —
+// callers therefore pair this resolver with `shell: process.platform === "win32"`
+// and `formatShellCommandForPlatform()` at every Node spawn site. That re-enables
+// shell metacharacter interpretation, so any user-controlled string passed as an
+// argument on Windows must be treated as untrusted; never concatenate user input
+// into argv on win32.
+import { existsSync as fsExistsSync } from "fs";
+import * as pathModule from "path";
+import { homedir as osHomedir } from "os";
+import { createLogger } from "./logger.js";
+
+const log = createLogger("binary");
+
+export type BinaryDeps = {
+  platform?: NodeJS.Platform;
+  env?: Record<string, string | undefined>;
+  existsSync?: (path: string) => boolean;
+  homedir?: () => string;
+};
+
+export function resolveCursorAgentBinary(deps: BinaryDeps = {}): string {
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const checkExists = deps.existsSync ?? fsExistsSync;
+  const home = (deps.homedir ?? osHomedir)();
+
+  const envOverride = env.CURSOR_AGENT_EXECUTABLE;
+  if (envOverride && envOverride.length > 0) {
+    return envOverride;
+  }
+
+  if (platform === "win32") {
+    const pathJoin = pathModule.win32.join;
+    const localAppData = env.LOCALAPPDATA ?? pathJoin(home, "AppData", "Local");
+    const knownPath = pathJoin(localAppData, "cursor-agent", "cursor-agent.cmd");
+    if (checkExists(knownPath)) {
+      return knownPath;
+    }
+    log.warn("cursor-agent not found at known Windows path, falling back to PATH", { checkedPath: knownPath });
+    return "cursor-agent.cmd";
+  }
+
+  const knownPaths = [
+    pathModule.join(home, ".cursor-agent", "cursor-agent"),
+    "/usr/local/bin/cursor-agent",
+  ];
+  for (const p of knownPaths) {
+    if (checkExists(p)) {
+      return p;
+    }
+  }
+
+  log.warn("cursor-agent not found at known paths, falling back to PATH", { checkedPaths: knownPaths });
+  return "cursor-agent";
+}
+
+export function formatShellCommandForPlatform(
+  command: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (platform !== "win32") {
+    return command;
+  }
+  if (command.startsWith("\"") && command.endsWith("\"")) {
+    return command;
+  }
+  return `"${command}"`;
+}

package/src/utils/errors.ts

@@ -0,0 +1,224 @@
+// src/utils/errors.ts
+
+export type ErrorType = "quota" | "auth" | "network" | "model" | "unknown";
+
+export interface ParsedError {
+  type: ErrorType;
+  recoverable: boolean;
+  message: string;
+  userMessage: string;
+  details: Record<string, string>;
+  suggestion?: string;
+}
+
+/**
+ * Strip ANSI escape codes from string
+ */
+export function stripAnsi(str: string): string {
+  if (typeof str !== "string") return String(str ?? "");
+  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
+
+/**
+ * Parse cursor-agent error output into structured format
+ */
+export function parseAgentError(stderr: string | unknown): ParsedError {
+  const input = typeof stderr === "string" ? stderr : String(stderr ?? "");
+  const clean = stripAnsi(input).trim();
+
+  // Quota/usage limit error
+  if (clean.includes("usage limit") || clean.includes("hit your usage limit")) {
+    const savingsMatch = clean.match(/saved \$(\d+(?:\.\d+)?)/i);
+    const resetMatch = clean.match(/reset[^0-9]*(\d{1,2}\/\d{1,2}\/\d{4})/i);
+    const modelMatch = clean.match(/continue with (\w+)/i);
+
+    const details: Record<string, string> = {};
+    if (savingsMatch) details.savings = `$${savingsMatch[1]}`;
+    if (resetMatch) details.resetDate = resetMatch[1];
+    if (modelMatch) details.affectedModel = modelMatch[1];
+
+    return {
+      type: "quota",
+      recoverable: false,
+      message: clean,
+      userMessage: "You've hit your Cursor usage limit",
+      details,
+      suggestion: "Switch to a different model or set a Spend Limit in Cursor settings",
+    };
+  }
+
+  // Authentication error
+  if (clean.includes("not logged in") || clean.includes("auth") || clean.includes("unauthorized")) {
+    return {
+      type: "auth",
+      recoverable: false,
+      message: clean,
+      userMessage: "Not authenticated with Cursor",
+      details: {},
+      suggestion: "Run: opencode auth login → Other → cursor-acp, or: cursor-agent login",
+    };
+  }
+
+  // Network error
+  if (clean.includes("ECONNREFUSED") || clean.includes("network") || clean.includes("fetch failed")) {
+    return {
+      type: "network",
+      recoverable: true,
+      message: clean,
+      userMessage: "Connection to Cursor failed",
+      details: {},
+      suggestion: "Check your internet connection and try again",
+    };
+  }
+
+  // Model not found / not available
+  if (clean.includes("model not found") || clean.includes("invalid model") || clean.includes("Cannot use this model")) {
+    // Extract model name and available models from error
+    const modelMatch = clean.match(/Cannot use this model: ([^.]+)/);
+    const availableMatch = clean.match(/Available models: (.+)/);
+
+    const details: Record<string, string> = {};
+    if (modelMatch) details.requested = modelMatch[1];
+    if (availableMatch) details.available = availableMatch[1].split(", ").slice(0, 5).join(", ") + "...";
+
+    return {
+      type: "model",
+      recoverable: false,
+      message: clean,
+      userMessage: modelMatch ? `Model '${modelMatch[1]}' not available` : "Requested model not available",
+      details,
+      suggestion: "Use cursor-acp/auto or check available models with: cursor-agent models",
+    };
+  }
+
+  // Unknown error
+  const recoverable = clean.includes("timeout") || clean.includes("ETIMEDOUT");
+  return {
+    type: "unknown",
+    recoverable,
+    message: clean,
+    userMessage: clean.substring(0, 200) || "An error occurred",
+    details: {},
+  };
+}
+
+/**
+ * Check if an error is recoverable (worth retrying).
+ */
+export function isRecoverableError(error: ParsedError): boolean {
+  return error.recoverable;
+}
+
+/** Resume-specific failure signatures from cursor-agent stderr/stdout. */
+const RESUME_FAILURE_PATTERNS = [
+  /\bsession\s+(?:has\s+(?:been\s+)?|is\s+|was\s+)?(?:not\s+found|expired|deleted|missing|no\s+longer\s+exists)/i,
+  /\bchat\s+(?:has\s+(?:been\s+)?|is\s+|was\s+)?(?:not\s+found|expired|deleted|missing|no\s+longer\s+exists)/i,
+  /\bconversation\s+(?:has\s+(?:been\s+)?|is\s+|was\s+)?(?:not\s+found|expired|deleted|missing|no\s+longer\s+exists)/i,
+  /\bthread\s+(?:has\s+(?:been\s+)?|is\s+|was\s+)?(?:not\s+found|expired|deleted|missing|no\s+longer\s+exists)/i,
+  /\bresume\s+(?:failed|error|invalid|aborted)(?:\s+(?:session|chat|conversation|thread))?/i,
+  /\bfailed\s+to\s+resume(?:\s+(?:session|chat|conversation|thread))?/i,
+  /\bcould\s+not\s+resume(?:\s+(?:session|chat|conversation|thread))?/i,
+  /\bno\s+active\s+session/i,
+  /\bno\s+such\s+session/i,
+  /\bno\s+such\s+chat/i,
+  /\binvalid\s+(?:session|chat|conversation|thread)(?:\s+id)?/i,
+  /\b(?:session|chat|conversation|thread)\s+invalid(?:\s+id)?/i,
+  /\b(?:session|chat|conversation|thread)\s+id\s+(?:is\s+)?(?:invalid|not\s+found|expired|missing)/i,
+  /\b(?:session|chat|conversation|thread)\s+(?:isn['’]t|wasn['’]t)\s+found/i,
+  /\b(?:session|chat|conversation|thread)\s+(?:can(?:not|\s+not)|could\s+not)\s+(?:be\s+)?resumed/i,
+  /\bunable\s+to\s+resume\b/i,
+  /\bcan(?:not|\s+not)\s+resume\b/i,
+];
+
+/** Continuations that turn a session-gone phrase into an auth/validation/network error. */
+const TRANSIENT_CONTINUATION_PATTERN = /^\s*[:;]?\s*(?:token|credential|credentials|auth|secret|password|format|network|quota|usage|limit|api|key|request(?:_|-|\s+)?id?|due\s+to\s+(?:network|auth|quota)|because\s+of\s+(?:network|auth|quota)|caused\s+by\s+(?:network|auth|quota))/i;
+
+/** Words in a continuation clause that indicate a transient infrastructure failure. */
+const TRANSIENT_CAUSE_WORDS =
+  /\b(?:auth(?:enticat(?:e|ion|ed))?|re-auth(?:enticate)?|token(?:\s+rotation)?|credential|password|secret|network|connection|internet|offline|quota|usage(?:\s+limit)?|api[\s-]?key|fetch\s+failed|econnrefused|timeout|timed\s+out)\b/i;
+
+/** Session-specific causes that should still count as resume failures. */
+const SESSION_SPECIFIC_CAUSE_WORDS =
+  /\b(?:inactiv(?:ity|e)|idle|policy|retention|archiv(?:e|ed)|purged|deleted|removed|expired)\b/i;
+
+/**
+ * Decide whether a cursor-agent failure is specific to the resumed session.
+ * Transient errors (network, auth, OOM, signal kills) should not evict a
+ * valid chat ID; only failures that indicate the session itself is gone.
+ */
+function isTransientContinuation(tail: string): boolean {
+  const trimmed = tail.trim();
+  if (!trimmed) return false;
+
+  const stripped = trimmed.replace(/^[\s:;,.]+/, "");
+
+  const causalMatch = stripped.match(/^(?:because of|due to)\s+(.+)/i);
+  if (causalMatch) {
+    const cause = causalMatch[1];
+    // Session-specific causes (inactivity, retention, purged, etc.) take
+    // precedence over transient words that may appear in the same clause
+    // (e.g. "inactivity timeout"). If the cause is clearly about the
+    // session being gone, treat it as a resume-specific failure.
+    if (SESSION_SPECIFIC_CAUSE_WORDS.test(cause)) {
+      return false;
+    }
+    if (TRANSIENT_CAUSE_WORDS.test(cause)) {
+      return true;
+    }
+  }
+
+  const firstSegment = stripped.split(/[,;]/)[0]?.trim() ?? "";
+  if (firstSegment) {
+    if (SESSION_SPECIFIC_CAUSE_WORDS.test(firstSegment)) {
+      return false;
+    }
+    if (TRANSIENT_CAUSE_WORDS.test(firstSegment)) {
+      return true;
+    }
+  }
+
+  if (SESSION_SPECIFIC_CAUSE_WORDS.test(stripped)) {
+    return false;
+  }
+
+  if (TRANSIENT_CAUSE_WORDS.test(stripped)) {
+    return true;
+  }
+
+  return TRANSIENT_CONTINUATION_PATTERN.test(tail);
+}
+
+export function isResumeSpecificFailure(stderr: unknown): boolean {
+  const text = typeof stderr === "string" ? stderr : String(stderr ?? "");
+  const clean = stripAnsi(text);
+  for (const pattern of RESUME_FAILURE_PATTERNS) {
+    const match = clean.match(pattern);
+    if (!match) continue;
+    const tail = clean.slice(match.index! + match[0].length);
+    if (!isTransientContinuation(tail)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Format parsed error for user display
+ */
+export function formatErrorForUser(error: ParsedError): string {
+  let output = `cursor-acp error: ${error.userMessage || error.message || "Unknown error"}`;
+
+  const details = error.details || {};
+  if (Object.keys(details).length > 0) {
+    const detailParts = Object.entries(details)
+      .map(([k, v]) => `${k}: ${v}`)
+      .join(" | ");
+    output += `\n  ${detailParts}`;
+  }
+
+  if (error.suggestion) {
+    output += `\n  Suggestion: ${error.suggestion}`;
+  }
+
+  return output;
+}

package/src/utils/logger.ts

@@ -0,0 +1,191 @@
+// src/utils/logger.ts
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+
+const MAX_LOG_SIZE = 5 * 1024 * 1024;
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+function getConfiguredLevel(): LogLevel {
+  const env = process.env.CURSOR_ACP_LOG_LEVEL?.toLowerCase();
+  if (env && env in LEVEL_PRIORITY) {
+    return env as LogLevel;
+  }
+  return "info";
+}
+
+function isSilent(): boolean {
+  return process.env.CURSOR_ACP_LOG_SILENT === "1" ||
+         process.env.CURSOR_ACP_LOG_SILENT === "true";
+}
+
+function shouldLog(level: LogLevel): boolean {
+  if (isSilent()) return false;
+  const configured = getConfiguredLevel();
+  return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[configured];
+}
+
+function formatMessage(level: LogLevel, component: string, message: string, data?: unknown): string {
+  const prefix = `[cursor-acp:${component}]`;
+  const levelTag = level.toUpperCase().padEnd(5);
+
+  let formatted = `${prefix} ${levelTag} ${message}`;
+
+  if (data !== undefined) {
+    if (typeof data === "object") {
+      formatted += ` ${JSON.stringify(data)}`;
+    } else {
+      formatted += ` ${data}`;
+    }
+  }
+
+  return formatted;
+}
+
+function isConsoleEnabled(): boolean {
+  const consoleEnv = process.env.CURSOR_ACP_LOG_CONSOLE;
+  return consoleEnv === "1" || consoleEnv === "true";
+}
+
+let logDirEnsured = false;
+let logFileError = false;
+let logStream: fs.WriteStream | null = null;
+let logBytesWritten = 0;
+
+function getLogDir(): string {
+  const override = process.env.CURSOR_ACP_LOG_DIR?.trim();
+  return override || path.join(os.homedir(), ".opencode-cursor");
+}
+
+function getLogFile(): string {
+  return path.join(getLogDir(), "plugin.log");
+}
+
+/** Reset internal state (for testing only) */
+export function _resetLoggerState(): void {
+  logDirEnsured = false;
+  logFileError = false;
+  if (logStream) {
+    logStream.end();
+    logStream = null;
+  }
+  logBytesWritten = 0;
+}
+
+function ensureLogDir(): void {
+  if (logDirEnsured) return;
+  try {
+    const logDir = getLogDir();
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    logDirEnsured = true;
+  } catch {
+    logFileError = true;
+  }
+}
+
+function openLogStream(): void {
+  if (logStream || logFileError) return;
+  ensureLogDir();
+  if (logFileError) return;
+
+  try {
+    // Seed byte counter from existing file size
+    try {
+      logBytesWritten = fs.statSync(getLogFile()).size;
+    } catch {
+      logBytesWritten = 0;
+    }
+    logStream = fs.createWriteStream(getLogFile(), { flags: "a" });
+    logStream.on("error", () => {
+      if (!logFileError) {
+        logFileError = true;
+        console.error(`[cursor-acp] Failed to write logs. Using: ${getLogFile()}`);
+      }
+      logStream = null;
+    });
+  } catch {
+    logFileError = true;
+  }
+}
+
+function rotateIfNeeded(): void {
+  if (logBytesWritten < MAX_LOG_SIZE) return;
+  try {
+    if (logStream) {
+      logStream.end();
+      logStream = null;
+    }
+    const logFile = getLogFile();
+    fs.renameSync(logFile, logFile + ".1");
+    logBytesWritten = 0;
+    openLogStream();
+  } catch {
+    if (!logFileError && !logStream) {
+      openLogStream();
+    }
+  }
+}
+
+function writeToFile(message: string): void {
+  if (logFileError) return;
+
+  if (!logStream) openLogStream();
+  if (logFileError || !logStream) return;
+
+  rotateIfNeeded();
+  if (logFileError || !logStream) return;
+
+  const timestamp = new Date().toISOString();
+  const line = `${timestamp} ${message}\n`;
+  logStream.write(line);
+  logBytesWritten += Buffer.byteLength(line);
+}
+
+export interface Logger {
+  debug: (message: string, data?: unknown) => void;
+  info: (message: string, data?: unknown) => void;
+  warn: (message: string, data?: unknown) => void;
+  error: (message: string, data?: unknown) => void;
+  isDebugEnabled: () => boolean;
+}
+
+export function createLogger(component: string): Logger {
+  return {
+    isDebugEnabled: () => shouldLog("debug"),
+    debug: (message: string, data?: unknown) => {
+      if (!shouldLog("debug")) return;
+      const formatted = formatMessage("debug", component, message, data);
+      writeToFile(formatted);
+      if (isConsoleEnabled()) console.error(formatted);
+    },
+    info: (message: string, data?: unknown) => {
+      if (!shouldLog("info")) return;
+      const formatted = formatMessage("info", component, message, data);
+      writeToFile(formatted);
+      if (isConsoleEnabled()) console.error(formatted);
+    },
+    warn: (message: string, data?: unknown) => {
+      if (!shouldLog("warn")) return;
+      const formatted = formatMessage("warn", component, message, data);
+      writeToFile(formatted);
+      if (isConsoleEnabled()) console.error(formatted);
+    },
+    error: (message: string, data?: unknown) => {
+      if (!shouldLog("error")) return;
+      const formatted = formatMessage("error", component, message, data);
+      writeToFile(formatted);
+      if (isConsoleEnabled()) console.error(formatted);
+    },
+  };
+}

package/src/utils/perf.ts

@@ -0,0 +1,76 @@
+import { createLogger } from "./logger.js";
+
+const log = createLogger("perf");
+
+export interface PerfMarker {
+  name: string;
+  ts: number;
+}
+
+export interface PerfPhase {
+  name: string;
+  deltaMs: number;
+  atMs: number;
+}
+
+export interface PerfSummary {
+  requestId: string;
+  total: number;
+  phaseTotals: Record<string, number>;
+  timeline: PerfPhase[];
+}
+
+function isTimingLogEnabled(): boolean {
+  const value = process.env.CURSOR_ACP_TIMING?.toLowerCase();
+  return value === "1" || value === "true" || value === "on" || value === "yes";
+}
+
+export class RequestPerf {
+  private markers: PerfMarker[] = [];
+  private readonly requestId: string;
+
+  constructor(requestId: string) {
+    this.requestId = requestId;
+    this.mark("request:start");
+  }
+
+  mark(name: string): void {
+    this.markers.push({ name, ts: Date.now() });
+  }
+
+  /** Log timing summary. Call once at request end. */
+  summarize(): PerfSummary | undefined {
+    if (this.markers.length < 2) return undefined;
+    const start = this.markers[0].ts;
+    const phaseTotals: Record<string, number> = {};
+    const timeline: PerfPhase[] = [];
+    for (let i = 1; i < this.markers.length; i++) {
+      const marker = this.markers[i];
+      const deltaMs = marker.ts - this.markers[i - 1].ts;
+      phaseTotals[marker.name] = (phaseTotals[marker.name] ?? 0) + deltaMs;
+      timeline.push({
+        name: marker.name,
+        deltaMs,
+        atMs: marker.ts - start,
+      });
+    }
+    const total = this.markers[this.markers.length - 1].ts - start;
+    const summary: PerfSummary = { requestId: this.requestId, total, phaseTotals, timeline };
+    if (isTimingLogEnabled()) {
+      log.info("Request timing", summary);
+    } else {
+      log.debug("Request timing", summary);
+    }
+    return summary;
+  }
+
+  /** Get elapsed ms since construction. */
+  elapsed(): number {
+    return this.markers.length > 0 ? Date.now() - this.markers[0].ts : 0;
+  }
+
+  /** Get all markers (for testing). */
+  getMarkers(): ReadonlyArray<PerfMarker> {
+    return this.markers;
+  }
+}