pi-cursor-sdk 0.4.0 → 0.5.2

package/src/cursor-provider-turn-runner.ts

@@ -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 type { CursorRuntime } from "./cursor-config.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
@@ -22,14 +21,15 @@ import type {
 	CursorProviderTurnSendResult,
 	LiveCursorProviderTurnRuntime,
 	LocalCursorProviderTurnPrepareResult,
+	StartedCursorProviderTurn,
 } from "./cursor-provider-turn-types.js";
 
 export type { CursorProviderTurnRunnerParams } from "./cursor-provider-turn-types.js";
 
-type LocalLivePreparedTurn = LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime };
+type LocalLivePreparedTurn = StartedCursorProviderTurn & LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime };
 
-function requireLocalLivePreparedTurn(prepared: CursorProviderTurnPrepareResult): LocalLivePreparedTurn {
-	if (prepared.runtimeTarget !== "local" || prepared.runtime.kind !== "live") {
+function requireLocalLivePreparedTurn(prepared: StartedCursorProviderTurn): LocalLivePreparedTurn {
+	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 as LocalLivePreparedTurn;
@@ -53,6 +53,7 @@ export class CursorProviderTurnRunner {
 	async run(sdkProcessErrorGuard: ReturnType<typeof installCursorSdkProcessErrorGuard>): Promise<void> {
 		const { stream, partial, model, context, options, sdkEventDebugRef } = this.params;
 		let prepared: CursorProviderTurnPrepareResult | undefined;
+		let started: StartedCursorProviderTurn | undefined;
 		let sendResult: CursorProviderTurnSendResult | undefined;
 		let liveCompletion: CursorLiveRunCompletion | undefined;
 		const runFinalizer = new CursorRunFinalizer({
@@ -65,21 +66,23 @@ 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 (resolvedConfig.runtime.value === "local" && this.params.request.purpose === "normal") {
 				if (
-					(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+					(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor)) ===
 					"stream_ended"
 				) {
 					return;
@@ -97,9 +100,33 @@ export class CursorProviderTurnRunner {
 				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(),
@@ -108,7 +135,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,
@@ -126,7 +153,7 @@ export class CursorProviderTurnRunner {
 
 			const outcomePromise = awaitFinalizeCursorRunOutcome({
 				run: send.run,
-				prepared,
+				prepared: started,
 				cursorAgentMessageOffset: send.cursorAgentMessageOffset,
 				modelId: model.id,
 				signal: options?.signal,
@@ -141,12 +168,12 @@ 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/src/cursor-provider-turn-send.ts

@@ -1,24 +1,20 @@
 import type { SendOptions } from "@cursor/sdk";
 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";
 import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type {
 	CursorProviderTurnRunnerParams,
-	CursorProviderTurnPrepareResult,
+	StartedCursorProviderTurn,
 	CursorProviderTurnSendResult,
 } from "./cursor-provider-turn-types.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 
 export interface SendCursorProviderTurnParams {
 	params: CursorProviderTurnRunnerParams;
-	prepared: CursorProviderTurnPrepareResult;
+	prepared: StartedCursorProviderTurn;
 	sdkEventDebug: CursorSdkEventDebugSink | undefined;
 	sdkProcessErrorGuard: ReturnType<typeof installCursorSdkProcessErrorGuard>;
 	throwIfAborted: () => void;
@@ -27,7 +23,7 @@ export interface SendCursorProviderTurnParams {
 
 const CLOUD_LEDGER_CANCEL_TIMEOUT_MS = 5000;
 
-async function requestBoundedCloudRunCancellation(run: Awaited<ReturnType<CursorProviderTurnPrepareResult["agent"]["send"]>>): Promise<boolean> {
+async function requestBoundedCloudRunCancellation(run: Awaited<ReturnType<StartedCursorProviderTurn["agent"]["send"]>>): Promise<boolean> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const timeout = new Promise<false>((resolve) => {
 		timer = setTimeout(() => resolve(false), CLOUD_LEDGER_CANCEL_TIMEOUT_MS);
@@ -75,9 +71,9 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 		abortRegistration?.signal.addEventListener("abort", abortListener, { once: true });
 		throwIfAborted();
 		let cursorAgentMessageOffset: number | undefined;
-		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));
 			}
@@ -102,6 +98,13 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 			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);
 			},
@@ -111,17 +114,23 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 			},
 		};
 		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);
 		}
@@ -143,7 +152,6 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 			sdkProcessErrorGuard.suppressAbortErrors();
 			liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
 			await run.cancel().catch(() => {});
-			throw new CursorLiveRunAbortError();
 		}
 
 		completed = true;

package/src/cursor-provider-turn-summary.ts

@@ -0,0 +1,94 @@
+import type { ModelSelection, SDKAgent } from "@cursor/sdk";
+import { buildCursorSummaryPrompt, estimateCursorPromptTokens } from "./context.js";
+import { configureCursorSdkHttp1 } from "./cursor-http1.js";
+import { createCursorNativeReplayId } from "./cursor-provider-live-run-drain.js";
+import type { PrepareCursorProviderTurnParams } from "./cursor-provider-turn-prepare.js";
+import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
+import type { CursorProviderTurnLifecycle, SummaryCursorProviderTurnPrepareResult } from "./cursor-provider-turn-types.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, type OpenCursorSessionStore } from "./cursor-session-store.js";
+import { getCursorPromptOptions } from "./cursor-usage-accounting.js";
+
+function summaryLifecycle(agent: SDKAgent, sessionStore: OpenCursorSessionStore): CursorProviderTurnLifecycle {
+	let disposal: Promise<void> | undefined;
+	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: PrepareCursorProviderTurnParams,
+	selection: ModelSelection,
+): Promise<SummaryCursorProviderTurnPrepareResult> {
+	const { params, cwd, resolvedApiKey, resolvedConfig, sdkEventDebug, throwIfAborted } = prepareParams;
+	let sessionStore: OpenCursorSessionStore | undefined;
+	let agent: SDKAgent | undefined;
+	let restoreCursorSdkOutputFilter: (() => void) | undefined;
+	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: string[] = [];
+		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/src/cursor-provider-turn-tool-ledger.ts

@@ -1,3 +1,4 @@
+import { normalizeCursorToolName } from "./cursor-tool-presentation-registry.js";
 import { getToolArgs, getToolName } from "./cursor-transcript-utils.js";
 
 export type CursorToolDisplaySource = "started" | "fallback" | "transcript";
@@ -53,12 +54,12 @@ export class CursorToolCompletionLedger {
 			return stepId;
 		}
 		const fingerprint = getStartedToolCallFingerprint(toolCall);
-		for (const [callId, startedToolCall] of this.startedToolCalls) {
-			if (getStartedToolCallFingerprint(startedToolCall) !== fingerprint) continue;
-			this.clearStartedToolCall(callId);
-			return callId;
-		}
-		return undefined;
+		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;
 	}
 
 	recordCompletedIdentity(identity: string): void {
@@ -121,5 +122,9 @@ export function getToolFingerprint(value: unknown): string {
 }
 
 export function getStartedToolCallFingerprint(toolCall: unknown): string {
-	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) });
 }

package/src/cursor-provider-turn-types.ts

@@ -6,7 +6,7 @@ import type {
 	Model,
 	SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
-import type { AgentModeOption, ModelSelection, SDKAgent, SDKImage } from "@cursor/sdk";
+import type { AgentModeOption, LocalAgentStore, ModelSelection, SDKAgent, SDKImage } from "@cursor/sdk";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import type { SessionCursorAgentLease } from "./cursor-session-agent.js";
 import type { planCursorSessionSend } from "./cursor-session-agent.js";
@@ -14,9 +14,22 @@ import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import type { CursorPrompt } from "./context.js";
 import type { CursorResolvedSetting } from "./cursor-config.js";
-import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
+import type { CursorRequestProvenance } from "./cursor-request-provenance.js";
+import type { CursorUsageRecorder, CursorUsageTurnRecorder } from "./cursor-usage-ledger.js";
+import type { CursorSessionStoreIdentity } from "./cursor-session-store.js";
+
+import type { CursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import type { CursorCloudLifecycleRecorder } from "./cursor-cloud-lifecycle.js";
+import type { CursorNativeToolDisplayState } from "./cursor-native-tool-display-state.js";
+import type { CursorTurnScope } from "./cursor-session-scope.js";
 
 export interface CursorProviderTurnRunnerParams {
+	scope: CursorTurnScope;
+	bridge?: CursorPiToolBridge;
+	nativeDisplay?: CursorNativeToolDisplayState;
+	recordCloudLifecycle: CursorCloudLifecycleRecorder;
+	request: CursorRequestProvenance;
+	usageRecorder: CursorUsageRecorder;
 	model: Model<Api>;
 	context: Context;
 	stream: AssistantMessageEventStream;
@@ -45,7 +58,8 @@ export interface CursorProviderTurnSendMeta {
 
 interface CursorProviderTurnRuntimeBase {
 	turnCoordinator: CursorSdkTurnCoordinator;
-	billedTurnUsage?: CursorSdkTurnUsage;
+	sdkRun?: Awaited<ReturnType<SDKAgent["send"]>>;
+	usageTerminalRecorded?: boolean;
 }
 
 /**
@@ -85,15 +99,30 @@ interface CursorProviderTurnPrepareResultBase {
 	lifecycle: CursorProviderTurnLifecycle;
 }
 
-export interface LocalCursorProviderTurnPrepareResult extends CursorProviderTurnPrepareResultBase {
+interface LocalCursorProviderTurnPrepareResultBase extends CursorProviderTurnPrepareResultBase {
 	runtimeTarget: "local";
+	store: LocalAgentStore;
+	storeIdentity: CursorSessionStoreIdentity;
+}
+
+export interface LocalCursorProviderTurnPrepareResult extends LocalCursorProviderTurnPrepareResultBase {
+	execution: "conversation";
 	runtime: CursorProviderTurnRuntime;
 	sessionAgentScopeKey: string;
 	sessionAgentLease: SessionCursorAgentLease;
 	localForce: CursorResolvedSetting<boolean>;
 }
 
+export interface SummaryCursorProviderTurnPrepareResult extends LocalCursorProviderTurnPrepareResultBase {
+	execution: "summary";
+	runtime: DirectCursorProviderTurnRuntime;
+	sessionAgentScopeKey?: undefined;
+	sessionAgentLease?: undefined;
+}
+
 export interface CloudCursorProviderTurnPrepareResult extends CursorProviderTurnPrepareResultBase {
+	execution: "conversation";
+	recordCloudLifecycle: CursorCloudLifecycleRecorder;
 	runtimeTarget: "cloud";
 	runtime: DirectCursorProviderTurnRuntime;
 	sessionAgentScopeKey?: undefined;
@@ -108,8 +137,12 @@ export interface CloudCursorProviderTurnPrepareResult extends CursorProviderTurn
  */
 export type CursorProviderTurnPrepareResult =
 	| LocalCursorProviderTurnPrepareResult
+	| SummaryCursorProviderTurnPrepareResult
 	| CloudCursorProviderTurnPrepareResult;
 
+/** Accounting has claimed the origin before this turn can execute a send. */
+export type StartedCursorProviderTurn = CursorProviderTurnPrepareResult & { usage: CursorUsageTurnRecorder };
+
 export interface CursorProviderTurnSend {
 	run: Awaited<ReturnType<SDKAgent["send"]>>;
 	cursorAgentMessageOffset: number | undefined;

package/src/cursor-provider.ts

@@ -22,8 +22,14 @@ 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 type { CursorTurnScope } from "./cursor-session-scope.js";
+import type { CursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import type { CursorNativeToolDisplayState } from "./cursor-native-tool-display-state.js";
+import type { CursorCloudLifecycleRecorder } from "./cursor-cloud-lifecycle.js";
+import type { CursorRequestProvenance } from "./cursor-request-provenance.js";
+import type { CursorUsageRecorder } from "./cursor-usage-ledger.js";
 import { runExclusiveCursorSessionTurn, __testUtils as cursorSessionTurnQueueTestUtils } from "./cursor-session-turn-queue.js";
+import { withCursorSdkOutputNoticeHandler, type CursorSdkOutputNoticeHandler } from "./cursor-sdk-output-filter.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -45,11 +51,23 @@ function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	};
 }
 
+export interface CursorProviderOwnership {
+	scope: CursorTurnScope;
+	bridge?: CursorPiToolBridge;
+	nativeDisplay?: CursorNativeToolDisplayState;
+	recordCloudLifecycle: CursorCloudLifecycleRecorder;
+	request: CursorRequestProvenance;
+	usageRecorder: CursorUsageRecorder;
+	reportSdkNotice?: CursorSdkOutputNoticeHandler;
+}
+
 export function streamCursor(
 	model: Model<Api>,
 	context: Context,
-	options?: SimpleStreamOptions,
+	options: SimpleStreamOptions | undefined,
+	ownership: CursorProviderOwnership,
 ): AssistantMessageEventStream {
+	const { scope, bridge, nativeDisplay, recordCloudLifecycle, request, usageRecorder } = ownership;
 	const stream = createAssistantMessageEventStream();
 	const sdkEventDebugRef: { current?: CursorSdkEventDebugSink } = {};
 	attachCursorSdkEventDebugPiStreamTap(stream, sdkEventDebugRef);
@@ -59,6 +77,12 @@ export function streamCursor(
 
 		const runner = new CursorProviderTurnRunner({
 			model,
+			scope,
+			bridge,
+			nativeDisplay,
+			recordCloudLifecycle,
+			request,
+			usageRecorder,
 			context,
 			stream,
 			partial,
@@ -69,8 +93,8 @@ export function streamCursor(
 		try {
 			stream.push({ type: "start", partial });
 			await runExclusiveCursorSessionTurn(
-				getCursorSessionScopeKey(),
-				() => runner.run(installCursorSdkProcessErrorGuard()),
+				scope.scopeKey,
+				() => withCursorSdkOutputNoticeHandler(ownership.reportSdkNotice, () => runner.run(installCursorSdkProcessErrorGuard())),
 				options?.signal,
 			);
 		} catch (error) {

package/src/cursor-question-tool.ts

@@ -11,7 +11,7 @@ export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
 export const CURSOR_ASK_QUESTION_ENV = "PI_CURSOR_ASK_QUESTION";
 
 export function resolveCursorAskQuestionEnabled(env: Record<string, string | undefined> = process.env): boolean {
-	return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], true);
+	return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], false);
 }
 
 /** Package-namespaced event while `cursor_ask_question` awaits pi UI input. */
@@ -216,13 +216,13 @@ export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi):
 		name: CURSOR_ASK_QUESTION_TOOL_NAME,
 		label: "Cursor question",
 		description:
-			"Ask the user a clarifying question from Cursor. Use when user preferences materially affect the next step; provide options when possible.",
-		promptSnippet: "Ask the user a clarifying question through pi UI when material choices affect Cursor's next step",
+			"Ask the user a clarifying question through pi UI. Do not use this unless the user asked to be prompted; otherwise proceed with a stated assumption.",
+		promptSnippet: "Do not prompt the user through cursor_ask_question unless they asked to be asked",
 		executionMode: "sequential",
 		parameters: CursorAskQuestionParamsSchema,
 		promptGuidelines: [
-			"Use cursor_ask_question only when running a Cursor model and user input would materially change the plan, scope, platform, or implementation path.",
-			"Prefer cursor_ask_question with 2-4 concrete options instead of guessing when Cursor plan mode needs user choices.",
+			"Do not call cursor_ask_question unless the user explicitly asked to be prompted or to choose among options.",
+			"If this tool is available, prefer a reasonable default and state the assumption instead of blocking on a questionnaire.",
 		],
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const questions = normalizeQuestions(params as CursorAskQuestionParams);

package/src/cursor-request-provenance.ts

@@ -0,0 +1,79 @@
+import { createHash } from "node:crypto";
+import { convertToLlm, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Context, Model } from "@earendil-works/pi-ai";
+
+export interface CursorRequestProvenance {
+	readonly purpose: "normal" | "compaction" | "tree";
+	readonly occupancyFloor?: number;
+	/** Canonical native source roles in converted conversation order, only for an equivalent request. */
+	readonly nativeSourceRoles?: readonly string[];
+}
+
+interface Measurement {
+	readonly api: string;
+	readonly provider: string;
+	readonly model: string;
+	readonly tokens: number;
+}
+
+/** Receipt data contains hashes and source-role/accounting scalars only, never conversation text. */
+export interface CursorRequestProjectionSnapshot {
+	readonly digest: string;
+	readonly measurements: readonly Measurement[];
+	readonly nativeSourceRoles: readonly string[];
+}
+
+function projectionDigest(messages: readonly unknown[]): string {
+	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: unknown) => {
+			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: ExtensionContext["sessionManager"]): CursorRequestProjectionSnapshot {
+	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: Measurement[] = [];
+	// 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 }));
+		}
+	}
+	const nativeSourceRoles = projection.messages.flatMap((message) =>
+		message.role === "system" ? [] : convertToLlm([message]).map(() => message.role));
+	return Object.freeze({
+		digest: projectionDigest(convertToLlm(projection.messages)),
+		measurements: Object.freeze(measurements),
+		nativeSourceRoles: Object.freeze(nativeSourceRoles),
+	});
+}
+
+export function resolveCursorRequestProvenance(
+	snapshot: CursorRequestProjectionSnapshot,
+	model: Model<Api>,
+	context: Context,
+	purpose: CursorRequestProvenance["purpose"],
+): CursorRequestProvenance {
+	// ponytail: canonical native origin only. Unmatched transforms stay conservative;
+	// upgrade if Pi exposes final request-bound source provenance.
+	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,
+		nativeSourceRoles: snapshot.nativeSourceRoles,
+		...(measurement ? { occupancyFloor: measurement.tokens } : {}),
+	});
+}

package/src/cursor-ripgrep-path.ts

@@ -4,16 +4,26 @@ import { dirname, isAbsolute, join } from "node:path";
 
 const RIPGREP_ENV = "CURSOR_RIPGREP_PATH";
 
-export function resolveBundledCursorRipgrepPath(
+export function resolveCursorSdkPlatformPackageDirectory(
 	fromModuleUrl: string | URL = import.meta.url,
 ): string | undefined {
 	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: string | URL = import.meta.url,
+): string | undefined {
+	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;