pi-cursor-sdk 0.4.0 → 0.5.2

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

@@ -4,32 +4,38 @@ import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-overri
 import { ensureCursorRipgrepPath } from "./cursor-ripgrep-path.js";
 import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
 import { acquireSessionCursorAgent, buildCursorSessionSendPrompt, planCursorSessionSend, resetSessionCursorAgent, } from "./cursor-session-agent.js";
-import { buildCursorPrompt, estimateCursorPromptTokens } from "./context.js";
+import { buildCursorPrompt, estimateCursorPromptTokens, getCursorPendingInput } 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 { buildCursorCustomSubagentDefinitions } from "./cursor-custom-subagent-definitions.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";
-function buildCursorCloudPromptContext(context, handoff) {
+import { prepareCursorSummaryProviderTurn } from "./cursor-provider-turn-summary.js";
+function buildCursorCloudPromptContext(context, handoff, nativeSourceRoles) {
     if (handoff === "bootstrap")
         return context;
     // Fresh cloud runs omit history, not the current Pi instructions. Replay before
     // selecting the user message, otherwise transcript-only inputs lose the prompt.
     const current = resolveCursorPiContext(context);
     const messages = getCursorConversationMessages(context);
+    if (nativeSourceRoles) {
+        const { start } = getCursorPendingInput(messages, nativeSourceRoles);
+        return { ...current, messages: messages.slice(start) };
+    }
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
         if (message.role === "user")
@@ -38,8 +44,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 {
@@ -60,7 +66,7 @@ function buildLocalCursorProviderTurnLifecycle(lease, scopeKey) {
     };
 }
 async function prepareCursorCloudProviderTurn(prepareParams) {
-    const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+    const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
     const { model, context, options } = params;
     let restoreCursorSdkOutputFilter;
     let cloudAgentForCleanup;
@@ -78,28 +84,32 @@ 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();
         restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+        const promptContext = buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value, params.request.nativeSourceRoles);
+        const nativeSourceRoles = params.request.nativeSourceRoles;
         const promptOptions = {
             ...getCursorPromptOptions(model),
+            nativeSourceRoles: nativeSourceRoles?.slice(nativeSourceRoles.length - getCursorConversationMessages(promptContext).length),
             agentMode,
             includePiBridgeGuidance: false,
             includePiAskQuestionGuidance: false,
         };
-        const prompt = buildCursorPrompt(buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value), promptOptions);
+        const prompt = buildCursorPrompt(promptContext, promptOptions);
         const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
         const agent = await suppressCursorSdkOutput(() => Agent.create(buildCursorCloudAgentOptions({
             apiKey: resolvedApiKey,
             modelSelection: selection,
             agentMode,
             resolvedConfig,
-            name: getCursorSessionName(),
+            name: params.scope.sessionName,
+            agents,
         })));
         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" });
@@ -132,11 +142,14 @@ async function prepareCursorCloudProviderTurn(prepareParams) {
             promptOptions,
             agentMode,
             localForce: false,
+            ...(customSubagentNames ? { customSubagentNames } : {}),
         });
         completed = true;
         cloudAgentForCleanup = undefined;
         return {
             runtimeTarget: "cloud",
+            execution: "conversation",
+            recordCloudLifecycle: params.recordCloudLifecycle,
             agent,
             cwd,
             payload: {
@@ -169,7 +182,7 @@ async function prepareCursorCloudProviderTurn(prepareParams) {
     }
 }
 async function prepareCursorLocalProviderTurn(prepareParams) {
-    const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+    const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
     const { model, context, options } = params;
     let restoreCursorSdkOutputFilter;
     let sessionAgentScopeKey;
@@ -190,13 +203,17 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         const queuedBridgeRequestsBeforeLiveRun = [];
         let liveRunForBridgeQueue;
         const sessionAgentAcquireParams = {
+            scope: params.scope,
+            bridge: params.bridge,
             apiKey: resolvedApiKey,
             agentMode,
             cwd,
             modelSelection: selection,
             settingSources,
             localSafety,
+            agents,
             localResume: resolvedConfig.local.resume.value,
+            storeRoot: resolvedConfig.local.storeRoot.value,
             useHttp1ForAgent,
             debugRecorder: sdkEventDebug,
             onBridgeToolRequest: (request) => {
@@ -217,9 +234,10 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         const buildPromptOptions = (plan) => {
             const promptOptions = {
                 ...getCursorPromptOptions(model),
+                nativeSourceRoles: params.request.nativeSourceRoles,
                 agentMode,
                 includePiBridgeGuidance,
-                includePiAskQuestionGuidance: bridgeToolNames.has("pi__cursor_ask_question"),
+                includePiAskQuestionGuidance: false,
             };
             if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
                 return promptOptions;
@@ -233,7 +251,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
                 }),
             };
         };
-        let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+        let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context, params.request.nativeSourceRoles);
         if (sessionAgentLease.created && sessionAgentLease.resumed && sendPlan.mode === "incremental") {
             sendPlan = { mode: "bootstrap", resetAgent: false, reason: "process_resume" };
         }
@@ -245,7 +263,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             sessionAgentScopeKey = sessionAgentLease.scopeKey;
             bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
             includePiBridgeGuidance = bridgeToolNames.size > 0;
-            sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+            sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context, params.request.nativeSourceRoles);
             promptOptions = buildPromptOptions(sendPlan);
             prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
         }
@@ -258,7 +276,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: {
@@ -281,6 +299,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             activeToolNames: activeToolNames ? [...activeToolNames] : [],
             sessionAgentScopeKey,
             bridgeRunId: bridgeRun?.id,
+            ...(customSubagentNames ? { customSubagentNames } : {}),
         });
         const nativeReplayId = createCursorNativeReplayId();
         const textDeltas = [];
@@ -295,6 +314,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
                 promptInputTokens,
                 textDeltas,
                 debugRecorder: sdkEventDebug,
+                nativeDisplay: params.nativeDisplay,
             })
             : undefined;
         if (liveRun) {
@@ -311,6 +331,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             liveRun,
             useNativeToolReplay,
             activeToolNames,
+            registeredToolNames: params.nativeDisplay ? new Set(params.nativeDisplay.registeredNativeToolSources.keys()) : undefined,
             nativeReplayId,
             textDeltas,
             debugRecorder: sdkEventDebug,
@@ -318,6 +339,9 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         completed = true;
         return {
             runtimeTarget: "local",
+            execution: "conversation",
+            store: sessionAgentLease.store,
+            storeIdentity: sessionAgentLease.storeIdentity,
             agent,
             cwd,
             payload: sendPayload,
@@ -363,10 +387,15 @@ 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);
-    const context = { ...prepareParams, agentMode, selection, fastEnabled };
+    if (resolvedConfig.runtime.value === "local" && params.request.purpose !== "normal") {
+        return prepareCursorSummaryProviderTurn(prepareParams, selection);
+    }
+    const agentMode = getCursorProviderAgentModeOrThrow(params.scope.scopeKey);
+    const agents = buildCursorCustomSubagentDefinitions(resolvedConfig.subagents.value);
+    const customSubagentNames = agents ? Object.keys(agents) : undefined;
+    const context = { ...prepareParams, agentMode, selection, fastEnabled, agents, customSubagentNames };
     return resolvedConfig.runtime.value === "cloud"
         ? prepareCursorCloudProviderTurn(context)
         : prepareCursorLocalProviderTurn(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,
+        })).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-turn-tool-ledger.js

@@ -1,3 +1,4 @@
+import { normalizeCursorToolName } from "./cursor-tool-presentation-registry.js";
 import { getToolArgs, getToolName } from "./cursor-transcript-utils.js";
 export class CursorToolCompletionLedger {
     startedToolCalls = new Map();
@@ -33,13 +34,14 @@ export class CursorToolCompletionLedger {
             return stepId;
         }
         const fingerprint = getStartedToolCallFingerprint(toolCall);
-        for (const [callId, startedToolCall] of this.startedToolCalls) {
-            if (getStartedToolCallFingerprint(startedToolCall) !== fingerprint)
-                continue;
+        const matches = [...this.startedToolCalls].filter(([, started]) => getStartedToolCallFingerprint(started) === fingerprint);
+        // Identical concurrent shells cannot be joined safely without a matching ID.
+        if (normalizeCursorToolName(getToolName(toolCall)) === "shell" && matches.length !== 1)
+            return undefined;
+        const callId = matches[0]?.[0];
+        if (callId !== undefined)
             this.clearStartedToolCall(callId);
-            return callId;
-        }
-        return undefined;
+        return callId;
     }
     recordCompletedIdentity(identity) {
         this.completedToolIdentities.add(identity);
@@ -95,5 +97,9 @@ export function getToolFingerprint(value) {
     }
 }
 export function getStartedToolCallFingerprint(toolCall) {
-    return getToolFingerprint({ toolName: getToolName(toolCall), args: getToolArgs(toolCall) });
+    const name = getToolName(toolCall);
+    // Accept legacy shell aliases; this does not establish that the SDK emits alias-changing pairs.
+    // Keep exact argument matching; assistant text alone is not completion proof.
+    const toolName = normalizeCursorToolName(name) === "shell" ? "shell" : name;
+    return getToolFingerprint({ toolName, args: getToolArgs(toolCall) });
 }