pi-cursor-sdk 0.4.0 → 0.5.0

package/dist/cursor-provider-turn-finalize.js

@@ -1,11 +1,9 @@
 import { loadCursorTranscriptWebToolCallsAfterOffset } from "./cursor-agent-message-web-tools.js";
 import { collectCursorCloudRunReport, formatCursorCloudRunReport, } from "./cursor-cloud-reporting.js";
-import { recordCursorCloudLifecycleRun } from "./cursor-cloud-lifecycle.js";
 import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { isCursorRunFinishedSuccessfully, resolveCursorRunOutcome, } from "./cursor-provider-run-outcome.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
-import { attachCursorSdkBilledTurnUsage } from "./cursor-sdk-billed-usage.js";
 export async function cacheSdkContextWindow(agentId, modelId, cwd, store) {
     try {
         const { createAgentPlatform } = await loadCursorSdk();
@@ -74,10 +72,30 @@ function recordCursorCloudReportingError(sdkEventDebug, error, apiKey) {
         // Debug reporting must never affect provider execution.
     }
 }
-/** Single wait/finalize path for SDK runs: wait, debug capture, transcript replay, incomplete tools, artifacts, context cache. */
+export async function recordCursorProviderTerminalUsage(prepared, status, waitUsage) {
+    if (prepared.runtime.usageTerminalRecorded)
+        return undefined;
+    prepared.runtime.usageTerminalRecorded = true;
+    try {
+        return await prepared.usage.recordTerminal({ status, waitUsage, handleUsage: prepared.runtime.sdkRun?.usage });
+    }
+    catch (error) {
+        prepared.usage.notePersistenceFailure(error);
+        return undefined;
+    }
+}
+/** Single wait/finalize path for SDK runs: accounting, replay, incomplete tools, artifacts, context cache. */
 export async function awaitFinalizeCursorRunOutcome(params) {
     const apiKey = params.resolvedApiKey ?? params.optionsApiKey;
-    const waitResult = params.waitResult ?? (await params.run.wait());
+    params.prepared.runtime.sdkRun = params.run;
+    let waitResult;
+    try {
+        waitResult = params.waitResult ?? (await params.run.wait());
+    }
+    catch (error) {
+        await recordCursorProviderTerminalUsage(params.prepared, params.signal?.aborted ? "abort" : "error");
+        throw error;
+    }
     const outcome = buildCursorRunOutcomeFromWait({
         waitResult,
         prepared: params.prepared,
@@ -87,16 +105,7 @@ export async function awaitFinalizeCursorRunOutcome(params) {
         resolvedApiKey: params.resolvedApiKey,
         optionsApiKey: params.optionsApiKey,
     });
-    const billed = await attachCursorSdkBilledTurnUsage({
-        agent: params.prepared.agent,
-        agentId: params.run.agentId,
-        runtime: params.prepared.runtimeTarget,
-        runId: params.run.id,
-    });
-    params.prepared.runtime.billedTurnUsage = billed.turn;
-    if (params.prepared.runtime.liveRun) {
-        params.prepared.runtime.liveRun.billedTurnUsage = billed.turn;
-    }
+    const billing = await recordCursorProviderTerminalUsage(params.prepared, outcome.kind === "finished" ? "success" : outcome.kind === "cancelled" ? "abort" : "error", waitResult.usage);
     let displayOnlyTraceBlock;
     if (params.prepared.runtimeTarget === "cloud" && isCursorRunFinishedSuccessfully(outcome)) {
         let report = { agentId: params.run.agentId, runId: params.run.id, branches: [] };
@@ -106,14 +115,14 @@ export async function awaitFinalizeCursorRunOutcome(params) {
                 run: params.run,
                 waitResult,
                 apiKey,
-                agentUsage: billed.agentUsage,
+                agentUsage: billing ? billing.status === "observed-pending-settlement" ? billing.snapshot : null : undefined,
             });
         }
         catch (error) {
             recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
         }
         try {
-            recordCursorCloudLifecycleRun(report, { apiKey });
+            params.prepared.recordCloudLifecycle(report, apiKey);
         }
         catch (error) {
             recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
@@ -137,8 +146,8 @@ export async function awaitFinalizeCursorRunOutcome(params) {
     catch {
         // Debug reporting must never affect provider execution.
     }
-    if (params.prepared.runtimeTarget === "local" && isCursorRunFinishedSuccessfully(outcome)) {
-        await replayCursorTranscriptWebToolCalls(params.run.agentId, params.prepared.cwd, params.cursorAgentMessageOffset, params.prepared.sessionAgentLease.store, params.prepared.runtime.turnCoordinator, params.sdkEventDebug);
+    if (params.prepared.runtimeTarget === "local" && params.prepared.execution === "conversation" && isCursorRunFinishedSuccessfully(outcome)) {
+        await replayCursorTranscriptWebToolCalls(params.run.agentId, params.prepared.cwd, params.cursorAgentMessageOffset, params.prepared.store, params.prepared.runtime.turnCoordinator, params.sdkEventDebug);
     }
     params.prepared.runtime.turnCoordinator.discardIncompleteStartedToolCalls(outcome.incompleteTools);
     try {
@@ -147,8 +156,8 @@ export async function awaitFinalizeCursorRunOutcome(params) {
     catch {
         // Debug artifact failures must never affect provider execution.
     }
-    if (params.prepared.runtimeTarget === "local" && params.cacheContextWindow !== false) {
-        await cacheSdkContextWindow(params.contextWindowAgentId ?? params.run.agentId, params.modelId, params.prepared.cwd, params.prepared.sessionAgentLease.store);
+    if (params.prepared.runtimeTarget === "local" && params.prepared.execution === "conversation" && params.cacheContextWindow !== false) {
+        await cacheSdkContextWindow(params.contextWindowAgentId ?? params.run.agentId, params.modelId, params.prepared.cwd, params.prepared.store);
     }
     return { outcome, displayOnlyTraceBlock };
 }

package/dist/cursor-provider-turn-prepare.js

@@ -7,22 +7,23 @@ import { acquireSessionCursorAgent, buildCursorSessionSendPrompt, planCursorSess
 import { buildCursorPrompt, estimateCursorPromptTokens } from "./context.js";
 import { getCursorPromptOptions } from "./cursor-usage-accounting.js";
 import { getActiveContextToolNames } from "./cursor-context-tools.js";
-import { abandonSessionCursorAgent, createCursorNativeReplayId, cursorLiveRuns, getActiveCursorLiveRunForCurrentScope, getPendingCursorLiveRun, } from "./cursor-provider-live-run-drain.js";
+import { abandonSessionCursorAgent, createCursorNativeReplayId, cursorLiveRuns, getActiveCursorLiveRunForCurrentScope, } from "./cursor-provider-live-run-drain.js";
 import { getCursorProviderAgentModeOrThrow, getEffectiveFastForModelId, } from "./cursor-state.js";
 import { resolveEffectiveCursorConfig } from "./cursor-runtime-state.js";
 import { buildCursorModelSelection } from "./model-discovery.js";
 import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
 import { formatCursorCloudPreflightError, buildCursorCloudAgentOptions, preflightCursorCloudRuntime, } from "./cursor-cloud-options.js";
 import { inspectCursorCloudLocalState } from "./cursor-cloud-local-state.js";
-import { getCursorSessionName, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
 import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js";
 import { buildCursorToolManifestText, resolveCursorToolManifestEnabled, } from "./cursor-tool-manifest.js";
 import { isCursorNativeToolDisplayRuntimeEnabled } from "./cursor-native-tool-display-state.js";
-import { createCursorCloudLifecyclePersistenceError, recordCursorCloudLifecycleSafely, } from "./cursor-cloud-lifecycle.js";
+import { createCursorCloudLifecyclePersistenceError } from "./cursor-cloud-lifecycle.js";
 import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { prepareCursorSummaryProviderTurn } from "./cursor-provider-turn-summary.js";
 function buildCursorCloudPromptContext(context, handoff) {
     if (handoff === "bootstrap")
         return context;
@@ -38,8 +39,8 @@ function buildCursorCloudPromptContext(context, handoff) {
     return { ...current, messages: messages.slice(-1) };
 }
 const CLOUD_SEND_PLAN = { mode: "bootstrap", resetAgent: false, reason: "initial" };
-export function resolveCursorProviderTurnConfig(cwd) {
-    return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+export function resolveCursorProviderTurnConfig(cwd, projectTrusted = getCursorSessionProjectTrusted(), scopeKey) {
+    return resolveEffectiveCursorConfig({ cwd, projectTrusted, scopeKey });
 }
 function buildCloudCursorProviderTurnLifecycle(agent) {
     return {
@@ -78,7 +79,7 @@ async function prepareCursorCloudProviderTurn(prepareParams) {
         });
         if (!preflight.ok)
             throw new Error(formatCursorCloudPreflightError(preflight));
-        if (getPendingCursorLiveRun(context) || getActiveCursorLiveRunForCurrentScope()) {
+        if (getActiveCursorLiveRunForCurrentScope(params.scope.scopeKey)) {
             throw new Error("Cursor cloud runtime cannot start while a local Cursor live run is pending; finish or abort the local run, then retry.");
         }
         const { Agent } = await loadCursorSdk();
@@ -96,10 +97,10 @@ async function prepareCursorCloudProviderTurn(prepareParams) {
             modelSelection: selection,
             agentMode,
             resolvedConfig,
-            name: getCursorSessionName(),
+            name: params.scope.sessionName,
         })));
         cloudAgentForCleanup = agent;
-        if (!recordCursorCloudLifecycleSafely({ agentId: agent.agentId }, resolvedApiKey)) {
+        if (!params.recordCloudLifecycle({ agentId: agent.agentId }, resolvedApiKey)) {
             throw createCursorCloudLifecyclePersistenceError(agent.agentId, "intent", undefined, resolvedApiKey);
         }
         sdkEventDebug?.recordProviderMeta({ runtime: "cloud", cloudAgentId: agent.agentId, phase: "agent_created" });
@@ -137,6 +138,8 @@ async function prepareCursorCloudProviderTurn(prepareParams) {
         cloudAgentForCleanup = undefined;
         return {
             runtimeTarget: "cloud",
+            execution: "conversation",
+            recordCloudLifecycle: params.recordCloudLifecycle,
             agent,
             cwd,
             payload: {
@@ -190,6 +193,8 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         const queuedBridgeRequestsBeforeLiveRun = [];
         let liveRunForBridgeQueue;
         const sessionAgentAcquireParams = {
+            scope: params.scope,
+            bridge: params.bridge,
             apiKey: resolvedApiKey,
             agentMode,
             cwd,
@@ -258,7 +263,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         };
         const sessionBridgeRun = bridgeRun;
         const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
-        const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+        const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled(params.nativeDisplay);
         const activeToolNames = getActiveContextToolNames(context);
         sdkEventDebug?.recordProviderMeta({
             model: {
@@ -295,6 +300,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
                 promptInputTokens,
                 textDeltas,
                 debugRecorder: sdkEventDebug,
+                nativeDisplay: params.nativeDisplay,
             })
             : undefined;
         if (liveRun) {
@@ -311,6 +317,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             liveRun,
             useNativeToolReplay,
             activeToolNames,
+            registeredToolNames: params.nativeDisplay ? new Set(params.nativeDisplay.registeredNativeToolSources.keys()) : undefined,
             nativeReplayId,
             textDeltas,
             debugRecorder: sdkEventDebug,
@@ -318,6 +325,9 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         completed = true;
         return {
             runtimeTarget: "local",
+            execution: "conversation",
+            store: sessionAgentLease.store,
+            storeIdentity: sessionAgentLease.storeIdentity,
             agent,
             cwd,
             payload: sendPayload,
@@ -363,9 +373,12 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
 export async function prepareCursorProviderTurn(prepareParams) {
     const { params, resolvedConfig } = prepareParams;
     const { model, options } = params;
-    const agentMode = getCursorProviderAgentModeOrThrow();
-    const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id);
+    const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id, params.scope.scopeKey);
     const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
+    if (resolvedConfig.runtime.value === "local" && params.request.purpose !== "normal") {
+        return prepareCursorSummaryProviderTurn(prepareParams, selection);
+    }
+    const agentMode = getCursorProviderAgentModeOrThrow(params.scope.scopeKey);
     const context = { ...prepareParams, agentMode, selection, fastEnabled };
     return resolvedConfig.runtime.value === "cloud"
         ? prepareCursorCloudProviderTurn(context)

package/dist/cursor-provider-turn-runner.js

@@ -1,6 +1,5 @@
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
-import { getCursorSessionCwd } from "./cursor-session-scope.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
@@ -9,7 +8,7 @@ import { CursorRunFinalizer } from "./cursor-provider-run-finalizer.js";
 import { prepareCursorProviderTurn, requireCursorApiKey, resolveCursorProviderTurnConfig, } from "./cursor-provider-turn-prepare.js";
 import { sendCursorProviderTurn } from "./cursor-provider-turn-send.js";
 function requireLocalLivePreparedTurn(prepared) {
-    if (prepared.runtimeTarget !== "local" || prepared.runtime.kind !== "live") {
+    if (prepared.runtimeTarget !== "local" || prepared.execution !== "conversation" || prepared.runtime.kind !== "live") {
         throw new Error("Cursor live run requires a local live prepared turn");
     }
     return prepared;
@@ -32,6 +31,7 @@ export class CursorProviderTurnRunner {
     async run(sdkProcessErrorGuard) {
         const { stream, partial, model, context, options, sdkEventDebugRef } = this.params;
         let prepared;
+        let started;
         let sendResult;
         let liveCompletion;
         const runFinalizer = new CursorRunFinalizer({
@@ -43,20 +43,22 @@ export class CursorProviderTurnRunner {
         });
         try {
             this.throwIfAborted();
-            const cwd = getCursorSessionCwd();
+            const { scope } = this.params;
+            const cwd = scope.cwd;
             this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
                 cwd,
                 modelId: model.id,
                 provider: model.provider,
+                scope,
             });
             sdkEventDebugRef.current = this.sdkEventDebug;
             this.sdkEventDebug?.recordContextSnapshot(context);
             // Resolved once here, before any drain await, so the drain decision and the
             // prepare dispatch below always act on the same config snapshot.
-            const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
+            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
             this.runtimeTarget = resolvedConfig.runtime.value;
-            if (resolvedConfig.runtime.value === "local") {
-                if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+            if (resolvedConfig.runtime.value === "local" && this.params.request.purpose === "normal") {
+                if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor)) ===
                     "stream_ended") {
                     return;
                 }
@@ -71,9 +73,33 @@ export class CursorProviderTurnRunner {
                 throwIfAborted: () => this.throwIfAborted(),
                 resolvedConfig,
             });
+            const usage = await this.params.usageRecorder.start({
+                agent: prepared.agent,
+                runtime: prepared.runtimeTarget,
+                model: { id: model.id, provider: model.provider, cost: { ...model.cost } },
+                modelSelection: prepared.meta.modelSelection,
+                purpose: this.params.request.purpose,
+                ...(prepared.runtimeTarget === "local" ? { storeIdentity: prepared.storeIdentity.stateRoot } : {}),
+                resumed: prepared.runtimeTarget === "local" && prepared.execution === "conversation" && prepared.sessionAgentLease.resumed === true,
+                newlyCreated: prepared.runtimeTarget !== "local" || prepared.execution === "summary" || (prepared.sessionAgentLease.created && !prepared.sessionAgentLease.resumed),
+            }).catch(error => {
+                this.params.usageRecorder.notePersistenceFailure(error);
+                throw error;
+            });
+            started = { ...prepared, usage };
+            if (started.runtime.liveRun) {
+                started.runtime.liveRun.onAbandon = async () => {
+                    try {
+                        await usage.recordTerminal({ status: "abandon" });
+                    }
+                    catch (error) {
+                        usage.notePersistenceFailure(error);
+                    }
+                };
+            }
             sendResult = await sendCursorProviderTurn({
                 params: this.params,
-                prepared,
+                prepared: started,
                 sdkEventDebug: this.sdkEventDebug,
                 sdkProcessErrorGuard,
                 throwIfAborted: () => this.throwIfAborted(),
@@ -81,7 +107,7 @@ export class CursorProviderTurnRunner {
             });
             const { send } = sendResult;
             if (prepared.runtime.kind === "live") {
-                const livePrepared = requireLocalLivePreparedTurn(prepared);
+                const livePrepared = requireLocalLivePreparedTurn(started);
                 liveCompletion = runFinalizer.startLiveRunCompletion({
                     send,
                     prepared: livePrepared,
@@ -98,7 +124,7 @@ export class CursorProviderTurnRunner {
             }
             const outcomePromise = awaitFinalizeCursorRunOutcome({
                 run: send.run,
-                prepared,
+                prepared: started,
                 cursorAgentMessageOffset: send.cursorAgentMessageOffset,
                 modelId: model.id,
                 signal: options?.signal,
@@ -113,13 +139,13 @@ export class CursorProviderTurnRunner {
             const finalized = await outcomePromise;
             await runFinalizer.applyTerminalEvent({
                 kind: "direct",
-                prepared,
+                prepared: started,
                 outcome: finalized.outcome,
                 displayOnlyTraceBlock: finalized.displayOnlyTraceBlock,
             });
         }
         catch (error) {
-            await runFinalizer.applyTerminalEvent({ kind: "error", prepared, error });
+            await runFinalizer.applyTerminalEvent({ kind: "error", prepared: started ?? prepared, error });
         }
         finally {
             await runFinalizer.cleanup(prepared, sendResult, liveCompletion);

package/dist/cursor-provider-turn-send.js

@@ -1,6 +1,5 @@
 import { countCursorAgentMessages } from "./cursor-agent-message-web-tools.js";
-import { createCursorCloudLifecyclePersistenceError, recordCursorCloudLifecycleSafely, } from "./cursor-cloud-lifecycle.js";
-import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import { createCursorCloudLifecyclePersistenceError } from "./cursor-cloud-lifecycle.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { consumeCursorLocalForceOverride } from "./cursor-runtime-state.js";
 import { recordCursorSessionAgentLineage } from "./cursor-session-agent-lineage.js";
@@ -52,9 +51,9 @@ export async function sendCursorProviderTurn(sendParams) {
         abortRegistration?.signal.addEventListener("abort", abortListener, { once: true });
         throwIfAborted();
         let cursorAgentMessageOffset;
-        if (prepared.runtimeTarget === "local") {
+        if (prepared.runtimeTarget === "local" && prepared.execution === "conversation") {
             try {
-                cursorAgentMessageOffset = await countCursorAgentMessages(agent.agentId, cwd, prepared.sessionAgentLease.store);
+                cursorAgentMessageOffset = await countCursorAgentMessages(agent.agentId, cwd, prepared.store);
             }
             catch (error) {
                 recordDebug(() => sdkEventDebug?.recordError("cursor_agent_message_count", error));
@@ -80,6 +79,14 @@ export async function sendCursorProviderTurn(sendParams) {
             mode: meta.agentMode,
             model: meta.modelSelection,
             onDelta: (args) => {
+                if (args.update.type === "turn-ended") {
+                    try {
+                        prepared.usage.observeRawTurn(args.update.usage);
+                    }
+                    catch (error) {
+                        params.usageRecorder.notePersistenceFailure(error);
+                    }
+                }
                 recordDebug(() => sdkEventDebug?.recordOnDelta(args.update));
                 turnCoordinator.handleDelta(args.update);
             },
@@ -89,17 +96,24 @@ export async function sendCursorProviderTurn(sendParams) {
             },
         };
         throwIfAborted();
-        if (prepared.runtimeTarget === "local" && consumeCursorLocalForceOverride(prepared.localForce)) {
+        if (prepared.runtimeTarget === "local" && prepared.execution === "conversation" && consumeCursorLocalForceOverride(prepared.localForce, params.scope.scopeKey)) {
             sendOptions.local = { force: true };
         }
         const runPromise = agent.send(payload, sendOptions);
         // Record at send initiation (promise created), including later reject/cancel paths.
-        if (prepared.runtimeTarget === "local") {
-            recordCursorSessionAgentLineage(agent.agentId);
+        if (prepared.runtimeTarget === "local" && prepared.execution === "conversation") {
+            recordCursorSessionAgentLineage(agent.agentId, params.scope.scopeKey);
         }
         const run = await runPromise;
         sdkRun = run;
-        if (prepared.runtimeTarget === "cloud" && !recordCursorCloudLifecycleSafely({ agentId: run.agentId, runId: run.id }, resolvedApiKey)) {
+        runtime.sdkRun = run;
+        try {
+            await prepared.usage.recordRun({ runId: run.id, requestId: run.requestId });
+        }
+        catch (error) {
+            params.usageRecorder.notePersistenceFailure(error);
+        }
+        if (prepared.runtimeTarget === "cloud" && !params.recordCloudLifecycle({ agentId: run.agentId, runId: run.id }, resolvedApiKey)) {
             const cancellationConfirmed = await requestBoundedCloudRunCancellation(run);
             throw createCursorCloudLifecyclePersistenceError(run.agentId, "run", cancellationConfirmed, resolvedApiKey);
         }
@@ -122,7 +136,6 @@ export async function sendCursorProviderTurn(sendParams) {
             sdkProcessErrorGuard.suppressAbortErrors();
             liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
             await run.cancel().catch(() => { });
-            throw new CursorLiveRunAbortError();
         }
         completed = true;
         return {

package/dist/cursor-provider-turn-summary.js

@@ -0,0 +1,89 @@
+import { buildCursorSummaryPrompt, estimateCursorPromptTokens } from "./context.js";
+import { configureCursorSdkHttp1 } from "./cursor-http1.js";
+import { createCursorNativeReplayId } from "./cursor-provider-live-run-drain.js";
+import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
+import { ensureCursorRipgrepPath } from "./cursor-ripgrep-path.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
+import { buildCursorLocalAgentOptions } from "./cursor-session-agent.js";
+import { openCursorSessionStoreForScope } from "./cursor-session-store.js";
+import { getCursorPromptOptions } from "./cursor-usage-accounting.js";
+function summaryLifecycle(agent, sessionStore) {
+    let disposal;
+    const dispose = () => disposal ??= (async () => {
+        try {
+            await agent[Symbol.asyncDispose]();
+        }
+        finally {
+            await sessionStore.dispose();
+        }
+    })();
+    return { trackRunCompletion: () => { }, commitSend: () => { }, abandon: dispose, dispose };
+}
+/** A native summary never enters the conversation pool or inherits its tool/mode/resume state. */
+export async function prepareCursorSummaryProviderTurn(prepareParams, selection) {
+    const { params, cwd, resolvedApiKey, resolvedConfig, sdkEventDebug, throwIfAborted } = prepareParams;
+    let sessionStore;
+    let agent;
+    let restoreCursorSdkOutputFilter;
+    let completed = false;
+    try {
+        ensureCursorRipgrepPath();
+        const sdk = await loadCursorSdk();
+        configureCursorSdkHttp1(sdk, resolvedConfig.local.useHttp1ForAgent);
+        restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+        sessionStore = (await openCursorSessionStoreForScope({
+            cwd, scopeKey: params.scope.scopeKey, persistent: false, hasResumeHandle: false,
+        })).sessionStore;
+        throwIfAborted();
+        agent = await suppressCursorSdkOutput(() => sdk.Agent.create({
+            apiKey: resolvedApiKey,
+            model: selection,
+            mode: "agent",
+            tools: [],
+            local: buildCursorLocalAgentOptions({ cwd, store: sessionStore.store, settingSources: [] }),
+        }));
+        throwIfAborted();
+        const prompt = buildCursorSummaryPrompt(params.context);
+        const promptInputTokens = estimateCursorPromptTokens(prompt, getCursorPromptOptions(params.model));
+        const nativeReplayId = createCursorNativeReplayId();
+        const textDeltas = [];
+        const turnCoordinator = new CursorSdkTurnCoordinator({
+            stream: params.stream, partial: params.partial, cwd, resolvedApiKey,
+            useNativeToolReplay: false, nativeReplayId, textDeltas, debugRecorder: sdkEventDebug,
+        });
+        sdkEventDebug?.recordProviderMeta({
+            purpose: params.request.purpose,
+            runtime: "local",
+            summaryAgentId: agent.agentId,
+            model: { id: params.model.id, provider: params.model.provider, selection },
+            agentMode: "agent", settingSources: [], tools: [], resumedAgent: false,
+        });
+        completed = true;
+        return {
+            runtimeTarget: "local", execution: "summary", agent, cwd,
+            store: sessionStore.store, storeIdentity: sessionStore.identity,
+            payload: { text: prompt.text },
+            meta: {
+                sendPlan: { mode: "bootstrap", resetAgent: false, reason: "initial" },
+                prompt, bootstrap: true, promptInputTokens,
+                useNativeToolReplay: false, bridgeEnabled: false, nativeReplayId,
+                agentMode: "agent", modelSelection: selection,
+            },
+            contextWindowAgentId: agent.agentId, textDeltas, restoreCursorSdkOutputFilter,
+            lifecycle: summaryLifecycle(agent, sessionStore),
+            runtime: { kind: "direct", turnCoordinator },
+        };
+    }
+    finally {
+        if (!completed) {
+            try {
+                await agent?.[Symbol.asyncDispose]().catch(() => { });
+            }
+            finally {
+                await sessionStore?.dispose().catch(() => { });
+                restoreCursorSdkOutputFilter?.();
+            }
+        }
+    }
+}

package/dist/cursor-provider.js

@@ -6,7 +6,6 @@ import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-gu
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { CursorProviderTurnRunner } from "./cursor-provider-turn-runner.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { runExclusiveCursorSessionTurn, __testUtils as cursorSessionTurnQueueTestUtils } from "./cursor-session-turn-queue.js";
 function makeInitialMessage(model) {
     return {
@@ -27,7 +26,8 @@ function makeInitialMessage(model) {
         timestamp: Date.now(),
     };
 }
-export function streamCursor(model, context, options) {
+export function streamCursor(model, context, options, ownership) {
+    const { scope, bridge, nativeDisplay, recordCloudLifecycle, request, usageRecorder } = ownership;
     const stream = createAssistantMessageEventStream();
     const sdkEventDebugRef = {};
     attachCursorSdkEventDebugPiStreamTap(stream, sdkEventDebugRef);
@@ -35,6 +35,12 @@ export function streamCursor(model, context, options) {
         const partial = makeInitialMessage(model);
         const runner = new CursorProviderTurnRunner({
             model,
+            scope,
+            bridge,
+            nativeDisplay,
+            recordCloudLifecycle,
+            request,
+            usageRecorder,
             context,
             stream,
             partial,
@@ -43,7 +49,7 @@ export function streamCursor(model, context, options) {
         });
         try {
             stream.push({ type: "start", partial });
-            await runExclusiveCursorSessionTurn(getCursorSessionScopeKey(), () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
+            await runExclusiveCursorSessionTurn(scope.scopeKey, () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
         }
         catch (error) {
             await runner.handleOuterCatch(error);

package/dist/cursor-request-provenance.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+function projectionDigest(messages) {
+    const hash = createHash("sha256");
+    for (const message of messages) {
+        // Stable value equivalence survives Pi's cloning and property insertion order.
+        hash.update(JSON.stringify(message, (_key, value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return value;
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+        }));
+        hash.update("\n");
+    }
+    return hash.digest("hex");
+}
+export function captureCursorRequestProjection(manager) {
+    const branch = manager.getBranch();
+    const projection = manager.buildSessionProjection();
+    const order = new Map(branch.map((entry, index) => [entry.id, index]));
+    const boundary = branch.findLastIndex((entry) => entry.type === "compaction" || entry.type === "context_edit");
+    const measurements = [];
+    // Raw branch chronology, not projected order or clocks, determines freshness.
+    for (const entry of [...projection.entries].sort((a, b) => (order.get(a.sourceEntry.id) ?? -1) - (order.get(b.sourceEntry.id) ?? -1))) {
+        if ((order.get(entry.sourceEntry.id) ?? -1) <= boundary)
+            continue;
+        for (const message of entry.messages) {
+            if (message.role !== "assistant" || message.stopReason === "error" || message.stopReason === "aborted")
+                continue;
+            const tokens = message.usage.totalTokens;
+            if (!Number.isFinite(tokens) || tokens <= 0)
+                continue;
+            measurements.push(Object.freeze({ api: message.api, provider: message.provider, model: message.model, tokens }));
+        }
+    }
+    return Object.freeze({ digest: projectionDigest(convertToLlm(projection.messages)), measurements: Object.freeze(measurements) });
+}
+export function resolveCursorRequestProvenance(snapshot, model, context, purpose) {
+    if (purpose !== "normal" || snapshot.digest !== projectionDigest(context.messages))
+        return Object.freeze({ purpose });
+    const measurement = snapshot.measurements.findLast((item) => item.api === model.api && item.provider === model.provider && item.model === model.id && item.tokens <= model.contextWindow);
+    return Object.freeze({ purpose, ...(measurement ? { occupancyFloor: measurement.tokens } : {}) });
+}

package/dist/cursor-ripgrep-path.js

@@ -2,12 +2,23 @@ import { accessSync, constants } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join } from "node:path";
 const RIPGREP_ENV = "CURSOR_RIPGREP_PATH";
-export function resolveBundledCursorRipgrepPath(fromModuleUrl = import.meta.url) {
+export function resolveCursorSdkPlatformPackageDirectory(fromModuleUrl = import.meta.url) {
     try {
         const require = createRequire(fromModuleUrl);
-        const platformPackage = `@cursor/sdk-${process.platform}-${process.arch}`;
         const sdkEntry = require.resolve("@cursor/sdk");
-        const packageDirectory = dirname(require.resolve(`${platformPackage}/package.json`, { paths: [dirname(sdkEntry)] }));
+        return dirname(require.resolve(`@cursor/sdk-${process.platform}-${process.arch}/package.json`, {
+            paths: [dirname(sdkEntry)],
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveBundledCursorRipgrepPath(fromModuleUrl = import.meta.url) {
+    const packageDirectory = resolveCursorSdkPlatformPackageDirectory(fromModuleUrl);
+    if (!packageDirectory)
+        return undefined;
+    try {
         const ripgrepPath = join(packageDirectory, "bin", process.platform === "win32" ? "rg.exe" : "rg");
         accessSync(ripgrepPath, constants.X_OK);
         return ripgrepPath;