pi-cursor-sdk 0.4.0 → 0.5.2

package/dist/cursor-provider.js

@@ -6,8 +6,8 @@ import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-gu
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { CursorProviderTurnRunner } from "./cursor-provider-turn-runner.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { runExclusiveCursorSessionTurn, __testUtils as cursorSessionTurnQueueTestUtils } from "./cursor-session-turn-queue.js";
+import { withCursorSdkOutputNoticeHandler } from "./cursor-sdk-output-filter.js";
 function makeInitialMessage(model) {
     return {
         role: "assistant",
@@ -27,7 +27,8 @@ function makeInitialMessage(model) {
         timestamp: Date.now(),
     };
 }
-export function streamCursor(model, context, options) {
+export function streamCursor(model, context, options, ownership) {
+    const { scope, bridge, nativeDisplay, recordCloudLifecycle, request, usageRecorder } = ownership;
     const stream = createAssistantMessageEventStream();
     const sdkEventDebugRef = {};
     attachCursorSdkEventDebugPiStreamTap(stream, sdkEventDebugRef);
@@ -35,6 +36,12 @@ export function streamCursor(model, context, options) {
         const partial = makeInitialMessage(model);
         const runner = new CursorProviderTurnRunner({
             model,
+            scope,
+            bridge,
+            nativeDisplay,
+            recordCloudLifecycle,
+            request,
+            usageRecorder,
             context,
             stream,
             partial,
@@ -43,7 +50,7 @@ export function streamCursor(model, context, options) {
         });
         try {
             stream.push({ type: "start", partial });
-            await runExclusiveCursorSessionTurn(getCursorSessionScopeKey(), () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
+            await runExclusiveCursorSessionTurn(scope.scopeKey, () => withCursorSdkOutputNoticeHandler(ownership.reportSdkNotice, () => runner.run(installCursorSdkProcessErrorGuard())), options?.signal);
         }
         catch (error) {
             await runner.handleOuterCatch(error);

package/dist/cursor-question-tool.js

@@ -8,7 +8,7 @@ import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js
 export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
 export const CURSOR_ASK_QUESTION_ENV = "PI_CURSOR_ASK_QUESTION";
 export function resolveCursorAskQuestionEnabled(env = process.env) {
-    return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], true);
+    return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], false);
 }
 /** Package-namespaced event while `cursor_ask_question` awaits pi UI input. */
 export const CURSOR_ASK_QUESTION_BLOCKED_EVENT = "pi-cursor-sdk:ask-question:blocked";
@@ -146,13 +146,13 @@ export function registerCursorQuestionTool(pi) {
     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.",
-        promptSnippet: "Ask the user a clarifying question through pi UI when material choices affect Cursor's next step",
+        description: "Ask the user a clarifying question through pi UI. Do not use this unless the user asked to be prompted; otherwise proceed with a stated assumption.",
+        promptSnippet: "Do not prompt the user through cursor_ask_question unless they asked to be asked",
         executionMode: "sequential",
         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.",
+            "Do not call cursor_ask_question unless the user explicitly asked to be prompted or to choose among options.",
+            "If this tool is available, prefer a reasonable default and state the assumption instead of blocking on a questionnaire.",
         ],
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const questions = normalizeQuestions(params);

package/dist/cursor-request-provenance.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+function projectionDigest(messages) {
+    const hash = createHash("sha256");
+    for (const message of messages) {
+        // Stable value equivalence survives Pi's cloning and property insertion order.
+        hash.update(JSON.stringify(message, (_key, value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return value;
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+        }));
+        hash.update("\n");
+    }
+    return hash.digest("hex");
+}
+export function captureCursorRequestProjection(manager) {
+    const branch = manager.getBranch();
+    const projection = manager.buildSessionProjection();
+    const order = new Map(branch.map((entry, index) => [entry.id, index]));
+    const boundary = branch.findLastIndex((entry) => entry.type === "compaction" || entry.type === "context_edit");
+    const measurements = [];
+    // Raw branch chronology, not projected order or clocks, determines freshness.
+    for (const entry of [...projection.entries].sort((a, b) => (order.get(a.sourceEntry.id) ?? -1) - (order.get(b.sourceEntry.id) ?? -1))) {
+        if ((order.get(entry.sourceEntry.id) ?? -1) <= boundary)
+            continue;
+        for (const message of entry.messages) {
+            if (message.role !== "assistant" || message.stopReason === "error" || message.stopReason === "aborted")
+                continue;
+            const tokens = message.usage.totalTokens;
+            if (!Number.isFinite(tokens) || tokens <= 0)
+                continue;
+            measurements.push(Object.freeze({ api: message.api, provider: message.provider, model: message.model, tokens }));
+        }
+    }
+    const nativeSourceRoles = projection.messages.flatMap((message) => message.role === "system" ? [] : convertToLlm([message]).map(() => message.role));
+    return Object.freeze({
+        digest: projectionDigest(convertToLlm(projection.messages)),
+        measurements: Object.freeze(measurements),
+        nativeSourceRoles: Object.freeze(nativeSourceRoles),
+    });
+}
+export function resolveCursorRequestProvenance(snapshot, model, context, purpose) {
+    // ponytail: canonical native origin only. Unmatched transforms stay conservative;
+    // upgrade if Pi exposes final request-bound source provenance.
+    if (purpose !== "normal" || snapshot.digest !== projectionDigest(context.messages))
+        return Object.freeze({ purpose });
+    const measurement = snapshot.measurements.findLast((item) => item.api === model.api && item.provider === model.provider && item.model === model.id && item.tokens <= model.contextWindow);
+    return Object.freeze({
+        purpose,
+        nativeSourceRoles: snapshot.nativeSourceRoles,
+        ...(measurement ? { occupancyFloor: measurement.tokens } : {}),
+    });
+}

package/dist/cursor-ripgrep-path.js

@@ -2,12 +2,23 @@ import { accessSync, constants } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join } from "node:path";
 const RIPGREP_ENV = "CURSOR_RIPGREP_PATH";
-export function resolveBundledCursorRipgrepPath(fromModuleUrl = import.meta.url) {
+export function resolveCursorSdkPlatformPackageDirectory(fromModuleUrl = import.meta.url) {
     try {
         const require = createRequire(fromModuleUrl);
-        const platformPackage = `@cursor/sdk-${process.platform}-${process.arch}`;
         const sdkEntry = require.resolve("@cursor/sdk");
-        const packageDirectory = dirname(require.resolve(`${platformPackage}/package.json`, { paths: [dirname(sdkEntry)] }));
+        return dirname(require.resolve(`@cursor/sdk-${process.platform}-${process.arch}/package.json`, {
+            paths: [dirname(sdkEntry)],
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveBundledCursorRipgrepPath(fromModuleUrl = import.meta.url) {
+    const packageDirectory = resolveCursorSdkPlatformPackageDirectory(fromModuleUrl);
+    if (!packageDirectory)
+        return undefined;
+    try {
         const ripgrepPath = join(packageDirectory, "bin", process.platform === "win32" ? "rg.exe" : "rg");
         accessSync(ripgrepPath, constants.X_OK);
         return ripgrepPath;

package/dist/cursor-runtime-state.js

@@ -2,7 +2,8 @@ import { registerCursorCloudLifecycleLedger, runCursorCloudLifecycleCommand, } f
 import { CURSOR_AUTO_REVIEW_ENV, CURSOR_CLOUD_ACK_ENV, CURSOR_CLOUD_ALLOW_LOCAL_STATE_ENV, CURSOR_CLOUD_AUTO_CREATE_PR_ENV, CURSOR_CLOUD_BRANCH_ENV, CURSOR_CLOUD_CONTEXT_ENV, CURSOR_CLOUD_DIRECT_PUSH_ENV, CURSOR_CLOUD_ENV_ENV, CURSOR_CLOUD_ENV_FROM_FILES_ENV, CURSOR_CLOUD_ENV_NAME_ENV, CURSOR_CLOUD_ENV_TYPE_ENV, CURSOR_CLOUD_REPO_ENV, CURSOR_CLOUD_SKIP_REVIEWER_REQUEST_ENV, CURSOR_LOCAL_FORCE_ENV, CURSOR_LOCAL_RESUME_ENV, CURSOR_RUNTIME_ENV, CURSOR_SANDBOX_ENV, getCursorSdkProjectConfigPath, getCursorSdkUserConfigPath, loadCursorSdkConfig, mergeCursorSdkConfigForUpdate, parseExplicitCursorCloudEnvNames, resolveCursorSdkConfig, updateCursorSdkConfig, } from "./cursor-config.js";
 import { asRecord } from "./cursor-record-utils.js";
 import { getResolvedSessionCursorHttp1Enabled } from "./cursor-http1.js";
-import { getCursorSessionCwd, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
+import { cursorSettingsScopeForContext, getCursorSessionSettings } from "./cursor-session-settings.js";
 export const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
 export const CURSOR_CLOUD_ACK_DISCLOSURE = [
     "Cursor Cloud executes this work remotely.",
@@ -12,11 +13,7 @@ export const CURSOR_CLOUD_ACK_DISCLOSURE = [
     "Cloud agents remain until you archive or delete them.",
     "Cloud Agents run in Max Mode, are billed at Cursor API pricing, and may require spend-limit setup.",
 ].join("\n\n");
-let cliCursorSnapshot = { config: {} };
-let cliLocalForceConsumed = false;
 let envLocalForceConsumed = false;
-let sessionCursorRuntime;
-let sessionCursorCloudAcknowledged = false;
 function isCursorRuntimeEntryData(value) {
     const record = asRecord(value);
     if (!record)
@@ -27,15 +24,17 @@ function isCursorRuntimeEntryData(value) {
 function stringFlagValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
-export function getCursorCliConfig() {
-    const config = structuredClone(cliCursorSnapshot.config);
-    const envNames = parseExplicitCursorCloudEnvNames(cliCursorSnapshot.cloudEnvNames, "--cursor-cloud-env");
+export function getCursorCliConfig(scopeKey) {
+    const cli = getCursorSessionSettings(scopeKey).cli;
+    const config = structuredClone(cli.config);
+    const envNames = parseExplicitCursorCloudEnvNames(cli.cloudEnvNames, "--cursor-cloud-env");
     if (envNames)
         config.cloud = { ...config.cloud, envNames };
     return config;
 }
-export function getCursorSessionConfig() {
-    const useHttp1ForAgent = getResolvedSessionCursorHttp1Enabled();
+export function getCursorSessionConfig(scopeKey) {
+    const { runtime: sessionCursorRuntime, cloudAcknowledged: sessionCursorCloudAcknowledged } = getCursorSessionSettings(scopeKey);
+    const useHttp1ForAgent = getResolvedSessionCursorHttp1Enabled(scopeKey);
     return {
         ...(sessionCursorRuntime
             ? {
@@ -49,8 +48,8 @@ export function getCursorSessionConfig() {
 export function resolveEffectiveCursorConfig(options) {
     const loadedConfig = loadCursorSdkConfig({ cwd: options.cwd, projectTrusted: options.projectTrusted === true });
     return resolveCursorSdkConfig({
-        cli: getCursorCliConfig(),
-        session: getCursorSessionConfig(),
+        cli: getCursorCliConfig(options.scopeKey),
+        session: getCursorSessionConfig(options.scopeKey),
         user: loadedConfig.user,
         project: loadedConfig.project,
     });
@@ -58,7 +57,10 @@ export function resolveEffectiveCursorConfig(options) {
 export function resolveEffectiveCursorConfigForContext(ctx) {
     return resolveEffectiveCursorConfig({
         cwd: ctx.cwd,
-        projectTrusted: getCursorSessionCwd() === ctx.cwd && getCursorSessionProjectTrusted(),
+        projectTrusted: cursorSettingsScopeForContext(ctx) === undefined
+            ? getCursorSessionScopeSnapshot().cwd === ctx.cwd && getCursorSessionScopeSnapshot().projectTrusted
+            : getCursorSessionSettings(cursorSettingsScopeForContext(ctx)).projectTrusted,
+        scopeKey: cursorSettingsScopeForContext(ctx),
     });
 }
 export function resolveCursorStatusRuntime(ctx) {
@@ -90,15 +92,16 @@ export function formatCursorStatus(runtime, fast, mode, useHttp1ForAgent = false
         parts.push("plan");
     return parts.join(" · ");
 }
-export function consumeCursorLocalForceOverride(resolved) {
+export function consumeCursorLocalForceOverride(resolved, scopeKey) {
     if (!resolved.value)
         return false;
-    if (resolved.source === "cli" && !cliLocalForceConsumed) {
-        if (cliCursorSnapshot.config.local) {
-            const { force: _, ...local } = cliCursorSnapshot.config.local;
-            cliCursorSnapshot.config.local = local;
+    const cli = getCursorSessionSettings(scopeKey).cli;
+    if (resolved.source === "cli" && !cli.localForceConsumed) {
+        if (cli.config.local) {
+            const { force: _, ...local } = cli.config.local;
+            cli.config.local = local;
         }
-        cliLocalForceConsumed = true;
+        cli.localForceConsumed = true;
         return true;
     }
     if (resolved.source === "environment" && !envLocalForceConsumed) {
@@ -107,19 +110,21 @@ export function consumeCursorLocalForceOverride(resolved) {
     }
     return false;
 }
-export function restoreSessionCursorRuntimeState(branch) {
-    sessionCursorRuntime = undefined;
-    sessionCursorCloudAcknowledged = false;
+export function restoreSessionCursorRuntimeState(branch, scopeKey) {
+    const state = getCursorSessionSettings(scopeKey);
+    state.runtime = undefined;
+    state.cloudAcknowledged = false;
     for (const entry of branch) {
         if (entry.type !== "custom" || entry.customType !== CURSOR_RUNTIME_ENTRY_TYPE)
             continue;
         if (isCursorRuntimeEntryData(entry.data)) {
-            sessionCursorRuntime = entry.data.runtime;
-            sessionCursorCloudAcknowledged ||= entry.data.cloudAcknowledged === true;
+            state.runtime = entry.data.runtime;
+            state.cloudAcknowledged ||= entry.data.cloudAcknowledged === true;
         }
     }
 }
-export function restoreCursorCliState(pi) {
+export function restoreCursorCliState(pi, scopeKey) {
+    const cli = getCursorSessionSettings(scopeKey).cli;
     const runtime = stringFlagValue(pi.getFlag("cursor-runtime"));
     const repo = stringFlagValue(pi.getFlag("cursor-cloud-repo"));
     const branch = stringFlagValue(pi.getFlag("cursor-cloud-branch"));
@@ -144,30 +149,29 @@ export function restoreCursorCliState(pi) {
     const local = {
         ...(pi.getFlag("cursor-auto-review") === true ? { autoReview: true } : {}),
         ...(pi.getFlag("cursor-sandbox") === true ? { sandboxOptions: { enabled: true } } : {}),
-        ...(!cliLocalForceConsumed && pi.getFlag("cursor-local-force") === true ? { force: true } : {}),
+        ...(!cli.localForceConsumed && pi.getFlag("cursor-local-force") === true ? { force: true } : {}),
         ...(pi.getFlag("cursor-no-local-resume") === true
             ? { resume: false }
             : pi.getFlag("cursor-local-resume") === true
                 ? { resume: true }
                 : {}),
     };
-    cliCursorSnapshot = {
-        config: {
-            ...(runtime ? { runtime } : {}),
-            ...(Object.keys(cloud).length ? { cloud } : {}),
-            ...(Object.keys(local).length ? { local } : {}),
-        },
-        ...(cloudEnvNames ? { cloudEnvNames } : {}),
+    cli.config = {
+        ...(runtime ? { runtime } : {}),
+        ...(Object.keys(cloud).length ? { cloud } : {}),
+        ...(Object.keys(local).length ? { local } : {}),
     };
+    cli.cloudEnvNames = cloudEnvNames;
 }
-function persistCursorRuntimePreference(pi, runtime, cloudAcknowledged = false) {
-    const acknowledged = sessionCursorCloudAcknowledged || cloudAcknowledged;
+function persistCursorRuntimePreference(pi, runtime, cloudAcknowledged, scopeKey) {
+    const state = getCursorSessionSettings(scopeKey);
+    const acknowledged = state.cloudAcknowledged || cloudAcknowledged;
     pi.appendEntry(CURSOR_RUNTIME_ENTRY_TYPE, {
         runtime,
         ...(acknowledged ? { cloudAcknowledged: true } : {}),
     });
-    sessionCursorRuntime = runtime;
-    sessionCursorCloudAcknowledged = acknowledged;
+    state.runtime = runtime;
+    state.cloudAcknowledged = acknowledged;
 }
 function registerCursorRuntimeFlags(pi) {
     pi.registerFlag("cursor-runtime", {
@@ -277,6 +281,7 @@ function registerCursorRuntimeCommand(pi, refreshStatus) {
     pi.registerCommand("cursor-runtime", {
         description: "Set Cursor runtime for this session: local or cloud",
         handler: async (args, ctx) => {
+            const scopeKey = cursorSettingsScopeForContext(ctx);
             const usage = "Usage: /cursor-runtime local|cloud [--save-user|--save-project]";
             const tokens = args.trim().split(/\s+/).filter(Boolean);
             const raw = tokens[0];
@@ -298,7 +303,7 @@ function registerCursorRuntimeCommand(pi, refreshStatus) {
                 ctx.ui.notify(`${currentResolution.message} Fix the explicit override before changing the session runtime.`, "error");
                 return;
             }
-            if (saveProject && (getCursorSessionCwd() !== ctx.cwd || !getCursorSessionProjectTrusted())) {
+            if (saveProject && (getCursorSessionScopeSnapshot(pi).cwd !== ctx.cwd || !getCursorSessionScopeSnapshot(pi).projectTrusted)) {
                 ctx.ui.notify("Cannot save Cursor project config without explicit project-trust provenance. Ensure .pi/settings.json or another Pi project resource exists, trust the project, then restart pi; or restart with --approve. Project-local package installs must use --approve on every run that reads or writes .pi/cursor-sdk.json.", "error");
                 return;
             }
@@ -328,7 +333,7 @@ function registerCursorRuntimeCommand(pi, refreshStatus) {
                 }
             }
             try {
-                persistCursorRuntimePreference(pi, raw, cloudAcknowledged);
+                persistCursorRuntimePreference(pi, raw, cloudAcknowledged, scopeKey);
             }
             catch (error) {
                 const effectiveResolution = resolveCursorStatusRuntime(ctx);
@@ -372,9 +377,11 @@ export function registerCursorCloudRuntimeControls(pi, options) {
     });
 }
 export function resetCursorRuntimeStateForTests() {
-    cliCursorSnapshot = { config: {} };
-    cliLocalForceConsumed = false;
+    const cli = getCursorSessionSettings().cli;
+    cli.config = {};
+    cli.cloudEnvNames = undefined;
+    cli.localForceConsumed = false;
     envLocalForceConsumed = false;
-    sessionCursorRuntime = undefined;
-    sessionCursorCloudAcknowledged = false;
+    getCursorSessionSettings().runtime = undefined;
+    getCursorSessionSettings().cloudAcknowledged = false;
 }

package/dist/cursor-sdk-billed-usage.js

@@ -1,86 +1,65 @@
-import { asRecord, getArray, getString } from "./cursor-record-utils.js";
-import { readCursorSdkTurnUsage } from "./cursor-usage-accounting.js";
-const BILLED_USAGE_TIMEOUT_MS = 5000;
-// ponytail: process-lifetime watermark of billed usage UUIDs per agentId; reset on process exit.
-// Upgrade to session-scoped storage if multi-day processes retain enough agent IDs to matter.
-const seenBilledRunIdsByAgent = new Map();
-export function isCursorSdkClientMintedRunId(runId) {
-    return runId.startsWith("run-");
+import { asRecord } from "./cursor-record-utils.js";
+const fields = ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens"];
+export function readCursorUsageTokens(value) {
+    const record = asRecord(value);
+    if (!record || fields.some(key => !Number.isSafeInteger(record[key]) || record[key] < 0))
+        return undefined;
+    if (record.reasoningTokens !== undefined && (!Number.isSafeInteger(record.reasoningTokens) || record.reasoningTokens < 0 || record.reasoningTokens > record.outputTokens))
+        return undefined;
+    return { inputTokens: record.inputTokens, outputTokens: record.outputTokens, cacheReadTokens: record.cacheReadTokens, cacheWriteTokens: record.cacheWriteTokens, totalTokens: record.totalTokens, ...(record.reasoningTokens === undefined ? {} : { reasoningTokens: record.reasoningTokens }) };
 }
-export function sumCursorSdkTurnUsage(usages) {
-    if (usages.length === 0)
+function readCost(value) {
+    const record = asRecord(value);
+    if (!record || ["rawCostCents", "chargedCents"].some(key => typeof record[key] !== "number" || !Number.isFinite(record[key]) || record[key] < 0))
         return undefined;
-    return usages.reduce((total, usage) => ({
-        inputTokens: total.inputTokens + usage.inputTokens,
-        outputTokens: total.outputTokens + usage.outputTokens,
-        cacheReadTokens: total.cacheReadTokens + usage.cacheReadTokens,
-        cacheWriteTokens: total.cacheWriteTokens + usage.cacheWriteTokens,
-    }));
+    return { rawCostCents: record.rawCostCents, chargedCents: record.chargedCents };
 }
-export function peekCursorBilledUsageRunIds(agentId) {
-    return seenBilledRunIdsByAgent.get(agentId) ?? new Set();
+function billedTokens(value) {
+    const usage = readCursorUsageTokens(value);
+    if (!usage || usage.totalTokens !== usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens)
+        return undefined;
+    return usage;
 }
-export function rememberCursorBilledUsageRunIds(agentId, runIds) {
-    if (runIds.length === 0)
-        return;
-    let seen = seenBilledRunIdsByAgent.get(agentId);
-    if (!seen) {
-        seen = new Set();
-        seenBilledRunIdsByAgent.set(agentId, seen);
+export function readCursorBilledSnapshot(value) {
+    const record = asRecord(value);
+    const usage = billedTokens(record?.usage);
+    if (!record || !usage || !Array.isArray(record.runs))
+        return undefined;
+    const cost = record.cost === undefined ? undefined : readCost(record.cost);
+    if (record.cost !== undefined && !cost)
+        return undefined;
+    const runs = [];
+    const ids = new Set();
+    for (const item of record.runs) {
+        const row = asRecord(item);
+        const tokens = billedTokens(row?.usage);
+        const rowCost = row?.cost === undefined ? undefined : readCost(row.cost);
+        if (!row || typeof row.runId !== "string" || !row.runId || row.runId.length > 256 || ids.has(row.runId) || !tokens || (row.cost !== undefined && !rowCost))
+            return undefined;
+        ids.add(row.runId);
+        runs.push({ runId: row.runId, usage: tokens, ...(rowCost ? { cost: rowCost } : {}) });
     }
-    for (const runId of runIds)
-        seen.add(runId);
+    if (fields.some(key => runs.reduce((sum, row) => sum + row.usage[key], 0) > usage[key]))
+        return undefined;
+    return { usage, runs, ...(cost ? { cost } : {}) };
 }
-function withTimeout(promise, timeoutMs = BILLED_USAGE_TIMEOUT_MS) {
+/** Fetch is only observation; the origin journal owns recognition. No run-ID guesses or private fallback. */
+export async function fetchCursorSdkAgentUsage(agent) {
+    if (typeof agent.getUsage !== "function")
+        return { status: "unavailable", reason: "unsupported" };
     let timer;
-    const timeout = new Promise((resolve) => {
-        timer = setTimeout(() => resolve(undefined), timeoutMs);
-        timer.unref?.();
-    });
-    return Promise.race([promise.catch(() => undefined), timeout]).finally(() => {
+    try {
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => resolve({ status: "unavailable", reason: "timeout" }), 5000);
+            timer.unref?.();
+        });
+        return await Promise.race([Promise.resolve().then(() => agent.getUsage()).then(value => {
+                const snapshot = readCursorBilledSnapshot(value);
+                return snapshot ? { status: "observed-pending-settlement", snapshot } : { status: "unavailable", reason: "invalid-response" };
+            }, () => ({ status: "unavailable", reason: "request-failed" })), timeout]);
+    }
+    finally {
         if (timer)
             clearTimeout(timer);
-    });
-}
-export function selectCursorBilledTurnUsage(agentUsage, options) {
-    const runs = (getArray(asRecord(agentUsage), "runs") ?? []).flatMap((item) => {
-        const record = asRecord(item);
-        const runId = getString(record, "runId");
-        const usage = readCursorSdkTurnUsage(record?.usage);
-        return runId && usage ? [{ runId, usage }] : [];
-    });
-    if (options.runtime === "cloud" && options.runId) {
-        const match = runs.find((run) => run.runId === options.runId);
-        return match ? { turn: match.usage, runIds: [match.runId] } : { runIds: [] };
     }
-    const unseen = runs.filter((run) => !options.seenRunIds?.has(run.runId));
-    return { turn: sumCursorSdkTurnUsage(unseen.map((run) => run.usage)), runIds: unseen.map((run) => run.runId) };
-}
-export async function fetchCursorSdkAgentUsage(agent, options) {
-    if (typeof agent.getUsage !== "function")
-        return undefined;
-    const query = options.runtime === "cloud" && options.runId && isCursorSdkClientMintedRunId(options.runId)
-        ? { runId: options.runId }
-        : undefined;
-    return withTimeout(Promise.resolve(agent.getUsage(query)));
-}
-export async function attachCursorSdkBilledTurnUsage(options) {
-    const agentUsage = await fetchCursorSdkAgentUsage(options.agent, {
-        runtime: options.runtime,
-        runId: options.runId,
-    });
-    if (!agentUsage)
-        return {};
-    const selected = selectCursorBilledTurnUsage(agentUsage, {
-        runtime: options.runtime,
-        runId: options.runtime === "cloud" ? options.runId : undefined,
-        seenRunIds: peekCursorBilledUsageRunIds(options.agentId),
-    });
-    rememberCursorBilledUsageRunIds(options.agentId, selected.runIds);
-    return { agentUsage, turn: selected.turn };
 }
-export const __testUtils = {
-    reset() {
-        seenBilledRunIdsByAgent.clear();
-    },
-};

package/dist/cursor-sdk-event-debug-session.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV, CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV, SESSION_MANIFEST, resolveCursorSdkEventDebugBaseDir, } from "./cursor-sdk-event-debug-constants.js";
-import { getCursorSessionFile, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
 const sessionDebugStates = new Map();
 function sanitizePathSegment(value) {
@@ -46,12 +46,12 @@ function resolveSessionDebugDir(cwd, env, scopeKey) {
         return resolve(pinned);
     return join(resolveCursorSdkEventDebugBaseDir(cwd, env), "sessions", slugSessionKey(scopeKey));
 }
-export function allocateCursorSdkEventDebugTurn(cwd, env) {
+export function allocateCursorSdkEventDebugTurn(cwd, env, scope = getCursorSessionScopeSnapshot()) {
     const pinnedRunDir = resolvePinnedRunArtifactDir(env[CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV]);
     if (pinnedRunDir) {
         return { artifactDir: pinnedRunDir, pinnedRun: true };
     }
-    const scopeKey = getCursorSessionScopeKey();
+    const scopeKey = scope.scopeKey;
     const sessionDir = resolveSessionDebugDir(cwd, env, scopeKey);
     mkdirSync(sessionDir, { recursive: true });
     let state = sessionDebugStates.get(scopeKey);
@@ -67,13 +67,13 @@ export function allocateCursorSdkEventDebugTurn(cwd, env) {
     const existing = readSessionManifest(sessionDir);
     const manifest = existing ?? {
         sessionKey: scopeKey,
-        sessionFile: getCursorSessionFile(),
+        sessionFile: scope.sessionFile,
         sessionDir,
         createdAt: new Date().toISOString(),
         updatedAt: new Date().toISOString(),
         turns: [],
     };
-    manifest.sessionFile = getCursorSessionFile();
+    manifest.sessionFile = scope.sessionFile;
     manifest.updatedAt = new Date().toISOString();
     manifest.turns.push({
         turn: state.turnCounter,
@@ -99,7 +99,6 @@ export function updateCursorSdkEventDebugSessionManifest(sessionDir, artifactDir
     turnEntry.finalizedAt = new Date().toISOString();
     turnEntry.summary = summary;
     manifest.updatedAt = new Date().toISOString();
-    manifest.sessionFile = getCursorSessionFile();
     writeSessionManifest(sessionDir, manifest);
 }
 export function resetCursorSdkEventDebugSessionStateForTests() {

package/dist/cursor-sdk-event-debug.js

@@ -3,7 +3,7 @@ import { copyFileSync, existsSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { serializeCursorPiToolBridgeDiagnostic } from "./cursor-pi-tool-bridge-diagnostics.js";
 import { asRecord } from "./cursor-record-utils.js";
-import { getCursorSessionFile } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { ARTIFACTS, CURSOR_SDK_EVENT_DEBUG_ENV, CURSOR_SDK_EVENT_DEBUG_LOG_PREFIX, CURSOR_SDK_EVENT_DEBUG_STDERR_ENV, SESSION_MANIFEST, SESSION_PI_SESSION_SNAPSHOT, } from "./cursor-sdk-event-debug-constants.js";
 import { allocateCursorSdkEventDebugTurn, resetCursorSdkEventDebugSessionStateForTests, slugSessionKey, updateCursorSdkEventDebugSessionManifest, } from "./cursor-sdk-event-debug-session.js";
@@ -122,6 +122,7 @@ export class CursorSdkEventDebugSink {
         timeline: {},
         errors: 0,
     };
+    sessionFile;
     metadata;
     jsonlBuffers = new Map();
     jsonlBufferBytes = new Map();
@@ -135,8 +136,9 @@ export class CursorSdkEventDebugSink {
         const env = options.env ?? process.env;
         if (!resolveCursorSdkEventDebugEnabled(env))
             return undefined;
-        const allocation = allocateCursorSdkEventDebugTurn(options.cwd, env);
-        return new CursorSdkEventDebugSink(allocation, options, env);
+        const scope = options.scope ?? getCursorSessionScopeSnapshot();
+        const allocation = allocateCursorSdkEventDebugTurn(options.cwd, env, scope);
+        return new CursorSdkEventDebugSink(allocation, { ...options, scope }, env);
     }
     constructor(allocation, options, env) {
         this.artifactDir = allocation.artifactDir;
@@ -145,6 +147,7 @@ export class CursorSdkEventDebugSink {
         this.sessionKey = allocation.sessionKey;
         this.pinnedRun = allocation.pinnedRun;
         this.env = env;
+        this.sessionFile = options.scope?.sessionFile;
         this.metadata = {
             capturedAt: new Date().toISOString(),
             modelId: options.modelId,
@@ -152,7 +155,7 @@ export class CursorSdkEventDebugSink {
             cwd: options.cwd,
             sessionDir: allocation.sessionDir,
             sessionKey: allocation.sessionKey,
-            sessionFile: getCursorSessionFile(),
+            sessionFile: this.sessionFile,
             turn: allocation.turn,
             pinnedRun: allocation.pinnedRun,
             artifacts: ARTIFACTS,
@@ -285,7 +288,7 @@ export class CursorSdkEventDebugSink {
         writeFileSync(join(this.artifactDir, ARTIFACTS.waitResult), `${JSON.stringify(result, null, 2)}\n`);
     }
     capturePiSessionSnapshot() {
-        const sessionFile = getCursorSessionFile();
+        const sessionFile = this.sessionFile;
         if (!sessionFile) {
             return { copied: false, reason: "session file unknown" };
         }
@@ -342,7 +345,7 @@ export class CursorSdkEventDebugSink {
             artifactDir: this.artifactDir,
             sessionDir: this.sessionDir,
             sessionKey: this.sessionKey,
-            sessionFile: getCursorSessionFile(),
+            sessionFile: this.sessionFile,
             turn: this.turn,
             elapsedMs: Date.now() - this.startedAt,
             counts: {

package/dist/cursor-sdk-output-filter.js

@@ -1 +1 @@
-export { CURSOR_SDK_STARTUP_NOISE_PATTERNS, installCursorSdkOutputFilter, isCursorSdkOutputSuppressed, isCursorSdkStartupNoise, suppressCursorSdkOutput, } from "../shared/cursor-sdk-output-filter.mjs";
+export { CURSOR_SDK_STARTUP_NOISE_PATTERNS, withCursorSdkOutputNoticeHandler, installCursorSdkOutputFilter, isCursorSdkOutputSuppressed, isCursorSdkStartupNoise, suppressCursorSdkOutput, } from "../shared/cursor-sdk-output-filter.mjs";