pi-cursor-sdk 0.1.36 → 0.1.38

package/src/cursor-skill-tool.ts

@@ -2,19 +2,15 @@ import type { Dirent } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
 	BuildSystemPromptOptions,
 	ExtensionAPI,
 	ExtensionContext,
-	ExtensionHandler,
-	SessionStartEvent,
 	Skill,
-	TurnStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { isCursorModel } from "./cursor-model.js";
-import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-snapshot.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js";
 
 export const CURSOR_ACTIVATE_SKILL_TOOL_NAME = "cursor_activate_skill";
 export const CURSOR_ACTIVATE_SKILL_MCP_NAME = "pi__cursor_activate_skill";
@@ -23,12 +19,7 @@ const AVAILABLE_SKILLS_SECTION_PATTERN = /\n\nThe following skills provide speci
 const MAX_SKILL_RESOURCES = 80;
 const RESOURCE_DIR_NAMES = ["scripts", "references", "assets"] as const;
 
-type CursorSkillToolExtensionApi = Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> & {
-	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
-	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
-	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
-	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
-};
+type CursorSkillToolExtensionApi = Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> & CursorModelLifecycleExtensionApi;
 
 type CursorActivateSkillParams = {
 	name?: string;
@@ -229,26 +220,28 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 		syncCursorSkillToolForModel(pi, model);
 	};
 
-	pi.on("session_start", (_event, ctx) => {
-		clearSkillsAndSync(ctx.model);
-	});
-	pi.on("model_select", (event) => {
-		clearSkillsAndSync(event.model);
-	});
-	pi.on("turn_start", (_event, ctx) => {
-		if (!isCursorModel(ctx.model)) setCurrentSkills([]);
-		syncCursorSkillToolForModel(pi, ctx.model);
-	});
-	pi.on("before_agent_start", (event, ctx) => {
-		if (isCursorModel(ctx.model)) {
-			setCurrentSkills(event.systemPromptOptions?.skills);
-		} else {
-			setCurrentSkills([]);
-		}
-		syncCursorSkillToolForModel(pi, ctx.model);
-		const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions);
-		if (resolved === event.systemPrompt) return undefined;
-		return { systemPrompt: resolved };
+	registerCursorModelLifecycle(pi, {
+		sessionStart: (_event, ctx) => {
+			clearSkillsAndSync(ctx.model);
+		},
+		modelSelect: (event) => {
+			clearSkillsAndSync(event.model);
+		},
+		turnStart: (_event, ctx) => {
+			if (!isCursorModel(ctx.model)) setCurrentSkills([]);
+			syncCursorSkillToolForModel(pi, ctx.model);
+		},
+		beforeAgentStart: (event, ctx) => {
+			if (isCursorModel(ctx.model)) {
+				setCurrentSkills(event.systemPromptOptions?.skills);
+			} else {
+				setCurrentSkills([]);
+			}
+			syncCursorSkillToolForModel(pi, ctx.model);
+			const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions);
+			if (resolved === event.systemPrompt) return undefined;
+			return { systemPrompt: resolved };
+		},
 	});
 }
 

package/src/cursor-state.ts

@@ -15,9 +15,12 @@ import {
 } from "./cursor-pi-tool-bridge-snapshot.js";
 import {
 	CURSOR_SETTING_SOURCES_ENV,
-	getEffectiveCursorSettingSources,
+	resolveCursorSettingSources,
 } from "./cursor-setting-sources.js";
 import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
+import { asRecord } from "./cursor-record-utils.js";
+import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
 
 const FAST_ENTRY_TYPE = "cursor-fast-state";
@@ -58,6 +61,7 @@ let cliForceFast = false;
 let cliForceNoFast = false;
 let sessionCursorAgentMode: AgentModeOption | undefined;
 let cliCursorModeState: CursorCliModeState = { kind: "unset" };
+const invalidCursorModeNotifiedSessionScopeKeys = new Set<string>();
 
 export function isCursorAgentMode(value: unknown): value is AgentModeOption {
 	return value === "agent" || value === "plan";
@@ -69,13 +73,10 @@ export function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined
 	return isCursorAgentMode(mode) ? mode : undefined;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 function isCursorFastEntryData(value: unknown): value is CursorFastEntryData {
-	if (!isRecord(value)) return false;
-	return (typeof value.modelId === "string" || typeof value.baseModelId === "string") && typeof value.fast === "boolean";
+	const record = asRecord(value);
+	if (!record) return false;
+	return (typeof record.modelId === "string" || typeof record.baseModelId === "string") && typeof record.fast === "boolean";
 }
 
 function getCursorFastEntryModelId(data: CursorFastEntryData): string {
@@ -83,17 +84,19 @@ function getCursorFastEntryModelId(data: CursorFastEntryData): string {
 }
 
 function isCursorModeEntryData(value: unknown): value is CursorModeEntryData {
-	return isRecord(value) && isCursorAgentMode(value.mode);
+	return isCursorAgentMode(asRecord(value)?.mode);
 }
 
 function parseCursorGlobalConfig(value: unknown): CursorGlobalConfig | undefined {
-	if (!isRecord(value)) return undefined;
-	const { fastDefaults } = value;
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const { fastDefaults } = record;
 	if (fastDefaults === undefined) return {};
-	if (!isRecord(fastDefaults)) return undefined;
+	const fastDefaultsRecord = asRecord(fastDefaults);
+	if (!fastDefaultsRecord) return undefined;
 	return {
 		fastDefaults: Object.fromEntries(
-			Object.entries(fastDefaults).filter((entry): entry is [string, boolean] => typeof entry[1] === "boolean"),
+			Object.entries(fastDefaultsRecord).filter((entry): entry is [string, boolean] => typeof entry[1] === "boolean"),
 		),
 	};
 }
@@ -174,23 +177,38 @@ function formatInvalidCursorMode(raw: string): string {
 	return `Invalid --cursor-mode "${raw}". Use "agent" or "plan".`;
 }
 
-export function getEffectiveCursorAgentMode(): AgentModeOption {
+export type CursorAgentModeResolution =
+	| { kind: "valid"; mode: AgentModeOption }
+	| { kind: "invalid"; raw: string; message: string };
+
+export function getStoredCursorAgentMode(): AgentModeOption {
+	return sessionCursorAgentMode ?? DEFAULT_CURSOR_AGENT_MODE;
+}
+
+export function resolveCursorAgentMode(): CursorAgentModeResolution {
 	switch (cliCursorModeState.kind) {
 		case "valid":
-			return cliCursorModeState.mode;
+			return { kind: "valid", mode: cliCursorModeState.mode };
 		case "invalid":
-			throw new Error(cliCursorModeState.message);
+			return { kind: "invalid", raw: cliCursorModeState.raw, message: cliCursorModeState.message };
 		case "unset":
-			return sessionCursorAgentMode ?? DEFAULT_CURSOR_AGENT_MODE;
+			return { kind: "valid", mode: getStoredCursorAgentMode() };
 	}
 }
 
+export function getCursorProviderAgentModeOrThrow(): AgentModeOption {
+	const resolution = resolveCursorAgentMode();
+	if (resolution.kind === "invalid") throw new Error(resolution.message);
+	return resolution.mode;
+}
+
 function formatCursorStatus(fast: boolean | undefined): string | undefined {
 	const parts: string[] = [];
+	const modeResolution = resolveCursorAgentMode();
 	if (fast === true) parts.push("fast");
-	if (cliCursorModeState.kind === "invalid") {
+	if (modeResolution.kind === "invalid") {
 		parts.push("mode invalid");
-	} else if (getEffectiveCursorAgentMode() === "plan") {
+	} else if (modeResolution.mode === "plan") {
 		parts.push("plan");
 	}
 	return parts.length > 0 ? `cursor ${parts.join(" · ")}` : undefined;
@@ -255,7 +273,7 @@ function persistCursorModePreference(pi: Pick<ExtensionAPI, "appendEntry">, mode
 	}
 }
 
-function restoreCliCursorMode(raw: boolean | string | undefined, mode: ExtensionContext["mode"], notify: ExtensionContext["ui"]["notify"]): void {
+function restoreCliCursorMode(raw: boolean | string | undefined): void {
 	cliCursorModeState = { kind: "unset" };
 	if (raw === undefined || raw === "" || raw === false) return;
 	const parsed = parseCursorAgentMode(raw);
@@ -266,15 +284,19 @@ function restoreCliCursorMode(raw: boolean | string | undefined, mode: Extension
 	const rawText = String(raw);
 	const message = formatInvalidCursorMode(rawText);
 	cliCursorModeState = { kind: "invalid", raw: rawText, message };
-	if (mode === "tui") {
-		notify(message, "error");
-		return;
-	}
-	throw new Error(message);
+}
+
+function notifyInvalidCursorModeIfCursorActive(ctx: Pick<ExtensionContext, "hasUI" | "mode" | "ui">): void {
+	const modeResolution = resolveCursorAgentMode();
+	if (modeResolution.kind !== "invalid" || !ctx.hasUI || ctx.mode !== "tui") return;
+	const scopeKey = getCursorSessionScopeKey();
+	if (invalidCursorModeNotifiedSessionScopeKeys.has(scopeKey)) return;
+	invalidCursorModeNotifiedSessionScopeKeys.add(scopeKey);
+	ctx.ui.notify(modeResolution.message, "error");
 }
 
 function formatEffectiveCursorSettingSourcesLabel(raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV]): string {
-	const effective = getEffectiveCursorSettingSources(raw);
+	const effective = resolveCursorSettingSources(raw);
 	const effectiveLabel = effective === undefined ? "none" : effective.join(",");
 	const rawLabel = raw?.trim() ? raw.trim() : "(unset → all)";
 	return `${rawLabel} (effective: ${effectiveLabel})`;
@@ -395,10 +417,11 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 			const usage = "Usage: /cursor-mode agent|plan";
 			const mode = parseCursorAgentMode(args);
 			if (!args.trim()) {
-				try {
-					ctx.ui.notify(`Cursor mode is ${getEffectiveCursorAgentMode()}. ${usage}`, "info");
-				} catch (error) {
-					ctx.ui.notify(`${error instanceof Error ? error.message : String(error)} ${usage}`, "error");
+				const modeResolution = resolveCursorAgentMode();
+				if (modeResolution.kind === "invalid") {
+					ctx.ui.notify(`${modeResolution.message} ${usage}`, "error");
+				} else {
+					ctx.ui.notify(`Cursor mode is ${modeResolution.mode}. ${usage}`, "info");
 				}
 				return;
 			}
@@ -429,28 +452,26 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 		},
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
-		globalFastPreferences = loadGlobalFastPreferences();
-		cliForceFast = pi.getFlag("cursor-fast") === true;
-		cliForceNoFast = pi.getFlag("cursor-no-fast") === true;
-		restoreSessionFastPreferences(ctx);
-		restoreSessionCursorMode(ctx);
-		restoreCliCursorMode(pi.getFlag("cursor-mode"), ctx.mode, ctx.ui.notify.bind(ctx.ui));
-		updateCursorStatus(ctx);
-	});
-
-	pi.on("model_select", async (event, ctx) => {
-		updateCursorStatus(ctx, event.model);
-	});
-
-	pi.on("turn_start", async (_event, ctx) => {
-		updateCursorStatus(ctx);
+	registerCursorModelLifecycle(pi, {
+		sessionStart: (_event, ctx) => {
+			globalFastPreferences = loadGlobalFastPreferences();
+			cliForceFast = pi.getFlag("cursor-fast") === true;
+			cliForceNoFast = pi.getFlag("cursor-no-fast") === true;
+			restoreSessionFastPreferences(ctx);
+			restoreSessionCursorMode(ctx);
+			restoreCliCursorMode(pi.getFlag("cursor-mode"));
+		},
+		sync: (ctx) => {
+			if (isCursorModel(ctx.model)) notifyInvalidCursorModeIfCursorActive(ctx);
+			updateCursorStatus(ctx);
+		},
 	});
 }
 
 function resetCursorModeStateForTests(): void {
 	sessionCursorAgentMode = undefined;
 	cliCursorModeState = { kind: "unset" };
+	invalidCursorModeNotifiedSessionScopeKeys.clear();
 }
 
 export const __testUtils = {

package/src/cursor-tool-lifecycle.ts

@@ -1,9 +1,10 @@
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { getCursorToolLifecycleLabelKind } from "./cursor-tool-presentation-registry.js";
-import { extractWebSearchQuery } from "./cursor-web-tool-activity.js";
-import { firstNonEmptyLine, getArray, getString, truncateArg } from "./cursor-transcript-utils.js";
-import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
+import { extractWebSearchQuery } from "./cursor-web-tool-args.js";
+import { getArray, getString } from "./cursor-record-utils.js";
+import { firstNonEmptyLine, truncateArg } from "./cursor-transcript-utils.js";
+import { classifyCursorToolVisibility, type CursorToolVisibility } from "./cursor-tool-visibility.js";
 
 /** Defer pending lifecycle lines so fast start+complete pairs coalesce into the completed replay card only. */
 export const CURSOR_TOOL_LIFECYCLE_DEFER_MS = 75;
@@ -12,8 +13,7 @@ export function isCursorToolLifecycleEligible(toolCall: unknown): boolean {
 	return classifyCursorToolVisibility(toolCall).lifecycleEligible;
 }
 
-function getCursorToolLifecycleTitle(toolCall: unknown): string {
-	const visibility = classifyCursorToolVisibility(toolCall);
+function getCursorToolLifecycleTitle(visibility: CursorToolVisibility): string {
 	return visibility.lifecycleTitle ?? `Cursor ${visibility.normalizedName}`;
 }
 
@@ -36,8 +36,10 @@ function scrubLifecycleDetail(value: string | undefined, apiKey?: string): strin
 	return scrubbed;
 }
 
-export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
-	const visibility = classifyCursorToolVisibility(toolCall);
+function buildCursorToolLifecycleLabelFromVisibility(
+	visibility: CursorToolVisibility,
+	apiKey?: string,
+): string | undefined {
 	const args = visibility.args;
 
 	switch (getCursorToolLifecycleLabelKind(visibility.normalizedKey)) {
@@ -79,8 +81,13 @@ export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string
 	}
 }
 
+export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
+	return buildCursorToolLifecycleLabelFromVisibility(classifyCursorToolVisibility(toolCall), apiKey);
+}
+
 export function formatCursorToolLifecycleProgressText(toolCall: unknown, apiKey?: string): string | undefined {
-	const label = buildCursorToolLifecycleLabel(toolCall, apiKey);
+	const visibility = classifyCursorToolVisibility(toolCall);
+	const label = buildCursorToolLifecycleLabelFromVisibility(visibility, apiKey);
 	if (!label) return undefined;
-	return `${getCursorToolLifecycleTitle(toolCall)}: ${label}\n`;
+	return `${getCursorToolLifecycleTitle(visibility)}: ${label}\n`;
 }