pi-cursor-sdk 0.1.28 → 0.1.30

package/src/cursor-run-final-text.ts

@@ -1,4 +1,5 @@
-import { hasUsableText } from "./cursor-record-utils.js";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { asRecord, hasUsableText } from "./cursor-record-utils.js";
 
 function isCursorTextBoundary(text: string, index: number): boolean {
 	if (index <= 0 || index >= text.length) return true;
@@ -39,6 +40,15 @@ export function trimCurrentTurnAlreadyEmittedCursorText(
 	return trimAlreadyEmittedCursorText(text, emittedText);
 }
 
+export function getFinalAssistantText(message: Pick<AssistantMessage, "content">): string {
+	for (let index = message.content.length - 1; index >= 0; index--) {
+		const block = asRecord(message.content[index]);
+		if (block?.type !== "text" || typeof block.text !== "string") continue;
+		if (hasUsableText(block.text)) return block.text;
+	}
+	return "";
+}
+
 export function selectCursorFinalText(
 	resultText: unknown,
 	textDeltas: readonly string[],

package/src/cursor-skill-tool.ts

@@ -0,0 +1,273 @@
+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";
+
+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 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 CursorActivateSkillParams = {
+	name?: string;
+};
+
+interface CursorSkillActivationDetails {
+	name?: string;
+	filePath?: string;
+	baseDir?: string;
+	resources: string[];
+	availableSkillNames: string[];
+}
+
+let currentSkillsByName = new Map<string, Skill>();
+
+function escapeXml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/\"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+function getVisibleSkills(skills: readonly Skill[] | undefined): Skill[] {
+	return (skills ?? []).filter((skill) => !skill.disableModelInvocation);
+}
+
+function setCurrentSkills(skills: readonly Skill[] | undefined): void {
+	currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
+}
+
+function getAvailableSkillNames(): string[] {
+	return [...currentSkillsByName.keys()].sort();
+}
+
+function shouldExposeSkillTool(model: ExtensionContext["model"]): boolean {
+	return isCursorModel(model) && resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
+}
+
+function syncCursorSkillToolForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
+	const activeToolNames = new Set(pi.getActiveTools());
+	const shouldBeActive = shouldExposeSkillTool(model);
+	const alreadyActive = activeToolNames.has(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+	if (shouldBeActive === alreadyActive) return;
+	if (shouldBeActive) {
+		activeToolNames.add(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+	} else {
+		activeToolNames.delete(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+	}
+	pi.setActiveTools([...activeToolNames]);
+}
+
+export function formatCursorSkillsForPrompt(skills: readonly Skill[]): string {
+	const visibleSkills = getVisibleSkills(skills);
+	if (visibleSkills.length === 0) return "";
+
+	const lines = [
+		"\n\nThe following skills provide specialized instructions for specific tasks.",
+		`When a task matches a skill's description, call ${CURSOR_ACTIVATE_SKILL_MCP_NAME} with the skill name to load its full SKILL.md instructions before proceeding.`,
+		"If the pi bridge is disabled and the activation tool is unavailable, use Cursor's file-read capability on the listed SKILL.md location instead.",
+		"When a skill references relative paths, resolve them against the skill directory (the parent of SKILL.md / dirname of the path) and use absolute paths in tool calls.",
+		"",
+		"<available_skills>",
+	];
+	for (const skill of visibleSkills) {
+		lines.push("  <skill>");
+		lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+		lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+		lines.push("  </skill>");
+	}
+	lines.push("</available_skills>");
+	return lines.join("\n");
+}
+
+export function resolveCursorSkillSystemPrompt(
+	systemPrompt: string,
+	model: ExtensionContext["model"],
+	systemPromptOptions?: BuildSystemPromptOptions,
+): string {
+	if (!isCursorModel(model)) return systemPrompt;
+	const skills = getVisibleSkills(systemPromptOptions?.skills);
+	if (skills.length === 0) return systemPrompt;
+	const replacement = formatCursorSkillsForPrompt(skills);
+	if (AVAILABLE_SKILLS_SECTION_PATTERN.test(systemPrompt)) {
+		return systemPrompt.replace(AVAILABLE_SKILLS_SECTION_PATTERN, replacement);
+	}
+	return `${systemPrompt}${replacement}`;
+}
+
+async function collectResourcePaths(root: string, absoluteDir: string, output: string[]): Promise<void> {
+	if (output.length >= MAX_SKILL_RESOURCES) return;
+	let entries: Dirent[];
+	try {
+		entries = await readdir(absoluteDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+		if (output.length >= MAX_SKILL_RESOURCES) return;
+		const absolutePath = join(absoluteDir, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) {
+			await collectResourcePaths(root, absolutePath, output);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		output.push(relative(root, absolutePath).replace(/\\/g, "/"));
+	}
+}
+
+async function listSkillResourcePaths(baseDir: string): Promise<string[]> {
+	const resources: string[] = [];
+	for (const resourceDirName of RESOURCE_DIR_NAMES) {
+		await collectResourcePaths(baseDir, join(baseDir, resourceDirName), resources);
+		if (resources.length >= MAX_SKILL_RESOURCES) break;
+	}
+	return resources;
+}
+
+function buildActivationDetails(skill: Skill | undefined, resources: string[] = []): CursorSkillActivationDetails {
+	return {
+		name: skill?.name,
+		filePath: skill?.filePath,
+		baseDir: skill ? dirname(skill.filePath) : undefined,
+		resources,
+		availableSkillNames: getAvailableSkillNames(),
+	};
+}
+
+function formatSkillResources(resources: readonly string[]): string {
+	if (resources.length === 0) return "<skill_resources />";
+	return [
+		"<skill_resources>",
+		...resources.map((resource) => `  <file>${escapeXml(resource)}</file>`),
+		"</skill_resources>",
+	].join("\n");
+}
+
+function wrapSkillContent(skill: Skill, content: string, resources: readonly string[]): string {
+	const baseDir = dirname(skill.filePath);
+	return [
+		`<skill_content name=\"${escapeXml(skill.name)}\">`,
+		content.trim(),
+		"",
+		`Skill directory: ${baseDir}`,
+		"Relative paths in this skill are relative to the skill directory.",
+		formatSkillResources(resources),
+		"</skill_content>",
+	].join("\n");
+}
+
+export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
+	pi.registerTool({
+		name: CURSOR_ACTIVATE_SKILL_TOOL_NAME,
+		label: "Cursor skill",
+		description: "Load full pi Agent Skill instructions for Cursor. Use with a skill name from the current <available_skills> catalog before applying that skill.",
+		parameters: Type.Object({
+			name: Type.String({ description: "Skill name from the current <available_skills> catalog" }),
+		}),
+		promptGuidelines: [
+			`Use ${CURSOR_ACTIVATE_SKILL_TOOL_NAME} only for skill names listed in the current <available_skills> catalog.`,
+			"After loading a skill, follow its instructions and resolve relative skill paths against the returned skill directory.",
+		],
+		async execute(_toolCallId, params) {
+			const requestedName = (params as CursorActivateSkillParams).name?.trim();
+			if (!requestedName) {
+				return {
+					content: [{ type: "text" as const, text: "No skill name was provided." }],
+					details: buildActivationDetails(undefined),
+					isError: true,
+				};
+			}
+			const skill = currentSkillsByName.get(requestedName);
+			if (!skill) {
+				return {
+					content: [{ type: "text" as const, text: `Skill not available: ${requestedName}. Available skills: ${getAvailableSkillNames().join(", ") || "none"}.` }],
+					details: buildActivationDetails(undefined),
+					isError: true,
+				};
+			}
+
+			try {
+				const [content, resources] = await Promise.all([
+					readFile(skill.filePath, "utf8"),
+					listSkillResourcePaths(dirname(skill.filePath)),
+				]);
+				return {
+					content: [{ type: "text" as const, text: wrapSkillContent(skill, content, resources) }],
+					details: buildActivationDetails(skill, resources),
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Failed to load skill ${requestedName} from ${skill.filePath}: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					],
+					details: buildActivationDetails(skill),
+					isError: true,
+				};
+			}
+		},
+	});
+
+	const clearSkillsAndSync = (model: ExtensionContext["model"]): void => {
+		setCurrentSkills([]);
+		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 };
+	});
+}
+
+export const __testUtils = {
+	AVAILABLE_SKILLS_SECTION_PATTERN,
+	buildActivationDetails,
+	setCurrentSkills,
+	listSkillResourcePaths,
+	wrapSkillContent,
+};

package/src/cursor-state.ts

@@ -29,7 +29,8 @@ export type CursorAgentMode = AgentModeOption;
 const DEFAULT_CURSOR_AGENT_MODE: AgentModeOption = "agent";
 
 interface CursorFastEntryData {
-	baseModelId: string;
+	modelId?: string;
+	baseModelId?: string;
 	fast: boolean;
 }
 
@@ -71,7 +72,11 @@ export function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined
 function isCursorFastEntryData(value: unknown): value is CursorFastEntryData {
 	if (!value || typeof value !== "object") return false;
 	const data = value as Record<string, unknown>;
-	return typeof data.baseModelId === "string" && typeof data.fast === "boolean";
+	return (typeof data.modelId === "string" || typeof data.baseModelId === "string") && typeof data.fast === "boolean";
+}
+
+function getCursorFastEntryModelId(data: CursorFastEntryData): string {
+	return data.modelId ?? data.baseModelId ?? "";
 }
 
 function isCursorModeEntryData(value: unknown): value is CursorModeEntryData {
@@ -113,7 +118,8 @@ function restoreSessionFastPreferences(ctx: { sessionManager: Pick<ExtensionCont
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type !== "custom" || entry.customType !== FAST_ENTRY_TYPE) continue;
 		if (isCursorFastEntryData(entry.data)) {
-			sessionFastPreferences.set(entry.data.baseModelId, entry.data.fast);
+			const modelId = getCursorFastEntryModelId(entry.data);
+			if (modelId) sessionFastPreferences.set(modelId, entry.data.fast);
 		}
 	}
 }
@@ -128,12 +134,26 @@ function restoreSessionCursorMode(ctx: { sessionManager: Pick<ExtensionContext["
 	}
 }
 
-function getEffectiveFast(baseModelId: string, modelId: string): boolean | undefined {
+function getFastPreferenceModelId(metadata: NonNullable<ReturnType<typeof getCursorModelMetadata>>): string {
+	return metadata.selectionModelId || metadata.baseModelId;
+}
+
+function getStoredFastPreference(metadata: NonNullable<ReturnType<typeof getCursorModelMetadata>>): boolean | undefined {
+	const preferenceModelId = getFastPreferenceModelId(metadata);
+	return (
+		sessionFastPreferences.get(preferenceModelId) ??
+		(preferenceModelId !== metadata.baseModelId ? sessionFastPreferences.get(metadata.baseModelId) : undefined) ??
+		globalFastPreferences.get(preferenceModelId) ??
+		(preferenceModelId !== metadata.baseModelId ? globalFastPreferences.get(metadata.baseModelId) : undefined)
+	);
+}
+
+function getEffectiveFast(modelId: string): boolean | undefined {
 	const metadata = getCursorModelMetadata(modelId);
 	if (!metadata?.supportsFast) return undefined;
 	if (cliForceNoFast) return false;
 	if (cliForceFast) return true;
-	return sessionFastPreferences.get(baseModelId) ?? globalFastPreferences.get(baseModelId) ?? metadata.defaultFast;
+	return getStoredFastPreference(metadata) ?? metadata.defaultFast;
 }
 
 function formatInvalidCursorMode(raw: string): string {
@@ -168,7 +188,7 @@ function updateCursorStatus(ctx: Pick<ExtensionContext, "model" | "ui">, model =
 		return;
 	}
 	const metadata = getCursorModelMetadata(model.id);
-	const fast = metadata?.supportsFast ? getEffectiveFast(metadata.baseModelId, model.id) : undefined;
+	const fast = metadata?.supportsFast ? getEffectiveFast(model.id) : undefined;
 	ctx.ui.setStatus("cursor", formatCursorStatus(fast));
 }
 
@@ -186,19 +206,19 @@ function restoreMapValue(map: Map<string, boolean>, key: string, previous: boole
 	}
 }
 
-function persistFastPreference(pi: Pick<ExtensionAPI, "appendEntry">, baseModelId: string, fast: boolean): void {
-	const previousSession = sessionFastPreferences.get(baseModelId);
-	const previousGlobal = globalFastPreferences.get(baseModelId);
+function persistFastPreference(pi: Pick<ExtensionAPI, "appendEntry">, modelId: string, fast: boolean): void {
+	const previousSession = sessionFastPreferences.get(modelId);
+	const previousGlobal = globalFastPreferences.get(modelId);
 	let savedGlobal = false;
-	sessionFastPreferences.set(baseModelId, fast);
-	globalFastPreferences.set(baseModelId, fast);
+	sessionFastPreferences.set(modelId, fast);
+	globalFastPreferences.set(modelId, fast);
 	try {
 		saveGlobalFastPreferences();
 		savedGlobal = true;
-		pi.appendEntry<CursorFastEntryData>(FAST_ENTRY_TYPE, { baseModelId, fast });
+		pi.appendEntry<CursorFastEntryData>(FAST_ENTRY_TYPE, { modelId, fast });
 	} catch (error) {
-		restoreMapValue(sessionFastPreferences, baseModelId, previousSession);
-		restoreMapValue(globalFastPreferences, baseModelId, previousGlobal);
+		restoreMapValue(sessionFastPreferences, modelId, previousSession);
+		restoreMapValue(globalFastPreferences, modelId, previousGlobal);
 		if (savedGlobal) {
 			try {
 				saveGlobalFastPreferences();
@@ -285,9 +305,7 @@ function emitCursorToolsDebugReport(
 }
 
 export function getEffectiveFastForModelId(modelId: string): boolean | undefined {
-	const metadata = getCursorModelMetadata(modelId);
-	if (!metadata) return undefined;
-	return getEffectiveFast(metadata.baseModelId, modelId);
+	return getEffectiveFast(modelId);
 }
 
 export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtensionApi): void {
@@ -327,10 +345,11 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 				return;
 			}
 
-			const current = getEffectiveFast(metadata.baseModelId, metadata.piModelId) ?? false;
+			const preferenceModelId = getFastPreferenceModelId(metadata);
+			const current = getEffectiveFast(metadata.piModelId) ?? false;
 			const next = !current;
 			try {
-				persistFastPreference(pi, metadata.baseModelId, next);
+				persistFastPreference(pi, preferenceModelId, next);
 			} catch (error) {
 				updateCursorStatus(ctx);
 				ctx.ui.notify(`Failed to save Cursor fast preference: ${error instanceof Error ? error.message : String(error)}`, "error");

package/src/cursor-tool-lifecycle.ts

@@ -45,7 +45,7 @@ export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string
 			return scrubLifecycleDetail(getString(args, "description"), apiKey) ?? "task";
 		}
 		case "shell": {
-			return "shell";
+			return scrubLifecycleDetail(getString(args, "command") ?? getString(args, "cmd"), apiKey);
 		}
 		case "mcp": {
 			return scrubLifecycleDetail(getString(args, "toolName"), apiKey) ?? "mcp";

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.16 local-agent ToolType values; actual exposure can vary by run.
+ * Representative @cursor/sdk@1.0.17 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-transcript-utils.ts

@@ -145,14 +145,18 @@ export function formatError(error: unknown): string {
 	return text ? `Error: ${text}` : "Error";
 }
 
+function normalizeDisplaySeparators(path: string): string {
+	return path.replace(/\\/g, "/");
+}
+
 export function formatDisplayPath(path: string, cwd = process.cwd()): string {
 	const trimmed = path.trim();
 	if (!trimmed) return trimmed;
-	if (!isAbsolute(trimmed)) return trimmed;
+	if (!isAbsolute(trimmed)) return normalizeDisplaySeparators(trimmed);
 	const relativePath = relative(cwd, trimmed);
 	if (!relativePath || relativePath === "") return ".";
-	if (relativePath.startsWith("..") || isAbsolute(relativePath)) return trimmed;
-	return relativePath;
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) return normalizeDisplaySeparators(trimmed);
+	return normalizeDisplaySeparators(relativePath);
 }
 
 export function formatDiffPath(path: string, cwd = process.cwd()): string {

package/src/index.ts

@@ -4,6 +4,7 @@ import { registerCursorRuntimeControls } from "./cursor-state.js";
 import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display.js";
 import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
+import { registerCursorSkillTool } from "./cursor-skill-tool.js";
 import { registerCursorSessionCwd } from "./cursor-session-cwd.js";
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context.js";
 import { registerCursorSessionAgent } from "./cursor-session-agent.js";
@@ -18,6 +19,7 @@ type CursorExtensionApi =
 	& Parameters<typeof registerCursorRuntimeControls>[0]
 	& Parameters<typeof registerCursorNativeToolDisplay>[0]
 	& Parameters<typeof registerCursorQuestionTool>[0]
+	& Parameters<typeof registerCursorSkillTool>[0]
 	& Parameters<typeof registerCursorPiToolBridge>[0]
 	& Parameters<typeof registerCursorAgentsContextDedup>[0];
 
@@ -46,6 +48,7 @@ export default async function (pi: CursorExtensionApi) {
 	registerCursorRuntimeControls(pi);
 	registerCursorNativeToolDisplay(pi);
 	registerCursorQuestionTool(pi);
+	registerCursorSkillTool(pi);
 	registerCursorPiToolBridge(pi);
 	registerCursorAgentsContextDedup(pi);
 	let fallbackIssue: CursorModelFallbackIssue | undefined;