pi-cursor-sdk 0.4.0 → 0.5.0

package/dist/index.js

@@ -4,38 +4,30 @@ import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-re
 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 { registerCursorProviderBinding } from "./cursor-provider-binding.js";
+import { getCursorSessionScopeSnapshot, 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 { 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));
-}
+import { registerCursorUsageLedger } from "./cursor-usage-ledger.js";
+import { registerCursorUsageCommand } from "./cursor-usage-command.js";
 export default async function (pi) {
     // Session cwd must register before other session_start listeners that depend on it.
     registerCursorSessionScope(pi);
+    registerCursorUsageLedger(pi);
+    registerCursorUsageCommand(pi);
+    const registerCursorProvider = registerCursorProviderBinding(pi);
     registerCursorSessionAgentLineage(pi);
     registerCursorSessionAgentLifecycle(pi);
     registerCursorSessionAgentResume(pi);
     pi.on("session_before_compact", async () => {
-        await prepareCursorSessionForCompaction();
+        await prepareCursorSessionForCompaction(getCursorSessionScopeSnapshot(pi).scopeKey);
     });
     registerCursorRuntimeControls(pi);
     registerCursorNativeToolDisplay(pi);
@@ -65,7 +57,7 @@ export default async function (pi) {
                     refreshFallbackIssue = issue;
                 },
             });
-            registerCursorProvider(pi, refreshedModels);
+            registerCursorProvider(refreshedModels);
             if (!ctx.hasUI)
                 return;
             if (refreshFallbackIssue) {
@@ -76,7 +68,7 @@ export default async function (pi) {
             }
         },
     });
-    registerCursorProvider(pi, models);
+    registerCursorProvider(models);
     // Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
     registerCursorSdkSessionProcessErrorGuard(pi);
 }

package/dist/model-discovery.js

@@ -2,7 +2,7 @@ import { getCursorModelSelectionIdentities } from "../shared/cursor-model-select
 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 { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 import { fingerprintApiKey, loadAnyCachedModelCatalog, loadFreshCachedModels, saveModelListCache, } from "./model-list-cache.js";
 const FALLBACK_CONTEXT_WINDOW = 128000;
 const FALLBACK_MAX_TOKENS = 16384;
@@ -46,7 +46,7 @@ function getThinkingLevelMap(item) {
     const reasoningParameter = getParameter(item, "reasoning");
     const effortParameter = getParameter(item, "effort");
     const thinkingParameter = getParameter(item, "thinking");
-    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter;
+    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter ?? getParameter(item, "reasoning_effort");
     if (!valueParameter)
         return undefined;
     if (valueParameter.id === "thinking" && hasBooleanValues(valueParameter)) {
@@ -147,6 +147,7 @@ function toMetadata(item, piModelId, selectionModelId, defaultParams, context, c
             reasoning: getParameter(item, "reasoning") !== undefined,
             effort: getParameter(item, "effort") !== undefined,
             thinking: getParameter(item, "thinking") !== undefined,
+            reasoning_effort: getParameter(item, "reasoning_effort") !== undefined,
             fast: getParameter(item, "fast") !== undefined,
         },
     };
@@ -179,14 +180,6 @@ function registerModelItems(items) {
 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) {
@@ -229,6 +222,9 @@ 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);
@@ -241,10 +237,6 @@ export function buildCursorModelSelection(modelId, thinkingLevel, fastEnabled) {
     }
     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");
@@ -278,7 +270,7 @@ export async function discoverModels(options = {}) {
         });
     }
     catch (error) {
-        const errorMessage = sanitizeDiscoveryError(error, apiKey);
+        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.
@@ -286,15 +278,15 @@ export async function discoverModels(options = {}) {
         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 } : {}),
+                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",
-            message: `Cursor model discovery failed${errorMessage ? `: ${errorMessage}` : ""}. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,
-            ...(errorMessage ? { errorMessage } : {}),
+            message: `Cursor model discovery failed: ${errorMessage} Using fallback Cursor models; run /cursor-refresh-models to retry discovery.`,
+            errorMessage,
         });
     }
 }

package/docs/cursor-dogfood-checklist.md

@@ -1,6 +1,6 @@
 # Cursor dogfood checklist
 
-Short maintainer checklist for **minimal-surface** validation after prompt, bridge, replay, or manifest changes. This is the fast path from pi-cursor-composer dogfood sessions—not a substitute for the required [platform smoke gate](./platform-smoke.md).
+Short maintainer menu for **minimal-surface** validation after prompt, bridge, replay, or manifest changes. Start with offline/faux checks and reuse exact-input retained evidence. Only changed behavior needing new real-service proof warrants a selected exercise on one representative environment; docs/metadata-only changes need no paid runs. The [platform smoke matrix](./platform-smoke.md) is optional, not a routine ship step. No full paid campaign replay or automatic paid retries. No paid Cloud testing for generic PRs/releases; only explicitly Cursor Cloud-focused PRs/issues may select necessary focused Cloud proof. Automated Cursor PR reviews continue unchanged.
 
 ## Minimal environment
 
@@ -33,7 +33,7 @@ Inspect the session JSONL under the temp `--session-dir`:
 | Pattern | Meaning |
 | --- | --- |
 | `cursor-replay-*` | Display-only replay of Cursor SDK activity—not callable |
-| `cursor-pi-bridge-run-*` | Live pi execution via bridge |
+| `cursor-pi-bridge-run-*` (run) / `cursor-pi-bridge-<32 hex>-t<counter>` (tool) | Live pi execution via bridge |
 | Callable tools | Cursor SDK host + MCP `listTools` + exposed `pi__*` only |
 
 Common mistake: treating `cursor-replay-*` IDs or pi transcript tool labels as tools to invoke.
@@ -60,6 +60,6 @@ Canonical visual evidence: `npm run smoke:visual` (see [Cursor native tool visua
 ## Related docs
 
 - [Cursor tool surfaces in pi](./cursor-tool-surfaces.md) — three namespaces and discoverability
-- [Platform smoke gate](./platform-smoke.md) — required cross-platform release gate
+- [Platform smoke](./platform-smoke.md) — focused selection and optional comprehensive matrix
 - [Cursor live smoke checklist](./cursor-live-smoke-checklist.md) — inner-loop/manual debug checks
 - [Cursor testing lessons](./cursor-testing-lessons.md) — auth, JSONL scans, plan-mode traps

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

@@ -1,10 +1,10 @@
 # Cursor Live Smoke Checklist
 
-> **Platform Smoke:** The required local cross-platform release gate is `npm run smoke:platform:all`; it runs doctor first. Cloud-runtime changes also require `npm run smoke:cloud`. See [docs/platform-smoke.md](./platform-smoke.md) for the full contract. The manual checks below remain useful inner-loop/debug tools but are not the required release gate.
+> **Cost-conscious verification:** Offline/faux checks first; reuse exact-input retained evidence. Use only the smallest meaningful changed-behavior live check on one representative environment when real-service proof is necessary. Docs/metadata-only changes need no paid runs. The full `smoke:platform:all` matrix is optional. No paid Cloud testing for generic PRs/releases; only explicitly Cursor Cloud-focused PRs/issues may select necessary focused Cloud proof. Automated Cursor PR reviews continue unchanged. See [docs/platform-smoke.md](./platform-smoke.md).
 
 ## Purpose
 
-Use this manual checklist during development and debugging of Cursor provider/runtime changes. Unit tests and mocks are necessary, but they are not enough for this extension. See [Cursor testing lessons](./cursor-testing-lessons.md) for auth/isolated-harness pitfalls and the plan-mode replay regression that motivated recent hardening. For release readiness, run the local platform gate in [docs/platform-smoke.md](./platform-smoke.md), plus `npm run smoke:cloud` for cloud-runtime changes; this checklist is inner-loop evidence only.
+Use this checklist as a menu, not a mandatory campaign. Select only behavior that changed and needs new real-service evidence after offline/faux checks and retained-proof reuse. Do not run host matrices merely for matrix coverage or automatically retry paid failures. See [Cursor testing lessons](./cursor-testing-lessons.md) for isolated-harness and replay pitfalls. Selected checks keep their distinct assertions, persisted evidence, visual proof, and cleanup requirements; do not claim unobserved coverage.
 
 ## Inner-loop rule
 
@@ -13,8 +13,8 @@ Use this manual checklist during development and debugging of Cursor provider/ru
 - 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.
-- Do not narrow the smoke scope to the apparent code diff. Treat provider reality, TUI behavior, bridge behavior, replay behavior, diagnostics safety, abort/cancel cleanup, usage accounting, packaging, and cleanup as in scope for every Cursor provider/runtime release.
+- If a selected check fails, retain evidence and diagnose offline before choosing a repair or a necessary follow-up call. No automatic paid retries.
+- Scope new live calls to changed behavior that needs real-service proof; retain valid proof for unchanged behavior. Do not run every checklist section or the full matrix as a routine commit/release step.
 - A check is passed only when the visible TUI/output, stderr diagnostics, and persisted JSONL agree with the expected behavior.
 
 ## Prerequisites
@@ -65,13 +65,13 @@ node scripts/validate-smoke-jsonl.mjs --replay-errors-only "$SMOKE_DIR/session-s
 
 The replay scan flags only error `toolResult` / error assistant messages with `Tool grep/cursor/find/ls not found`, not successful reads of docs that mention those strings. See [Cursor testing lessons](./cursor-testing-lessons.md#what-counts-as-a-replay-failure).
 
-`npm run smoke:live` is a helper only; it polls the section 3 TUI for answer/footer evidence and then cleans up the tmux session, but it does not replace the canonical rendered-PNG visual review in section 4. Run the relevant helper `--self-test` (`smoke:live`, `smoke:visual`, `smoke:steering`, or `smoke:isolated`) when changing sealed PATH or env wrappers. Release readiness requires the platform smoke gate. Run focused manual checks below when debugging detailed visual TUI behavior, bridge, standalone native replay, abort/cancel, packaging, cleanup, or any touched runtime surface before rerunning the platform gate.
+`npm run smoke:live` is a helper only; it polls the section 3 TUI for answer/footer evidence and then cleans up the tmux session, but it does not replace the canonical rendered-PNG visual review in section 4. Run the relevant helper `--self-test` (`smoke:live`, `smoke:visual`, `smoke:steering`, or `smoke:isolated`) when changing sealed PATH or env wrappers. For changed behavior needing new live evidence, select the relevant manual check or existing single-suite/single-target platform run, not both by default. The comprehensive matrix is optional.
 
 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`; local `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 0.87.1; 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.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`.
 - `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 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 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.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`.
 
 ```bash
 VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1016-visual.XXXXXX)"
@@ -185,7 +185,7 @@ npm run smoke:visual -- "${VISUAL_ARGS[@]}" \
   --prompt 'Stay in Cursor plan mode. If Cursor exposes plan, todo, task, or mode activity for this request, use that capability to outline a tiny unit test without editing files. Otherwise answer with a concise numbered plan. Do not use shell or file mutation tools.'
 ```
 
-By default, `npm run smoke:visual` writes `.ansi`, `.txt`, `.html`, `.png`, and `.jsonl.path` artifacts. If Playwright Chromium is unavailable in an agent-harness run, rerun with `--no-screenshot`, open the generated `.html` with `agent_browser`, save a PNG screenshot, and record that PNG path beside the runner artifacts. To visually audit bridge behavior or ambient Cursor settings, opt in with `--bridge`, `--bridge --expose-builtin-tools`, or `--setting-sources <value>` and label that evidence separately; do not count those opt-in runs as default native replay matrix proof.
+By default, `npm run smoke:visual` writes `.ansi`, `.txt`, `.html`, `.png`, and `.jsonl.path` artifacts. Check browser availability before a paid run. If PNG rendering fails but ANSI/HTML evidence was retained, render that retained evidence with the canonical browser/xterm path and save a PNG; do not repeat the model call merely to produce a screenshot. To visually audit bridge behavior or ambient Cursor settings, opt in with `--bridge`, `--bridge --expose-builtin-tools`, or `--setting-sources <value>` and label that evidence separately; do not count those opt-in runs as default native replay matrix proof.
 
 Expected proof for each category is defined in [Cursor Native Tool Visual Audit Workflow](./cursor-native-tool-visual-audit.md). Do not mark a category passed because the prompt was sent. A category passes only when the PNG shows the expected card and the JSONL shows the expected completed `toolCall` / `toolResult` pair with the expected `isError` state.
 
@@ -193,7 +193,7 @@ Pass criteria:
 
 - PNG screenshots exist for every claimed card category, not only text/JSONL logs.
 - JSONL paths exist for every claimed card category.
-- Required cutover categories have matching PNG + JSONL proof from the default native replay matrix: read, grep/search, find/glob, list, shell success, write, edit/diff, and true read failure.
+- Each selected changed category has matching PNG + JSONL proof; retained exact-input proof covers unchanged categories. Do not claim unobserved categories.
 - Native-looking read/search/find/list/shell/write/edit cards use intended pi card styling.
 - Shell success is not red/error-styled; stdout is readable.
 - Edit/diff previews show red/green added/removed colors and readable paths.
@@ -271,7 +271,7 @@ Allowed fields:
 
 - event name
 - run-safe correlation IDs that are not endpoint path components
-- bridge/pi tool call IDs derived from the run-safe ID
+- bridge run IDs remain `cursor-pi-bridge-run-*`; provider-facing bridge/pi tool call IDs encode the same run UUID as 32 hex characters, use the `cursor-pi-bridge-<32 hex>-t<counter>` shape, and stay within the 64-character limit
 - hashed Cursor MCP call correlation IDs of the form `cursor-mcp-call-<8 hex chars>`
 - exposed pi/MCP tool name pairs
 - pending/queued/cancelled counts
@@ -316,7 +316,7 @@ Pass criteria:
 
 ## 9. Long-running bridge and abort/cancel
 
-Use this focused check when debugging abort cleanup. The platform smoke gate is the release-blocking source of truth for every Cursor provider/runtime release.
+Select this check only when changed abort cleanup needs new real-service evidence; otherwise reuse valid retained proof. Keep process, bridge, and persisted-session cleanup assertions intact.
 
 Use a harmless long-running command and interrupt it after the bridge request is queued:
 
@@ -353,8 +353,8 @@ Script-enforced pass criteria:
 
 Additional manual usage checks for provider/accounting changes:
 
-- Tool-heavy runs should show nonzero output for visible assistant/tool-call activity.
-- Split runs should count consumed tool-result input once on the following assistant turn.
+- Each assistant message's disjoint input/cache/output components should sum to `totalTokens` and describe one coherent current context, not cumulative billed spend.
+- In split runs, earlier tool results can remain in later current-context estimates. Fresh, attributable LOCAL SDK usage takes precedence; late raw and billed facts remain in the separate ledger without rewriting emitted messages. See [context, compaction, and Cursor usage](../README.md#context-compaction-and-cursor-usage).
 
 ## 11. Standard local gates
 
@@ -385,7 +385,7 @@ Pass criteria:
 
 ## Coverage gaps this checklist makes explicit
 
-Everything in this section is in scope when using this checklist for Cursor provider/runtime debugging. Release readiness still comes from the platform smoke gate:
+Use this list to choose meaningful changed-behavior coverage, not to trigger a full paid replay. Prefer offline contracts and valid retained evidence:
 
 - Long-running bridged tool abort/cancel cleanup.
 - Native replay cards beyond read, especially shell/edit/write cards, when those renderers change.
@@ -395,4 +395,4 @@ Everything in this section is in scope when using this checklist for Cursor prov
 - Ambient Cursor setting-source behavior when startup filtering or local Cursor settings handling changes.
 - Model discovery aliases/context variants when model-discovery code or Cursor SDK versions change.
 
-If any surface has no adequate platform or focused live check, add that coverage before release instead of assuming mocks cover reality.
+If changed behavior needs real-service proof and neither retained evidence nor an existing focused check covers it, report the specific gap and choose the smallest meaningful check. Do not assume mocks prove service behavior or make unrelated optional lanes a release requirement.