@cursor/july 0.1.94 → 0.1.95

package/src/internal/deploy-manifest.ts

@@ -168,12 +168,17 @@ export function buildAgentDeployManifest(
     declarations: {
       egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
       publicRoutePaths,
+      // v2 ignores authored storage; deploy manifests describe
+      // Cursor-hosted deployments, where framework-storage-selection.ts
+      // injects the Cursor-hosted mirror.
       frameworkStorage:
-        project.storage === undefined
-          ? "none"
-          : isCursorHostedStorage(project.storage)
-            ? "cursor-hosted"
-            : "other",
+        project.agent.architecture === "v2"
+          ? "cursor-hosted"
+          : project.storage === undefined
+            ? "none"
+            : isCursorHostedStorage(project.storage)
+              ? "cursor-hosted"
+              : "other",
       ...(project.agent.architecture === undefined
         ? {}
         : { architecture: project.agent.architecture }),

package/src/internal/discovery.ts

@@ -307,7 +307,7 @@ export async function loadAgentProject(
   const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
   const abs = await loadABs(ctx, agentDir);
   const abConfig = await loadABConfig(ctx, agentDir);
-  const storage = await loadStorage(ctx, agentDir);
+  const storage = await loadStorage(ctx, agentDir, agent.architecture);
   const artifacts = await loadArtifacts(ctx, agentDir);
   const otel = await loadOtel(ctx, agentDir);
   await appendArtifactTool(ctx, agentDir, agent, artifacts);
@@ -2151,12 +2151,35 @@ async function loadABConfig(
 
 async function loadStorage(
   ctx: DiscoveryContext,
-  agentDir: string
+  agentDir: string,
+  architecture: AgentArchitecture | undefined
 ): Promise<StorageDefinition | undefined> {
   const path = await findModuleFile(agentDir, "storage");
   if (path === undefined) {
     return undefined;
   }
+  if (architecture === "v2") {
+    // Storage is a hosting-mode decision on v2, made by
+    // framework-storage-selection.ts: the state root when self-hosted,
+    // Cursor-managed storage on Cursor hosting. Fail early (error
+    // diagnostics refuse serve and deploy) rather than silently running
+    // with storage the author believes they configured. Not imported.
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        'agent/storage.ts is not supported on architecture "v2": the platform selects storage (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Delete the file.',
+    });
+    return undefined;
+  }
+  // v1 keeps loading the authored sink, with notice: defineStorage is going
+  // away with the v1 control plane.
+  ctx.diagnostics.push({
+    severity: "warning",
+    path: displayPath(ctx, path),
+    message:
+      'agent/storage.ts (defineStorage) is deprecated and going away: architecture "v2" selects storage automatically (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Still honored on v1.',
+  });
   const definition = await importDefault(ctx, path, "storage");
   return definition as StorageDefinition | undefined;
 }

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

@@ -2,19 +2,31 @@
  * Which backend framework session state is mirrored to.
  *
  * Framework state — session records, event chunks, the continuation index —
- * is how a session outlives the process that served it. Today that mirror
- * exists only when the agent author wrote `agent/storage.ts`, which makes
- * platform durability an agent-level decision: of the first-party agents,
- * some choose `cursorHostedStorage()` and some choose `fileKv()` (pod-local
- * disk, lost on pod replacement), and one selects between them at runtime by
- * reading the deployment-id environment variable itself.
+ * is how a session outlives the process that served it. On architecture v1
+ * that mirror exists only when the agent author wrote `agent/storage.ts`,
+ * which makes platform durability an agent-level decision: of the
+ * first-party agents, some choose `cursorHostedStorage()` and some choose
+ * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
+ * between them at runtime by reading the deployment-id environment variable
+ * itself.
  *
- * That selection is a hosting-mode question, not an authoring question, and
- * this module is where it will move. It deliberately reproduces today's
- * behavior exactly for now — authored definition or nothing — so the change
- * that makes framework durability automatic is a change to
- * {@link selectFrameworkStorageDefinition} alone, reviewable on its own and
- * revertable without touching the engine.
+ * That selection is a hosting-mode question, not an authoring question.
+ * Architecture v2 moves it here: `agent/storage.ts` is rejected at
+ * discovery (error diagnostic, so serve and deploy fail early), and the
+ * platform picks the default —
+ *
+ * - **Cursor-managed hosting** (the deployment-generation environment
+ *   variable is set, same signal that registers `GET /v1/manifest`):
+ *   the Cursor-hosted backend, so session records, event chunks, `host.kv`,
+ *   eval runs, and A/B samples land in the control plane and survive pod
+ *   replacement. 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.
+ *
+ * v1 keeps the authored definition (or nothing) so existing deployments are
+ * untouched while they run.
  *
  * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
  * already holds `session.json` and `events.ndjson` unconditionally, through
@@ -22,24 +34,54 @@
  * pod's filesystem.
  */
 
-import type { StorageDefinition } from "../storage.js";
+import { defineStorage, type StorageDefinition } from "../storage.js";
+import { cursorHostedStorage } 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";
 
 export interface FrameworkStorageSelectionInput {
-  /** `agent/storage.ts`, when the author wrote one. */
+  /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
   readonly authored: StorageDefinition | undefined;
+  /** {@link AgentConfig.architecture}; omitted means v1. */
+  readonly architecture?: AgentArchitecture | undefined;
+  /** Environment override for tests; defaults to `process.env`. */
+  readonly env?: Record<string, string | undefined>;
 }
 
 /**
  * Pick the backend for framework session state.
  *
  * Returns `undefined` when there is no mirror, in which case the pod's local
- * disk is the only copy — the condition F0 exists to remove for hosted
- * deployments.
+ * disk is the only copy.
  */
 export function selectFrameworkStorageDefinition(
   input: FrameworkStorageSelectionInput
 ): StorageDefinition | undefined {
-  // Today: the author decides, or there is no mirror. Hosting-mode selection
-  // replaces this body; every caller already routes through here.
-  return input.authored;
+  if (input.architecture !== "v2") {
+    // v1: the author decides, or there is no mirror.
+    return input.authored;
+  }
+  if (input.authored !== undefined) {
+    // Discovery rejects agent/storage.ts on v2 before an engine is built;
+    // an authored definition reaching this point is a wiring bug. Raise
+    // rather than silently discard what the author believes is configured.
+    throw new Error(
+      'defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.'
+    );
+  }
+  const env = input.env ?? process.env;
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+    // Self-hosted v2: the state root is the durable copy.
+    return undefined;
+  }
+  return defineStorage({
+    name: "cursor-hosted",
+    ...cursorHostedStorage({
+      // 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.
+      apiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+  });
 }

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

@@ -0,0 +1,37 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * A `send()` captured outside the delivery (typically at channel `onStart`,
+ * which binds directly to the engine) reached the engine during a hosted
+ * admission window. Running it would start a local July session on a
+ * sessionless pod — invisible to the control plane, destroyed with the pod —
+ * so it fails loudly instead. This is a deterministic authored bug and is
+ * surfaced as a non-retryable 422 by the admission route.
+ */
+export class HostedAdmissionLocalSendError extends Error {
+  constructor() {
+    super(
+      "send() reached the local engine during hosted admission. A send " +
+        "captured at channel startup (onStart) bypasses hosted capture and " +
+        "would run an invisible local session on a sessionless pod. Use the " +
+        "per-delivery send passed to the task callback " +
+        "(task: (args) => args.send(…)) instead."
+    );
+  }
+}
+
+const admissionWindow = new AsyncLocalStorage<true>();
+
+/**
+ * Run `work` inside the hosted admission window. The context follows the
+ * async graph, including `waitUntil` task bodies scheduled during dispatch,
+ * so the engine can refuse local sends that bypass the capture stub.
+ */
+export function runDuringHostedAdmission<T>(work: () => T): T {
+  return admissionWindow.run(true, work);
+}
+
+/** True while executing inside a hosted admission window. */
+export function isDuringHostedAdmission(): boolean {
+  return admissionWindow.getStore() === true;
+}

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

@@ -3,6 +3,11 @@ export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
 export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
 export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
 
+export type HostedAdmissionManagedAutomation = {
+  automationUuid: string;
+  mcpServerNames: string[];
+};
+
 export type HostedAdmission = {
   v: 2;
   channelId: string;
@@ -12,6 +17,7 @@ export type HostedAdmission = {
   sessionMode: "event" | "continuation";
   mailboxContinuationKey: string;
   payload: unknown;
+  managedAutomation?: HostedAdmissionManagedAutomation;
 };
 
 export type HostedAdmissionOutcome =
@@ -39,13 +45,49 @@ const DELIVERY_KEYS = new Set([
   "sessionMode",
   "mailboxContinuationKey",
   "payload",
+  "managedAutomation",
 ]);
+const MANAGED_AUTOMATION_KEYS = new Set(["automationUuid", "mcpServerNames"]);
+/** More names than any real automation configures is a malformed envelope. */
+const MANAGED_AUTOMATION_MAX_SERVERS = 64;
 const EXECUTION_KEYS = new Set(["v", "admissionToken", "sessionPublicId"]);
 
 function boundedString(value: unknown, max: number): value is string {
   return typeof value === "string" && value.length > 0 && value.length <= max;
 }
 
+/**
+ * Parse the optional managed-automation slice. Absent → valid (undefined);
+ * present-but-malformed → invalid (the whole admission fails closed, the
+ * strict posture the rest of the envelope already takes).
+ */
+function parseManagedAutomation(
+  value: unknown
+): { managedAutomation?: HostedAdmissionManagedAutomation } | undefined {
+  if (value === undefined) {
+    return {};
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some((key) => !MANAGED_AUTOMATION_KEYS.has(key)) ||
+    !boundedString(body.automationUuid, 128) ||
+    !Array.isArray(body.mcpServerNames) ||
+    body.mcpServerNames.length > MANAGED_AUTOMATION_MAX_SERVERS ||
+    !body.mcpServerNames.every((name) => boundedString(name, 256))
+  ) {
+    return undefined;
+  }
+  return {
+    managedAutomation: {
+      automationUuid: body.automationUuid,
+      mcpServerNames: body.mcpServerNames,
+    },
+  };
+}
+
 export function parseHostedAdmission(
   value: unknown
 ): HostedAdmission | undefined {
@@ -62,7 +104,8 @@ export function parseHostedAdmission(
     !boundedString(body.eventType, 128) ||
     !boundedString(body.deliveryId, 256) ||
     (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||
-    !boundedString(body.mailboxContinuationKey, 512)
+    !boundedString(body.mailboxContinuationKey, 512) ||
+    parseManagedAutomation(body.managedAutomation) === undefined
   ) {
     return undefined;
   }

package/src/internal/hosted-delivery.ts

@@ -10,6 +10,14 @@ import type {
   ChannelHandlerArgs,
   SendMessageOptions,
 } from "../types.js";
+import {
+  createDeferredChannelSession,
+  DeferredChannelSessionError,
+} from "./deferred-channel-session.js";
+import {
+  HostedAdmissionLocalSendError,
+  runDuringHostedAdmission,
+} from "./hosted-admission-context.js";
 import {
   HOSTED_ADMISSION_PATH,
   HOSTED_DELIVERY_HEADER,
@@ -19,6 +27,7 @@ import {
   parseHostedAdmission,
   parseHostedExecution,
 } from "./hosted-delivery-protocol.js";
+import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { errorResponse, readJsonObject } from "./http-channel.js";
 import type { Router } from "./router.js";
 
@@ -45,19 +54,66 @@ type ExecutionReply = {
   body: Record<string, unknown>;
 };
 
-class HostedSendAdmitted extends Error {
-  constructor(
-    readonly prompt: string,
-    readonly options: SendMessageOptions
-  ) {
-    super("hosted channel admitted a send");
+/**
+ * A second `send()` in one delivery is a deterministic authored bug — the
+ * wire protocol carries exactly one pending send per delivery — so it must
+ * fail the delivery exactly once. It surfaces as a 422 because the control
+ * plane retries 5xx admissions (fresh pod, side effects re-run, identical
+ * failure, up to the Temporal attempt cap); a non-5xx/408/429 status makes
+ * it reject the delivery non-retryably instead.
+ */
+class HostedSendLimitExceeded extends Error {
+  constructor() {
+    super(
+      "The hosted delivery protocol carries exactly one pending send per " +
+        "delivery, and this delivery already captured one. Combine both " +
+        "messages into a single send(), or split the work across deliveries."
+    );
   }
 }
 
+// Authored/task-derived text stays bounded on this internal response path
+// (and is never persisted to Temporal history by the control plane).
+const MAX_ERROR_MESSAGE_LENGTH = 1024;
+
+function boundedMessage(text: string): string {
+  return text.length > MAX_ERROR_MESSAGE_LENGTH
+    ? `${text.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
+    : text;
+}
+
+/**
+ * Classify deterministic authored protocol violations as non-retryable 422
+ * admissions. Anything else returns `undefined` so callers fall through to
+ * the existing (retryable or rethrow) handling.
+ */
+function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
+  const code =
+    error instanceof HostedSendLimitExceeded
+      ? "hosted_send_limit_exceeded"
+      : error instanceof DeferredChannelSessionError
+        ? "hosted_deferred_session_unusable"
+        : error instanceof HostedAdmissionLocalSendError
+          ? "hosted_local_send_rejected"
+          : undefined;
+  if (code === undefined) {
+    return undefined;
+  }
+  return {
+    response: errorResponse(
+      422,
+      code,
+      boundedMessage((error as Error).message)
+    ),
+  };
+}
+
 /**
  * Run authored admission without creating a framework session. V1 GitHub
- * `task` callbacks execute as sessionless work; `send` is captured and
- * resumed only after the control plane allocates `ses_…`.
+ * `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.
  */
 export async function dispatchHostedAdmission(
   input: DispatchInput
@@ -71,24 +127,28 @@ 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));
+}
 
+async function runAdmission(
+  input: DispatchInput,
+  github: NonNullable<ReturnType<typeof getGitHubChannelOptions>>
+): Promise<AdmissionDispatch> {
   const background: Promise<unknown>[] = [];
-  let deferredSend: HostedSendAdmitted | undefined;
+  let captured: { message: string; options: SendMessageOptions } | undefined;
   const args = withPropagatingGitHubBackgroundErrors({
     ...input.args,
     send: async (message, options = {}) => {
-      throw new HostedSendAdmitted(message, options);
+      if (captured !== undefined) {
+        throw new HostedSendLimitExceeded();
+      }
+      captured = { message, options };
+      return createDeferredChannelSession();
     },
     waitUntil: (promise) => {
-      background.push(
-        promise.catch((error: unknown) => {
-          if (error instanceof HostedSendAdmitted) {
-            deferredSend = error;
-            return;
-          }
-          throw error;
-        })
-      );
+      background.push(promise);
     },
   });
   let dispatched: Response;
@@ -101,20 +161,9 @@ export async function dispatchHostedAdmission(
       args,
     });
   } catch (error) {
-    if (error instanceof HostedSendAdmitted) {
-      return {
-        response: Response.json({
-          ok: true,
-          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-          outcome: "send",
-        }),
-        pendingSend: {
-          channelId: input.delivery.channelId,
-          message: error.prompt,
-          options: error.options,
-          mailboxContinuationKey: input.delivery.mailboxContinuationKey,
-        },
-      };
+    const rejected = nonRetryableRejection(error);
+    if (rejected !== undefined) {
+      return rejected;
     }
     throw error;
   }
@@ -129,15 +178,20 @@ export async function dispatchHostedAdmission(
 
   try {
     await Promise.all(background);
-  } catch {
+  } catch (error) {
+    const rejected = nonRetryableRejection(error);
+    if (rejected !== undefined) {
+      return rejected;
+    }
     return {
-      response: Response.json(
-        { ok: false, error: "background_dispatch_failed" },
-        { status: 503 }
+      response: errorResponse(
+        503,
+        "background_dispatch_failed",
+        boundedMessage(error instanceof Error ? error.message : String(error))
       ),
     };
   }
-  if (deferredSend !== undefined) {
+  if (captured !== undefined) {
     return {
       response: Response.json({
         ok: true,
@@ -146,8 +200,8 @@ export async function dispatchHostedAdmission(
       }),
       pendingSend: {
         channelId: input.delivery.channelId,
-        message: deferredSend.prompt,
-        options: deferredSend.options,
+        message: captured.message,
+        options: captured.options,
         mailboxContinuationKey: input.delivery.mailboxContinuationKey,
       },
     };
@@ -241,6 +295,7 @@ export function registerHostedDeliveryRoute(input: {
           )
         );
       }
+      recordHostedManagedAutomation(delivery);
       const channel = input.channels.find(
         (candidate) => candidate.id === delivery.channelId
       );

package/src/internal/hosted-managed-automation.ts

@@ -0,0 +1,72 @@
+/**
+ * Managed-automation envelope slices by provider delivery id (plan 0002
+ * G2), recorded at hosted admission so channel code running the delivery's
+ * task (or session turn) can attach the customer's MCP servers through the
+ * control-plane relay. In-memory and TTL-bounded like the hosted pending-
+ * send table: the envelope slice carries names only (never credentials)
+ * and evaporates with the process.
+ *
+ * A leaf module (protocol type import only) so product channels can read
+ * it without pulling the hosted-delivery route — and its session-engine
+ * dependency graph — into their bundles.
+ *
+ * INTERNAL: first-party multi-tenant deployment plumbing. Deliberately
+ * excluded from the published `@cursor/july` npm package (see the `files`
+ * whitelist); consumed by internal deployments via relative source imports.
+ */
+
+import type { HostedAdmissionManagedAutomation } from "./hosted-delivery-protocol.js";
+
+const managedAutomationByDelivery = new Map<
+  string,
+  { managedAutomation: HostedAdmissionManagedAutomation; expiresAt: number }
+>();
+/** Long enough to outlive a slow review run kicked off by the delivery. */
+const MANAGED_AUTOMATION_TTL_MS = 60 * 60_000;
+const MANAGED_AUTOMATION_MAX_ENTRIES = 10_000;
+
+export function recordHostedManagedAutomation(delivery: {
+  deliveryId: string;
+  managedAutomation?: HostedAdmissionManagedAutomation;
+}): void {
+  if (delivery.managedAutomation === undefined) {
+    return;
+  }
+  const now = Date.now();
+  for (const [key, entry] of managedAutomationByDelivery) {
+    if (entry.expiresAt <= now) {
+      managedAutomationByDelivery.delete(key);
+    }
+  }
+  if (managedAutomationByDelivery.size >= MANAGED_AUTOMATION_MAX_ENTRIES) {
+    managedAutomationByDelivery.clear();
+  }
+  managedAutomationByDelivery.set(delivery.deliveryId, {
+    managedAutomation: delivery.managedAutomation,
+    expiresAt: now + MANAGED_AUTOMATION_TTL_MS,
+  });
+}
+
+/**
+ * The managed automation the control plane attributed to a hosted delivery,
+ * when the envelope carried one. Undefined for non-managed deliveries,
+ * expired entries, and non-hosted (webhook/stream) dispatch paths.
+ */
+export function getHostedManagedAutomation(
+  deliveryId: string
+): HostedAdmissionManagedAutomation | undefined {
+  const entry = managedAutomationByDelivery.get(deliveryId);
+  if (entry === undefined) {
+    return undefined;
+  }
+  if (entry.expiresAt <= Date.now()) {
+    managedAutomationByDelivery.delete(deliveryId);
+    return undefined;
+  }
+  return entry.managedAutomation;
+}
+
+/** Drop recorded managed-automation slices (tests only). */
+export function resetHostedManagedAutomationForTest(): void {
+  managedAutomationByDelivery.clear();
+}