pi-cursor-sdk 0.1.13 → 0.1.15

package/src/cursor-question-tool.ts

@@ -0,0 +1,247 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge.js";
+
+export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
+
+interface CursorQuestionOption {
+	label: string;
+	value: string;
+	description?: string;
+}
+
+interface CursorQuestion {
+	id: string;
+	question: string;
+	options: CursorQuestionOption[];
+	allowCustom: boolean;
+}
+
+interface CursorQuestionAnswer {
+	id: string;
+	question: string;
+	answer: string | null;
+	value?: string;
+	wasCustom: boolean;
+	cancelled: boolean;
+}
+
+interface CursorQuestionDetails {
+	questions: CursorQuestion[];
+	answers: CursorQuestionAnswer[];
+	uiAvailable: boolean;
+	cancelled: boolean;
+}
+
+type RawQuestionOption = string | { label?: string; value?: string; description?: string };
+
+type RawQuestion = {
+	id?: string;
+	question?: string;
+	prompt?: string;
+	options?: RawQuestionOption[];
+	choices?: RawQuestionOption[];
+	allowCustom?: boolean;
+};
+
+type CursorAskQuestionParams = RawQuestion & {
+	questions?: RawQuestion[];
+};
+
+const QuestionOptionSchema = Type.Union([
+	Type.String(),
+	Type.Object({
+		label: Type.String({ description: "User-facing option label" }),
+		value: Type.Optional(Type.String({ description: "Optional value returned to Cursor; defaults to label" })),
+		description: Type.Optional(Type.String({ description: "Optional helper text shown by compatible pi UIs" })),
+	}),
+]);
+
+const QuestionSchema = Type.Object({
+	id: Type.Optional(Type.String({ description: "Stable question identifier" })),
+	question: Type.Optional(Type.String({ description: "Question to ask the user" })),
+	prompt: Type.Optional(Type.String({ description: "Alias for question" })),
+	options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Choices the user can select" })),
+	choices: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Alias for options" })),
+	allowCustom: Type.Optional(Type.Boolean({ description: "Allow a typed answer in addition to listed options; defaults to true" })),
+});
+
+const CursorAskQuestionParamsSchema = Type.Object({
+	question: Type.Optional(Type.String({ description: "Question to ask the user" })),
+	prompt: Type.Optional(Type.String({ description: "Alias for question" })),
+	options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Choices the user can select" })),
+	choices: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Alias for options" })),
+	allowCustom: Type.Optional(Type.Boolean({ description: "Allow a typed answer in addition to listed options; defaults to true" })),
+	questions: Type.Optional(Type.Array(QuestionSchema, { description: "Ask multiple questions sequentially" })),
+});
+
+function isCursorModel(model: ExtensionContext["model"]): boolean {
+	return model?.provider === "cursor" || model?.api === "cursor-sdk";
+}
+
+function normalizeOption(option: RawQuestionOption, index: number): CursorQuestionOption | undefined {
+	if (typeof option === "string") {
+		const trimmed = option.trim();
+		return trimmed ? { label: trimmed, value: trimmed } : undefined;
+	}
+	const label = option.label?.trim() || option.value?.trim() || `Option ${index + 1}`;
+	return {
+		label,
+		value: option.value?.trim() || label,
+		...(option.description?.trim() ? { description: option.description.trim() } : {}),
+	};
+}
+
+function normalizeOptions(options: RawQuestionOption[] | undefined): CursorQuestionOption[] {
+	return (options ?? []).map(normalizeOption).filter((option): option is CursorQuestionOption => option !== undefined);
+}
+
+function normalizeQuestion(raw: RawQuestion, index: number): CursorQuestion | undefined {
+	const question = raw.question?.trim() || raw.prompt?.trim();
+	if (!question) return undefined;
+	return {
+		id: raw.id?.trim() || `question_${index + 1}`,
+		question,
+		options: normalizeOptions(raw.options ?? raw.choices),
+		allowCustom: raw.allowCustom !== false,
+	};
+}
+
+function normalizeQuestions(params: CursorAskQuestionParams): CursorQuestion[] {
+	const rawQuestions = Array.isArray(params.questions) && params.questions.length > 0 ? params.questions : [params];
+	return rawQuestions.map(normalizeQuestion).filter((question): question is CursorQuestion => question !== undefined);
+}
+
+function summarizeAnswers(answers: CursorQuestionAnswer[]): string {
+	if (answers.length === 0) return "No answer was collected.";
+	if (answers.length === 1) {
+		const [answer] = answers;
+		return answer.cancelled || answer.answer === null ? "User cancelled the question." : `User answered: ${answer.answer}`;
+	}
+	return [
+		"User answered:",
+		...answers.map((answer) => {
+			const value = answer.cancelled || answer.answer === null ? "cancelled" : answer.answer;
+			return `- ${answer.id}: ${value}`;
+		}),
+	].join("\n");
+}
+
+function buildDetails(questions: CursorQuestion[], answers: CursorQuestionAnswer[], uiAvailable: boolean): CursorQuestionDetails {
+	return {
+		questions,
+		answers,
+		uiAvailable,
+		cancelled: answers.some((answer) => answer.cancelled),
+	};
+}
+
+async function askOneQuestion(question: CursorQuestion, ctx: { ui: ExtensionContext["ui"] }): Promise<CursorQuestionAnswer> {
+	if (question.options.length > 0) {
+		const labels = question.options.map((option) => option.description ? `${option.label} — ${option.description}` : option.label);
+		const customLabel = "Type a custom answer";
+		const choices = question.allowCustom ? [...labels, customLabel] : labels;
+		const selected = await ctx.ui.select(question.question, choices);
+		if (!selected) {
+			return { id: question.id, question: question.question, answer: null, wasCustom: false, cancelled: true };
+		}
+		if (selected === customLabel) {
+			const customAnswer = await ctx.ui.input(question.question, "Type your answer");
+			const trimmed = customAnswer?.trim();
+			return trimmed
+				? { id: question.id, question: question.question, answer: trimmed, value: trimmed, wasCustom: true, cancelled: false }
+				: { id: question.id, question: question.question, answer: null, wasCustom: true, cancelled: true };
+		}
+		const selectedIndex = labels.indexOf(selected);
+		const selectedOption = selectedIndex >= 0 ? question.options[selectedIndex] : undefined;
+		const answer = selectedOption?.label ?? selected;
+		return {
+			id: question.id,
+			question: question.question,
+			answer,
+			value: selectedOption?.value ?? answer,
+			wasCustom: false,
+			cancelled: false,
+		};
+	}
+
+	const answer = await ctx.ui.input(question.question, "Type your answer");
+	const trimmed = answer?.trim();
+	return trimmed
+		? { id: question.id, question: question.question, answer: trimmed, value: trimmed, wasCustom: true, cancelled: false }
+		: { id: question.id, question: question.question, answer: null, wasCustom: true, cancelled: true };
+}
+
+function syncCursorQuestionToolForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
+	const activeToolNames = new Set(pi.getActiveTools());
+	const shouldBeActive = isCursorModel(model) && resolveCursorPiToolBridgeEnabled();
+	const alreadyActive = activeToolNames.has(CURSOR_ASK_QUESTION_TOOL_NAME);
+	if (shouldBeActive === alreadyActive) return;
+	if (shouldBeActive) {
+		activeToolNames.add(CURSOR_ASK_QUESTION_TOOL_NAME);
+	} else {
+		activeToolNames.delete(CURSOR_ASK_QUESTION_TOOL_NAME);
+	}
+	pi.setActiveTools([...activeToolNames]);
+}
+
+export function registerCursorQuestionTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		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.",
+		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.",
+		],
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const questions = normalizeQuestions(params as CursorAskQuestionParams);
+			if (questions.length === 0) {
+				return {
+					content: [{ type: "text" as const, text: "No valid question was provided." }],
+					details: buildDetails([], [], ctx.hasUI),
+					isError: true,
+				};
+			}
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Cannot ask the user because pi UI is unavailable. Make a reasonable default choice and state the assumption before proceeding.",
+						},
+					],
+					details: buildDetails(questions, [], false),
+					isError: true,
+				};
+			}
+
+			const answers: CursorQuestionAnswer[] = [];
+			for (const question of questions) {
+				const answer = await askOneQuestion(question, ctx);
+				answers.push(answer);
+				if (answer.cancelled) break;
+			}
+
+			return {
+				content: [{ type: "text" as const, text: summarizeAnswers(answers) }],
+				details: buildDetails(questions, answers, true),
+			};
+		},
+		renderCall(args, theme) {
+			const questions = normalizeQuestions(args as CursorAskQuestionParams);
+			const label = questions[0]?.question ?? "Ask the user";
+			return new Text(theme.fg("toolTitle", theme.bold("cursor question ")) + theme.fg("muted", label), 0, 0);
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		syncCursorQuestionToolForModel(pi, ctx.model);
+	});
+	pi.on("model_select", (event) => {
+		syncCursorQuestionToolForModel(pi, event.model);
+	});
+}

package/src/cursor-session-cwd.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const state = {
+	sessionCwd: process.cwd(),
+};
+
+/**
+ * Pi session cwd when known; falls back to process.cwd() before session_start.
+ * Updated on session_start only until pi threads cwd into streamSimple—mid-session cwd
+ * changes without a new session_start event are not reflected here.
+ */
+export function getCursorSessionCwd(): string {
+	return state.sessionCwd;
+}
+
+function setCursorSessionCwd(cwd: string): void {
+	state.sessionCwd = cwd;
+}
+
+function resetCursorSessionCwd(): void {
+	state.sessionCwd = process.cwd();
+}
+
+export function registerCursorSessionCwd(pi: ExtensionAPI): void {
+	pi.on("session_start", (_event, ctx) => {
+		setCursorSessionCwd(ctx.cwd);
+	});
+}
+
+export const __testUtils = {
+	set: setCursorSessionCwd,
+	reset: resetCursorSessionCwd,
+};

package/src/cursor-tool-names.ts

@@ -0,0 +1,67 @@
+export const CURSOR_REPLAY_ACTIVITY_TOOL_NAME = "cursor";
+
+export const CURSOR_REPLAY_LEGACY_TOOL_NAMES = [
+	"cursor_edit",
+	"cursor_write",
+	"cursor_read_lints",
+	"cursor_delete",
+	"cursor_update_todos",
+	"cursor_task",
+	"cursor_create_plan",
+	"cursor_generate_image",
+	"cursor_mcp",
+] as const;
+
+export type CursorReplayLegacyToolName = (typeof CURSOR_REPLAY_LEGACY_TOOL_NAMES)[number];
+export type CursorReplayToolName = typeof CURSOR_REPLAY_ACTIVITY_TOOL_NAME | CursorReplayLegacyToolName;
+
+const CURSOR_REPLAY_SOURCE_TOOL_NAMES = {
+	cursor_edit: "edit",
+	cursor_write: "write",
+	cursor_read_lints: "readLints",
+	cursor_delete: "delete",
+	cursor_update_todos: "updateTodos",
+	cursor_task: "task",
+	cursor_create_plan: "createPlan",
+	cursor_generate_image: "generateImage",
+	cursor_mcp: "MCP",
+} as const satisfies Record<CursorReplayLegacyToolName, string>;
+
+const CURSOR_REPLAY_PROMPT_LABELS = {
+	cursor_edit: "Cursor edit",
+	cursor_write: "Cursor write",
+	cursor_read_lints: "Cursor diagnostics",
+	cursor_delete: "Cursor delete",
+	cursor_update_todos: "Cursor todos",
+	cursor_task: "Cursor task",
+	cursor_create_plan: "Cursor plan",
+	cursor_generate_image: "Cursor image generation",
+	cursor_mcp: "Cursor MCP",
+} as const satisfies Record<CursorReplayLegacyToolName, string>;
+
+export function isCursorReplayLegacyToolName(toolName: string): toolName is CursorReplayLegacyToolName {
+	return CURSOR_REPLAY_LEGACY_TOOL_NAMES.some((legacyToolName) => legacyToolName === toolName);
+}
+
+export function isCursorReplayToolName(toolName: string): toolName is CursorReplayToolName {
+	return toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME || isCursorReplayLegacyToolName(toolName);
+}
+
+export function isExcludedFromCursorBridgeExposure(toolName: string): boolean {
+	return isCursorReplayLegacyToolName(toolName) || toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME;
+}
+
+export function getCursorReplaySourceToolName(toolName: CursorReplayLegacyToolName): string {
+	return CURSOR_REPLAY_SOURCE_TOOL_NAMES[toolName];
+}
+
+export function getCursorReplayPromptLabel(toolName: string): string {
+	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return "Cursor activity";
+	if (isCursorReplayLegacyToolName(toolName)) return CURSOR_REPLAY_PROMPT_LABELS[toolName];
+	return toolName;
+}
+
+export function getCursorReplayDisplayLabel(toolName: CursorReplayToolName): string {
+	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return "Cursor activity";
+	return CURSOR_REPLAY_PROMPT_LABELS[toolName];
+}