pi-cursor-sdk 0.2.0 → 0.3.7

package/src/cursor-session-agent-lifecycle.ts

@@ -7,6 +7,11 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { clearCursorSdkHttp1 } from "./cursor-http1.js";
 import { onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import {
+	disposeSessionCursorAgent,
+	invalidateSessionAgent,
+	resetSessionCursorAgent,
+} from "./cursor-session-agent.js";
 
 export interface CursorSessionAgentLifecycleExtensionApi {
 	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
@@ -18,11 +23,9 @@ export interface CursorSessionAgentLifecycleExtensionApi {
 
 export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
 	onCursorSessionScopeKeyChange(async (previousScopeKey) => {
-		const { disposeSessionCursorAgent } = await import("./cursor-session-agent.js");
 		await disposeSessionCursorAgent(previousScopeKey);
 	});
 	pi.on("session_shutdown", async (event) => {
-		const { disposeSessionCursorAgent, resetSessionCursorAgent } = await import("./cursor-session-agent.js");
 		try {
 			if (event.reason === "reload") {
 				await resetSessionCursorAgent();
@@ -33,20 +36,16 @@ export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecy
 			clearCursorSdkHttp1();
 		}
 	});
-	pi.on("session_compact", async () => {
-		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+	pi.on("session_compact", () => {
 		invalidateSessionAgent();
 	});
-	pi.on("session_before_tree", async () => {
-		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+	pi.on("session_before_tree", () => {
 		invalidateSessionAgent();
 	});
 	pi.on("session_tree", async () => {
-		const { resetSessionCursorAgent } = await import("./cursor-session-agent.js");
 		await resetSessionCursorAgent();
 	});
-	pi.on("model_select", async () => {
-		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+	pi.on("model_select", () => {
 		invalidateSessionAgent();
 	});
 }

package/src/cursor-session-agent-resume.ts

@@ -81,6 +81,19 @@ const state: CursorSessionResumeState = {
 	unownedUserEntryIds: new Set(),
 };
 
+// Compaction summarizer sends commit a one-message resume handle. Drop it so the
+// next normal turn_end cannot persist that lineage (#223).
+let resumeHandlePersistSuppressed = false;
+
+export function suppressCursorSessionAgentResumeHandlePersist(): void {
+	resumeHandlePersistSuppressed = true;
+	state.pendingHandle = undefined;
+}
+
+export function allowCursorSessionAgentResumeHandlePersist(): void {
+	resumeHandlePersistSuppressed = false;
+}
+
 function hashParts(parts: readonly string[]): string {
 	const hash = createHash("sha256");
 	for (const part of parts) {
@@ -360,6 +373,7 @@ export function getMatchingCursorSessionAgentResumeHandle(poolKey: string): Curs
 }
 
 export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle): void {
+	if (resumeHandlePersistSuppressed) return;
 	if (!isCursorLocalAgentId(input.agentId)) return;
 	state.pendingHandle = {
 		runtime: input.runtime,
@@ -371,6 +385,11 @@ export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessio
 }
 
 function flushPendingCursorSessionAgentResumeHandle(branch: readonly SessionEntry[]): void {
+	if (resumeHandlePersistSuppressed) {
+		state.pendingHandle = undefined;
+		restoreFromBranch(branch);
+		return;
+	}
 	restoreFromBranch(branch);
 	const pending = state.pendingHandle;
 	state.pendingHandle = undefined;
@@ -442,6 +461,8 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		restoreFromSessionManager(ctx.sessionManager);
 	});
 	pi.on("session_compact", (event, ctx) => {
+		state.pendingHandle = undefined;
+		resumeHandlePersistSuppressed = false;
 		const branch = ctx.sessionManager.getBranch();
 		if (branch.length > 0) {
 			restoreFromSessionManager(ctx.sessionManager);
@@ -471,6 +492,7 @@ function resetStateForTests(): void {
 	state.lastBranchHandle = undefined;
 	state.pendingHandle = undefined;
 	state.unownedUserEntryIds = new Set();
+	resumeHandlePersistSuppressed = false;
 }
 
 export const __testUtils = {
@@ -479,4 +501,5 @@ export const __testUtils = {
 	reset: resetStateForTests,
 	set: setStateForTests,
 	state,
+	isResumeHandlePersistSuppressed: () => resumeHandlePersistSuppressed,
 };

package/src/cursor-session-compaction-prep.ts

@@ -1,15 +1,19 @@
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
+import { suppressCursorSessionAgentResumeHandlePersist } from "./cursor-session-agent-resume.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 
 /**
  * Prepare the pooled Cursor session agent for pi compaction summarization.
  * Releases any scoped live-run drain state still tied to the pooled agent, then
  * disposes the pool entry so summarization acquires a clean SDK agent.
+ * Suppresses local-resume handle persist so the summarizer send cannot leak
+ * a one-message handle into the next normal turn (#223).
  */
 export async function prepareCursorSessionForCompaction(
 	scopeKey: string = getCursorSessionScopeKey(),
 ): Promise<void> {
+	suppressCursorSessionAgentResumeHandlePersist();
 	while (true) {
 		const run = cursorLiveRuns.getActiveForScope(scopeKey);
 		if (!run || run.disposed) break;

package/src/cursor-skill-tool.ts

@@ -18,7 +18,7 @@ import { resolveEffectiveCursorConfigForContext } from "./cursor-runtime-state.j
 export const CURSOR_ACTIVATE_SKILL_TOOL_NAME = "cursor_activate_skill";
 export const CURSOR_ACTIVATE_SKILL_MCP_NAME = "pi__cursor_activate_skill";
 
-const AVAILABLE_SKILLS_SECTION_PATTERN = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
+const AVAILABLE_SKILLS_SECTION_PATTERN = /<skills>\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>\n<\/skills>|\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
 const MAX_SKILL_RESOURCES = 80;
 const RESOURCE_DIR_NAMES = ["scripts", "references", "assets"] as const;
 

package/src/cursor-tool-manifest.ts

@@ -4,7 +4,7 @@ import type { CursorPiToolBridgeSnapshot } from "./cursor-pi-tool-bridge-types.j
 export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
 
 /**
- * Representative @cursor/sdk@1.0.23 local-agent ToolType values; actual exposure can vary by run.
+ * Representative @cursor/sdk@1.0.27 local-agent ToolType values; actual exposure can vary by run.
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY =

package/src/cursor-usage-accounting.ts

@@ -91,18 +91,30 @@ function getCursorSdkUncachedInputTokens(turnUsage: CursorSdkTurnUsage): number
 	return turnUsage.inputTokens - turnUsage.cacheReadTokens - turnUsage.cacheWriteTokens;
 }
 
-export function isCursorSdkUsageSafeForPiMessage(turnUsage: CursorSdkTurnUsage, model: Model<Api>): boolean {
+export function isCursorSdkUsagePartitionSafe(turnUsage: CursorSdkTurnUsage, model: Model<Api>): boolean {
 	const counts = [turnUsage.inputTokens, turnUsage.outputTokens, turnUsage.cacheReadTokens, turnUsage.cacheWriteTokens];
 	const uncachedInput = getCursorSdkUncachedInputTokens(turnUsage);
 	return (
 		counts.every((count) => Number.isFinite(count) && count >= 0) &&
 		Number.isFinite(uncachedInput) &&
 		uncachedInput >= 0 &&
-		turnUsage.outputTokens <= model.maxTokens &&
+		turnUsage.outputTokens <= model.maxTokens
+	);
+}
+
+export function isCursorSdkUsageSafeForPiMessage(turnUsage: CursorSdkTurnUsage, model: Model<Api>): boolean {
+	return (
+		isCursorSdkUsagePartitionSafe(turnUsage, model) &&
 		turnUsage.inputTokens + turnUsage.outputTokens <= model.contextWindow
 	);
 }
 
+export interface CursorSdkUsageApplyOptions {
+	runtime: CursorRuntime;
+	turn?: CursorSdkTurnUsage;
+	billed?: CursorSdkTurnUsage;
+}
+
 export function applyCursorSdkUsage(partial: AssistantMessage, turnUsage: CursorSdkTurnUsage): void {
 	// Pi treats input/cacheRead/cacheWrite as disjoint additive prompt components.
 	partial.usage.input = getCursorSdkUncachedInputTokens(turnUsage);
@@ -117,8 +129,23 @@ function isCompatibleCursorAssistantMeasurement(assistant: AssistantMessage, mod
 	return assistant.api === model.api && assistant.provider === model.provider && assistant.model === model.id;
 }
 
+function getLatestCompactionBoundary(context: Context): { index: number; tokensBefore?: number } | undefined {
+	for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+		const message = context.messages[index] as { role?: string; tokensBefore?: number };
+		if (message.role !== "compactionSummary") continue;
+		const tokensBefore = message.tokensBefore;
+		return {
+			index,
+			tokensBefore: Number.isFinite(tokensBefore) && tokensBefore !== undefined && tokensBefore > 0 ? Math.floor(tokensBefore) : undefined,
+		};
+	}
+	return undefined;
+}
+
 function getLastAcceptedContextOccupancy(context: Context, model: Model<Api>): number {
+	const boundary = getLatestCompactionBoundary(context);
 	for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+		if (boundary && index < boundary.index) break;
 		const message = context.messages[index];
 		if (message.role !== "assistant" || !("usage" in message)) continue;
 		const assistant = message as AssistantMessage;
@@ -127,7 +154,9 @@ function getLastAcceptedContextOccupancy(context: Context, model: Model<Api>): n
 		const { usage } = assistant;
 		const total =
 			usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
-		if (Number.isFinite(total) && total > 0 && total <= model.contextWindow) return total;
+		if (!Number.isFinite(total) || total <= 0 || total > model.contextWindow) continue;
+		if (boundary?.tokensBefore !== undefined && total >= boundary.tokensBefore) continue;
+		return total;
 	}
 	return 0;
 }
@@ -146,18 +175,50 @@ export function applyCursorApproximateUsage(partial: AssistantMessage, model: Mo
 	);
 }
 
+function applyCursorOccupancyEstimate(partial: AssistantMessage, model: Model<Api>, context: Context): void {
+	partial.usage.totalTokens = Math.max(
+		estimateCursorContextTotalTokens(partial, model, context),
+		getLastAcceptedContextOccupancy(context, model),
+	);
+}
+
+function isCurrentLocalOccupancy(turn: CursorSdkTurnUsage, model: Model<Api>, context: Context): boolean {
+	if (!isCursorSdkUsageSafeForPiMessage(turn, model)) return false;
+	const tokensBefore = getLatestCompactionBoundary(context)?.tokensBefore;
+	return tokensBefore === undefined || turn.inputTokens + turn.outputTokens < tokensBefore;
+}
+
+function applyResolvedCursorOccupancy(
+	partial: AssistantMessage,
+	model: Model<Api>,
+	context: Context,
+	localTurn: CursorSdkTurnUsage | undefined,
+): void {
+	if (localTurn && isCurrentLocalOccupancy(localTurn, model, context)) {
+		partial.usage.totalTokens = localTurn.inputTokens + localTurn.outputTokens;
+		return;
+	}
+	applyCursorOccupancyEstimate(partial, model, context);
+}
+
 export function applyCursorUsage(
 	partial: AssistantMessage,
 	model: Model<Api>,
 	context: Context,
 	sessionInputTokens: number,
-	sdkUsage?: { runtime: CursorRuntime; turn?: CursorSdkTurnUsage },
+	sdkUsage?: CursorSdkUsageApplyOptions,
 ): void {
-	// Only local raw turn-ended usage has a captured full-prompt/cache-partition contract.
-	// Cloud raw usage remains display-only until its field semantics are independently observed.
-	const usage = sdkUsage?.runtime === "local" ? sdkUsage.turn : undefined;
-	if (usage && isCursorSdkUsageSafeForPiMessage(usage, model)) {
-		applyCursorSdkUsage(partial, usage);
+	const billed = sdkUsage?.billed;
+	const localTurn = sdkUsage?.runtime === "local" ? sdkUsage.turn : undefined;
+	if (billed && isCursorSdkUsagePartitionSafe(billed, model)) {
+		applyCursorSdkUsage(partial, billed);
+		applyResolvedCursorOccupancy(partial, model, context, localTurn);
+		return;
+	}
+	// Only local raw turn-ended usage has a captured full-prompt/cache-partition occupancy contract.
+	if (localTurn && isCursorSdkUsageSafeForPiMessage(localTurn, model)) {
+		applyCursorSdkUsage(partial, localTurn);
+		applyResolvedCursorOccupancy(partial, model, context, localTurn);
 		return;
 	}
 	applyCursorApproximateUsage(partial, model, context, sessionInputTokens);

package/src/index.ts

@@ -15,6 +15,7 @@ import { registerCursorFallbackIssueWarning } from "./cursor-fallback-warning.js
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context-registration.js";
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
+import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
 
 type CursorExtensionApi =
 	& Pick<ExtensionAPI, "registerProvider" | "registerCommand" | "on">
@@ -54,7 +55,6 @@ export default async function (pi: CursorExtensionApi) {
 	registerCursorSessionAgentLifecycle(pi);
 	registerCursorSessionAgentResume(pi);
 	pi.on("session_before_compact", async () => {
-		const { prepareCursorSessionForCompaction } = await import("./cursor-session-compaction-prep.js");
 		await prepareCursorSessionForCompaction();
 	});
 	registerCursorRuntimeControls(pi);

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"declaration": false,
+		"sourceMap": false
+	}
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "noEmit": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}