pi-cursor-sdk 0.2.0 → 0.3.6

package/dist/cursor-provider-run-outcome.js

@@ -0,0 +1,76 @@
+import { selectCursorFinalText } from "./cursor-run-final-text.js";
+import { formatCursorSdkAbortMessage, formatCursorSdkRunFailureDetail, resolveCursorSdkAbortCause, sanitizeCursorProviderError, } from "./cursor-provider-errors.js";
+import { hasUsableText } from "./cursor-record-utils.js";
+import { buildIncompleteCursorToolRunOutcome, } from "./cursor-incomplete-tool-visibility.js";
+function hasCursorAssistantText(resultText, textDeltas, fallbackText) {
+    return (hasUsableText(typeof resultText === "string" ? resultText : undefined) ||
+        hasUsableText(textDeltas.join("")) ||
+        hasUsableText(fallbackText));
+}
+export function isCursorRunFinishedSuccessfully(outcome) {
+    return outcome.kind === "finished";
+}
+function buildCursorRunAbortMessage(signalAborted, sdkStatusCancelled) {
+    return formatCursorSdkAbortMessage(resolveCursorSdkAbortCause({
+        signalAborted,
+        sdkStatusCancelled,
+    }));
+}
+export function resolveCursorRunOutcome(params) {
+    const { waitResult, signalAborted } = params;
+    const sdkCancelled = waitResult.status === "cancelled";
+    const callerAborted = signalAborted === true;
+    if (callerAborted || sdkCancelled) {
+        const incompleteTools = buildIncompleteCursorToolRunOutcome({
+            status: "cancelled",
+            signalAborted: callerAborted,
+            assistantTextProduced: false,
+        });
+        return {
+            kind: "cancelled",
+            waitResult,
+            incompleteTools,
+            abortMessage: buildCursorRunAbortMessage(callerAborted, sdkCancelled),
+        };
+    }
+    if (waitResult.status === "error") {
+        const failureDetail = formatCursorSdkRunFailureDetail(waitResult, params.runResultFallback, params.runErrorFallback);
+        return {
+            kind: "error",
+            waitResult,
+            incompleteTools: buildIncompleteCursorToolRunOutcome({
+                status: "error",
+                assistantTextProduced: false,
+            }),
+            errorMessage: sanitizeCursorProviderError(failureDetail, params.resolvedApiKey ?? params.optionsApiKey, params.runtimeTarget),
+        };
+    }
+    const assistantTextProduced = hasCursorAssistantText(waitResult.result, params.textDeltas, params.planTextCandidate);
+    const incompleteTools = buildIncompleteCursorToolRunOutcome({
+        status: waitResult.status,
+        assistantTextProduced,
+    });
+    const finalText = selectCursorFinalText(waitResult.result, params.textDeltas, params.emittedText, params.planTextCandidate, params.selectFinalTextOptions);
+    return {
+        kind: "finished",
+        waitResult,
+        finalText,
+        incompleteTools,
+        assistantTextProduced,
+    };
+}
+export function classifyCursorRunEmission(outcome) {
+    switch (outcome.kind) {
+        case "finished":
+            return "finished";
+        case "cancelled":
+            return "cancelled";
+        case "error":
+            return "failed";
+    }
+}
+export function getCursorRunAbortMessage(outcome) {
+    if (outcome.kind === "cancelled")
+        return outcome.abortMessage;
+    return buildCursorRunAbortMessage(false, outcome.waitResult.status === "cancelled");
+}

package/dist/cursor-provider-turn-coordinator.js

@@ -0,0 +1,275 @@
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { recordDiscardedIncompleteStartedToolCall, } from "./cursor-sdk-event-debug.js";
+import { buildIncompleteCursorToolRunOutcome, resolveIncompleteCursorToolVisibility, } from "./cursor-incomplete-tool-visibility.js";
+import { getToolName } from "./cursor-transcript-utils.js";
+import { getNormalizedCursorToolName } from "./cursor-tool-visibility.js";
+import { buildCursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import { getField } from "./cursor-record-utils.js";
+import { CursorTurnDisplayRouter } from "./cursor-provider-turn-display-router.js";
+import { createTurnCoordinatorContentEmitter, CursorToolLifecycleEmitter, } from "./cursor-provider-turn-lifecycle-emitter.js";
+import { resolveCursorToolCompletion } from "./cursor-provider-turn-sdk-normalizer.js";
+import { CursorShellOutputTracker, formatCursorShellOutputProgressText, getCursorShellOutputDelta, isCursorShellToolCall, } from "./cursor-provider-turn-shell-output.js";
+import { CursorToolCompletionLedger, getToolFingerprint, } from "./cursor-provider-turn-tool-ledger.js";
+import { readCursorSdkTurnUsageFromUpdate } from "./cursor-usage-accounting.js";
+export class CursorSdkTurnCoordinator {
+    stream;
+    partial;
+    cwd;
+    resolvedApiKey;
+    liveRun;
+    useNativeToolReplay;
+    activeToolNames;
+    nativeReplayId;
+    textDeltas;
+    debugRecorder;
+    ledger = new CursorToolCompletionLedger();
+    shellOutput = new CursorShellOutputTracker();
+    displayRouter;
+    lifecycleEmitter;
+    contentEmitter;
+    sdkTurnUsage;
+    constructor(options) {
+        this.stream = options.stream;
+        this.partial = options.partial;
+        this.cwd = options.cwd;
+        this.resolvedApiKey = options.resolvedApiKey;
+        this.liveRun = options.liveRun;
+        this.useNativeToolReplay = options.useNativeToolReplay;
+        this.activeToolNames = options.activeToolNames;
+        this.nativeReplayId = options.nativeReplayId;
+        this.textDeltas = options.textDeltas;
+        this.debugRecorder = options.debugRecorder;
+        this.contentEmitter = createTurnCoordinatorContentEmitter(options.stream, options.partial);
+        this.displayRouter = new CursorTurnDisplayRouter({
+            cwd: options.cwd,
+            resolvedApiKey: options.resolvedApiKey,
+            liveRun: options.liveRun,
+            useNativeToolReplay: options.useNativeToolReplay,
+            activeToolNames: options.activeToolNames,
+            nativeReplayId: options.nativeReplayId,
+            contentEmitter: this.contentEmitter,
+            debugRecorder: options.debugRecorder,
+        });
+        this.lifecycleEmitter = new CursorToolLifecycleEmitter({
+            liveRun: options.liveRun,
+            resolvedApiKey: options.resolvedApiKey,
+            contentEmitter: this.contentEmitter,
+            debugRecorder: options.debugRecorder,
+            hasStartedToolCall: (callId) => this.ledger.hasStartedToolCall(callId),
+            isBridgeMcpToolCall: (toolCall) => options.liveRun?.bridgeRun?.isBridgeMcpToolCall(toolCall) ?? false,
+        });
+    }
+    get planTextCandidate() {
+        return this.displayRouter.planTextCandidate;
+    }
+    get replayStarted() {
+        return this.displayRouter.nativeToolReplayStarted;
+    }
+    get lastSdkTurnUsage() {
+        return this.sdkTurnUsage;
+    }
+    discardIncompleteStartedToolCalls(outcome = buildIncompleteCursorToolRunOutcome()) {
+        for (const [callId, toolCall] of this.ledger.startedToolCallEntries()) {
+            const toolName = getNormalizedCursorToolName(toolCall);
+            recordDiscardedIncompleteStartedToolCall(this.debugRecorder, process.env, {
+                toolName,
+                callId,
+                reason: outcome.reason,
+            });
+            const visibilityDecision = resolveIncompleteCursorToolVisibility(toolCall, outcome);
+            if (visibilityDecision !== "emit") {
+                this.displayRouter.recordIncompleteSkip(toolName, visibilityDecision === "debugOnly" && outcome.assistantTextProduced
+                    ? "successful-run-text-produced"
+                    : visibilityDecision);
+                continue;
+            }
+            const action = this.displayRouter.routeIncompleteStartedToolCall(toolCall, outcome.reason);
+            if (action)
+                this.displayRouter.emitDisplayAction(action);
+        }
+        this.ledger.clearStartedToolCalls();
+        this.shellOutput.clear();
+        this.lifecycleEmitter.clear();
+    }
+    closeTraceBlock() {
+        this.contentEmitter.closeThinking();
+    }
+    flushText(deltas) {
+        return this.contentEmitter.flushText(deltas);
+    }
+    handleDelta(update) {
+        const sdkTurnUsage = readCursorSdkTurnUsageFromUpdate(update);
+        if (sdkTurnUsage)
+            this.sdkTurnUsage = sdkTurnUsage;
+        if (this.liveRun && (update.type === "turn-ended" || sdkTurnUsage)) {
+            cursorLiveRuns.recordSdkTurnEnded(this.liveRun, sdkTurnUsage);
+        }
+        if (update.type === "text-delta") {
+            this.textDeltas.push(update.text);
+            if (this.liveRun) {
+                cursorLiveRuns.queueEvent(this.liveRun, { type: "text-delta", text: update.text });
+            }
+            else {
+                this.contentEmitter.appendTextDelta(update.text);
+            }
+            return;
+        }
+        if (update.type === "thinking-delta") {
+            if (this.liveRun) {
+                cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: update.text });
+            }
+            else {
+                this.contentEmitter.appendThinkingDelta(update.text);
+            }
+            return;
+        }
+        if (update.type === "thinking-completed") {
+            if (this.liveRun) {
+                cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-completed" });
+            }
+            else {
+                this.contentEmitter.closeThinking();
+            }
+            return;
+        }
+        if (update.type === "partial-tool-call") {
+            this.lifecycleEmitter.maybeSchedule(update.callId, update.toolCall);
+            return;
+        }
+        if (update.type === "tool-call-started") {
+            if (this.liveRun?.bridgeRun?.isBridgeMcpToolCall(update.toolCall)) {
+                if (typeof update.callId === "string")
+                    this.ledger.markBridgeStarted(update.callId);
+            }
+            else {
+                this.lifecycleEmitter.maybeSchedule(update.callId, update.toolCall);
+                this.ledger.registerStartedToolCall(update.callId, update.toolCall);
+                if (isCursorShellToolCall(update.toolCall) && typeof update.callId === "string") {
+                    this.shellOutput.onShellToolStarted(update.callId);
+                }
+            }
+            return;
+        }
+        if (update.type === "tool-call-completed") {
+            const resolution = resolveCursorToolCompletion({
+                source: "delta",
+                callId: update.callId,
+                toolCall: update.toolCall,
+                startedToolCall: this.ledger.getStartedToolCall(update.callId),
+                liveRun: this.liveRun,
+                ledger: this.ledger,
+                shellOutput: this.shellOutput,
+                onClearStartedCallId: (callId) => {
+                    this.lifecycleEmitter.cancel(callId);
+                    this.shellOutput.onShellToolCleared(callId);
+                },
+            });
+            if (resolution.action === "ignore-bridge") {
+                this.displayRouter.recordIgnoreBridgeDecision(resolution.identity, getToolName(update.toolCall), "delta");
+                return;
+            }
+            this.handleCompletedToolCall(resolution.toolCall, {
+                identity: resolution.identity,
+                source: resolution.source,
+            });
+            if (resolution.matchedStartedCallId && resolution.matchedStartedCallId !== update.callId) {
+                this.ledger.recordCompletedIdentity(`cursor-tool:${resolution.matchedStartedCallId}`);
+            }
+            return;
+        }
+        if (update.type === "shell-output-delta") {
+            const delta = getCursorShellOutputDelta(update);
+            if (delta) {
+                const progress = this.shellOutput.appendShellOutputDelta(delta);
+                const progressText = progress ? formatCursorShellOutputProgressText(progress, this.resolvedApiKey) : undefined;
+                if (progressText) {
+                    if (this.liveRun) {
+                        cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: progressText });
+                    }
+                    else {
+                        this.contentEmitter.appendThinkingDelta(progressText);
+                    }
+                }
+            }
+            return;
+        }
+        if (update.type === "summary") {
+            const summary = `Cursor summary: ${truncateCursorDisplayLine(update.summary)}\n`;
+            if (this.liveRun) {
+                cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: summary });
+            }
+            else {
+                this.contentEmitter.appendThinkingDelta(summary);
+            }
+        }
+    }
+    handleStep(stepEnvelope) {
+        const stepType = getField(stepEnvelope, "type");
+        const step = getField(stepEnvelope, "message") ? stepEnvelope : undefined;
+        const rawStepToolCall = getField(step, "message");
+        if (stepType !== "toolCall")
+            return;
+        const toolCall = rawStepToolCall;
+        const stepId = getField(stepEnvelope, "id") ?? getField(toolCall, "id") ?? getField(toolCall, "callId");
+        if (!toolCall)
+            return;
+        const resolution = resolveCursorToolCompletion({
+            source: "step",
+            callId: stepId,
+            toolCall,
+            liveRun: this.liveRun,
+            ledger: this.ledger,
+            shellOutput: this.shellOutput,
+            onClearStartedCallId: (callId) => {
+                this.lifecycleEmitter.cancel(callId);
+                this.shellOutput.onShellToolCleared(callId);
+            },
+        });
+        if (resolution.action === "ignore-bridge") {
+            this.displayRouter.recordIgnoreBridgeDecision(resolution.identity, getToolName(toolCall), "step");
+            return;
+        }
+        this.handleCompletedToolCall(resolution.toolCall, {
+            identity: resolution.identity,
+            source: resolution.source,
+        });
+        if (resolution.matchedStartedCallId && resolution.matchedStartedCallId !== stepId) {
+            this.ledger.recordCompletedIdentity(`cursor-tool:${resolution.matchedStartedCallId}`);
+        }
+    }
+    handleTranscriptCompletedToolCalls(toolCalls) {
+        for (const { identity, toolCall } of toolCalls) {
+            this.handleCompletedToolCall(toolCall, { identity, source: "transcript" });
+        }
+    }
+    handleCompletedToolCall(toolCall, options = {}) {
+        const display = buildCursorPiToolDisplay(toolCall, { cwd: this.cwd });
+        const fingerprint = getToolFingerprint({
+            toolName: display.toolName,
+            args: display.args,
+            result: display.result,
+        });
+        const duplicateReason = this.ledger.shouldSkipDuplicateCompletion({
+            identity: options.identity,
+            source: options.source,
+            fingerprint,
+        });
+        if (duplicateReason) {
+            this.displayRouter.recordDuplicateSkip(display.toolName, {
+                identity: options.identity,
+                source: options.source,
+                reason: duplicateReason,
+            });
+            return;
+        }
+        this.ledger.recordCompletedTool({
+            identity: options.identity,
+            source: options.source,
+            fingerprint,
+        });
+        const action = this.displayRouter.routeCompletedToolCall(toolCall, options);
+        if (action)
+            this.displayRouter.emitDisplayAction(action);
+    }
+}

package/dist/cursor-provider-turn-display-router.js

@@ -0,0 +1,158 @@
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { resolveNativeReplayDisposition } from "./cursor-native-replay-routing.js";
+import { buildIncompleteCursorToolDisplay, formatIncompleteCursorToolTrace, } from "./cursor-incomplete-tool-visibility.js";
+import { scrubPiToolDisplay, scrubSensitiveText } from "./cursor-sensitive-text.js";
+import { buildCursorPiToolDisplay, formatCursorToolTranscript, getCursorCreatePlanText, } from "./cursor-tool-transcript.js";
+import { getToolName } from "./cursor-transcript-utils.js";
+function formatCursorToolName(toolCall) {
+    return truncateCursorDisplayLine(getToolName(toolCall), 80) || "unknown";
+}
+export class CursorTurnDisplayRouter {
+    cwd;
+    resolvedApiKey;
+    liveRun;
+    useNativeToolReplay;
+    activeToolNames;
+    nativeReplayId;
+    contentEmitter;
+    debugRecorder;
+    nativeToolDisplayCounter = 0;
+    nativeToolReplayStarted = false;
+    planTextCandidate;
+    constructor(options) {
+        this.cwd = options.cwd;
+        this.resolvedApiKey = options.resolvedApiKey;
+        this.liveRun = options.liveRun;
+        this.useNativeToolReplay = options.useNativeToolReplay;
+        this.activeToolNames = options.activeToolNames;
+        this.nativeReplayId = options.nativeReplayId;
+        this.contentEmitter = options.contentEmitter;
+        this.debugRecorder = options.debugRecorder;
+    }
+    routeCompletedToolCall(toolCall, options = {}) {
+        const planText = getCursorCreatePlanText(toolCall);
+        if (planText)
+            this.planTextCandidate = scrubSensitiveText(planText, this.resolvedApiKey);
+        const transcript = scrubSensitiveText(formatCursorToolTranscript(toolCall, { cwd: this.cwd }), this.resolvedApiKey);
+        const display = buildCursorPiToolDisplay(toolCall, { cwd: this.cwd });
+        const disposition = resolveNativeReplayDisposition({
+            toolName: display.toolName,
+            useNativeToolReplay: this.useNativeToolReplay,
+            activeToolNames: this.activeToolNames,
+            hasLiveRun: this.liveRun !== undefined,
+        });
+        if (disposition === "queue_replay" && this.liveRun) {
+            this.nativeToolReplayStarted = true;
+            const id = `${this.nativeReplayId}-tool-${++this.nativeToolDisplayCounter}`;
+            const scrubbedDisplay = scrubPiToolDisplay(display, this.resolvedApiKey);
+            this.recordDisplayDecision({
+                action: "queue_replay",
+                disposition,
+                toolName: display.toolName,
+                identity: options.identity,
+                source: options.source,
+                transcript,
+                replayToolId: id,
+            });
+            return { kind: "queue_replay", tool: scrubbedDisplay, replayToolId: id, disposition };
+        }
+        const traceText = disposition === "inactive_trace"
+            ? formatInactiveCursorReplayTrace(scrubPiToolDisplay(display, this.resolvedApiKey))
+            : transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`;
+        this.recordDisplayDecision({
+            action: "emit_trace",
+            disposition,
+            toolName: display.toolName,
+            identity: options.identity,
+            source: options.source,
+            transcript,
+            traceText,
+        });
+        return { kind: "emit_trace", traceText, disposition };
+    }
+    routeIncompleteStartedToolCall(toolCall, reason) {
+        const display = scrubPiToolDisplay(buildIncompleteCursorToolDisplay(toolCall, reason, { apiKey: this.resolvedApiKey }), this.resolvedApiKey);
+        const disposition = resolveNativeReplayDisposition({
+            toolName: display.toolName,
+            useNativeToolReplay: this.useNativeToolReplay,
+            activeToolNames: this.activeToolNames,
+            hasLiveRun: this.liveRun !== undefined,
+        });
+        if (disposition === "queue_replay" && this.liveRun && reason !== "abort") {
+            this.nativeToolReplayStarted = true;
+            const id = `${this.nativeReplayId}-tool-${++this.nativeToolDisplayCounter}`;
+            this.recordDisplayDecision({
+                action: "queue_replay",
+                disposition,
+                toolName: display.toolName,
+                source: "started",
+                reason: "incomplete-started-tool-call",
+                replayToolId: id,
+            });
+            return { kind: "queue_replay", tool: display, replayToolId: id, disposition };
+        }
+        const traceText = disposition === "inactive_trace"
+            ? formatInactiveCursorReplayTrace(display)
+            : formatIncompleteCursorToolTrace(display);
+        this.recordDisplayDecision({
+            action: "emit_trace",
+            disposition,
+            toolName: display.toolName,
+            source: "started",
+            reason: "incomplete-started-tool-call",
+            traceText,
+        });
+        return { kind: "emit_trace", traceText, disposition };
+    }
+    emitDisplayAction(action) {
+        if (action.kind === "queue_replay") {
+            if (!this.liveRun)
+                return;
+            cursorLiveRuns.queueEvent(this.liveRun, {
+                type: "tool",
+                tool: { ...action.tool, id: action.replayToolId },
+            });
+            return;
+        }
+        this.emitCursorToolTrace(action.traceText);
+    }
+    recordIgnoreBridgeDecision(identity, toolName, source) {
+        this.debugRecorder?.recordDisplayDecision({
+            action: "ignore-bridge",
+            toolName,
+            identity,
+            source,
+        });
+    }
+    recordDuplicateSkip(toolName, options) {
+        this.recordDisplayDecision({
+            action: "skip-duplicate",
+            toolName,
+            identity: options.identity,
+            source: options.source,
+            reason: options.reason,
+        });
+    }
+    recordIncompleteSkip(toolName, reason) {
+        this.recordDisplayDecision({
+            action: "skip-incomplete-fast-local",
+            toolName,
+            source: "started",
+            reason,
+        });
+    }
+    recordDisplayDecision(decision) {
+        this.debugRecorder?.recordDisplayDecision(decision);
+    }
+    emitCursorToolTrace(text) {
+        const traceText = text.endsWith("\n") ? text : `${text}\n`;
+        if (this.liveRun) {
+            cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: traceText });
+            cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-completed" });
+            return;
+        }
+        this.contentEmitter.appendThinkingBlock(traceText);
+    }
+}

package/dist/cursor-provider-turn-emit.js

@@ -0,0 +1,35 @@
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import { cursorLiveRuns, drainCursorLiveRunTurn, flushPendingCursorLiveRunTraceEventsToStream, settleCursorLiveToolBatch, } from "./cursor-provider-live-run-drain.js";
+import { buildIncompleteCursorToolRunOutcome, } from "./cursor-incomplete-tool-visibility.js";
+export async function emitCursorLiveTurn(emitParams) {
+    const { params, prepared, sdkEventDebug, discardIncompleteTools } = emitParams;
+    if (prepared.runtime.kind !== "live")
+        throw new Error("emitCursorLiveTurn requires a live run");
+    const { liveRun, turnCoordinator } = prepared.runtime;
+    const { options, model } = params;
+    try {
+        await cursorLiveRuns.withRunLease(liveRun, options?.signal, async () => {
+            await cursorLiveRuns.waitForProgress(liveRun, options?.signal);
+            await settleCursorLiveToolBatch(liveRun);
+            turnCoordinator.closeTraceBlock();
+            await drainCursorLiveRunTurn(params.stream, params.partial, model, params.context, liveRun, 0, {
+                mode: "emit",
+                signal: options?.signal,
+                debugRecorder: sdkEventDebug,
+            });
+        });
+    }
+    catch (caught) {
+        if (caught instanceof CursorLiveRunAbortError) {
+            discardIncompleteTools({ status: "cancelled", signalAborted: true });
+            turnCoordinator.closeTraceBlock();
+            flushPendingCursorLiveRunTraceEventsToStream(params.stream, params.partial, liveRun, {
+                includeTracesBehindQueuedTools: true,
+            });
+        }
+        throw caught;
+    }
+}
+export function discardIncompleteToolsFromPrepared(prepared, outcome) {
+    prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(buildIncompleteCursorToolRunOutcome(outcome));
+}