@cursor/july 0.1.105 → 0.1.108

package/dist/internal/session-engine.js

@@ -36,11 +36,12 @@ import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
 import { assertTimeArgs, normalizeAsOf, schemaTimeWindowKeys, sessionClock, } from "./as-of.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
+import { mergeChannelStateMutation, mergeChannelStateSkipNull, } from "./channel-state.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { applyCloudUsageToEvents, cloudSdkAgentIdFromEvents, isUnpricedCompletedTurn, mapSdkTokenUsage, } from "./cloud-turn-cost.js";
 import { applyAgentContinuationDefaults, channelContinuationIdentity, httpContinuationIdentity, } from "./continuation-channel.js";
 import { continuationSource, resolveV2Key, V2EngineError, } from "./continuation-identity.js";
-import { describeError } from "./describe-error.js";
+import { describeError, describeErrorCode } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
@@ -52,6 +53,7 @@ import { createHostKvApi } from "./host-kv.js";
 import { createHostOtelApi } from "./host-otel.js";
 import { createHostPlatforms, createHostSlackClient, } from "./host-platforms.js";
 import { HostedAdmissionLocalSendError, isDuringHostedAdmission, } from "./hosted-admission-context.js";
+import { hostedSessionResumeKey } from "./hosted-catch-protocol.js";
 import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, parseContinuationToken, } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { isMcpNeedsAuthError, McpHost } from "./mcp-host.js";
@@ -75,6 +77,7 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import { buildAgentsMdContent, buildCloudMemorySection, buildCloudSessionWorkspaceSection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, } from "./workspace.js";
 import { syncSessionWorkspaceFiles, syncWorkspaceToStore, WorkspaceFileRefusal, wipeSessionWorkspace, } from "./workspace-sync.js";
 export const HTTP_CHANNEL_ID = "http";
+export { mergeChannelStateSkipNull } from "./channel-state.js";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export class SessionBusyError extends Error {
     constructor(sessionId) {
@@ -570,8 +573,8 @@ export class SessionEngine {
      */
     send(channelId_1, message_1) {
         return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
-            var _a;
-            var _b, _c, _d, _e, _f, _g;
+            var _a, _b;
+            var _c, _d, _e, _f, _g, _h;
             if (isDuringHostedAdmission()) {
                 // Only sends that bypassed the admission capture stub (typically a
                 // startup-captured `onStart` send) reach the engine inside the
@@ -592,7 +595,7 @@ export class SessionEngine {
                 sendOptions = Object.assign(Object.assign({}, options), { continuationToken: cKey });
                 skipContinuationLookup = cKey.startsWith("evt:");
             }
-            const auth = (_b = sendOptions.auth) !== null && _b !== void 0 ? _b : null;
+            const auth = (_c = sendOptions.auth) !== null && _c !== void 0 ? _c : null;
             let existing = skipContinuationLookup || sendOptions.continuationToken === undefined
                 ? undefined
                 : yield this.sessions.findByContinuation(channelId, sendOptions.continuationToken);
@@ -603,6 +606,16 @@ export class SessionEngine {
                 // fell outside the startup restore window, or restore is lazy-only).
                 existing = yield this.restoreSessionByContinuation(channelId, sendOptions.continuationToken);
             }
+            if (existing === undefined &&
+                sendOptions.hostedSessionId !== undefined &&
+                ((_a = sendOptions.mailboxContinuation) === null || _a === void 0 ? void 0 : _a.key) ===
+                    hostedSessionResumeKey(sendOptions.hostedSessionId)) {
+                // Explicit control-plane resume of an existing session: the CP named
+                // the session by its own id and stamped the matching resume key. The
+                // session keeps its original continuation key (a PR lane must stay
+                // addressable by its webhooks); this is a follow-up turn by id.
+                existing = yield this.getOrRestoreSession(sendOptions.hostedSessionId);
+            }
             if (existing !== undefined) {
                 if (sendOptions.hostedSessionId !== undefined &&
                     existing.sessionId !== sendOptions.hostedSessionId) {
@@ -638,7 +651,7 @@ export class SessionEngine {
                     record = yield this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { channelState: mergeChannelStateSkipNull(current.channelState, sendOptions.refreshState) })));
                 }
                 const since = (yield this.logs.get(record.sessionId)).count;
-                const coalesced = yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_c = sendOptions.admission) !== null && _c !== void 0 ? _c : "preempt" }, (sendOptions.coalesceSourceTs === undefined
+                const coalesced = yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_d = sendOptions.admission) !== null && _d !== void 0 ? _d : "preempt" }, (sendOptions.coalesceSourceTs === undefined
                     ? {}
                     : { sourceTs: sendOptions.coalesceSourceTs })));
                 return this.channelSession(record.sessionId, record, false, coalesced, since);
@@ -655,13 +668,13 @@ export class SessionEngine {
             const frozenAsOf = normalizeAsOf(sendOptions.asOf);
             assertTimeArgs(this.project.agent.tools, frozenAsOf);
             let record = {
-                sessionId: (_d = sendOptions.hostedSessionId) !== null && _d !== void 0 ? _d : newSessionId(),
+                sessionId: (_e = sendOptions.hostedSessionId) !== null && _e !== void 0 ? _e : newSessionId(),
                 channelId,
-                mode: (_e = sendOptions.mode) !== null && _e !== void 0 ? _e : "chat",
+                mode: (_f = sendOptions.mode) !== null && _f !== void 0 ? _f : "chat",
                 purpose,
                 dryRun: sendOptions.dryRun === true ? true : undefined,
                 asOf: frozenAsOf,
-                continuationKey: (_f = sendOptions.continuationToken) !== null && _f !== void 0 ? _f : newContinuationKey(),
+                continuationKey: (_g = sendOptions.continuationToken) !== null && _g !== void 0 ? _g : newContinuationKey(),
                 auth,
                 title: sendOptions.title,
                 channelState,
@@ -675,7 +688,7 @@ export class SessionEngine {
                 updatedAt: now,
             };
             yield this.sessions.save(record);
-            (_a = this.storage) === null || _a === void 0 ? void 0 : _a.sessionRecord(record);
+            (_b = this.storage) === null || _b === void 0 ? void 0 : _b.sessionRecord(record);
             yield this.appendEvent(record.sessionId, {
                 type: "session.started",
                 data: {
@@ -685,7 +698,7 @@ export class SessionEngine {
             });
             record = yield this.enrollABs(record);
             const since = (yield this.logs.get(record.sessionId)).count;
-            yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_g = sendOptions.admission) !== null && _g !== void 0 ? _g : "preempt" }, (sendOptions.coalesceSourceTs === undefined
+            yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_h = sendOptions.admission) !== null && _h !== void 0 ? _h : "preempt" }, (sendOptions.coalesceSourceTs === undefined
                 ? {}
                 : { sourceTs: sendOptions.coalesceSourceTs })));
             return this.channelSession(record.sessionId, record, true, false, since);
@@ -1118,11 +1131,17 @@ export class SessionEngine {
                     poll.unref();
                     try {
                         outcome = yield this.executeTurn(record, turnId, message, isFirstTurn, abort.signal);
+                        if (outcome.status === "cancelled") {
+                            outcome.cancellationReason = abort.signal.aborted
+                                ? "signal"
+                                : "runner";
+                        }
                     }
                     catch (error) {
                         outcome = {
                             status: "error",
                             errorMessage: describeError(error),
+                            errorCode: describeErrorCode(error),
                         };
                     }
                     finally {
@@ -1562,10 +1581,15 @@ export class SessionEngine {
     }
     executeTurn(record, turnId, message, isFirstTurn, signal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
             const sessionId = record.sessionId;
             const workspaceDir = this.scaffoldDir(record);
             const harnessCwd = this.harnessCwd(record);
+            const turnChannelState = structuredClone((_a = record.channelState) !== null && _a !== void 0 ? _a : null);
+            const eventContext = {
+                channelState: structuredClone(turnChannelState),
+                session: this.sessionInfo(record),
+            };
             // Hold the open log so tool events append synchronously. Fire-and-forget
             // `appendEvent` races parallel tool completions and delays the live stream
             // until the next await tick — often after *all* parallel tools finish.
@@ -1573,7 +1597,7 @@ export class SessionEngine {
             const emit = (payload) => {
                 try {
                     const event = log.append(Object.assign(Object.assign({}, payload), { turnId }));
-                    this.queueDispatch(sessionId, event);
+                    this.queueDispatch(sessionId, event, eventContext);
                 }
                 catch (error) {
                     this.logger(`[agent-sdk] failed to record event for ${sessionId}: ${describeError(error)}`);
@@ -1640,7 +1664,7 @@ export class SessionEngine {
                     if (hasPendingFiles && runtime !== "cloud") {
                         const root = yield this.resolveFileSystem({
                             sessionId,
-                            continuationKey: (_a = record.continuationKey) !== null && _a !== void 0 ? _a : undefined,
+                            continuationKey: (_b = record.continuationKey) !== null && _b !== void 0 ? _b : undefined,
                             cache: true,
                             cwd: harnessCwd,
                         });
@@ -1664,7 +1688,7 @@ export class SessionEngine {
                     const instructionsInvisibleToHarness = isFirstTurn &&
                         (this.hasBorrowedWorkspace(record) ||
                             (yield isNestedInGitRepo(harnessCwd)));
-                    const request = yield this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
+                    const request = yield this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, eventContext, (update) => __awaiter(this, void 0, void 0, function* () {
                         const turn = this.turnRoots.get(sessionId);
                         if (turn !== undefined) {
                             update = yield applyWebScratchUpdate({
@@ -1700,7 +1724,11 @@ export class SessionEngine {
                 catch (error) {
                     this.approvals.cancelSession(sessionId, "deny");
                     this.auths.cancelSession(sessionId, "deny");
-                    outcome = { status: "error", errorMessage: describeError(error) };
+                    outcome = {
+                        status: "error",
+                        errorMessage: describeError(error),
+                        errorCode: describeErrorCode(error),
+                    };
                 }
                 finally {
                     permit.release();
@@ -1718,16 +1746,17 @@ export class SessionEngine {
             if (mapper.title !== undefined) {
                 const title = mapper.title;
                 yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { title })));
+                eventContext.session = Object.assign(Object.assign({}, eventContext.session), { title });
             }
-            const finalResult = (_b = outcome.result) !== null && _b !== void 0 ? _b : mapper.finalText;
-            const finalUsage = (_c = outcome.usage) !== null && _c !== void 0 ? _c : mapper.usage;
+            const finalResult = (_c = outcome.result) !== null && _c !== void 0 ? _c : mapper.finalText;
+            const finalUsage = (_d = outcome.usage) !== null && _d !== void 0 ? _d : mapper.usage;
             const finalCost = finalUsage === undefined
                 ? undefined
                 : yield this.estimateTurnCost({
-                    model: (_d = this.project.agent.model) !== null && _d !== void 0 ? _d : DEFAULT_MODEL,
+                    model: (_e = this.project.agent.model) !== null && _e !== void 0 ? _e : DEFAULT_MODEL,
                     usage: finalUsage,
                     agentId: record.sdkAgentId,
-                    conversationId: (_e = record.sdkAgentId) !== null && _e !== void 0 ? _e : sessionId,
+                    conversationId: (_f = record.sdkAgentId) !== null && _f !== void 0 ? _f : sessionId,
                 });
             if (finalCost !== undefined) {
                 outcome = Object.assign(Object.assign({}, outcome), { cost: finalCost });
@@ -1739,7 +1768,8 @@ export class SessionEngine {
                     text: finalResult,
                     dryRun: record.dryRun === true,
                     ctx: {
-                        session: this.sessionInfo(record),
+                        session: eventContext.session,
+                        channelState: turnChannelState,
                         host: this.hostForSession(sessionId),
                         artifacts: this.artifactsApi({ sessionId, turnId }),
                         stateRoot: this.stateRoot,
@@ -1765,7 +1795,7 @@ export class SessionEngine {
                         usage: finalUsage,
                         cost: finalCost,
                     },
-                });
+                }, eventContext);
             }
             else {
                 const interrupted = signal.aborted && outcome.status === "cancelled";
@@ -1773,24 +1803,25 @@ export class SessionEngine {
                     type: "turn.failed",
                     turnId,
                     data: {
+                        status: outcome.status,
                         message: interrupted
                             ? "turn interrupted"
-                            : ((_f = outcome.errorMessage) !== null && _f !== void 0 ? _f : (outcome.status === "cancelled"
+                            : ((_g = outcome.errorMessage) !== null && _g !== void 0 ? _g : (outcome.status === "cancelled"
                                 ? "turn cancelled"
                                 : "turn failed")),
                     },
-                });
+                }, eventContext);
             }
             const current = yield this.sessions.get(sessionId);
-            const mode = (_g = current === null || current === void 0 ? void 0 : current.mode) !== null && _g !== void 0 ? _g : record.mode;
+            const mode = (_h = current === null || current === void 0 ? void 0 : current.mode) !== null && _h !== void 0 ? _h : record.mode;
             if (mode === "task") {
                 yield this.appendEvent(sessionId, outcome.status === "finished"
                     ? { type: "session.completed", turnId, data: {} }
                     : {
                         type: "session.failed",
                         turnId,
-                        data: { message: (_h = outcome.errorMessage) !== null && _h !== void 0 ? _h : "task failed" },
-                    });
+                        data: { message: (_j = outcome.errorMessage) !== null && _j !== void 0 ? _j : "task failed" },
+                    }, eventContext);
                 yield this.wipeCloudSessionWorkspace(sessionId);
             }
             else {
@@ -1798,7 +1829,7 @@ export class SessionEngine {
                     type: "session.waiting",
                     turnId,
                     data: {},
-                });
+                }, eventContext);
             }
             return Object.assign(Object.assign({}, outcome), { result: finalResult, usage: finalUsage });
         });
@@ -1952,7 +1983,7 @@ export class SessionEngine {
         }
         return undefined;
     }
-    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal, images) {
+    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, eventContext, onUpdate, signal, images) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             var _d;
@@ -2157,13 +2188,14 @@ export class SessionEngine {
                     }
                     yield this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { sdkAgentId })));
                     record.sdkAgentId = sdkAgentId;
+                    eventContext.session = Object.assign(Object.assign({}, eventContext.session), { sdkAgentId });
                     yield this.appendEvent(record.sessionId, {
                         type: "agent.bound",
                         turnId,
                         data: Object.assign({ sdkAgentId }, (sdkAgentId.startsWith("bc-")
                             ? { url: `https://cursor.com/agents/${sdkAgentId}` }
                             : {})),
-                    });
+                    }, eventContext);
                 }) });
         });
     }
@@ -3389,15 +3421,15 @@ export class SessionEngine {
     // ==========================================================================
     // Events: append, dispatch to channel handlers + hooks
     // ==========================================================================
-    appendEvent(sessionId, payload) {
+    appendEvent(sessionId, payload, context) {
         return __awaiter(this, void 0, void 0, function* () {
             const log = yield this.logs.get(sessionId);
             const event = log.append(payload);
-            this.queueDispatch(sessionId, event);
+            this.queueDispatch(sessionId, event, context);
             return event;
         });
     }
-    queueDispatch(sessionId, event) {
+    queueDispatch(sessionId, event, context) {
         var _a;
         var _b;
         // Single funnel for both append paths (appendEvent + the held-log emit),
@@ -3405,7 +3437,7 @@ export class SessionEngine {
         (_a = this.storage) === null || _a === void 0 ? void 0 : _a.event(event);
         const chain = (_b = this.dispatchChains.get(sessionId)) !== null && _b !== void 0 ? _b : Promise.resolve();
         const next = chain
-            .then(() => this.dispatchEvent(sessionId, event))
+            .then(() => this.dispatchEvent(sessionId, event, context))
             .catch((error) => {
             this.logger(`[agent-sdk] event dispatch failed for ${sessionId}: ${describeError(error)}`);
         })
@@ -3418,17 +3450,25 @@ export class SessionEngine {
         });
         this.dispatchChains.set(sessionId, next);
     }
-    dispatchEvent(sessionId, event) {
+    dispatchEvent(sessionId, event, context) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
-            var _b;
+            var _b, _c;
             const record = yield this.sessions.get(sessionId);
             if (record === undefined) {
                 return;
             }
+            const channelState = context === undefined
+                ? ((_b = record.channelState) !== null && _b !== void 0 ? _b : null)
+                : context.channelState;
+            const channelStateBefore = context === undefined ? undefined : structuredClone(channelState);
             const sessionCtx = {
-                session: this.sessionInfo(record),
+                session: (_c = context === null || context === void 0 ? void 0 : context.session) !== null && _c !== void 0 ? _c : this.sessionInfo(record),
                 host: this.hostForSession(record.sessionId),
+                artifacts: this.artifactsApi({
+                    sessionId: record.sessionId,
+                    turnId: event.turnId,
+                }),
             };
             const channelEvents = this.channelEventHandlersFor(record.channelId);
             if (channelEvents !== undefined) {
@@ -3440,7 +3480,7 @@ export class SessionEngine {
                 ];
                 const channelCtx = {
                     channelId: record.channelId,
-                    state: ((_b = record.channelState) !== null && _b !== void 0 ? _b : null),
+                    state: channelState,
                     continuationToken: record.continuationKey,
                     setContinuationToken: (token) => this.setContinuationToken(sessionId, token),
                 };
@@ -3455,8 +3495,19 @@ export class SessionEngine {
                         this.logger(`[agent-sdk] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`);
                     }
                 }
-                // Handlers mutate channel state in place; persist after each batch.
-                yield this.updateRecord(sessionId, (current) => (Object.assign({}, current)));
+                if (context === undefined || channelStateBefore === undefined) {
+                    // Handlers mutate live channel state in place; save the current record.
+                    yield this.updateRecord(sessionId, (current) => (Object.assign({}, current)));
+                }
+                else {
+                    const updatedState = channelCtx.state;
+                    context.channelState = updatedState;
+                    yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { channelState: mergeChannelStateMutation({
+                            current: current.channelState,
+                            before: channelStateBefore,
+                            after: updatedState,
+                        }) })));
+                }
             }
             for (const hook of this.project.hooks) {
                 const handlers = [
@@ -3471,10 +3522,7 @@ export class SessionEngine {
                         yield handler(event, Object.assign(Object.assign({}, sessionCtx), { agent: { name: this.project.name }, channel: {
                                 id: record.channelId,
                                 continuationToken: record.continuationKey,
-                            }, stateRoot: this.stateRoot, artifacts: this.artifactsApi({
-                                sessionId: record.sessionId,
-                                turnId: event.turnId,
-                            }) }));
+                            }, stateRoot: this.stateRoot }));
                     }
                     catch (error) {
                         this.logger(`[agent-sdk] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`);
@@ -3507,6 +3555,10 @@ export class SessionEngine {
      * conversation whose blobs persisted but whose record (which selects the
      * conversation to hydrate) never reached the sink. No-op without a
      * storage mirror.
+     *
+     * Under a debounced event policy the turn-end flush is a timer, not the
+     * chain's tail, so flush explicitly before waiting on the queue; a no-op
+     * when the chain already flushed.
      */
     drainSessionDurability(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -3517,6 +3569,7 @@ export class SessionEngine {
             if (chain !== undefined) {
                 yield chain.catch(() => { });
             }
+            this.storage.flushSession(sessionId);
             yield this.storage.whenIdle();
         });
     }
@@ -3537,6 +3590,10 @@ export class SessionEngine {
                     yield active;
                     continue;
                 }
+                const dispatch = this.dispatchChains.get(sessionId);
+                if (dispatch !== undefined) {
+                    yield dispatch.catch(() => { });
+                }
                 return (_a = this.lastOutcomes.get(sessionId)) !== null && _a !== void 0 ? _a : { status: "finished" };
             }
         });
@@ -4340,30 +4397,6 @@ function mergePendingWorkspaceFiles(current, incoming) {
     }
     return Object.assign(Object.assign({}, current), incoming);
 }
-/**
- * Shallow-merge a wake patch into durable channel state. Null / undefined
- * patch values leave the existing key alone so sticky fields survive.
- */
-export function mergeChannelStateSkipNull(current, patch) {
-    if (patch === undefined) {
-        return current;
-    }
-    if (typeof patch !== "object" ||
-        patch === null ||
-        Array.isArray(patch) ||
-        typeof current !== "object" ||
-        current === null ||
-        Array.isArray(current)) {
-        return structuredClone(patch);
-    }
-    const merged = Object.assign({}, current);
-    for (const [key, value] of Object.entries(patch)) {
-        if (value !== null && value !== undefined) {
-            merged[key] = value;
-        }
-    }
-    return merged;
-}
 function eventsNdjson(events) {
     if (events.length === 0) {
         return undefined;