pi-cursor-sdk 0.4.0 → 0.5.2

package/dist/cursor-session-agent.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 import { getRegisteredCursorPiToolBridge, } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
 import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
@@ -26,11 +27,14 @@ function assertScopeAcceptsAcquire(scopeKey) {
     }
     terminalDisposedScopeGenerations.delete(scopeKey);
 }
-function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error) {
+function samePoolIdentity(entry, poolKey, capturedStoreRoot) {
+    return entry.poolKey === poolKey && entry.storeRoot === capturedStoreRoot;
+}
+function rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, storeRoot, error) {
     if (!(error instanceof SessionCursorAgentCreationSupersededError))
         return;
     const replacement = sessionAgentsByScope.get(scopeKey);
-    if (replacement && replacement.poolKey !== poolKey) {
+    if (replacement && !samePoolIdentity(replacement, poolKey, storeRoot)) {
         throw error;
     }
 }
@@ -82,12 +86,25 @@ function buildLocalSafetyPoolKey(localSafety) {
 function buildApiKeyPoolKeyFingerprint(apiKey) {
     return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
-function buildBridgePoolKeySuffix() {
-    const registeredBridge = getRegisteredCursorPiToolBridge();
+function buildBridgePoolKeySuffix(registeredBridge) {
     if (!registeredBridge)
         return "bridge:absent";
     return registeredBridge.getToolSurfaceSignature();
 }
+function buildCustomSubagentPoolKeySuffix(agents) {
+    const definitions = Object.entries(agents ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    if (!definitions.length)
+        return [];
+    const content = definitions.map(([name, entry]) => [
+        name, entry.description, entry.prompt,
+        entry.model === undefined ? null : entry.model === "inherit" ? "inherit" : {
+            id: entry.model.id,
+            params: [...(entry.model.params ?? [])].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : a.value < b.value ? -1 : a.value > b.value ? 1 : 0)
+                .map(({ id, value }) => ({ id, value })),
+        },
+    ]);
+    return [`subagents:${createHash("sha256").update(JSON.stringify(content)).digest("hex")}`];
+}
 function buildSessionAgentPoolKey(scopeKey, params) {
     return [
         scopeKey,
@@ -101,7 +118,8 @@ function buildSessionAgentPoolKey(scopeKey, params) {
                 ? "http1:on"
                 : "http1:off",
         buildApiKeyPoolKeyFingerprint(params.apiKey),
-        buildBridgePoolKeySuffix(),
+        buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
+        ...buildCustomSubagentPoolKeySuffix(params.agents),
     ].join("\0");
 }
 async function disposePoolEntry(entry, options) {
@@ -179,7 +197,7 @@ function commitSessionAgentSendForLease(scopeKey, poolKey, instanceId, context,
             poolKey: entry.poolKey,
             sendState: entry.sendState,
             storeIdentity: entry.sessionStore.identity,
-        });
+        }, scopeKey);
     }
 }
 function normalizeRunCompletion(completion) {
@@ -253,11 +271,11 @@ function leaseFromEntry(entry, scopeKey, params, created) {
         },
     };
 }
-function getCurrentReadyPoolEntry(scopeKey, poolKey) {
+function getCurrentReadyPoolEntry(scopeKey, poolKey, storeRoot) {
     const current = sessionAgentsByScope.get(scopeKey);
     if (current?.status !== "ready")
         return undefined;
-    if (current.poolKey !== poolKey)
+    if (!samePoolIdentity(current, poolKey, storeRoot))
         return undefined;
     return current;
 }
@@ -270,7 +288,7 @@ async function tryLeaseReadyEntry(entry, scopeKey, params, poolKey, created) {
         await disposePoolEntryForScope(scopeKey);
         return undefined;
     }
-    const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey);
+    const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey, params.storeRoot);
     if (!readyEntry)
         return undefined;
     return leaseFromEntry(readyEntry, scopeKey, params, created);
@@ -279,7 +297,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
     let bridgeRun;
     let sessionStore;
     try {
-        const registeredBridge = getRegisteredCursorPiToolBridge();
+        const registeredBridge = params.bridge;
         if (registeredBridge) {
             bridgeRun = await registeredBridge.createRun({
                 onToolRequest: params.onBridgeToolRequest,
@@ -299,16 +317,15 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             createAgent ??= sdk.Agent.create;
             resumeAgent ??= sdk.Agent.resume;
         }
-        const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey) : undefined;
+        const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey, scopeKey) : undefined;
         const storeSelection = await openCursorSessionStoreForScope({
             cwd: params.cwd,
             scopeKey,
             persistent: persistentStore,
-            hasResumeHandle: resumeHandle !== undefined,
-            resumeIdentity: resumeHandle?.storeIdentity,
+            storeRoot: params.storeRoot,
+            resume: resumeHandle ? { identity: resumeHandle.storeIdentity, agentId: resumeHandle.agentId } : undefined,
         });
         sessionStore = storeSelection.sessionStore;
-        const { identities } = storeSelection;
         const resumeAttemptAllowed = storeSelection.resumeAttemptAllowed;
         let resumeNotice = storeSelection.resumeFallback ? LOCAL_RESUME_FALLBACK_NOTICE : undefined;
         const buildAgentOptions = () => ({
@@ -322,6 +339,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
                 store: sessionStore.store,
             }),
             ...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
+            ...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
         });
         let agent;
         let effectiveSendState = sendState;
@@ -335,9 +353,11 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             catch {
                 if (persistentStore)
                     resumeNotice = LOCAL_RESUME_FALLBACK_NOTICE;
-                if (!cursorSessionStoreIdentitiesEqual(sessionStore.identity, identities.sessionStore)) {
+                if (storeSelection.persistent && !cursorSessionStoreIdentitiesEqual(sessionStore.identity, storeSelection.identities.sessionStore)) {
+                    const { identities } = storeSelection;
+                    const replacement = await openCursorSessionStore(params.cwd, identities.sessionStore, identities.workspaceRoot, identities.storeRoot);
                     await sessionStore.dispose().catch(() => undefined);
-                    sessionStore = await openCursorSessionStore(params.cwd, identities.sessionStore);
+                    sessionStore = replacement;
                 }
             }
         }
@@ -349,6 +369,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
         return {
             status: "ready",
             poolKey: resolvedPoolKey,
+            storeRoot: params.storeRoot,
             instanceId,
             scopeKey,
             agent,
@@ -373,9 +394,11 @@ export function invalidateSessionAgent(scopeKey = getCursorSessionScopeKey(), op
     if (options?.deadTransport)
         deadTransportScopeKeys.add(scopeKey);
 }
-export async function acquireSessionCursorAgent(params) {
-    const scopeKey = getCursorSessionScopeKey();
-    const persistentStore = getCursorSessionFile() !== undefined;
+export async function acquireSessionCursorAgent(input) {
+    const params = { ...input, bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
+    const scopeKey = params.scope?.scopeKey ?? getCursorSessionScopeKey();
+    const persistentStore = (params.scope ? params.scope.sessionFile : getCursorSessionFile()) !== undefined;
+    params.storeRoot = persistentStore && params.storeRoot !== undefined ? normalizeCursorCustomStoreRoot(params.storeRoot) : undefined;
     while (true) {
         assertScopeAcceptsAcquire(scopeKey);
         if (invalidatedScopeKeys.has(scopeKey)) {
@@ -383,7 +406,7 @@ export async function acquireSessionCursorAgent(params) {
         }
         const poolKey = buildSessionAgentPoolKey(scopeKey, params);
         const state = getSessionCursorAgentPoolState(scopeKey);
-        if ((state.status === "ready" || state.status === "busy") && state.poolKey !== poolKey) {
+        if ((state.status === "ready" || state.status === "busy") && !samePoolIdentity(state, poolKey, params.storeRoot)) {
             await disposePoolEntryForScope(scopeKey);
             continue;
         }
@@ -398,7 +421,7 @@ export async function acquireSessionCursorAgent(params) {
             continue;
         }
         if (state.status === "creating") {
-            if (state.poolKey !== poolKey) {
+            if (!samePoolIdentity(state, poolKey, params.storeRoot)) {
                 await disposePoolEntryForScope(scopeKey);
                 continue;
             }
@@ -408,7 +431,7 @@ export async function acquireSessionCursorAgent(params) {
             catch (error) {
                 if (error instanceof SessionCursorAgentCreationSupersededError) {
                     assertScopeAcceptsAcquire(scopeKey);
-                    rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+                    rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
                     continue;
                 }
                 throw error;
@@ -436,6 +459,7 @@ export async function acquireSessionCursorAgent(params) {
         placeholder = {
             status: "creating",
             poolKey,
+            storeRoot: params.storeRoot,
             instanceId,
             scopeKey,
             sendState,
@@ -456,7 +480,7 @@ export async function acquireSessionCursorAgent(params) {
             }
             if (error instanceof SessionCursorAgentCreationSupersededError) {
                 assertScopeAcceptsAcquire(scopeKey);
-                rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+                rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
                 continue;
             }
             throw error;
@@ -495,8 +519,6 @@ export const __testUtils = {
     resetSessionCursorAgent,
     refreshSessionCursorAgentConfig,
     disposeAllSessionCursorAgents,
-    buildApiKeyPoolKeyFingerprint,
-    buildSessionAgentPoolKey,
     setDeadTransportAgentDisposeTimeoutMs(ms) {
         const previous = deadTransportAgentDisposeTimeoutMs;
         deadTransportAgentDisposeTimeoutMs = ms;

package/dist/cursor-session-compaction-prep.js

@@ -1,16 +1,11 @@
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
-import { suppressCursorSessionAgentResumeHandlePersist } from "./cursor-session-agent-resume.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 /**
- * Prepare the pooled Cursor session agent for pi compaction summarization.
- * Releases any scoped live-run drain state still tied to the pooled agent, then
- * disposes the pool entry so summarization acquires a clean SDK agent.
- * Suppresses local-resume handle persist so the summarizer send cannot leak
- * a one-message handle into the next normal turn (#223).
+ * Release scoped conversation runs and reset the pool before compaction.
+ * Summary execution owns a separate temporary agent, never this pool.
  */
 export async function prepareCursorSessionForCompaction(scopeKey = getCursorSessionScopeKey()) {
-    suppressCursorSessionAgentResumeHandlePersist();
     while (true) {
         const run = cursorLiveRuns.getActiveForScope(scopeKey);
         if (!run || run.disposed)

package/dist/cursor-session-scope.js

@@ -12,40 +12,58 @@ const state = {
     projectTrusted: false,
     sessionGeneration: 0,
 };
-const scopeGenerations = new Map([[ANONYMOUS_SESSION_SCOPE_KEY, state.sessionGeneration]]);
+const scopes = new Map();
+const scopeChangeHandlers = new Map();
+const scopeGenerations = new Map([[ANONYMOUS_SESSION_SCOPE_KEY, 0]]);
 const projectTrustResolutionCwds = new Set();
 let nextSessionGeneration = 1;
-let scopeChangeHandler;
-/**
- * Pi session file when known; used to scope reused Cursor SDK agents to one pi session.
- */
+function scopeKeyFor(record) {
+    if (record.sessionFile)
+        return record.sessionFile;
+    if (record.sessionId)
+        return `${EPHEMERAL_SESSION_SCOPE_PREFIX}${record.sessionId}`;
+    return ANONYMOUS_SESSION_SCOPE_KEY;
+}
+export function cursorSessionScopeKeyForManager(manager) {
+    return manager.getSessionFile?.() ?? (manager.getSessionId?.()
+        ? `${EPHEMERAL_SESSION_SCOPE_PREFIX}${manager.getSessionId()}`
+        : ANONYMOUS_SESSION_SCOPE_KEY);
+}
+export function getCursorSessionScopeSnapshot(pi) {
+    if (!pi && scopes.size > 1)
+        throw new Error("Cursor provider ownership requires a session-bound provider closure when multiple extensions are loaded.");
+    const record = pi ? scopes.get(pi) : state;
+    if (!record)
+        throw new Error("Cursor session binding is no longer active.");
+    const scopeKey = scopeKeyFor(record);
+    return Object.freeze({
+        cwd: record.sessionCwd,
+        scopeKey,
+        sessionFile: record.sessionFile,
+        sessionId: record.sessionId,
+        sessionName: record.sessionName,
+        projectTrusted: record.projectTrusted,
+        generation: getCursorSessionScopeGeneration(scopeKey),
+    });
+}
+export function hasLiveCursorSessions() {
+    return scopes.size > 0;
+}
 export function getCursorSessionFile() {
     return state.sessionFile;
 }
-/**
- * Stable scope key for session-agent pooling. Falls back to a process-local anonymous key
- * before the first session_start (tests and early startup).
- */
+/** Stable pool key, with process-local anonymous fallback before session_start. */
 export function getCursorSessionScopeKey() {
-    if (state.sessionFile)
-        return state.sessionFile;
-    if (state.sessionId)
-        return `${EPHEMERAL_SESSION_SCOPE_PREFIX}${state.sessionId}`;
-    return ANONYMOUS_SESSION_SCOPE_KEY;
+    return scopeKeyFor(state);
 }
 export function getCursorSessionScopeGeneration(scopeKey = getCursorSessionScopeKey()) {
     return scopeGenerations.get(scopeKey) ?? 0;
 }
-/**
- * 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() {
     return state.sessionCwd;
 }
-export function getCursorSessionProjectTrusted() {
-    return state.projectTrusted;
+export function getCursorSessionProjectTrusted(pi) {
+    return pi ? scopes.get(pi)?.projectTrusted === true : state.projectTrusted;
 }
 export function getCursorSessionName() {
     return state.sessionName;
@@ -61,9 +79,8 @@ function setCursorSessionScope(cwd, sessionFile, sessionId, projectTrusted = fal
     state.sessionId = sessionId;
     state.sessionName = normalizeCursorSessionName(sessionName);
     state.projectTrusted = projectTrusted;
-    state.sessionGeneration = nextSessionGeneration;
-    nextSessionGeneration += 1;
-    scopeGenerations.set(getCursorSessionScopeKey(), state.sessionGeneration);
+    state.sessionGeneration = nextSessionGeneration++;
+    scopeGenerations.set(scopeKeyFor(state), state.sessionGeneration);
 }
 function recordProjectTrustResolution(cwd) {
     projectTrustResolutionCwds.add(resolve(cwd));
@@ -72,35 +89,50 @@ function isCliProjectTrustApproved(args = process.argv.slice(2)) {
     return parseArgs(args).projectTrustOverride === true;
 }
 function resetCursorSessionScope() {
-    state.sessionCwd = process.cwd();
-    state.sessionFile = undefined;
-    state.sessionId = undefined;
-    state.sessionName = undefined;
-    state.projectTrusted = false;
-    state.sessionGeneration = 0;
+    Object.assign(state, {
+        sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
+        sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+    });
     nextSessionGeneration = 1;
     scopeGenerations.clear();
-    scopeGenerations.set(ANONYMOUS_SESSION_SCOPE_KEY, state.sessionGeneration);
+    scopeGenerations.set(ANONYMOUS_SESSION_SCOPE_KEY, 0);
     projectTrustResolutionCwds.clear();
+    scopes.clear();
+    scopeChangeHandlers.clear();
 }
-export function onCursorSessionScopeKeyChange(handler) {
-    scopeChangeHandler = handler;
+export function onCursorSessionScopeKeyChange(pi, handler) {
+    scopeChangeHandlers.set(pi, handler);
 }
 export function registerCursorSessionScope(pi) {
+    // A fresh binding has no previous pooled scope to steal from the last-bound mirror.
+    const record = {
+        sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
+        sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+    };
+    scopes.set(pi, record);
+    const trustedCwds = new Set();
     pi.on("project_trust", (event) => {
-        recordProjectTrustResolution(event.cwd);
+        trustedCwds.add(resolve(event.cwd));
         return { trusted: "undecided" };
     });
     pi.on("session_start", async (_event, ctx) => {
-        const previousScopeKey = getCursorSessionScopeKey();
+        const previousScopeKey = scopeKeyFor(record);
+        const wasBound = record.sessionGeneration > 0;
         setCursorSessionScope(ctx.cwd, ctx.sessionManager?.getSessionFile?.() ?? undefined, ctx.sessionManager?.getSessionId?.() ?? undefined, ctx.isProjectTrusted?.() === true
-            && (projectTrustResolutionCwds.has(resolve(ctx.cwd)) || isCliProjectTrustApproved()), ctx.sessionManager?.getSessionName?.() ?? undefined);
-        if (previousScopeKey !== getCursorSessionScopeKey()) {
-            await scopeChangeHandler?.(previousScopeKey);
+            && (trustedCwds.has(resolve(ctx.cwd)) || projectTrustResolutionCwds.has(resolve(ctx.cwd)) || isCliProjectTrustApproved()), ctx.sessionManager?.getSessionName?.() ?? undefined);
+        Object.assign(record, state);
+        scopes.set(pi, record);
+        if (wasBound && previousScopeKey !== scopeKeyFor(record)) {
+            await scopeChangeHandlers.get(pi)?.(previousScopeKey);
         }
     });
     pi.on("session_info_changed", (event) => {
-        state.sessionName = normalizeCursorSessionName(event.name);
+        record.sessionName = normalizeCursorSessionName(event.name);
+        Object.assign(state, record);
+    });
+    pi.on("session_shutdown", () => {
+        scopes.delete(pi);
+        scopeChangeHandlers.delete(pi);
     });
 }
 export const __testUtils = {

package/dist/cursor-session-send-policy.js

@@ -1,14 +1,14 @@
 import { buildCursorIncrementalPrompt, buildCursorPrompt, shouldBootstrapCursorContext, } from "./context.js";
 // Long-lived SDK session agents can drift tool-call behavior; recreate the agent after this many successful incremental sends.
 export const MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP = 20;
-export function planCursorSessionSend(sendState, context) {
+export function planCursorSessionSend(sendState, context, nativeSourceRoles) {
     if (!sendState.bootstrapped) {
         return { mode: "bootstrap", resetAgent: false, reason: "initial" };
     }
     if (sendState.incrementalSendCount >= MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP) {
         return { mode: "bootstrap", resetAgent: true, reason: "incremental_threshold" };
     }
-    if (shouldBootstrapCursorContext(sendState, context)) {
+    if (shouldBootstrapCursorContext(sendState, context, nativeSourceRoles)) {
         return { mode: "bootstrap", resetAgent: true, reason: "context_divergence" };
     }
     return { mode: "incremental", resetAgent: false, reason: "incremental" };

package/dist/cursor-session-settings.js

@@ -0,0 +1,61 @@
+import { cursorSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+function createCliSettings() {
+    return {
+        forceFast: false, forceNoFast: false,
+        mode: { kind: "unset" },
+        config: {},
+        cloudEnvNames: undefined,
+        localForceConsumed: false,
+    };
+}
+function createSettings() {
+    return {
+        fast: new Map(),
+        mode: undefined,
+        runtime: undefined,
+        cloudAcknowledged: false,
+        http1: undefined,
+        projectTrusted: false,
+        cli: createCliSettings(),
+    };
+}
+const settings = new Map();
+let cliOwners = new WeakMap();
+let legacySettings = createSettings();
+export function getCursorSessionSettings(scopeKey) {
+    if (scopeKey === undefined)
+        return legacySettings;
+    let value = settings.get(scopeKey);
+    if (!value) {
+        value = createSettings();
+        settings.set(scopeKey, value);
+    }
+    return value;
+}
+export function cursorSettingsScopeForContext(ctx) {
+    const manager = ctx.sessionManager;
+    return manager ? cursorSessionScopeKeyForManager(manager) : undefined;
+}
+export function registerCursorSessionSettings(pi) {
+    let scopeKey;
+    let cli = createCliSettings();
+    pi.on("session_start", (_event, ctx) => {
+        if (scopeKey)
+            settings.delete(scopeKey);
+        scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager);
+        legacySettings = getCursorSessionSettings(scopeKey);
+        // Reload creates a new ExtensionAPI but retains the same public manager.
+        // Keep the run's one-shot CLI consumption without retaining dead managers.
+        cli = cliOwners.get(ctx.sessionManager) ?? cli;
+        cliOwners.set(ctx.sessionManager, cli);
+        legacySettings.cli = cli;
+        legacySettings.projectTrusted = getCursorSessionProjectTrusted(pi);
+    });
+    pi.on("session_shutdown", () => { if (scopeKey)
+        settings.delete(scopeKey); });
+}
+export function resetCursorSessionSettingsForTests() {
+    settings.clear();
+    cliOwners = new WeakMap();
+    legacySettings = createSettings();
+}