@cursor/july 0.1.97 → 0.1.99

package/src/internal/framework-storage-selection.ts

@@ -17,17 +17,19 @@
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
- *   the Cursor-hosted backend. When the deployment carries a
- *   **framework-level file store**
- *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), session records, event
- *   transcripts, and the continuation index live there — file-shaped state
- *   on file storage, apart from the author-facing user store — while
- *   `host.kv`, eval runs, A/B samples, and conditional writes stay on the
- *   control-plane KV proxy (see framework-file-storage.ts). Without one
- *   (a deploy predating framework-store provisioning), everything goes to
- *   the KV proxy as before. The API key resolves through the full
- *   credential chain on every call because hosted freeze snapshots listen
- *   unsigned and the binder drops the key file after restore.
+ *   the deployment's **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`) holds session records, event
+ *   transcripts, and the continuation index — file-shaped state on file
+ *   storage, apart from the author-facing user store. The control-plane KV
+ *   proxy is *not* used: it authorizes by mapping a pod service account to
+ *   a v1 deployment row, which no v2 deployment has, so every call 403s and
+ *   fails the delivery that read it. The KV half is inert until the proxy
+ *   resolves v2 deployments (see null-kv-storage.ts). Without a framework
+ *   store (a deploy predating framework-store provisioning) there is
+ *   nothing left to mirror to, so the state root is again the only copy.
+ *   The API key resolves through the full credential chain on every call
+ *   because hosted freeze snapshots listen unsigned and the binder drops
+ *   the key file after restore.
  * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
  *   is correct when the operator owns the disk.
  *
@@ -45,15 +47,17 @@ import {
   cursorHostedFiles,
 } from "../files-backends/cursor-hosted.js";
 import { defineStorage, type StorageDefinition } from "../storage.js";
-import { cursorHostedStorage } from "../storage-backends/cursor-hosted.js";
+import { CURSOR_HOSTED_STORAGE } from "../storage-backends/cursor-hosted.js";
 import type { AgentArchitecture } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import {
   composeFrameworkStorage,
   fileSinkStorageCore,
-  frameworkGuardedCas,
 } from "./framework-file-storage.js";
+import { nullKvStorage } from "./null-kv-storage.js";
+
+const cursorHostedMarker = { [CURSOR_HOSTED_STORAGE]: true } as const;
 
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
@@ -96,23 +100,38 @@ export function selectFrameworkStorageDefinition(
   // comes up). Follow-ups restore lazily by continuation or session id;
   // GET /v1/sessions lists from the sink either way.
   const policy = { restore: "off" } as const;
-  // Full chain (env → key file → stored login): frozen engines listen
-  // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
-  // definition is constructed.
-  const resolveApiKey = (): string | undefined => resolveApiKeySync()?.apiKey;
-  const kv = cursorHostedStorage({ resolveApiKey });
   const frameworkStoreId = cursorFrameworkStoreSourceId(
     env as NodeJS.ProcessEnv
   );
   if (frameworkStoreId === undefined) {
-    return defineStorage({ name: "cursor-hosted", policy, ...kv });
+    // Nothing to mirror to: the KV proxy rejects v2 service accounts, so a
+    // definition over it would fail every delivery that reads it. The state
+    // root is the durable copy, as when self-hosted.
+    return undefined;
   }
-  // Framework session state on the framework-level file store; author kv,
-  // evals, and A/B tables stay on the KV proxy (spread from `kv`, which
-  // also carries the cursor-hosted marker for GET /v1/sessions).
+  // Full chain (env → key file → stored login): frozen engines listen
+  // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
+  // definition is constructed.
+  const resolveApiKey = (): string | undefined => resolveApiKeySync()?.apiKey;
+  // Framework session state on the framework-level file store, which
+  // authorizes by store source id and so works for v2. Everything the KV
+  // proxy used to serve — author kv, eval runs, A/B samples, conditional
+  // writes — is inert; `defineStorage` derives the eval/A/B tables over the
+  // core, which means that bookkeeping reads back empty rather than 403ing.
+  //
+  // Restoring `cursorHostedStorage()` here once the proxy resolves v2
+  // deployments also means restoring the guard its `cas` group needs: a
+  // conditional write over a `session/` or `continuation/` key would run on
+  // the KV database while the plain core routes that key to the file store.
+  const kv = nullKvStorage();
   return defineStorage({
     name: "cursor-hosted (framework files)",
     policy,
+    // GET /v1/sessions still prefers the durable list: session records live
+    // on the framework store, which the composed core lists. Spread rather
+    // than named, the way cursorHostedStorage carries it: the marker is a
+    // platform stamp, not part of the authored config surface.
+    ...cursorHostedMarker,
     ...kv,
     ...composeFrameworkStorage({
       kv,
@@ -120,8 +139,5 @@ export function selectFrameworkStorageDefinition(
         cursorHostedFiles({ storeSourceId: frameworkStoreId, resolveApiKey })
       ),
     }),
-    // CAS stays on the KV proxy but must refuse framework-file keys, or a
-    // future coordination path would split-brain against the plain core.
-    cas: frameworkGuardedCas(kv.cas),
   });
 }

package/src/internal/hosted-admission-adapter.ts

@@ -0,0 +1,42 @@
+import type { ChannelHandlerArgs } from "../types.js";
+
+/**
+ * Hosted-admission hook a channel pack attaches to its definition.
+ *
+ * Hosted delivery looks this up from the mounted definition — it does not
+ * switch on `channelKind`. A new forge implements `dispatch` / `getOutcome`
+ * next to its webhook handler and calls {@link attachHostedAdmissionAdapter}
+ * from the channel constructor.
+ */
+export type HostedAdmissionDispatchOutcome = "skip" | "task";
+
+export type HostedAdmissionAdapter = {
+  kind: string;
+  /**
+   * Optional wrap of the capturing `send` / `waitUntil` args (GitHub uses
+   * this to propagate background-task errors). Identity when omitted.
+   */
+  prepareArgs?(args: ChannelHandlerArgs): ChannelHandlerArgs;
+  dispatch(input: {
+    eventType: string;
+    payload: unknown;
+    deliveryId: string;
+    args: ChannelHandlerArgs;
+  }): Promise<Response>;
+  getOutcome(response: Response): HostedAdmissionDispatchOutcome | undefined;
+};
+
+const adapters = new WeakMap<object, HostedAdmissionAdapter>();
+
+export function attachHostedAdmissionAdapter(
+  definition: object,
+  adapter: HostedAdmissionAdapter
+): void {
+  adapters.set(definition, adapter);
+}
+
+export function getHostedAdmissionAdapter(
+  definition: object
+): HostedAdmissionAdapter | undefined {
+  return adapters.get(definition);
+}

package/src/internal/hosted-delivery-protocol.ts

@@ -18,7 +18,12 @@ export type HostedAdmissionManagedAutomation = {
 export type HostedAdmission = {
   v: 2;
   channelId: string;
-  channelKind: "github";
+  /**
+   * Mailbox / subscription channel kind (`github`, `origin`, …). The guest
+   * resolves dispatch from the mounted definition's hosted-admission
+   * adapter; this field is not an allowlist.
+   */
+  channelKind: string;
   eventType: string;
   deliveryId: string;
   sessionMode: "event" | "continuation";
@@ -107,7 +112,7 @@ export function parseHostedAdmission(
     !Object.hasOwn(body, "payload") ||
     body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
     !boundedString(body.channelId, 128) ||
-    body.channelKind !== "github" ||
+    !boundedString(body.channelKind, 128) ||
     !boundedString(body.eventType, 128) ||
     !boundedString(body.deliveryId, 256) ||
     (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||

package/src/internal/hosted-delivery.ts

@@ -1,10 +1,4 @@
 import { randomBytes } from "node:crypto";
-import {
-  dispatchGitHubWebhook,
-  getGitHubChannelOptions,
-  getGitHubDispatchOutcome,
-  withPropagatingGitHubBackgroundErrors,
-} from "../channels/github/github-channel.js";
 import type {
   AuthPolicy,
   ChannelHandlerArgs,
@@ -14,6 +8,10 @@ import {
   createDeferredChannelSession,
   DeferredChannelSessionError,
 } from "./deferred-channel-session.js";
+import {
+  getHostedAdmissionAdapter,
+  type HostedAdmissionAdapter,
+} from "./hosted-admission-adapter.js";
 import {
   HostedAdmissionLocalSendError,
   runDuringHostedAdmission,
@@ -30,12 +28,19 @@ import {
 import {
   abortReasonFromTurnStatus,
   HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+  hostedErrorStackSnippet,
   hostedExecutionDiagId,
   writeHostedExecutionDiag,
 } from "./hosted-execution-diag.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { errorResponse, readJsonObject } from "./http-channel.js";
+import type { LogRingEntry } from "./log-ring.js";
 import type { Router } from "./router.js";
+import {
+  type SessionRunExecutionWrite,
+  serializeSessionRunError,
+  snapshotSessionRunLogs,
+} from "./session-run-log.js";
 
 type DispatchInput = {
   delivery: HostedAdmission;
@@ -115,17 +120,20 @@ function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
 }
 
 /**
- * Run authored admission without creating a framework session. V1 GitHub
+ * Run authored admission without creating a framework session. Authored
  * `task` callbacks execute as sessionless work; the first `send` is captured
  * and executed only after the control plane allocates `ses_…`. Capturing
  * does not terminate the caller — `send` returns an inert deferred handle so
  * a task body runs to completion before the admission response is computed.
+ *
+ * Dispatch is the adapter the mounted channel attached. Hosted delivery
+ * does not switch on `channelKind`.
  */
 export async function dispatchHostedAdmission(
   input: DispatchInput
 ): Promise<AdmissionDispatch> {
-  const github = getGitHubChannelOptions(input.definition);
-  if (github === undefined) {
+  const adapter = getHostedAdmissionAdapter(input.definition);
+  if (adapter === undefined || adapter.kind !== input.delivery.channelKind) {
     return {
       response: Response.json(
         { ok: false, error: "channel_kind_mismatch" },
@@ -135,16 +143,16 @@ export async function dispatchHostedAdmission(
   }
   // The admission window marker follows the async graph into task bodies so
   // the engine can refuse local sends that would bypass the capture stub.
-  return runDuringHostedAdmission(() => runAdmission(input, github));
+  return runDuringHostedAdmission(() => runAdmission(input, adapter));
 }
 
 async function runAdmission(
   input: DispatchInput,
-  github: NonNullable<ReturnType<typeof getGitHubChannelOptions>>
+  adapter: HostedAdmissionAdapter
 ): Promise<AdmissionDispatch> {
   const background: Promise<unknown>[] = [];
   let captured: { message: string; options: SendMessageOptions } | undefined;
-  const args = withPropagatingGitHubBackgroundErrors({
+  const capturingArgs: ChannelHandlerArgs = {
     ...input.args,
     send: async (message, options = {}) => {
       if (captured !== undefined) {
@@ -156,12 +164,12 @@ async function runAdmission(
     waitUntil: (promise) => {
       background.push(promise);
     },
-  });
+  };
+  const args = adapter.prepareArgs?.(capturingArgs) ?? capturingArgs;
   let dispatched: Response;
   try {
-    dispatched = await dispatchGitHubWebhook({
-      options: github,
-      eventName: input.delivery.eventType,
+    dispatched = await adapter.dispatch({
+      eventType: input.delivery.eventType,
       payload: input.delivery.payload,
       deliveryId: input.delivery.deliveryId,
       args,
@@ -212,7 +220,7 @@ async function runAdmission(
       },
     };
   }
-  const outcome = getGitHubDispatchOutcome(dispatched);
+  const outcome = adapter.getOutcome(dispatched);
   if (outcome === undefined) {
     return {
       response: Response.json(
@@ -264,6 +272,15 @@ export function registerHostedDeliveryRoute(input: {
    * `hosted-execution.json` from that path after the POST returns.
    */
   stateRoot?: string;
+  /**
+   * Upsert this execution into the v2 session-level framework-store log.
+   * Called for the pre-turn `running` claim and every terminal outcome so
+   * a dead Node process still leaves a leftover. Soft-fail inside the
+   * store; this path still awaits so a parked pod cannot shed the write.
+   */
+  persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
+  /** Snapshot of the process log ring at persist time. */
+  snapshotLogs?(): LogRingEntry[];
 }): void {
   const pending = new Map<
     string,
@@ -404,30 +421,64 @@ export function registerHostedDeliveryRoute(input: {
           abortReason?:
             | ReturnType<typeof abortReasonFromTurnStatus>
             | "execute_throw";
+          error?: unknown;
         }): Promise<void> => {
-          if (input.stateRoot === undefined) {
-            return;
-          }
+          const durationMs = Math.max(
+            0,
+            Math.round(performance.now() - startedAt)
+          );
           const message =
             fields.message === undefined
               ? undefined
               : boundedMessage(fields.message);
-          await writeHostedExecutionDiag(input.stateRoot, {
-            v: 1,
-            executionId,
-            writtenAt: new Date().toISOString(),
-            sessionPublicId: execution.sessionPublicId,
-            sessionId: fields.sessionId,
-            turnStatus: fields.turnStatus,
-            durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
-            ...(message === undefined ? {} : { message }),
-            ...(message !== undefined && /abort/i.test(message)
-              ? { signalAborted: true }
-              : {}),
-            ...(fields.abortReason === undefined
-              ? {}
-              : { abortReason: fields.abortReason }),
-          });
+          const stack =
+            fields.error === undefined
+              ? undefined
+              : hostedErrorStackSnippet(fields.error);
+          if (input.stateRoot !== undefined) {
+            await writeHostedExecutionDiag(input.stateRoot, {
+              v: 1,
+              executionId,
+              writtenAt: new Date().toISOString(),
+              sessionPublicId: execution.sessionPublicId,
+              sessionId: fields.sessionId,
+              turnStatus: fields.turnStatus,
+              durationMs,
+              ...(message === undefined ? {} : { message }),
+              ...(stack === undefined || stack.length === 0 ? {} : { stack }),
+              ...(message !== undefined && /abort/i.test(message)
+                ? { signalAborted: true }
+                : {}),
+              ...(fields.abortReason === undefined
+                ? {}
+                : { abortReason: fields.abortReason }),
+            });
+          }
+          if (input.persistSessionRun === undefined) {
+            return;
+          }
+          const error =
+            fields.error === undefined
+              ? undefined
+              : serializeSessionRunError(fields.error);
+          try {
+            await input.persistSessionRun({
+              executionId,
+              writtenAt: new Date().toISOString(),
+              sessionPublicId: execution.sessionPublicId,
+              sessionId: fields.sessionId,
+              turnStatus: fields.turnStatus,
+              durationMs,
+              ...(fields.abortReason === undefined
+                ? {}
+                : { abortReason: fields.abortReason }),
+              ...(message === undefined ? {} : { message }),
+              ...(error === undefined ? {} : { error }),
+              logs: snapshotSessionRunLogs(input.snapshotLogs?.() ?? []),
+            });
+          } catch {
+            // Soft-fail: a store outage must not change the HTTP reply.
+          }
         };
         // Claim the file before the turn runs. The host reads it after its
         // own POST returns, which for a 9-minute timeout is while this turn
@@ -486,6 +537,7 @@ export function registerHostedDeliveryRoute(input: {
             turnStatus: "error",
             message: error instanceof Error ? error.message : String(error),
             abortReason: "execute_throw",
+            error,
           });
           throw error;
         }

package/src/internal/hosted-execution-diag.ts

@@ -46,6 +46,8 @@ export type HostedExecutionDiag = {
   turnStatus: string;
   durationMs: number;
   message?: string;
+  /** First frames of a thrown Error; omitted on soft turn failures. */
+  stack?: string;
   signalAborted?: boolean;
   requestId?: string;
   abortReason?: HostedExecutionDiagAbortReason;
@@ -63,6 +65,7 @@ const DIAG_KEYS = new Set([
   "turnStatus",
   "durationMs",
   "message",
+  "stack",
   "signalAborted",
   "requestId",
   "abortReason",
@@ -86,6 +89,42 @@ function boundedOptionalString(
     : undefined;
 }
 
+/** First line + frames; factory `last_error` is 1024 chars with a TAS prefix. */
+export const HOSTED_ERROR_STACK_LINE_COUNT = 5;
+export const HOSTED_ERROR_SNIPPET_MAX_CHARS = 700;
+
+/**
+ * Bounded throw text for the hosted 500 body and the on-disk diag `stack`.
+ * Prefers `Error.stack` (message line + `at` frames) so `last_error` is not
+ * the generic "Internal server error." when the throw has a stack.
+ */
+export function hostedErrorStackSnippet(error: unknown): string {
+  if (error instanceof Error) {
+    const stack = error.stack?.trim();
+    if (stack !== undefined && stack.length > 0) {
+      const lines = stack
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0)
+        .slice(0, HOSTED_ERROR_STACK_LINE_COUNT);
+      const text = lines.join("\n");
+      return text.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
+        ? `${text.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
+        : text;
+    }
+    return error.message.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
+      ? `${error.message.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
+      : error.message;
+  }
+  const text = String(error);
+  if (text.length === 0) {
+    return "";
+  }
+  return text.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
+    ? `${text.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
+    : text;
+}
+
 export function hostedExecutionDiagPath(stateRoot: string): string {
   return join(stateRoot, HOSTED_EXECUTION_DIAG_FILENAME);
 }
@@ -147,6 +186,10 @@ export function parseHostedExecutionDiag(
     return undefined;
   }
   const message = boundedOptionalString(body.message, 1024);
+  const stack = boundedOptionalString(
+    body.stack,
+    HOSTED_ERROR_SNIPPET_MAX_CHARS
+  );
   const requestId = boundedOptionalString(body.requestId, 128);
   const abortReason =
     body.abortReason === undefined
@@ -173,6 +216,7 @@ export function parseHostedExecutionDiag(
     turnStatus: body.turnStatus,
     durationMs: body.durationMs,
     ...(message === undefined ? {} : { message }),
+    ...(stack === undefined ? {} : { stack }),
     ...(body.signalAborted === true ? { signalAborted: true } : {}),
     ...(requestId === undefined ? {} : { requestId }),
     ...(abortReason === undefined ? {} : { abortReason }),
@@ -196,6 +240,7 @@ export async function writeHostedExecutionDiag(
       serialized.length > HOSTED_EXECUTION_DIAG_MAX_BYTES
         ? JSON.stringify({
             ...diag,
+            stack: undefined,
             message: boundedOptionalString(diag.message, 256),
           })
         : serialized;

package/src/internal/http-channel.ts

@@ -95,6 +95,13 @@ export function buildHttpChannelRoutes(args: {
           "Expected a JSON body with a string `message`."
         );
       }
+      if (body.asOf !== undefined && typeof body.asOf !== "string") {
+        return errorResponse(
+          400,
+          "invalid_request",
+          "`asOf` must be an ISO-8601 instant with a timezone when provided."
+        );
+      }
       const message = await transformMessage(body.message, ctx.auth);
       const workspaceFiles = readWorkspaceFiles(body.workspaceFiles);
       // Per-session cloud attach (create only). Eval harness uses this to pin
@@ -105,6 +112,7 @@ export function buildHttpChannelRoutes(args: {
         ...(typeof body.title === "string" ? { title: body.title } : {}),
         ...(body.purpose === "eval" ? { purpose: "eval" as const } : {}),
         ...(body.dryRun === true ? { dryRun: true } : {}),
+        asOf: body.asOf,
         ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
         ...(cloud === undefined ? {} : { cloud }),
       });

package/src/internal/null-kv-storage.ts

@@ -0,0 +1,74 @@
+/**
+ * The inert KV half of hosted v2 storage.
+ *
+ * The control-plane KV proxy (`/internal/agent-serve/storage/*`) authorizes a
+ * request by mapping the caller's pod service account to a row in the v1
+ * deployment table. Architecture v2 registers its deployments in the factory
+ * control plane instead, so every proxy call from a v2 pod answers
+ * `403 No Agent Serve deployment is bound to this service account`. The
+ * lazy-restore path deliberately propagates read failures (a store outage must
+ * not read as "unknown continuation token"), so those 403s fail follow-up
+ * deliveries outright.
+ *
+ * This backend stands in for the proxy until it can resolve v2 deployments:
+ * writes are dropped, reads are definitive misses, and lists are empty. It is
+ * paired with the framework file store (see framework-file-storage.ts), which
+ * authorizes by store source id rather than by deployment row and therefore
+ * still carries session records, event transcripts, and the continuation
+ * index — the state sessions are restored from.
+ *
+ * Author KV is the one thing that must not silently accept writes here, since
+ * handlers read their own writes back. {@link AUTHOR_KV_UNSUPPORTED} marks the
+ * definition so `ctx.host.kv` falls back to `--state-root` disk instead, the
+ * same fallback a deployment with no configured backend gets.
+ */
+
+import type { StorageConfig } from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+/**
+ * Marker stamped on a definition whose KV core cannot serve `ctx.host.kv`,
+ * even though `get` is present for framework session state. Explicit
+ * `unique symbol` annotation required for `--isolatedDeclarations` (TS9010).
+ */
+export const AUTHOR_KV_UNSUPPORTED: unique symbol = Symbol.for(
+  "@cursor/july.storage.author-kv-unsupported"
+);
+
+/** True when `value` was built from {@link nullKvStorage}. */
+export function isAuthorKvUnsupported(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[AUTHOR_KV_UNSUPPORTED] === true
+  );
+}
+
+type NullKvStorageMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  readonly [AUTHOR_KV_UNSUPPORTED]: true;
+};
+
+/**
+ * A KV core that stores nothing. `get` resolving `undefined` is honest here
+ * rather than dangerous: nothing was ever written, so a miss cannot shadow a
+ * session that exists elsewhere.
+ *
+ * No `cas` group and no `listNewest`: conditional writes over a store that
+ * forgets would report a lock acquired, and write-time ordering means nothing
+ * without writes.
+ */
+export function nullKvStorage(): NullKvStorageMethods {
+  return {
+    [AUTHOR_KV_UNSUPPORTED]: true,
+    put(): void {},
+    get(): JsonValue | undefined {
+      return undefined;
+    },
+    delete(): void {},
+    list(): [] {
+      return [];
+    },
+  };
+}