@cursor/july 0.1.107 → 0.1.108

package/src/internal/session-engine.ts

@@ -114,6 +114,10 @@ import {
   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,
@@ -132,7 +136,7 @@ import {
   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 { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
@@ -160,6 +164,7 @@ import {
   HostedAdmissionLocalSendError,
   isDuringHostedAdmission,
 } from "./hosted-admission-context.js";
+import { hostedSessionResumeKey } from "./hosted-catch-protocol.js";
 import {
   formatContinuationToken,
   newContinuationKey,
@@ -217,11 +222,17 @@ import {
 } from "./workspace-sync.js";
 
 export const HTTP_CHANNEL_ID = "http";
+export { mergeChannelStateSkipNull } from "./channel-state.js";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 
 /** Authored surfaces mirrored onto the Agent Store before a first cloud prompt. */
 type CloudSyncSurface = "skills" | "workspace";
 
+interface EventDispatchContext {
+  channelState: JsonValue;
+  session: SessionInfo;
+}
+
 /** The Agent Store cloud turns read authored files from, and where the VM mounts it. */
 interface CloudStoreTarget {
   sink: FileSink;
@@ -1019,6 +1030,18 @@ export class SessionEngine {
         sendOptions.continuationToken
       );
     }
+    if (
+      existing === undefined &&
+      sendOptions.hostedSessionId !== undefined &&
+      sendOptions.mailboxContinuation?.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 = await this.getOrRestoreSession(sendOptions.hostedSessionId);
+    }
 
     if (existing !== undefined) {
       if (
@@ -1668,10 +1691,16 @@ export class SessionEngine {
             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 {
           clearInterval(poll);
@@ -2192,6 +2221,11 @@ export class SessionEngine {
     const sessionId = record.sessionId;
     const workspaceDir = this.scaffoldDir(record);
     const harnessCwd = this.harnessCwd(record);
+    const turnChannelState = structuredClone(record.channelState ?? null);
+    const eventContext: EventDispatchContext = {
+      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.
@@ -2199,7 +2233,7 @@ export class SessionEngine {
     const emit = (payload: SessionEventPayload): void => {
       try {
         const event = log.append({ ...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)}`
@@ -2311,6 +2345,7 @@ export class SessionEngine {
           isFirstTurn,
           instructionsInvisibleToHarness,
           emit,
+          eventContext,
           async (update) => {
             const turn = this.turnRoots.get(sessionId);
             if (turn !== undefined) {
@@ -2352,7 +2387,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();
         this.dropTurnFileSystem(sessionId);
@@ -2371,6 +2410,7 @@ export class SessionEngine {
     if (mapper.title !== undefined) {
       const title = mapper.title;
       await this.updateRecord(sessionId, (current) => ({ ...current, title }));
+      eventContext.session = { ...eventContext.session, title };
     }
 
     const finalResult = outcome.result ?? mapper.finalText;
@@ -2395,7 +2435,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,
@@ -2414,29 +2455,38 @@ export class SessionEngine {
     }
 
     if (outcome.status === "finished") {
-      await this.appendEvent(sessionId, {
-        type: "turn.completed",
-        turnId,
-        data: {
-          result: finalResult,
-          usage: finalUsage,
-          cost: finalCost,
+      await this.appendEvent(
+        sessionId,
+        {
+          type: "turn.completed",
+          turnId,
+          data: {
+            result: finalResult,
+            usage: finalUsage,
+            cost: finalCost,
+          },
         },
-      });
+        eventContext
+      );
     } else {
       const interrupted = signal.aborted && outcome.status === "cancelled";
-      await this.appendEvent(sessionId, {
-        type: "turn.failed",
-        turnId,
-        data: {
-          message: interrupted
-            ? "turn interrupted"
-            : (outcome.errorMessage ??
-              (outcome.status === "cancelled"
-                ? "turn cancelled"
-                : "turn failed")),
+      await this.appendEvent(
+        sessionId,
+        {
+          type: "turn.failed",
+          turnId,
+          data: {
+            status: outcome.status,
+            message: interrupted
+              ? "turn interrupted"
+              : (outcome.errorMessage ??
+                (outcome.status === "cancelled"
+                  ? "turn cancelled"
+                  : "turn failed")),
+          },
         },
-      });
+        eventContext
+      );
     }
 
     const current = await this.sessions.get(sessionId);
@@ -2450,15 +2500,20 @@ export class SessionEngine {
               type: "session.failed",
               turnId,
               data: { message: outcome.errorMessage ?? "task failed" },
-            }
+            },
+        eventContext
       );
       await this.wipeCloudSessionWorkspace(sessionId);
     } else {
-      await this.appendEvent(sessionId, {
-        type: "session.waiting",
-        turnId,
-        data: {},
-      });
+      await this.appendEvent(
+        sessionId,
+        {
+          type: "session.waiting",
+          turnId,
+          data: {},
+        },
+        eventContext
+      );
     }
 
     return {
@@ -2664,6 +2719,7 @@ export class SessionEngine {
     isFirstTurn: boolean,
     instructionsInvisibleToHarness: boolean,
     emit: (payload: SessionEventPayload) => void,
+    eventContext: EventDispatchContext,
     onUpdate: RunnerTurnRequest["onUpdate"],
     signal: AbortSignal,
     images?: Array<{ data: string; mimeType: string }>
@@ -2944,16 +3000,21 @@ export class SessionEngine {
           sdkAgentId,
         }));
         record.sdkAgentId = sdkAgentId;
-        await this.appendEvent(record.sessionId, {
-          type: "agent.bound",
-          turnId,
-          data: {
-            sdkAgentId,
-            ...(sdkAgentId.startsWith("bc-")
-              ? { url: `https://cursor.com/agents/${sdkAgentId}` }
-              : {}),
+        eventContext.session = { ...eventContext.session, sdkAgentId };
+        await this.appendEvent(
+          record.sessionId,
+          {
+            type: "agent.bound",
+            turnId,
+            data: {
+              sdkAgentId,
+              ...(sdkAgentId.startsWith("bc-")
+                ? { url: `https://cursor.com/agents/${sdkAgentId}` }
+                : {}),
+            },
           },
-        });
+          eventContext
+        );
       },
     };
   }
@@ -4606,21 +4667,26 @@ export class SessionEngine {
 
   private async appendEvent(
     sessionId: string,
-    payload: SessionEventPayload & { turnId?: string }
+    payload: SessionEventPayload & { turnId?: string },
+    context?: EventDispatchContext
   ): Promise<SessionEvent> {
     const log = await this.logs.get(sessionId);
     const event = log.append(payload);
-    this.queueDispatch(sessionId, event);
+    this.queueDispatch(sessionId, event, context);
     return event;
   }
 
-  private queueDispatch(sessionId: string, event: SessionEvent): void {
+  private queueDispatch(
+    sessionId: string,
+    event: SessionEvent,
+    context?: EventDispatchContext
+  ): void {
     // Single funnel for both append paths (appendEvent + the held-log emit),
     // so the storage sink sees every durable event exactly once.
     this.storage?.event(event);
     const chain = this.dispatchChains.get(sessionId) ?? 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)}`
@@ -4637,16 +4703,27 @@ export class SessionEngine {
 
   private async dispatchEvent(
     sessionId: string,
-    event: SessionEvent
+    event: SessionEvent,
+    context?: EventDispatchContext
   ): Promise<void> {
     const record = await this.sessions.get(sessionId);
     if (record === undefined) {
       return;
     }
+    const channelState =
+      context === undefined
+        ? (record.channelState ?? null)
+        : context.channelState;
+    const channelStateBefore =
+      context === undefined ? undefined : structuredClone(channelState);
 
     const sessionCtx: SessionContext = {
-      session: this.sessionInfo(record),
+      session: context?.session ?? 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) {
@@ -4658,7 +4735,7 @@ export class SessionEngine {
       ];
       const channelCtx = {
         channelId: record.channelId,
-        state: (record.channelState ?? null) as JsonValue,
+        state: channelState,
         continuationToken: record.continuationKey,
         setContinuationToken: (token: string | null) =>
           this.setContinuationToken(sessionId, token),
@@ -4675,8 +4752,21 @@ export class SessionEngine {
           );
         }
       }
-      // Handlers mutate channel state in place; persist after each batch.
-      await this.updateRecord(sessionId, (current) => ({ ...current }));
+      if (context === undefined || channelStateBefore === undefined) {
+        // Handlers mutate live channel state in place; save the current record.
+        await this.updateRecord(sessionId, (current) => ({ ...current }));
+      } else {
+        const updatedState = channelCtx.state as JsonValue;
+        context.channelState = updatedState;
+        await this.updateRecord(sessionId, (current) => ({
+          ...current,
+          channelState: mergeChannelStateMutation({
+            current: current.channelState,
+            before: channelStateBefore,
+            after: updatedState,
+          }),
+        }));
+      }
     }
 
     for (const hook of this.project.hooks) {
@@ -4697,10 +4787,6 @@ export class SessionEngine {
               continuationToken: record.continuationKey,
             },
             stateRoot: this.stateRoot,
-            artifacts: this.artifactsApi({
-              sessionId: record.sessionId,
-              turnId: event.turnId,
-            }),
           });
         } catch (error) {
           this.logger(
@@ -4776,6 +4862,10 @@ export class SessionEngine {
         await active;
         continue;
       }
+      const dispatch = this.dispatchChains.get(sessionId);
+      if (dispatch !== undefined) {
+        await dispatch.catch(() => {});
+      }
       return this.lastOutcomes.get(sessionId) ?? { status: "finished" };
     }
   }
@@ -5770,38 +5860,6 @@ function mergePendingWorkspaceFiles(
   return { ...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: JsonValue | undefined,
-  patch: JsonValue | undefined
-): JsonValue | undefined {
-  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: Record<string, JsonValue> = {
-    ...(current as Record<string, JsonValue>),
-  };
-  for (const [key, value] of Object.entries(patch)) {
-    if (value !== null && value !== undefined) {
-      merged[key] = value as JsonValue;
-    }
-  }
-  return merged;
-}
-
 function eventsNdjson(events: SessionEvent[]): string | undefined {
   if (events.length === 0) {
     return undefined;

package/src/storage-backends/cursor-hosted.ts

@@ -169,6 +169,30 @@ export interface KvListKeysResponse {
   truncated?: boolean;
 }
 
+const STORAGE_RPC_ERROR_CODES = new Set([
+  "agentsdk_kv_credential_missing",
+  "agentsdk_kv_cursor_invalid",
+  "agentsdk_kv_deployment_unbound",
+  "agentsdk_kv_key_invalid",
+  "agentsdk_kv_request_invalid",
+  "agentsdk_kv_storage_not_allowed",
+  "agentsdk_kv_value_invalid",
+  "agentsdk_kv_version_invalid",
+]);
+
+export class StorageRpcError extends Error {
+  readonly code = "agent_dependency_failed";
+  readonly reasonCode: string;
+  readonly status: number;
+
+  constructor(message: string, reasonCode: string, status: number) {
+    super(message);
+    this.name = "StorageRpcError";
+    this.reasonCode = reasonCode;
+    this.status = status;
+  }
+}
+
 function toCasResult(response: KvCasResponse): KvCasResult {
   if (response.ok) {
     if (response.version === null) {
@@ -251,7 +275,22 @@ export async function storageRpc<T>(
       typeof (parsed as { error: unknown }).error === "string"
         ? (parsed as { error: string }).error
         : `HTTP ${response.status}`;
-    throw new Error(`cursorHostedStorage ${path}: ${error}`);
+    const candidate =
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "code" in parsed &&
+      typeof (parsed as { code: unknown }).code === "string"
+        ? (parsed as { code: string }).code
+        : undefined;
+    const code =
+      candidate !== undefined && STORAGE_RPC_ERROR_CODES.has(candidate)
+        ? candidate
+        : "agentsdk_storage_http_error";
+    throw new StorageRpcError(
+      `cursorHostedStorage ${path}: ${error}`,
+      code,
+      response.status
+    );
   }
   return parsed as T;
 }

package/src/types.ts

@@ -1778,7 +1778,14 @@ export type SessionEventPayload =
       type: "turn.bound";
       data: { requestId: string };
     }
-  | { type: "turn.failed"; data: { message: string } }
+  | {
+      type: "turn.failed";
+      data: {
+        message: string;
+        /** Machine-readable terminal status. Omitted on legacy stored events. */
+        status?: "error" | "cancelled";
+      };
+    }
   | {
       /**
        * A Slack follow-up queued mid-turn reached the running agent: the
@@ -1953,6 +1960,10 @@ export interface TurnOutcome {
   status: "finished" | "error" | "cancelled";
   result?: string;
   errorMessage?: string;
+  /** Stable machine-readable runner code when the failure supplied one. */
+  errorCode?: string;
+  /** Why a cancelled turn stopped, when the engine observed the boundary. */
+  cancellationReason?: "signal" | "runner";
   usage?: TurnUsage;
   /** Cost of {@link usage} from the Cloud Agents cost endpoint. */
   cost?: TurnCost;
@@ -2023,7 +2034,10 @@ export interface ChannelSession {
   getEventStream(options?: {
     startIndex?: number;
   }): Promise<ReadableStream<Uint8Array>>;
-  /** Resolves when the currently running turn reaches a terminal event. */
+  /**
+   * Resolves after the currently running turn reaches a terminal event and
+   * handlers already queued for that session have settled.
+   */
   waitForCompletion(): Promise<TurnOutcome>;
   /** Re-key the session's channel-local continuation token. */
   setContinuationToken(token: string | null): Promise<void>;
@@ -2384,7 +2398,14 @@ export interface ReceiveInput {
   target?: JsonObject;
 }
 
-/** Per-event channel context: live (persisted) state plus session ops. */
+/**
+ * Per-event channel context. `state` is mutable. Turn events receive the
+ * state snapshot captured for that turn; handler mutations are recursively
+ * merged into the latest persisted state so fields refreshed by overlapping
+ * deliveries survive. At paths changed by the handler, objects merge
+ * recursively, arrays and scalars replace the latest value, and deletion
+ * removes the latest value. Events outside a turn receive current live state.
+ */
 export interface ChannelEventContext<TState = JsonValue> {
   channelId: string;
   state: TState;
@@ -2401,6 +2422,11 @@ export interface SessionContext {
    * relative path cannot read another session's files.
    */
   host: HostContext;
+  /**
+   * Durable artifacts bound to this event's session and turn. `tag`
+   * auto-fills both ids and rejects a conflicting explicit `sessionId`.
+   */
+  artifacts: ArtifactsApi;
 }
 
 export type ChannelEventHandler<
@@ -2711,6 +2737,8 @@ export type ArtifactsDefinition = ArtifactsConfig &
  */
 export interface ResultContext {
   session: SessionInfo;
+  /** Durable channel state captured for this turn. */
+  channelState: JsonValue;
   host: HostContext;
   artifacts: ArtifactsApi;
   stateRoot: string;
@@ -3542,8 +3570,11 @@ export interface ServeOptions {
   stateRoot?: string;
   /**
    * Cursor API key for the SDK runner and Cursor account MCP connections.
-   * When omitted, falls back to `CURSOR_API_KEY`, then to the credential
-   * stored by `agent-sdk login`.
+   * When omitted, falls back to `CURSOR_API_KEY`, then
+   * `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
+   * when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the credential
+   * stored by `agent-sdk login`. A bind file wins over
+   * `CURSOR_SERVICE_ACCOUNT_KEY`.
    */
   apiKey?: string;
   /** Run schedules on their cron cadence. Defaults to `!dev`. */
@@ -3628,7 +3659,9 @@ export interface ServeOptions {
    * GitHub and Origin subscriptions are registered independently.
    * The stream is read as the host's Cursor user, so this requires a signed-in
    * host: `serve` throws when no key resolves from `apiKey` here,
-   * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, or `agent-sdk login`.
+   * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`
+   * (hosted default `/run/cursor/secrets/CURSOR_API_KEY` when unset),
+   * `CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`.
    */
   cursorEvents?: {
     repos: string[];