pi-cursor-sdk 0.2.0 → 0.3.6

package/dist/context.js

@@ -0,0 +1,338 @@
+import { createHash } from "node:crypto";
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+import { CURSOR_PI_BRIDGE_PREFERENCE_TEXT } from "./cursor-bridge-contract.js";
+import { getCursorReplayPromptLabel } from "./cursor-tool-presentation-registry.js";
+export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
+export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
+const SECTION_SEPARATOR = "\n\n";
+export function getCursorPlanModeToolGuidanceText(agentMode, options = {}) {
+    if (agentMode !== "plan")
+        return undefined;
+    return [
+        "Cursor SDK mode is plan for this run. In pi-cursor-sdk, plan mode may still use available Cursor SDK/MCP tools for inspection when needed.",
+        "Safe/read-only shell commands that inspect or print information are allowed when Cursor chooses to call Shell; do not say Shell is blocked by plan mode and then call it anyway.",
+        options.includePiBridgeGuidance === false
+            ? undefined
+            : "Exposed pi__* bridge tools are also callable in plan mode when the user asks for them or they are needed to answer.",
+    ].filter((line) => line !== undefined).join("\n");
+}
+export function getCursorToolTailGuardText(options = {}) {
+    return [
+        "Shell: use explicit `cd` to repo path for project commands; session cwd may differ from tool args.",
+        options.includePlanModeGuidance === false
+            ? undefined
+            : getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance: options.includePiBridgeGuidance }),
+        "Exact-output requests: output exactly the requested text; no preamble or checks unless asked.",
+        "Tools: call available Cursor SDK/MCP tools; never print tool cards as assistant text.",
+        options.includePiBridgeGuidance === false ? undefined : CURSOR_PI_BRIDGE_PREFERENCE_TEXT,
+    ].filter((line) => line !== undefined).join("\n");
+}
+function getCursorToolBoundaryText(options = {}) {
+    const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
+    const includePiAskQuestionGuidance = includePiBridgeGuidance && options.includePiAskQuestionGuidance !== false;
+    const lines = [
+        "Cursor SDK tool boundary:",
+        "Call only Cursor SDK/MCP tools exposed in this run; pi history names, replay labels, and transcript names are not callable.",
+        includePiBridgeGuidance
+            ? "For exposed pi bridge tools, call pi__* MCP names, not pi card/history names."
+            : undefined,
+        "Do not claim pi-side or WebSearch/WebFetch tools unless Cursor ran an equivalent tool.",
+        includePiAskQuestionGuidance ? "Use pi__cursor_ask_question for material choices if exposed." : undefined,
+        getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance }),
+        "Images: only latest user images are sent; ask to reattach prior images.",
+    ].filter((line) => line !== undefined);
+    if (options.hasToolManifest) {
+        lines.push("See callable surfaces below.");
+    }
+    return lines.join("\n");
+}
+function getCursorBootstrapTailSections(options = {}) {
+    return [
+        "Answer the latest user request above using the instructions and Cursor SDK capabilities available in this run.",
+        getCursorToolTailGuardText({ ...options, includePlanModeGuidance: false }),
+    ];
+}
+function normalizePiContextMessages(messages) {
+    return convertToLlm(messages);
+}
+function isTextBlock(block) {
+    return block.type === "text";
+}
+function isImageBlock(block) {
+    return block.type === "image";
+}
+function isToolCallBlock(block) {
+    return block.type === "toolCall";
+}
+function extractLatestImages(messages) {
+    // Find the last user message and extract images only from it
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role !== "user")
+            continue;
+        if (typeof msg.content === "string")
+            return [];
+        const images = [];
+        for (const block of msg.content) {
+            if (isImageBlock(block) && block.data && block.mimeType) {
+                images.push({ data: block.data, mimeType: block.mimeType });
+            }
+        }
+        return images;
+    }
+    return [];
+}
+function formatContentBlocks(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .map((block) => {
+        if (isTextBlock(block))
+            return block.text;
+        if (isImageBlock(block))
+            return "[image omitted from transcript]";
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function formatToolCall(toolCall) {
+    const args = JSON.stringify(toolCall.arguments) ?? "";
+    return `Tool call (${getCursorReplayPromptLabel(toolCall.name)}, call ${toolCall.id}): ${args}`;
+}
+function sanitizeSystemPromptForCursor(systemPrompt) {
+    let sanitized = systemPrompt;
+    sanitized = sanitized.replace(/Available tools:\n[\s\S]*?\n\nIn addition to the tools above, you may have access to other custom tools depending on the project\.\n\n/g, "Pi tool catalog omitted: Cursor can call only Cursor SDK tools exposed in this run.\n\n");
+    sanitized = sanitized.replace(/Guidelines:\n[\s\S]*?\n\nPi documentation /g, "Guidelines:\n- Be concise in your responses.\n- Show file paths clearly when working with files.\n\nPi documentation ");
+    // Keep the Agent Skills catalog. Cursor-specific skill activation wording is normalized
+    // by cursor-skill-tool.ts before this prompt reaches the Cursor SDK provider.
+    sanitized = sanitized.replace(/\n+Semantic code intelligence priority:[\s\S]*$/g, "");
+    return sanitized.trim();
+}
+function formatMessage(msg) {
+    switch (msg.role) {
+        case "user": {
+            const text = formatContentBlocks(msg.content);
+            return text ? `User: ${text}` : undefined;
+        }
+        case "assistant": {
+            const blocks = Array.isArray(msg.content) ? msg.content : [{ type: "text", text: String(msg.content) }];
+            const textParts = [];
+            for (const block of blocks) {
+                if (isTextBlock(block)) {
+                    textParts.push(block.text);
+                }
+                else if (isToolCallBlock(block)) {
+                    textParts.push(formatToolCall(block));
+                }
+                // Omit thinking content from transcript
+            }
+            return textParts.length > 0 ? `Assistant: ${textParts.join("\n")}` : undefined;
+        }
+        case "toolResult": {
+            const text = formatContentBlocks(msg.content);
+            const label = msg.isError ? "Tool error" : "Tool result";
+            return `${label} (${getCursorReplayPromptLabel(msg.toolName)}, call ${msg.toolCallId}): ${text}`;
+        }
+    }
+}
+function getLatestUserMessageIndex(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        if (messages[index].role === "user")
+            return index;
+    }
+    return -1;
+}
+function getSectionCost(section) {
+    return section.length + SECTION_SEPARATOR.length;
+}
+function applyPromptBudget(sectionsBeforeMessages, messageSections, sectionsAfterMessages, latestUserMessageIndex, options) {
+    const maxInputTokens = options.maxInputTokens;
+    if (maxInputTokens === undefined || !Number.isFinite(maxInputTokens) || maxInputTokens <= 0) {
+        return [...sectionsBeforeMessages, ...messageSections.map((section) => section.text), ...sectionsAfterMessages];
+    }
+    const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_CHARS_PER_TOKEN;
+    const maxChars = Math.max(1, Math.floor(maxInputTokens * charsPerToken));
+    const requiredMessageSections = messageSections.filter((section) => section.index === latestUserMessageIndex);
+    const requiredCost = [...sectionsBeforeMessages, ...requiredMessageSections.map((section) => section.text), ...sectionsAfterMessages].reduce((total, section) => total + getSectionCost(section), 0);
+    let remainingChars = maxChars - requiredCost;
+    const includedMessageIndexes = new Set(requiredMessageSections.map((section) => section.index));
+    let omittedMessageCount = 0;
+    for (let index = messageSections.length - 1; index >= 0; index -= 1) {
+        const section = messageSections[index];
+        if (includedMessageIndexes.has(section.index))
+            continue;
+        const cost = getSectionCost(section.text);
+        if (cost <= remainingChars) {
+            includedMessageIndexes.add(section.index);
+            remainingChars -= cost;
+            continue;
+        }
+        omittedMessageCount += messageSections
+            .slice(0, index + 1)
+            .filter((candidate) => !includedMessageIndexes.has(candidate.index)).length;
+        break;
+    }
+    const budgetNotice = omittedMessageCount > 0
+        ? [`[Earlier transcript omitted: ${omittedMessageCount} message${omittedMessageCount === 1 ? "" : "s"} to fit Cursor context budget]`]
+        : [];
+    const includedMessages = messageSections
+        .filter((section) => includedMessageIndexes.has(section.index))
+        .map((section) => section.text);
+    return [...sectionsBeforeMessages, ...budgetNotice, ...includedMessages, ...sectionsAfterMessages];
+}
+export function estimateCursorTextTokens(text, options = {}) {
+    const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_CHARS_PER_TOKEN;
+    return Math.ceil(text.length / charsPerToken);
+}
+export function estimateCursorPromptTokens(prompt, options = {}) {
+    return estimateCursorTextTokens(prompt.text, options) + prompt.images.length * (options.imageTokenEstimate ?? CURSOR_IMAGE_TOKEN_ESTIMATE);
+}
+export function estimateCursorPromptMessageTokens(message, options = {}) {
+    const text = formatMessage(message);
+    return text ? estimateCursorTextTokens(text, options) : 0;
+}
+export function estimateCursorContextTokens(context, options = {}) {
+    return estimateCursorPromptTokens(buildCursorPrompt(context, options), options);
+}
+function hashCursorContextValue(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function serializeMessageForFingerprint(message, index) {
+    switch (message.role) {
+        case "user": {
+            const text = typeof message.content === "string"
+                ? message.content
+                : JSON.stringify(message.content);
+            return hashCursorContextValue(`user:${message.timestamp ?? index}:${text}`);
+        }
+        case "assistant":
+            return hashCursorContextValue(`assistant:${message.timestamp ?? index}:${JSON.stringify(message.content)}`);
+        case "toolResult":
+            return hashCursorContextValue(`toolResult:${message.timestamp ?? index}:${message.toolCallId}:${message.toolName}:${JSON.stringify(message.content)}:${message.isError === true}`);
+    }
+}
+function serializeRawPiMessageForFingerprint(message, index) {
+    const role = message.role;
+    switch (role) {
+        case "branchSummary": {
+            const entry = message;
+            return hashCursorContextValue(`branchSummary:${entry.timestamp ?? index}:${entry.fromId ?? ""}:${entry.summary ?? ""}`);
+        }
+        case "compactionSummary": {
+            const entry = message;
+            return hashCursorContextValue(`compactionSummary:${entry.timestamp ?? index}:${entry.tokensBefore ?? ""}:${entry.summary ?? ""}`);
+        }
+        case "custom": {
+            const entry = message;
+            return hashCursorContextValue(`custom:${entry.timestamp ?? index}:${entry.customType ?? ""}:${JSON.stringify(entry.content)}`);
+        }
+        case "bashExecution": {
+            const entry = message;
+            if (entry.excludeFromContext) {
+                return hashCursorContextValue(`bashExecution:excluded:${entry.timestamp ?? index}`);
+            }
+            return hashCursorContextValue(`bashExecution:${entry.timestamp ?? index}:${entry.command ?? ""}:${entry.output ?? ""}:${entry.exitCode ?? ""}:${entry.cancelled === true}`);
+        }
+        default:
+            return serializeMessageForFingerprint(message, index);
+    }
+}
+function parseCursorContextFingerprint(fingerprint) {
+    try {
+        const parsed = JSON.parse(fingerprint);
+        if (!parsed || typeof parsed.systemHash !== "string" || !Array.isArray(parsed.messageHashes))
+            return undefined;
+        if (!parsed.messageHashes.every((entry) => typeof entry === "string"))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function computeCursorContextFingerprint(context) {
+    const payload = {
+        systemHash: hashCursorContextValue(context.systemPrompt ?? ""),
+        messageHashes: context.messages.map((message, index) => serializeRawPiMessageForFingerprint(message, index)),
+    };
+    return JSON.stringify(payload);
+}
+export function shouldBootstrapCursorContext(sendState, context) {
+    if (!sendState.bootstrapped)
+        return true;
+    const previous = parseCursorContextFingerprint(sendState.contextFingerprint);
+    if (!previous)
+        return true;
+    const current = parseCursorContextFingerprint(computeCursorContextFingerprint(context));
+    if (!current)
+        return true;
+    if (current.systemHash !== previous.systemHash)
+        return true;
+    if (current.messageHashes.length < previous.messageHashes.length)
+        return true;
+    if (current.messageHashes.length > previous.messageHashes.length) {
+        for (let index = previous.messageHashes.length; index < context.messages.length; index += 1) {
+            const role = context.messages[index].role;
+            if (role === "branchSummary" || role === "compactionSummary")
+                return true;
+        }
+    }
+    for (let index = 0; index < previous.messageHashes.length; index += 1) {
+        if (current.messageHashes[index] !== previous.messageHashes[index])
+            return true;
+    }
+    return false;
+}
+/** @deprecated Use planCursorSessionSend() for send mode and shouldBootstrapCursorContext() for context-only checks. */
+export function shouldBootstrapCursorSend(sendState, context) {
+    return shouldBootstrapCursorContext(sendState, context);
+}
+export function buildCursorIncrementalPrompt(context, options = {}) {
+    // Incremental sends omit Pi system instructions and the full tool boundary; the session agent retains both from bootstrap.
+    const messages = normalizePiContextMessages(context.messages);
+    const latestUserMessageIndex = getLatestUserMessageIndex(messages);
+    const latestUserMessage = latestUserMessageIndex >= 0 ? messages[latestUserMessageIndex] : undefined;
+    const latestUserText = latestUserMessage ? formatMessage(latestUserMessage) : undefined;
+    const sectionsBeforeMessages = [
+        "Continue the conversation using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from earlier context as if they were available.",
+    ];
+    const latestUserMessageSections = latestUserText && latestUserMessageIndex >= 0 ? [{ index: latestUserMessageIndex, text: latestUserText }] : [];
+    const images = extractLatestImages(messages);
+    const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
+    const budgetOptions = options.maxInputTokens === undefined
+        ? options
+        : { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
+    const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [getCursorToolTailGuardText(options)], latestUserMessageIndex, budgetOptions);
+    return { text: parts.join(SECTION_SEPARATOR), images };
+}
+export function buildCursorPrompt(context, options = {}) {
+    const sectionsBeforeMessages = [getCursorToolBoundaryText({
+            agentMode: options.agentMode,
+            hasToolManifest: Boolean(options.toolManifest),
+            includePiBridgeGuidance: options.includePiBridgeGuidance,
+            includePiAskQuestionGuidance: options.includePiAskQuestionGuidance,
+        })];
+    if (options.toolManifest) {
+        sectionsBeforeMessages.push(options.toolManifest);
+    }
+    if (context.systemPrompt) {
+        sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
+    }
+    const messages = normalizePiContextMessages(context.messages);
+    const messageSections = messages
+        .map((msg, index) => {
+        const text = formatMessage(msg);
+        return text ? { index, text } : undefined;
+    })
+        .filter((section) => section !== undefined);
+    const sectionsAfterMessages = getCursorBootstrapTailSections(options);
+    const images = extractLatestImages(messages);
+    const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
+    const budgetOptions = options.maxInputTokens === undefined
+        ? options
+        : { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
+    const parts = applyPromptBudget(sectionsBeforeMessages, messageSections, sectionsAfterMessages, getLatestUserMessageIndex(messages), budgetOptions);
+    const text = parts.join(SECTION_SEPARATOR);
+    return { text, images };
+}

package/dist/cursor-active-tools.js

@@ -0,0 +1,3 @@
+export function arePiToolsDisabled(pi) {
+    return pi.getActiveTools().length === 0;
+}

package/dist/cursor-agent-message-web-tools.js

@@ -0,0 +1,165 @@
+import { asRecord, getArray, getString } from "./cursor-record-utils.js";
+import { stringifyUnknown } from "./cursor-transcript-utils.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+const CURSOR_AGENT_MESSAGE_PAGE_LIMIT = 8;
+function getOneofCaseValue(value, caseName) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    if (record.case === caseName)
+        return record.value;
+    return record[caseName];
+}
+async function hasCursorAgentMessageAt(agentId, cwd, offset, store) {
+    const { Agent } = await loadCursorSdk();
+    const messages = await Agent.messages.list(agentId, {
+        runtime: "local",
+        cwd,
+        ...(store ? { store } : {}),
+        limit: 1,
+        offset,
+    });
+    return messages.length > 0;
+}
+export async function countCursorAgentMessages(agentId, cwd, store) {
+    let high = 1;
+    while (await hasCursorAgentMessageAt(agentId, cwd, high, store)) {
+        high *= 2;
+    }
+    let low = 0;
+    while (low < high) {
+        const mid = Math.floor((low + high) / 2);
+        if (await hasCursorAgentMessageAt(agentId, cwd, mid, store))
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    return low;
+}
+export async function loadCursorTranscriptWebToolCallsAfterOffset(options) {
+    if (options.offset === undefined)
+        return [];
+    const { Agent } = await loadCursorSdk();
+    const messages = await Agent.messages.list(options.agentId, {
+        runtime: "local",
+        cwd: options.cwd,
+        ...(options.store ? { store: options.store } : {}),
+        limit: CURSOR_AGENT_MESSAGE_PAGE_LIMIT,
+        offset: options.offset,
+    });
+    return collectCursorTranscriptWebToolCalls(messages);
+}
+export function collectCursorTranscriptWebToolCalls(messages) {
+    const toolCalls = [];
+    for (const [messageIndex, message] of messages.entries()) {
+        const messageId = message.uuid || `${message.agent_id || "cursor-agent"}:${messageIndex}`;
+        const steps = getAgentConversationSteps(message.message);
+        for (const [stepIndex, step] of steps.entries()) {
+            const webTool = getStepWebToolPayload(step);
+            if (!webTool)
+                continue;
+            const converted = convertCursorTranscriptWebTool(webTool);
+            if (!converted)
+                continue;
+            const args = asRecord(converted.args);
+            const toolCallId = getString(args, "toolCallId") ?? getString(args, "tool_call_id") ?? `${stepIndex}`;
+            toolCalls.push({
+                identity: `cursor-transcript:${messageId}:${webTool.kind}:${toolCallId}`,
+                toolCall: converted,
+            });
+        }
+    }
+    return toolCalls;
+}
+function getAgentConversationSteps(message) {
+    const record = asRecord(message);
+    const turn = getOneofCaseValue(record?.turn, "agentConversationTurn") ?? record?.agentConversationTurn;
+    return getArray(asRecord(turn), "steps") ?? [];
+}
+function getStepToolCall(step) {
+    const stepRecord = asRecord(step);
+    const message = asRecord(stepRecord?.message);
+    return getOneofCaseValue(message, "toolCall") ?? stepRecord?.toolCall ?? message?.toolCall;
+}
+function getStepWebToolPayload(step) {
+    const toolCall = getStepToolCall(step);
+    const toolCallRecord = asRecord(toolCall);
+    const tool = toolCallRecord?.tool;
+    const webSearchPayload = getOneofCaseValue(tool, "webSearchToolCall") ??
+        getOneofCaseValue(toolCall, "webSearchToolCall") ??
+        toolCallRecord?.webSearchToolCall;
+    if (webSearchPayload)
+        return { kind: "webSearch", payload: webSearchPayload };
+    const webFetchPayload = getOneofCaseValue(tool, "webFetchToolCall") ??
+        getOneofCaseValue(toolCall, "webFetchToolCall") ??
+        toolCallRecord?.webFetchToolCall;
+    if (webFetchPayload)
+        return { kind: "webFetch", payload: webFetchPayload };
+    return undefined;
+}
+function convertCursorTranscriptWebTool(webTool) {
+    const payload = asRecord(webTool.payload);
+    if (!payload)
+        return undefined;
+    const rawArgs = asRecord(payload.args) ?? {};
+    const args = normalizeWebToolArgs(webTool.kind, rawArgs);
+    const result = normalizeWebToolResult(payload.result);
+    if (!result)
+        return undefined;
+    return {
+        name: webTool.kind,
+        args,
+        result,
+    };
+}
+function normalizeWebToolArgs(kind, rawArgs) {
+    const args = { ...rawArgs };
+    if (kind === "webSearch") {
+        const query = getString(args, "searchTerm") ?? getString(args, "search_term") ?? getString(args, "query") ?? getString(args, "q");
+        if (query && !args.searchTerm)
+            args.searchTerm = query;
+        return args;
+    }
+    const url = getString(args, "url") ?? getString(args, "uri") ?? getString(args, "href");
+    if (url && !args.url)
+        args.url = url;
+    return args;
+}
+function normalizeWebToolResult(result) {
+    if (result === undefined)
+        return undefined;
+    const success = getTranscriptResultCase(result, "success");
+    if (success !== undefined) {
+        return {
+            status: "success",
+            value: { content: [{ type: "text", text: transcriptWebSuccessText(success) }] },
+        };
+    }
+    const error = getTranscriptResultCase(result, "error");
+    if (error !== undefined)
+        return { status: "error", error };
+    return {
+        status: "success",
+        value: { content: [{ type: "text", text: transcriptWebSuccessText(result) }] },
+    };
+}
+function getTranscriptResultCase(result, caseName) {
+    const record = asRecord(result);
+    return getOneofCaseValue(record?.result, caseName) ?? record?.[caseName];
+}
+function transcriptWebSuccessText(success) {
+    const successRecord = asRecord(success);
+    const references = getArray(successRecord, "references");
+    const chunks = references
+        ?.map((reference) => getString(asRecord(reference), "chunk"))
+        .filter((chunk) => Boolean(chunk?.trim()));
+    if (chunks && chunks.length > 0)
+        return chunks.join("\n\n");
+    const content = getArray(successRecord, "content");
+    const text = content
+        ?.map((entry) => getString(asRecord(entry), "text"))
+        .filter((entry) => Boolean(entry?.trim()));
+    if (text && text.length > 0)
+        return text.join("\n");
+    return stringifyUnknown(success).trim() || "Cursor web activity completed.";
+}

package/dist/cursor-agents-context-registration.js

@@ -0,0 +1,17 @@
+import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
+import { resolveEffectiveCursorConfigForContext } from "./cursor-runtime-state.js";
+import { resolveCursorFacingSystemPrompt } from "./cursor-agents-context.js";
+export function registerCursorAgentsContextDedup(pi) {
+    registerCursorModelLifecycle(pi, {
+        beforeAgentStart: (event, ctx) => {
+            if (!isCursorModel(ctx.model))
+                return undefined;
+            const runtime = resolveEffectiveCursorConfigForContext(ctx).runtime.value;
+            const resolved = resolveCursorFacingSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions, undefined, undefined, runtime);
+            if (resolved === event.systemPrompt)
+                return undefined;
+            return { systemPrompt: resolved };
+        },
+    });
+}

package/dist/cursor-agents-context.js

@@ -0,0 +1,113 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+import { isCursorModel } from "./cursor-model.js";
+import { cursorSettingSourcesIncludes, getEffectiveCursorSettingSources, resolveCursorSettingSources, } from "./cursor-setting-sources.js";
+export const CURSOR_PRESERVE_PI_AGENTS_MD_ENV = "PI_CURSOR_PRESERVE_PI_AGENTS_MD";
+/** Opening tag prefix pi `buildSystemPrompt()` uses for each context file (path attribute only). */
+export const PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX = '<project_instructions path="';
+const PI_PROJECT_INSTRUCTIONS_CLOSE = "</project_instructions>";
+const PI_PROJECT_CONTEXT_OPEN = "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n";
+const PI_PROJECT_CONTEXT_CLOSE = "</project_context>\n";
+function normalizeContextPath(filePath) {
+    return filePath.replace(/\\/g, "/");
+}
+function normalizeDirPath(dirPath) {
+    const normalized = normalizeContextPath(dirPath).replace(/\/+$/, "");
+    return normalized || "/";
+}
+/** Pi context filenames that can overlap Cursor project/user ambient rules. */
+const CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES = new Set(["agents.md", "claude.md"]);
+export function getAgentsContextFileBaseName(filePath) {
+    const normalized = normalizeContextPath(filePath);
+    return normalized.slice(normalized.lastIndexOf("/") + 1).toLowerCase();
+}
+function isPiAgentDirContextFilePath(filePath, fileName, agentDir = getAgentDir()) {
+    const normalized = normalizeContextPath(filePath);
+    const expectedPath = `${normalizeDirPath(agentDir)}/${fileName}`;
+    return normalized.toLowerCase() === expectedPath.toLowerCase();
+}
+/** Actual pi agent dir `AGENTS.md` — overlaps Cursor `user` setting source (global agent instructions). */
+export function isPiAgentDirAgentsMdPath(filePath, agentDir = getAgentDir()) {
+    return isPiAgentDirContextFilePath(filePath, "agents.md", agentDir);
+}
+/** Actual pi agent dir `CLAUDE.md` — kept because Cursor user rules use `~/.claude/CLAUDE.md`. */
+export function isPiAgentDirClaudeMdPath(filePath, agentDir = getAgentDir()) {
+    return isPiAgentDirContextFilePath(filePath, "claude.md", agentDir);
+}
+/**
+ * Classify whether a pi-loaded context file overlaps Cursor ambient rules.
+ * Project/repo `AGENTS.md` and `CLAUDE.md` overlap Cursor `project` sources.
+ * Only the actual pi agent dir `AGENTS.md` overlaps Cursor `user`; agent-dir `CLAUDE.md` is kept
+ * because Cursor user rules use `~/.claude/CLAUDE.md`, not pi's agent dir path.
+ */
+export function classifyContextFileOverlap(filePath, agentDir = getAgentDir()) {
+    const base = getAgentsContextFileBaseName(filePath);
+    if (!CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES.has(base))
+        return "none";
+    if (base === "agents.md" && isPiAgentDirAgentsMdPath(filePath, agentDir))
+        return "cursor-user-agents";
+    if (base === "claude.md" && isPiAgentDirClaudeMdPath(filePath, agentDir))
+        return "none";
+    return "cursor-project-rules";
+}
+export function shouldRemovePiAgentsContextFile(file, settingSources, agentDir) {
+    switch (classifyContextFileOverlap(file.path, agentDir)) {
+        case "cursor-user-agents":
+            return cursorSettingSourcesIncludes(settingSources, "user");
+        case "cursor-project-rules":
+            return cursorSettingSourcesIncludes(settingSources, "project");
+        default:
+            return false;
+    }
+}
+export function shouldSuppressPiAgentsContext(model, contextFiles, settingSources, agentDir) {
+    if (!isCursorModel(model))
+        return false;
+    if (parseEnvBoolean(process.env[CURSOR_PRESERVE_PI_AGENTS_MD_ENV], false))
+        return false;
+    if (contextFiles.length === 0)
+        return false;
+    return contextFiles.some((file) => shouldRemovePiAgentsContextFile(file, settingSources, agentDir));
+}
+/** Exact pi `buildSystemPrompt()` serialization for one context file block (including trailing blank line). */
+export function serializePiProjectInstructionsBlock(file) {
+    return `${PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX}${file.path}">\n${file.content}\n${PI_PROJECT_INSTRUCTIONS_CLOSE}\n\n`;
+}
+/** Exact pi `buildSystemPrompt()` serialization for the full project context section. */
+export function serializePiProjectContextSection(contextFiles) {
+    if (contextFiles.length === 0)
+        return "";
+    return `${PI_PROJECT_CONTEXT_OPEN}${contextFiles.map(serializePiProjectInstructionsBlock).join("")}${PI_PROJECT_CONTEXT_CLOSE}`;
+}
+/** Remove pi context blocks that overlap Cursor setting sources. */
+export function removePiAgentsContextFromSystemPrompt(systemPrompt, contextFiles, settingSources, agentDir) {
+    const retainedContextFiles = [];
+    let removedAny = false;
+    for (const file of contextFiles) {
+        if (shouldRemovePiAgentsContextFile(file, settingSources, agentDir)) {
+            removedAny = true;
+            continue;
+        }
+        retainedContextFiles.push(file);
+    }
+    if (!removedAny)
+        return systemPrompt;
+    const originalSection = serializePiProjectContextSection(contextFiles);
+    const start = systemPrompt.indexOf(originalSection);
+    if (start < 0)
+        return systemPrompt;
+    const replacementSection = serializePiProjectContextSection(retainedContextFiles);
+    return systemPrompt.slice(0, start) + replacementSection + systemPrompt.slice(start + originalSection.length);
+}
+export function resolveCursorFacingSystemPrompt(systemPrompt, model, systemPromptOptions, settingSourcesRaw, agentDir, runtime = "local") {
+    if (runtime === "cloud" || !systemPromptOptions)
+        return systemPrompt;
+    const contextFiles = systemPromptOptions.contextFiles ?? [];
+    const settingSources = settingSourcesRaw === undefined
+        ? getEffectiveCursorSettingSources()
+        : resolveCursorSettingSources(settingSourcesRaw);
+    if (!shouldSuppressPiAgentsContext(model, contextFiles, settingSources, agentDir)) {
+        return systemPrompt;
+    }
+    return removePiAgentsContextFromSystemPrompt(systemPrompt, contextFiles, settingSources, agentDir);
+}

package/dist/cursor-api-key.js

@@ -0,0 +1,34 @@
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+export const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
+const CURSOR_PROVIDER_ID = "cursor";
+// Non-secret literal sentinel for pi's provider registry. Pi 0.77 treats `$ENV_VAR`
+// values as unconfigured when the env var is absent, which hides fallback models
+// before `/login`. Keep the provider available and resolve the real key in the
+// Cursor provider turn path from pi auth or CURSOR_API_KEY.
+export const CURSOR_API_KEY_CONFIG_VALUE = "pi-cursor-sdk-cursor-api-key-placeholder";
+const CURSOR_API_KEY_PLACEHOLDERS = new Set([
+    CURSOR_API_KEY_ENV_VAR,
+    `$${CURSOR_API_KEY_ENV_VAR}`,
+    `\${${CURSOR_API_KEY_ENV_VAR}}`,
+    CURSOR_API_KEY_CONFIG_VALUE,
+]);
+export function resolveCursorApiKey(apiKey) {
+    const trimmed = apiKey?.trim();
+    if (!trimmed)
+        return undefined;
+    if (CURSOR_API_KEY_PLACEHOLDERS.has(trimmed))
+        return process.env.CURSOR_API_KEY?.trim() || undefined;
+    return trimmed;
+}
+function getStoredCursorApiKey() {
+    try {
+        const credential = readStoredCredential(CURSOR_PROVIDER_ID);
+        return resolveCursorApiKey(credential?.type === "api_key" ? credential.key : undefined);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveCursorRuntimeApiKey() {
+    return Promise.resolve(getStoredCursorApiKey() ?? resolveCursorApiKey(process.env.CURSOR_API_KEY));
+}