pi-cursor-sdk 0.2.0 → 0.3.7

package/dist/index.js

@@ -0,0 +1,82 @@
+import { discoverModels } from "./model-discovery.js";
+import { registerCursorRuntimeControls } from "./cursor-state.js";
+import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-registration.js";
+import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import { registerCursorQuestionTool } from "./cursor-question-tool.js";
+import { registerCursorSkillTool } from "./cursor-skill-tool.js";
+import { registerCursorSessionScope } from "./cursor-session-scope.js";
+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 { streamCursorLazy } from "./cursor-provider-lazy.js";
+import { CURSOR_API_KEY_CONFIG_VALUE, resolveCursorApiKey } 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";
+import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
+import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
+function createCursorProviderConfig(models) {
+    return {
+        name: "Cursor",
+        baseUrl: "https://cursor.com",
+        apiKey: CURSOR_API_KEY_CONFIG_VALUE,
+        api: "cursor-sdk",
+        models,
+        streamSimple: streamCursorLazy,
+    };
+}
+function registerCursorProvider(pi, models) {
+    pi.registerProvider("cursor", createCursorProviderConfig(models));
+}
+export default async function (pi) {
+    // Session cwd must register before other session_start listeners that depend on it.
+    registerCursorSessionScope(pi);
+    registerCursorSessionAgentLineage(pi);
+    registerCursorSessionAgentLifecycle(pi);
+    registerCursorSessionAgentResume(pi);
+    pi.on("session_before_compact", async () => {
+        await prepareCursorSessionForCompaction();
+    });
+    registerCursorRuntimeControls(pi);
+    registerCursorNativeToolDisplay(pi);
+    registerCursorQuestionTool(pi);
+    registerCursorSkillTool(pi);
+    registerCursorPiToolBridge(pi);
+    registerCursorAgentsContextDedup(pi);
+    registerCursorOverflowNormalization(pi);
+    let fallbackIssue;
+    const models = await discoverModels({
+        onFallback: (issue) => {
+            fallbackIssue = issue;
+        },
+    });
+    if (fallbackIssue) {
+        registerCursorFallbackIssueWarning(pi, 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(pi, refreshedModels);
+            if (!ctx.hasUI)
+                return;
+            if (refreshFallbackIssue) {
+                ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
+            }
+            else {
+                ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
+            }
+        },
+    });
+    registerCursorProvider(pi, models);
+    // Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
+    registerCursorSdkSessionProcessErrorGuard(pi);
+}

package/dist/model-discovery.js

@@ -0,0 +1,305 @@
+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 { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import { fingerprintApiKey, loadAnyCachedModelCatalog, loadFreshCachedModels, saveModelListCache, } from "./model-list-cache.js";
+const FALLBACK_CONTEXT_WINDOW = 128000;
+const FALLBACK_MAX_TOKENS = 16384;
+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 }));
+}
+function getParameter(item, id) {
+    return item.parameters?.find((parameter) => parameter.id === id);
+}
+function hasBooleanValues(parameter) {
+    const values = new Set((parameter?.values ?? []).map((value) => value.value.toLowerCase()));
+    return values.has("false") && values.has("true");
+}
+function getParameterValue(parameter, lowerValue) {
+    const value = parameter?.values.find((candidate) => candidate.value.toLowerCase() === lowerValue);
+    return value?.value ?? null;
+}
+function getPreferredParameterValue(parameter, lowerValues) {
+    for (const value of lowerValues) {
+        const candidate = getParameterValue(parameter, value);
+        if (candidate)
+            return candidate;
+    }
+    return null;
+}
+function mapComparableLevel(parameter, level) {
+    if (level === "xhigh") {
+        return getPreferredParameterValue(parameter, ["xhigh", "extra-high"]);
+    }
+    return getParameterValue(parameter, level);
+}
+function getThinkingLevelMap(item) {
+    const reasoningParameter = getParameter(item, "reasoning");
+    const effortParameter = getParameter(item, "effort");
+    const thinkingParameter = getParameter(item, "thinking");
+    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter;
+    if (!valueParameter)
+        return undefined;
+    if (valueParameter.id === "thinking" && hasBooleanValues(valueParameter)) {
+        return {
+            off: getParameterValue(valueParameter, "false"),
+            minimal: null,
+            low: null,
+            medium: null,
+            high: getParameterValue(valueParameter, "true"),
+            xhigh: null,
+            max: null,
+        };
+    }
+    return {
+        off: getParameterValue(reasoningParameter, "none") ??
+            getParameterValue(reasoningParameter, "off") ??
+            getParameterValue(thinkingParameter, "false"),
+        minimal: mapComparableLevel(valueParameter, "minimal"),
+        low: mapComparableLevel(valueParameter, "low"),
+        medium: mapComparableLevel(valueParameter, "medium"),
+        high: mapComparableLevel(valueParameter, "high"),
+        xhigh: mapComparableLevel(valueParameter, "xhigh"),
+        max: mapComparableLevel(valueParameter, "max"),
+    };
+}
+function parseContextWindow(value) {
+    const match = /^(\d+(?:\.\d+)?)([km])$/i.exec(value.trim());
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    const unit = match[2]?.toLowerCase();
+    if (!Number.isFinite(amount))
+        return undefined;
+    return Math.round(amount * (unit === "m" ? 1000000 : 1000));
+}
+function getDefaultParams(item) {
+    if (!item.variants?.length)
+        return [];
+    const defaultVariant = item.variants.find((variant) => variant.isDefault) ?? item.variants[0];
+    return cloneParams(defaultVariant?.params ?? []);
+}
+function replaceParam(params, id, value) {
+    let replaced = false;
+    const next = params.map((param) => {
+        if (param.id !== id)
+            return { ...param };
+        replaced = true;
+        return { id, value };
+    });
+    if (!replaced)
+        next.push({ id, value });
+    return next;
+}
+function getParamValue(params, id) {
+    return params.find((param) => param.id === id)?.value;
+}
+function getModelName(item, context, alias, fastOverride) {
+    const displayName = item.displayName || item.id;
+    const qualifiers = [];
+    if (alias)
+        qualifiers.push(alias);
+    if (fastOverride === true)
+        qualifiers.push("fast");
+    if (fastOverride === false)
+        qualifiers.push("slow");
+    const baseName = qualifiers.length > 0 ? `${displayName} (${qualifiers.join(", ")})` : displayName;
+    return context ? `${baseName} @ ${context}` : baseName;
+}
+function getContextWindow(contextWindowCache, selectionKeys, context, baseModelId) {
+    for (const key of new Set(selectionKeys)) {
+        const contextWindow = contextWindowCache.get(key);
+        if (contextWindow !== undefined)
+            return contextWindow;
+    }
+    return ((context ? parseContextWindow(context) : undefined) ??
+        (baseModelId ? contextWindowCache.get(baseModelId) : undefined) ??
+        contextWindowCache.get("default") ??
+        FALLBACK_CONTEXT_WINDOW);
+}
+function toMetadata(item, piModelId, selectionModelId, defaultParams, context, contextWindowCache, contextWindowKeys, fastOverride) {
+    const thinkingLevelMap = getThinkingLevelMap(item);
+    const fastValue = getParamValue(defaultParams, "fast")?.toLowerCase();
+    return {
+        piModelId,
+        baseModelId: item.id,
+        selectionModelId,
+        displayName: item.displayName || item.id,
+        defaultParams: cloneParams(defaultParams),
+        ...(context ? { context } : {}),
+        contextWindow: getContextWindow(contextWindowCache, contextWindowKeys, context, item.id),
+        supportsFast: getParameter(item, "fast") !== undefined,
+        defaultFast: fastValue === "true",
+        ...(fastOverride !== undefined ? { fastOverride } : {}),
+        supportsReasoning: thinkingLevelMap !== undefined,
+        ...(thinkingLevelMap ? { thinkingLevelMap } : {}),
+        parameterIds: {
+            context: getParameter(item, "context") !== undefined,
+            reasoning: getParameter(item, "reasoning") !== undefined,
+            effort: getParameter(item, "effort") !== undefined,
+            thinking: getParameter(item, "thinking") !== undefined,
+            fast: getParameter(item, "fast") !== undefined,
+        },
+    };
+}
+function toModelConfig(metadata, name) {
+    return {
+        id: metadata.piModelId,
+        name,
+        reasoning: metadata.supportsReasoning,
+        ...(metadata.thinkingLevelMap ? { thinkingLevelMap: metadata.thinkingLevelMap } : {}),
+        input: [...TEXT_AND_IMAGE_INPUT],
+        cost: { ...ZERO_COST },
+        contextWindow: metadata.contextWindow,
+        maxTokens: FALLBACK_MAX_TOKENS,
+    };
+}
+function registerModelItems(items) {
+    metadataByPiModelId.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);
+        const alias = selectionModelId === item.id ? undefined : selectionModelId;
+        return toModelConfig(metadata, getModelName(item, context, alias, fastOverride));
+    });
+}
+export function getCursorModelMetadata(modelId) {
+    return metadataByPiModelId.get(modelId);
+}
+export function getCursorModelMetadataEntries() {
+    return [...metadataByPiModelId.values()].map((metadata) => ({
+        ...metadata,
+        defaultParams: cloneParams(metadata.defaultParams),
+        ...(metadata.thinkingLevelMap ? { thinkingLevelMap: { ...metadata.thinkingLevelMap } } : {}),
+        parameterIds: { ...metadata.parameterIds },
+    }));
+}
+function setParam(params, id, value) {
+    const existing = params.find((param) => param.id === id);
+    if (existing) {
+        existing.value = value;
+    }
+    else {
+        params.push({ id, value });
+    }
+}
+function deleteParam(params, id) {
+    const index = params.findIndex((param) => param.id === id);
+    if (index >= 0)
+        params.splice(index, 1);
+}
+function applyThinkingLevel(metadata, params, level) {
+    const mapped = metadata.thinkingLevelMap?.[level];
+    if (mapped === undefined || mapped === null)
+        return;
+    if (level === "off") {
+        if (metadata.parameterIds.thinking && mapped === "false") {
+            setParam(params, "thinking", mapped);
+            deleteParam(params, "effort");
+            return;
+        }
+        if (metadata.parameterIds.reasoning) {
+            setParam(params, "reasoning", mapped);
+        }
+        return;
+    }
+    if (metadata.parameterIds.effort) {
+        if (metadata.parameterIds.thinking)
+            setParam(params, "thinking", "true");
+        setParam(params, "effort", mapped);
+        return;
+    }
+    if (metadata.parameterIds.reasoning) {
+        setParam(params, "reasoning", mapped);
+        return;
+    }
+    if (metadata.parameterIds.thinking) {
+        setParam(params, "thinking", mapped);
+    }
+}
+export function buildCursorModelSelection(modelId, thinkingLevel, fastEnabled) {
+    const metadata = getCursorModelMetadata(modelId);
+    if (!metadata)
+        return { id: modelId };
+    const params = cloneParams(metadata.defaultParams);
+    applyThinkingLevel(metadata, params, thinkingLevel);
+    if (metadata.supportsFast && fastEnabled !== undefined) {
+        setParam(params, "fast", fastEnabled ? "true" : "false");
+    }
+    return params.length > 0 ? { id: metadata.selectionModelId, params } : { id: metadata.selectionModelId };
+}
+function sanitizeDiscoveryError(error, apiKey) {
+    const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    return scrubSensitiveText(message, apiKey).trim() || undefined;
+}
+async function useFallbackModels(options, issue) {
+    options.onFallback?.(issue);
+    const { FALLBACK_MODEL_ITEMS } = await import("./cursor-fallback-models.generated.js");
+    return registerModelItems(FALLBACK_MODEL_ITEMS);
+}
+export async function discoverModels(options = {}) {
+    const apiKey = await getDiscoveryApiKey(options.apiKey);
+    if (!apiKey) {
+        return useFallbackModels(options, {
+            reason: "missing-api-key",
+            message: `Cursor model discovery needs an API key from ${AUTH_SETUP_HINT}. Using fallback Cursor models so /login and model selection still work; fallback models can run once auth exists. ${CATALOG_REFRESH_HINT}`,
+        });
+    }
+    const keyFingerprint = fingerprintApiKey(apiKey);
+    if (!options.forceRefresh) {
+        const cachedModels = loadFreshCachedModels(keyFingerprint);
+        if (cachedModels && cachedModels.length > 0) {
+            return registerModelItems(cachedModels);
+        }
+    }
+    try {
+        const { Cursor } = await loadCursorSdk();
+        const models = await Cursor.models.list({ apiKey });
+        if (models.length > 0) {
+            saveModelListCache(keyFingerprint, models);
+            return registerModelItems(models);
+        }
+        return useFallbackModels(options, {
+            reason: "empty-model-list",
+            message: `Cursor model discovery returned no models. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,
+        });
+    }
+    catch (error) {
+        const errorMessage = sanitizeDiscoveryError(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?.({
+                reason: "cached-after-error",
+                message: `Cursor model discovery failed; using cached Cursor model catalog from ${new Date(cachedCatalog.fetchedAt).toISOString()}.${errorMessage ? ` ${errorMessage}` : ""}`,
+                ...(errorMessage ? { errorMessage } : {}),
+            });
+            return registerModelItems(cachedCatalog.models);
+        }
+        return useFallbackModels(options, {
+            reason: "discovery-failed",
+            message: `Cursor model discovery failed${errorMessage ? `: ${errorMessage}` : ""}. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,
+            ...(errorMessage ? { errorMessage } : {}),
+        });
+    }
+}
+export const __testUtils = {
+    parseContextWindow,
+    registerModelItems,
+    normalizeApiKey: resolveCursorApiKey,
+};

package/dist/model-list-cache.js

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, 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";
+import { asRecord } from "./cursor-record-utils.js";
+const MODEL_LIST_CACHE_FILE = "cursor-sdk-model-list.json";
+const MODEL_LIST_CACHE_VERSION = 1;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHE_CLOCK_SKEW_MS = 5 * 60 * 1000;
+const DISABLE_ENV_VAR = "PI_CURSOR_SDK_DISABLE_MODEL_CACHE";
+const TTL_ENV_VAR = "PI_CURSOR_SDK_MODEL_CACHE_TTL_MS";
+function getCachePath() {
+    return join(getAgentDir(), MODEL_LIST_CACHE_FILE);
+}
+export function isModelCacheDisabled() {
+    return parseEnvBoolean(process.env[DISABLE_ENV_VAR], false);
+}
+export function getModelCacheTtlMs() {
+    const raw = process.env[TTL_ENV_VAR];
+    if (raw === undefined)
+        return DEFAULT_TTL_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_TTL_MS;
+    return parsed;
+}
+// Fingerprint the API key so a key change invalidates the cache, without ever
+// persisting the key itself.
+export function fingerprintApiKey(apiKey) {
+    return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isModelParameterValue(value) {
+    const record = asRecord(value);
+    return record !== undefined && typeof record.id === "string" && typeof record.value === "string";
+}
+function isModelParameterDefinitionValue(value) {
+    const record = asRecord(value);
+    return record !== undefined && typeof record.value === "string" && (record.displayName === undefined || typeof record.displayName === "string");
+}
+function isModelParameterDefinition(value) {
+    const record = asRecord(value);
+    if (!record)
+        return false;
+    return (typeof record.id === "string" &&
+        (record.displayName === undefined || typeof record.displayName === "string") &&
+        Array.isArray(record.values) &&
+        record.values.every(isModelParameterDefinitionValue));
+}
+function isModelVariant(value) {
+    const record = asRecord(value);
+    if (!record)
+        return false;
+    return (Array.isArray(record.params) &&
+        record.params.every(isModelParameterValue) &&
+        typeof record.displayName === "string" &&
+        (record.description === undefined || typeof record.description === "string") &&
+        (record.isDefault === undefined || typeof record.isDefault === "boolean"));
+}
+function isModelListItem(value) {
+    const record = asRecord(value);
+    if (!record)
+        return false;
+    return (typeof record.id === "string" &&
+        typeof record.displayName === "string" &&
+        (record.description === undefined || typeof record.description === "string") &&
+        (record.aliases === undefined || isStringArray(record.aliases)) &&
+        (record.parameters === undefined || (Array.isArray(record.parameters) && record.parameters.every(isModelParameterDefinition))) &&
+        (record.variants === undefined || (Array.isArray(record.variants) && record.variants.every(isModelVariant))));
+}
+function isValidFetchedAt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= Date.now() + MAX_CACHE_CLOCK_SKEW_MS;
+}
+function parseModelListCacheFile(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    if (record.version !== MODEL_LIST_CACHE_VERSION ||
+        !isValidFetchedAt(record.fetchedAt) ||
+        typeof record.keyFingerprint !== "string" ||
+        !Array.isArray(record.models) ||
+        !record.models.every(isModelListItem)) {
+        return undefined;
+    }
+    return {
+        version: record.version,
+        fetchedAt: record.fetchedAt,
+        keyFingerprint: record.keyFingerprint,
+        models: record.models,
+    };
+}
+function readCacheFile() {
+    const path = getCachePath();
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return parseModelListCacheFile(JSON.parse(readFileSync(path, "utf-8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Return cached models only when caching is enabled, the key matches, and the
+// entry is within the TTL. Used on the hot startup path to skip the network.
+export function loadFreshCachedModels(keyFingerprint, now = Date.now()) {
+    if (isModelCacheDisabled())
+        return undefined;
+    const ttlMs = getModelCacheTtlMs();
+    if (ttlMs <= 0)
+        return undefined;
+    const cache = readCacheFile();
+    if (!cache || cache.keyFingerprint !== keyFingerprint)
+        return undefined;
+    if (now - cache.fetchedAt > ttlMs)
+        return undefined;
+    return cache.models;
+}
+// Return cached models regardless of age, as long as the key matches. Used as a
+// resilience fallback when a live discovery request fails.
+export function loadAnyCachedModelCatalog(keyFingerprint) {
+    if (isModelCacheDisabled())
+        return undefined;
+    const cache = readCacheFile();
+    if (!cache || cache.keyFingerprint !== keyFingerprint)
+        return undefined;
+    return { fetchedAt: cache.fetchedAt, models: cache.models };
+}
+export function saveModelListCache(keyFingerprint, models) {
+    if (isModelCacheDisabled())
+        return false;
+    try {
+        const path = getCachePath();
+        mkdirSync(dirname(path), { recursive: true });
+        const data = {
+            version: MODEL_LIST_CACHE_VERSION,
+            fetchedAt: Date.now(),
+            keyFingerprint,
+            models,
+        };
+        writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const __testUtils = {
+    getCachePath,
+    DEFAULT_TTL_MS,
+    DISABLE_ENV_VAR,
+    TTL_ENV_VAR,
+};

package/docs/cursor-dogfood-checklist.md

@@ -4,7 +4,8 @@ Short maintainer checklist for **minimal-surface** validation after prompt, brid
 
 ## Minimal environment
 
-- Extension only: `pi --approve -e . --cursor-no-fast --model cursor/composer-2-5`
+- Build first after any `src/` edit: `npm run build` (the pi manifest loads compiled `dist/`)
+- Extension only: `pi --approve -e . --cursor-no-fast --model cursor/grok-4.6`
 - Fresh session dir: `--session-dir /tmp/pi-cursor-dogfood-<id>`
 - Baseline surface (no ambient Cursor MCP/rules):
   - `PI_CURSOR_SETTING_SOURCES=none`, **or**

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

@@ -8,8 +8,9 @@ Use this manual checklist during development and debugging of Cursor provider/ru
 
 ## Inner-loop rule
 
+- Build first: `npm run build` after any `src/` edit — the pi manifest loads compiled `dist/`, so unbuilt runs validate stale code. (the cloud/steering/local-resume/provider-debug launchers rebuild automatically even when run directly with `node scripts/...`; `smoke:live`/`smoke:visual`/`smoke:isolated` build via their npm scripts; direct `pi -e .` invocations do not build.)
 - Run from a clean working tree except for the intended branch diff.
-- Use the local extension under test: `pi --approve -e . --cursor-no-fast --model cursor/composer-2-5`.
+- Use the local extension under test: `pi --approve -e . --cursor-no-fast --model cursor/grok-4.6`.
 - Use a temporary `--session-dir` for every run.
 - Do not paste or commit Cursor API keys, raw session contents with secrets, endpoint URLs, or local private paths.
 - If an inner-loop check fails, stop and fix or use [docs/platform-smoke.md](./platform-smoke.md) as the release-blocking source of truth. Do not treat this checklist as a narrower replacement for the platform gate.
@@ -68,8 +69,8 @@ The replay scan flags only error `toolResult` / error assistant messages with `T
 Pass criteria:
 
 - `pi --version` reports Pi 0.84.0 for this cutover baseline.
-- `npm ls` shows `@cursor/sdk@1.0.23` and local `@earendil-works/*@0.84.0` packages.
-- `cursor/composer-2-5` appears in the model list.
+- `npm ls` shows `@cursor/sdk@1.0.27` and local `@earendil-works/*@0.84.0` packages.
+- `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.
 
@@ -77,7 +78,7 @@ Pass criteria:
 
 ```bash
 PI_CURSOR_SETTING_SOURCES=none \
-pi --approve -e . --cursor-no-fast --model cursor/composer-2-5 \
+pi --approve -e . --cursor-no-fast --model cursor/grok-4.6 \
   --session-dir "$SMOKE_DIR/basic" \
   --no-tools \
   -p 'Live smoke. Reply exactly: PI_CURSOR_SMOKE_OK' \
@@ -95,7 +96,7 @@ Pass criteria:
 ## 2. Default setting-source startup noise check
 
 ```bash
-pi --approve -e . --cursor-no-fast --model cursor/composer-2-5 \
+pi --approve -e . --cursor-no-fast --model cursor/grok-4.6 \
   --session-dir "$SMOKE_DIR/default-settings" \
   --no-tools \
   -p 'Default settings smoke. Include PRODUCT=42 in the final answer.' \
@@ -117,7 +118,7 @@ Run a real interactive session under tmux:
 ```bash
 SESSION="pi-cursor-sdk-smoke-$(date +%s)"
 tmux new-session -d -s "$SESSION" -x 120 -y 40 -- zsh -lc \
-  "cd '$PWD' && PI_CURSOR_SETTING_SOURCES=none pi --approve -e . --cursor-no-fast --model cursor/composer-2-5 --session-dir '$SMOKE_DIR/tui' --session-id cursor-sdk-1016-tui --no-tools 'TUI smoke. Compute 19 + 23. Reply only with SUM=<number>.'"
+  "cd '$PWD' && PI_CURSOR_SETTING_SOURCES=none pi --approve -e . --cursor-no-fast --model cursor/grok-4.6 --session-dir '$SMOKE_DIR/tui' --session-id cursor-sdk-1016-tui --no-tools 'TUI smoke. Compute 19 + 23. Reply only with SUM=<number>.'"
 ```
 
 Observe with `tmux capture-pane -pt "$SESSION"` or attach manually.
@@ -133,7 +134,7 @@ Pass criteria:
 
 ## 4. Focused visual card/color rendering check
 
-This is the canonical inner-loop visual debug path for Cursor provider/runtime changes. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Pi 0.84.0, `@cursor/sdk@1.0.23`, 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 the canonical inner-loop visual debug path for Cursor provider/runtime changes. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Pi 0.84.0, `@cursor/sdk@1.0.27`, 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)"
@@ -204,7 +205,7 @@ Pass criteria:
 
 ```bash
 PI_CURSOR_SETTING_SOURCES=none \
-pi --approve -e . --cursor-no-fast --cursor-mode plan --model cursor/composer-2-5 \
+pi --approve -e . --cursor-no-fast --cursor-mode plan --model cursor/grok-4.6 \
   --session-dir "$SMOKE_DIR/cursor-mode-plan" \
   --session-id cursor-sdk-1016-plan \
   --no-tools \
@@ -226,7 +227,7 @@ Pass criteria:
 PI_CURSOR_SETTING_SOURCES=none \
 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 \
 PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 \
-pi --approve -e . --cursor-no-fast --model cursor/composer-2-5 \
+pi --approve -e . --cursor-no-fast --model cursor/grok-4.6 \
   --session-dir "$SMOKE_DIR/bridge" \
   -p 'Bridge smoke. Do exactly two tool calls before answering: first call pi__read on ./package.json; second call pi__read on ./definitely-missing-pi-cursor-sdk-smoke-file.txt. Then answer: OK_NAME=<package name>; MISSING_RESULT=<error or success>. Do not use shell.' \
   > "$SMOKE_DIR/bridge.stdout.txt" \
@@ -247,7 +248,7 @@ Pass criteria:
 PI_CURSOR_SETTING_SOURCES=none \
 PI_CURSOR_PI_TOOL_BRIDGE=0 \
 PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
-pi --approve -e . --cursor-no-fast --model cursor/composer-2-5 \
+pi --approve -e . --cursor-no-fast --model cursor/grok-4.6 \
   --session-dir "$SMOKE_DIR/native-replay" \
   -p 'Native replay smoke. Use your Cursor file-reading capability to read ./README.md, then answer README_SEEN=yes if it contains pi-cursor-sdk.' \
   > "$SMOKE_DIR/native-replay.stdout.txt" \
@@ -321,7 +322,7 @@ Use a harmless long-running command and interrupt it after the bridge request is
 PI_CURSOR_SETTING_SOURCES=none \
 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 \
 PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 \
-pi --approve -e . --cursor-no-fast --model cursor/composer-2-5 \
+pi --approve -e . --cursor-no-fast --model cursor/grok-4.6 \
   --session-dir "$SMOKE_DIR/abort" \
   -p 'Abort smoke. Call pi__bash with command: sleep 30 && echo SHOULD_NOT_PRINT. Do not answer until the tool completes.'
 ```
@@ -365,7 +366,7 @@ npm pack --dry-run
 Pass criteria:
 
 - All commands exit `0`.
-- `npm pack --dry-run` includes all new runtime source files and excludes local smoke artifacts, sessions, package tarballs, `.env*`, `.pi/`, `dist/`, and `coverage/`.
+- `npm pack --dry-run` includes all new runtime source files and the compiled `dist/` output, and excludes local smoke artifacts, sessions, package tarballs, `.env*`, `.pi/`, and `coverage/`.
 
 ## 12. Cleanup