pi-cursor-sdk 0.5.0 → 0.5.2

package/dist/cursor-state.js

@@ -3,6 +3,7 @@ import { runCursorSessionAgentCleanupCommand } from "./cursor-session-agent-clea
 import { CURSOR_HTTP1_ENTRY_TYPE, getStoredCursorHttp1Enabled, isCursorHttp1EntryData, setCursorHttp1GlobalPreferenceAuthoritative, setStoredCursorHttp1Enabled, } from "./cursor-http1.js";
 import { buildCursorPiToolBridgeSnapshot, CURSOR_PI_TOOL_BRIDGE_ENV, resolveCursorPiToolBridgeEnabled, } from "./cursor-pi-tool-bridge-snapshot.js";
 import { CURSOR_SETTING_SOURCES_ENV, DEFAULT_CURSOR_SETTING_SOURCES, resolveCursorSettingSources, } from "./cursor-setting-sources.js";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
 import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
 import { asRecord } from "./cursor-record-utils.js";
@@ -10,9 +11,10 @@ import { getCursorSessionScopeSnapshot, getCursorSessionScopeKey } from "./curso
 import { cursorSettingsScopeForContext, getCursorSessionSettings, registerCursorSessionSettings, resetCursorSessionSettingsForTests } from "./cursor-session-settings.js";
 import { refreshSessionCursorAgentConfig } from "./cursor-session-agent.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
-import { cursorFastDefaultsFromConfig, getCursorSdkUserConfigPath, loadCursorSdkUserConfig, mergeCursorSdkConfigForUpdate, resolveCursorFastDefault, updateCursorSdkConfig, } from "./cursor-config.js";
+import { cursorFastDefaultsFromConfig, getCursorSdkUserConfigPath, loadCursorSdkUserConfig, mergeCursorSdkConfigForUpdate, resolveCursorFastDefault, resolveCursorLocalStoreRoot, updateCursorSdkConfig, } from "./cursor-config.js";
 import { CURSOR_RUNTIME_ENTRY_TYPE, formatCursorStatus, registerCursorCloudRuntimeControls, resetCursorRuntimeStateForTests, resolveCursorStatusRuntime, restoreCursorCliState, restoreSessionCursorRuntimeState, } from "./cursor-runtime-state.js";
 export { consumeCursorLocalForceOverride, getCursorCliConfig, getCursorSessionConfig, } from "./cursor-runtime-state.js";
+export const CURSOR_FOOTER_ENV = "PI_CURSOR_FOOTER";
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const MODE_ENTRY_TYPE = "cursor-mode-state";
 const DEFAULT_CURSOR_AGENT_MODE = "agent";
@@ -152,7 +154,7 @@ export function getCursorProviderAgentModeOrThrow(scopeKey) {
     return resolution.mode;
 }
 function updateCursorStatus(ctx, model = ctx.model) {
-    if (!model || !isCursorModel(model)) {
+    if (!model || !isCursorModel(model) || !parseEnvBoolean(process.env[CURSOR_FOOTER_ENV], true)) {
         ctx.ui.setStatus("cursor", undefined);
         return;
     }
@@ -413,7 +415,8 @@ export function registerCursorRuntimeControls(pi) {
     pi.registerCommand("cursor-local-resume-cleanup", {
         description: "Dry-run or delete recorded superseded local Cursor SDK agents",
         handler: async (args, ctx) => {
-            await runCursorSessionAgentCleanupCommand(pi, args, ctx);
+            const storeRoot = resolveCursorLocalStoreRoot({ user: loadCursorSdkUserConfig() }).value;
+            await runCursorSessionAgentCleanupCommand(pi, args, ctx, storeRoot);
         },
     });
     pi.registerCommand("cursor-refresh-config", {

package/dist/cursor-tool-manifest.js

@@ -1,7 +1,7 @@
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
 /**
- * Representative @cursor/sdk@1.0.32 local-agent ToolType values; actual exposure can vary by run.
+ * Representative Cursor SDK local-agent ToolType values; actual exposure can vary by run.
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY = "read/shell/search/edit/write and other host tools when Cursor exposes them";

package/dist/index.js

@@ -9,7 +9,7 @@ import { getCursorSessionScopeSnapshot, registerCursorSessionScope } from "./cur
 import { registerCursorSessionAgentLifecycle } from "./cursor-session-agent-lifecycle.js";
 import { registerCursorSessionAgentLineage } from "./cursor-session-agent-lineage.js";
 import { registerCursorSessionAgentResume } from "./cursor-session-agent-resume.js";
-import { resolveCursorApiKey } from "./cursor-api-key.js";
+import { normalizeCursorApiKey } from "./cursor-api-key.js";
 import { registerCursorFallbackIssueWarning } from "./cursor-fallback-warning.js";
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context-registration.js";
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
@@ -22,7 +22,9 @@ export default async function (pi) {
     registerCursorSessionScope(pi);
     registerCursorUsageLedger(pi);
     registerCursorUsageCommand(pi);
+    let fallbackIssue;
     const registerCursorProvider = registerCursorProviderBinding(pi);
+    const setFallbackWarning = registerCursorFallbackIssueWarning(pi);
     registerCursorSessionAgentLineage(pi);
     registerCursorSessionAgentLifecycle(pi);
     registerCursorSessionAgentResume(pi);
@@ -36,39 +38,39 @@ export default async function (pi) {
     registerCursorPiToolBridge(pi);
     registerCursorAgentsContextDedup(pi);
     registerCursorOverflowNormalization(pi);
-    let fallbackIssue;
     const models = await discoverModels({
+        apiKey: normalizeCursorApiKey(process.env.CURSOR_API_KEY),
+        allowNetwork: false,
         onFallback: (issue) => {
             fallbackIssue = issue;
         },
     });
-    if (fallbackIssue) {
-        registerCursorFallbackIssueWarning(pi, fallbackIssue);
-    }
+    setFallbackWarning(fallbackIssue);
     pi.registerCommand("cursor-refresh-models", {
         description: "Refresh the live Cursor model catalog without restarting pi",
         handler: async (_args, ctx) => {
-            let refreshFallbackIssue;
-            const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
-            const refreshedModels = await discoverModels({
-                apiKey,
-                forceRefresh: true,
-                onFallback: (issue) => {
-                    refreshFallbackIssue = issue;
-                },
-            });
-            registerCursorProvider(refreshedModels);
+            const result = await ctx.modelRegistry.refresh({ providers: ["cursor"], allowNetwork: true, force: true, signal: ctx.signal });
             if (!ctx.hasUI)
                 return;
-            if (refreshFallbackIssue) {
-                ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
+            if (result.aborted) {
+                ctx.ui.notify("Cursor model catalog refresh was cancelled.", "warning");
+            }
+            else if (result.errors.has("cursor")) {
+                ctx.ui.notify("Cursor model catalog refresh failed; the previous catalog was retained.", "warning");
+            }
+            else if (fallbackIssue) {
+                ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${fallbackIssue.message}`, "warning");
             }
             else {
-                ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
+                const count = ctx.modelRegistry.getAll().filter((model) => model.provider === "cursor").length;
+                ctx.ui.notify(`Cursor model catalog refreshed with ${count} model${count === 1 ? "" : "s"}.`, "info");
             }
         },
     });
-    registerCursorProvider(models);
+    registerCursorProvider(models, (issue) => {
+        fallbackIssue = issue;
+        setFallbackWarning(issue);
+    });
     // Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
     registerCursorSdkSessionProcessErrorGuard(pi);
 }

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 }));
@@ -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));
     });
@@ -235,15 +233,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 +274,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.36 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 +304,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 +327,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.36`; 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.36`, 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)"