pi-cursor-sdk 0.5.0 → 0.5.3

package/dist/model-discovery.js

@@ -1,7 +1,7 @@
 import { getCursorModelSelectionIdentities } from "../shared/cursor-model-selection-identities.mjs";
 import { loadContextWindowCache } from "./context-window-cache.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
-import { resolveCursorApiKey, resolveCursorRuntimeApiKey } from "./cursor-api-key.js";
+import { normalizeCursorApiKey } from "./cursor-api-key.js";
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 import { fingerprintApiKey, loadAnyCachedModelCatalog, loadFreshCachedModels, saveModelListCache, } from "./model-list-cache.js";
 const FALLBACK_CONTEXT_WINDOW = 128000;
@@ -10,9 +10,6 @@ const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 const TEXT_AND_IMAGE_INPUT = ["text", "image"];
 const AUTH_SETUP_HINT = "/login (Use an API key -> Cursor) or CURSOR_API_KEY; startup discovery does not parse Pi CLI arguments, and Cursor Agent CLI/Desktop login is not reused";
 const CATALOG_REFRESH_HINT = "After adding auth to an already-started pi session, run /cursor-refresh-models to refresh the full live Cursor model catalog without restarting pi.";
-async function getDiscoveryApiKey(apiKey) {
-    return resolveCursorApiKey(apiKey) ?? resolveCursorRuntimeApiKey();
-}
 const metadataByPiModelId = new Map();
 function cloneParams(params) {
     return params.map((param) => ({ ...param }));
@@ -44,9 +41,9 @@ function mapComparableLevel(parameter, level) {
 }
 function getThinkingLevelMap(item) {
     const reasoningParameter = getParameter(item, "reasoning");
-    const effortParameter = getParameter(item, "effort");
+    const effortParameter = getParameter(item, "effort") ?? getParameter(item, "reasoning_effort");
     const thinkingParameter = getParameter(item, "thinking");
-    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter ?? getParameter(item, "reasoning_effort");
+    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter;
     if (!valueParameter)
         return undefined;
     if (valueParameter.id === "thinking" && hasBooleanValues(valueParameter)) {
@@ -135,6 +132,7 @@ function toMetadata(item, piModelId, selectionModelId, defaultParams, context, c
         selectionModelId,
         displayName: item.displayName || item.id,
         defaultParams: cloneParams(defaultParams),
+        catalogDefaultContext: getParamValue(getDefaultParams(item), "context"),
         ...(context ? { context } : {}),
         contextWindow: getContextWindow(contextWindowCache, contextWindowKeys, context, item.id),
         supportsFast: getParameter(item, "fast") !== undefined,
@@ -164,15 +162,15 @@ function toModelConfig(metadata, name) {
         maxTokens: FALLBACK_MAX_TOKENS,
     };
 }
-function registerModelItems(items) {
-    metadataByPiModelId.clear();
+function registerModelItems(items, metadataMap = metadataByPiModelId) {
+    metadataMap.clear();
     const contextWindowCache = loadContextWindowCache();
     return getCursorModelSelectionIdentities(items).map(({ model: item, selectionModelId, context, fastOverride, piModelId, contextWindowKey, baseContextWindowKey }) => {
         const defaultParams = getDefaultParams(item);
         const contextParams = context ? replaceParam(defaultParams, "context", context) : defaultParams;
         const params = fastOverride === undefined ? contextParams : replaceParam(contextParams, "fast", fastOverride ? "true" : "false");
         const metadata = toMetadata(item, piModelId, selectionModelId, params, context, contextWindowCache, [piModelId, contextWindowKey, baseContextWindowKey], fastOverride);
-        metadataByPiModelId.set(piModelId, metadata);
+        metadataMap.set(piModelId, metadata);
         const alias = selectionModelId === item.id ? undefined : selectionModelId;
         return toModelConfig(metadata, getModelName(item, context, alias, fastOverride));
     });
@@ -198,10 +196,12 @@ function applyThinkingLevel(metadata, params, level) {
     const mapped = metadata.thinkingLevelMap?.[level];
     if (mapped === undefined || mapped === null)
         return;
+    const effortId = metadata.parameterIds.effort ? "effort" : metadata.parameterIds.reasoning_effort ? "reasoning_effort" : undefined;
     if (level === "off") {
         if (metadata.parameterIds.thinking && mapped === "false") {
             setParam(params, "thinking", mapped);
-            deleteParam(params, "effort");
+            if (effortId)
+                deleteParam(params, effortId);
             return;
         }
         if (metadata.parameterIds.reasoning) {
@@ -209,10 +209,10 @@ function applyThinkingLevel(metadata, params, level) {
         }
         return;
     }
-    if (metadata.parameterIds.effort) {
+    if (effortId) {
         if (metadata.parameterIds.thinking)
             setParam(params, "thinking", "true");
-        setParam(params, "effort", mapped);
+        setParam(params, effortId, mapped);
         return;
     }
     if (metadata.parameterIds.reasoning) {
@@ -222,9 +222,6 @@ function applyThinkingLevel(metadata, params, level) {
     if (metadata.parameterIds.thinking) {
         setParam(params, "thinking", mapped);
     }
-    else if (metadata.parameterIds.reasoning_effort) {
-        setParam(params, "reasoning_effort", mapped);
-    }
 }
 export function buildCursorModelSelection(modelId, thinkingLevel, fastEnabled) {
     const metadata = getCursorModelMetadata(modelId);
@@ -235,15 +232,40 @@ export function buildCursorModelSelection(modelId, thinkingLevel, fastEnabled) {
     if (metadata.supportsFast && fastEnabled !== undefined) {
         setParam(params, "fast", fastEnabled ? "true" : "false");
     }
+    // Grok 4.7 rejects its explicit catalog-default context. Keep the selected
+    // variant's metadata intact and leave effort, fast and other contexts explicit.
+    if (metadata.baseModelId === "grok-4.7" && metadata.catalogDefaultContext !== undefined &&
+        getParamValue(params, "context") === metadata.catalogDefaultContext) {
+        deleteParam(params, "context");
+    }
     return params.length > 0 ? { id: metadata.selectionModelId, params } : { id: metadata.selectionModelId };
 }
 async function useFallbackModels(options, issue) {
-    options.onFallback?.(issue);
     const { FALLBACK_MODEL_ITEMS } = await import("./cursor-fallback-models.generated.js");
-    return registerModelItems(FALLBACK_MODEL_ITEMS);
+    return publishModelItems(FALLBACK_MODEL_ITEMS, options, issue);
+}
+async function publishModelItems(items, options, issue, cacheFingerprint) {
+    options.signal?.throwIfAborted();
+    const metadata = new Map();
+    const models = registerModelItems(items, metadata);
+    const update = () => {
+        metadataByPiModelId.clear();
+        for (const [id, value] of metadata)
+            metadataByPiModelId.set(id, value);
+        if (cacheFingerprint)
+            saveModelListCache(cacheFingerprint, items);
+        if (issue)
+            options.onFallback?.(issue);
+    };
+    if (options.publish)
+        await options.publish(models, update);
+    else
+        update();
+    return models;
 }
 export async function discoverModels(options = {}) {
-    const apiKey = await getDiscoveryApiKey(options.apiKey);
+    options.signal?.throwIfAborted();
+    const apiKey = normalizeCursorApiKey(options.apiKey);
     if (!apiKey) {
         return useFallbackModels(options, {
             reason: "missing-api-key",
@@ -251,18 +273,29 @@ export async function discoverModels(options = {}) {
         });
     }
     const keyFingerprint = fingerprintApiKey(apiKey);
-    if (!options.forceRefresh) {
-        const cachedModels = loadFreshCachedModels(keyFingerprint);
+    if (!options.forceRefresh || options.allowNetwork === false) {
+        const cachedModels = options.allowNetwork === false
+            ? loadAnyCachedModelCatalog(keyFingerprint)?.models
+            : loadFreshCachedModels(keyFingerprint);
         if (cachedModels && cachedModels.length > 0) {
-            return registerModelItems(cachedModels);
+            return publishModelItems(cachedModels, options);
         }
     }
+    if (options.allowNetwork === false) {
+        return useFallbackModels(options, {
+            reason: "cache-only",
+            message: `Using fallback Cursor models until a live catalog is requested. ${CATALOG_REFRESH_HINT}`,
+        });
+    }
     try {
         const { Cursor } = await loadCursorSdk();
+        options.signal?.throwIfAborted();
+        // SDK 1.0.37 CursorRequestOptions has no caller signal. A late response
+        // still cannot publish outside the native generation that requested it.
         const models = await Cursor.models.list({ apiKey });
+        options.signal?.throwIfAborted();
         if (models.length > 0) {
-            saveModelListCache(keyFingerprint, models);
-            return registerModelItems(models);
+            return publishModelItems(models, options, undefined, keyFingerprint);
         }
         return useFallbackModels(options, {
             reason: "empty-model-list",
@@ -270,18 +303,18 @@ export async function discoverModels(options = {}) {
         });
     }
     catch (error) {
+        options.signal?.throwIfAborted();
         const errorMessage = sanitizeCursorProviderError(error, apiKey);
         // Prefer a previously cached catalog over the generic bundled fallback when
         // a live refresh fails (e.g. transient network/auth errors), but keep the
         // provenance visible so refresh commands do not claim a live refresh worked.
         const cachedCatalog = loadAnyCachedModelCatalog(keyFingerprint);
         if (cachedCatalog && cachedCatalog.models.length > 0) {
-            options.onFallback?.({
+            return publishModelItems(cachedCatalog.models, options, {
                 reason: "cached-after-error",
                 message: `Cursor model discovery failed; using cached Cursor model catalog from ${new Date(cachedCatalog.fetchedAt).toISOString()}. ${errorMessage}`,
                 errorMessage,
             });
-            return registerModelItems(cachedCatalog.models);
         }
         return useFallbackModels(options, {
             reason: "discovery-failed",
@@ -293,5 +326,4 @@ export async function discoverModels(options = {}) {
 export const __testUtils = {
     parseContextWindow,
     registerModelItems,
-    normalizeApiKey: resolveCursorApiKey,
 };

package/dist/model-list-cache.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
@@ -148,6 +148,17 @@ export function saveModelListCache(keyFingerprint, models) {
         return false;
     }
 }
+/** Delete only our valid regular-file catalog, never a user link or other data. */
+export function clearModelListCache() {
+    try {
+        const path = getCachePath();
+        if (lstatSync(path).isFile() && readCacheFile())
+            unlinkSync(path);
+    }
+    catch {
+        // Cache cleanup is best-effort; it must not break native logout.
+    }
+}
 export const __testUtils = {
     getCachePath,
     DEFAULT_TTL_MS,

package/docs/cursor-live-smoke-checklist.md

@@ -71,7 +71,7 @@ Pass criteria:
 
 - `node --version` reports Node 24+.
 - `pi --version` reports official Pi 0.87.1 or the selected official-latest/current-`fitchmultz/pi` compatibility target.
-- `npm ls` shows exact `@cursor/sdk@1.0.32`; development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 0.99.1 and host TypeBox 1.3.27; and the bundled bridge runtime closure `@modelcontextprotocol/server@2.1.0`, `@modelcontextprotocol/hono@2.0.1`, `hono@4.13.9`, and `@hono/node-server@2.1.1`.
+- `npm ls` shows exact `@cursor/sdk@1.0.37`; development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 1.0.4 with matching lockfile-resolved transitives, nested host TypeBox 1.3.27 and root validation TypeBox 1.3.36; and the bundled bridge runtime closure `@modelcontextprotocol/server@2.3.1`, `@modelcontextprotocol/hono@2.0.2`, `hono@4.13.13`, and `@hono/node-server@2.1.3`. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run.
 - `cursor/grok-4.6` appears in the model list.
 - No Cursor key or auth token is printed.
 - If neither `~/.pi/agent/auth.json` cursor auth nor `CURSOR_API_KEY` is available, stop and report the live smoke as blocked.
@@ -136,7 +136,7 @@ Pass criteria:
 
 ## 4. Focused visual card/color rendering check
 
-This is a visual debug menu for changed card/color behavior requiring new live evidence. Select only the relevant category below, or reuse a batched existing platform suite; do not execute the entire list by default. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Node 24+, official Pi 0.87.1 or another current compatibility target, exact `@cursor/sdk@1.0.32`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
+This is a visual debug menu for changed card/color behavior requiring new live evidence. Select only the relevant category below, or reuse a batched existing platform suite; do not execute the entire list by default. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Node 24+, official Pi 0.87.1 or another current compatibility target, exact `@cursor/sdk@1.0.37`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
 
 ```bash
 VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1016-visual.XXXXXX)"