@cursor/july 0.1.105 → 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(
@@ -4744,6 +4830,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.
    */
   async drainSessionDurability(sessionId: string): Promise<void> {
     if (this.storage === undefined) {
@@ -4753,6 +4843,7 @@ export class SessionEngine {
     if (chain !== undefined) {
       await chain.catch(() => {});
     }
+    this.storage.flushSession(sessionId);
     await this.storage.whenIdle();
   }
 
@@ -4771,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" };
     }
   }
@@ -5765,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/reminders.ts

@@ -1,30 +1,48 @@
 /**
- * Runtime reminders — per-session durable wakes.
+ * Runtime reminders — per-session durable wakes — and named handlers
+ * authored at `agent/reminders/<name>.ts`.
  *
  * ```ts
+ * import { defineReminder } from "@cursor/july/reminders";
  * import type { ReminderCreateInput } from "@cursor/july/reminders";
  *
+ * // agent/reminders/verdict_recheck.ts
+ * export default defineReminder({
+ *   async run({ args, followup }) {
+ *     await followup({ message: `Recheck ${String(args.headSha)}` });
+ *     return { action: "delivered" };
+ *   },
+ * });
+ *
+ * import verdictRecheck from "./reminders/verdict_recheck.js";
+ *
  * // Recurring ≈ setInterval; one-shot ≈ setTimeout.
  * await host.reminders?.create({
  *   purpose: "ci_recheck",
  *   channelId: session.channelId,
  *   continuationToken: session.continuationKey!,
  *   delay: "2h",
- *   prompt: "Re-check CI. Only act if still failing.",
+ *   handler: verdictRecheck,
+ *   args: { headSha: "abc" },
  * });
  * ```
  *
  * Distinct from `defineSchedule` (deploy-time global cron under
  * `agent/schedules/`). Reminders are created at runtime and bound to a
- * channel continuation. Prefer `run` + function `until` for host policy
- * (silent ticks); agents use prompt-form create via tools.
+ * channel continuation. Prefer named `handler` + serializable `args` for
+ * hosted v2 durability; anonymous `run` remains on local and hosted v1.
  */
 
+import { brandDefinition } from "./internal/brand.js";
+import type { ReminderDefinition, ReminderHandlerConfig } from "./types.js";
+
 export type {
   ReminderBusyPolicy,
   ReminderCreateInput,
+  ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
+  ReminderHandlerConfig,
   ReminderHostApi,
   ReminderInfo,
   ReminderReschedule,
@@ -33,3 +51,16 @@ export type {
   ReminderTarget,
   ReminderUntilContext,
 } from "./types.js";
+
+/**
+ * Brand a named reminder handler for `agent/reminders/<name>.ts`.
+ * The registry name is the module stem (not a field on the definition).
+ */
+export function defineReminder(
+  config: ReminderHandlerConfig
+): ReminderDefinition {
+  if (typeof config.run !== "function") {
+    throw new Error("defineReminder requires a `run` function");
+  }
+  return brandDefinition("reminder", config);
+}

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;
 }