@cursor/july 0.1.96 → 0.1.99

package/src/internal/deploy-client.ts

@@ -260,6 +260,13 @@ export interface AgentkitDeployStatus {
   status: AgentkitCustomerStatus;
   progress: AgentkitDeployProgress;
   statusMessage: string | null;
+  /** Why the bake failed. Null/absent unless `status` is `failed`. */
+  lastError?: string | null;
+  /**
+   * `owner/name` scopes the deployment's GitHub/Origin channels watch.
+   * Absent on control planes that predate the field.
+   */
+  repositories?: string[];
 }
 
 export const TERMINAL_AGENTKIT_DEPLOY_STATUSES: ReadonlySet<AgentkitCustomerStatus> =
@@ -350,6 +357,8 @@ const agentkitDeployStatusSchema = z
       "stopped",
     ]),
     statusMessage: z.string().nullable(),
+    // Optional: backends that predate the v2 bake-failure column omit it.
+    lastError: z.string().nullable().optional(),
   })
   .passthrough();
 
@@ -598,6 +607,8 @@ export class AgentServeDeployClient {
     agentPath?: string;
     components?: AgentkitDeployComponent[];
     repositories?: string[];
+    /** Redeploy an existing Cursor-managed (multi-tenant) product. */
+    multiTenant?: boolean;
   }): Promise<AgentkitDeployAccepted> {
     const slugError = validateDeploymentSlug(args.slug);
     if (slugError !== undefined) {
@@ -626,6 +637,7 @@ export class AgentServeDeployClient {
           args.repositories !== undefined && args.repositories.length > 0
             ? args.repositories
             : undefined,
+        ...(args.multiTenant === true ? { multiTenant: true } : {}),
       },
       context: { verb: "deploy", slug: args.slug },
     });
@@ -890,6 +902,37 @@ export class AgentServeDeployClient {
   }
 }
 
+const MCP_GATEWAY_PATH =
+  /^\/internal\/agent-serve\/mcp\/(\d+)\/([^/]+)(?:\/tools)?\/?$/;
+
+/**
+ * Inverse of {@link AgentServeDeployClient.mcpGatewayUrl}. Also accepts
+ * the hosted `--cloud-tools-url` form (`…/tools`).
+ */
+export function parseAgentServeMcpGatewayUrl(
+  url: string
+): { teamId: number; slug: string } | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const match = MCP_GATEWAY_PATH.exec(parsed.pathname);
+  if (match === null) {
+    return undefined;
+  }
+  const teamId = Number.parseInt(match[1]!, 10);
+  if (!Number.isInteger(teamId) || teamId <= 0) {
+    return undefined;
+  }
+  const slug = decodeURIComponent(match[2]!);
+  if (validateDeploymentSlug(slug) !== undefined) {
+    return undefined;
+  }
+  return { teamId, slug };
+}
+
 // ============================================================================
 // Error mapping (HTTP → actionable human messages)
 // ============================================================================

package/src/internal/env-file.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared `.env` / `.env.local` writers for CLI commands that mint tokens.
+ */
+
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
+async function readOptionalFile(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+/**
+ * Append `KEY=value` lines to an env file, replacing every existing line
+ * for the same key instead of appending duplicates. Creates the file when
+ * missing.
+ */
+export async function upsertEnvFile(
+  path: string,
+  entries: Array<{ key: string; value: string }>
+): Promise<void> {
+  const existing = await readOptionalFile(path);
+  const lines =
+    existing === "" ? [] : existing.replace(/\r?\n$/, "").split(/\r?\n/);
+  // A stale `export KEY=…` line would shadow or duplicate the bare line
+  // under some loaders; treat both spellings as the same entry.
+  const matchesKey = (line: string, key: string): boolean =>
+    line.startsWith(`${key}=`) || line.startsWith(`export ${key}=`);
+  for (const { key, value } of entries) {
+    const next = `${key}=${value}`;
+    let replaced = false;
+    for (let i = 0; i < lines.length; ) {
+      if (!matchesKey(lines[i] ?? "", key)) {
+        i += 1;
+        continue;
+      }
+      if (replaced) {
+        lines.splice(i, 1);
+        continue;
+      }
+      lines[i] = next;
+      replaced = true;
+      i += 1;
+    }
+    if (!replaced) {
+      lines.push(next);
+    }
+  }
+  // writeFile's mode only applies on create; clamp pre-existing files too.
+  await writeFile(path, `${lines.join("\n")}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+/**
+ * Ensure the agent directory's .gitignore covers .env.local (create or
+ * append). A bare `.env` line does not count — that pattern matches only
+ * the file literally named .env.
+ */
+export async function ensureEnvLocalGitignored(dir: string): Promise<boolean> {
+  const path = join(dir, ".gitignore");
+  const existing = await readOptionalFile(path);
+  const covered = existing
+    .split(/\r?\n/)
+    .some((line) => /^\.env(\.local\*?|\.\*|\*)$/.test(line.trim()));
+  if (covered) {
+    return false;
+  }
+  const next =
+    existing === "" || existing.endsWith("\n")
+      ? `${existing}.env.local\n`
+      : `${existing}\n.env.local\n`;
+  await writeFile(path, next);
+  return true;
+}

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

@@ -8,15 +8,16 @@
  *   is browsable from the dashboard and mountable on cloud-runtime VMs;
  * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
  *   holds engine-owned session state — session records, event transcripts,
- *   the continuation index, and the SDK conversation mirror — and is never
- *   exposed to authors or models.
+ *   hosted-execution run logs, the continuation index, and the SDK
+ *   conversation mirror — and is never exposed to authors or models.
  *
  * This module puts framework session state on the framework store. The
  * {@link storageKeys} scheme was designed for exactly this: keys are a
  * stable versioned contract that sinks may route on, so
  * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
- * kind — `session` / `session-events` / `continuation` go to the framework
- * file store (file-shaped; the store accepts values up to 64 MiB per
+ * kind — `session` / `session-events` / `session-runs` / `continuation`
+ * go to the framework file store (file-shaped; the store accepts values
+ * up to 64 MiB per
  * object without chunking, versus the KV proxy's 1 MiB row cap), while
  * author `kv`, eval runs, A/B samples, and conditional writes stay on the
  * control-plane KV proxy (the dashboard reads them there, and CAS needs a
@@ -40,6 +41,7 @@ import { mapBounded } from "./bounded.js";
 const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
   "session",
   "session-events",
+  "session-runs",
   "continuation",
 ]);
 
@@ -165,13 +167,16 @@ function decodeDocument(key: string, bytes: Uint8Array): JsonValue {
  * Split one storage core by key kind: framework session state to `files`,
  * everything else to `kv`. Spread over the KV backend when building the
  * full definition so its `evals` / `abs` groups (and the cursor-hosted
- * marker) ride along untouched; wrap the KV `cas` group with
- * {@link frameworkGuardedCas} rather than spreading it as-is.
+ * marker) ride along untouched. A KV `cas` group must not be spread as-is:
+ * conditional writes run on a KV database row, so one over a `session/` or
+ * `continuation/` key would read and write a different store than the
+ * routed plain core — silent split-brain. Nothing in the package CASes
+ * those kinds today.
  */
 export function composeFrameworkStorage(input: {
   kv: FileSinkStorageCore;
   files: FileSinkStorageCore;
-}): FileSinkStorageCore {
+}): FileSinkStorageCore & Pick<StorageConfig, "listNewest"> {
   const route = (key: string): FileSinkStorageCore =>
     isFrameworkFileKey(key) ? input.files : input.kv;
   return {
@@ -179,44 +184,11 @@ export function composeFrameworkStorage(input: {
     get: (key, ctx) => route(key).get(key, ctx),
     delete: (key, ctx) => route(key).delete(key, ctx),
     list: (prefix, ctx) => route(prefix).list(prefix, ctx),
-  };
-}
-
-/**
- * The KV backend's conditional writes, refusing framework-file keys.
- *
- * CAS runs on the KV proxy (a database row version); the plain core routes
- * framework session state to the file store. A future coordination path
- * that CASes a `session/` or `continuation/` key would otherwise read and
- * write a different store than the plain path — silent split-brain. Fail
- * loudly instead; nothing in the package CASes those kinds today.
- */
-export function frameworkGuardedCas(
-  cas: NonNullable<StorageConfig["cas"]>
-): NonNullable<StorageConfig["cas"]> {
-  const refuse = (key: string): void => {
-    if (isFrameworkFileKey(key)) {
-      throw new Error(
-        `framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`
-      );
-    }
-  };
-  return {
-    getWithVersion: (key, ctx) => {
-      refuse(key);
-      return cas.getWithVersion(key, ctx);
-    },
-    putIfAbsent: (key, value, ctx) => {
-      refuse(key);
-      return cas.putIfAbsent(key, value, ctx);
-    },
-    putIfVersion: (key, value, expectedVersion, ctx) => {
-      refuse(key);
-      return cas.putIfVersion(key, value, expectedVersion, ctx);
-    },
-    listKeys: (prefix, ctx) => {
-      refuse(prefix);
-      return cas.listKeys(prefix, ctx);
-    },
+    // Session records — the only `listNewest` consumer — are framework file
+    // keys, and the file store has no write-time ordering. Spreading the KV
+    // backend's `listNewest` through would query rows that live elsewhere
+    // (stale KV leftovers, or nothing), so the composed core explicitly has
+    // none and the engine falls back to the routed `list`.
+    listNewest: undefined,
   };
 }

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

@@ -2,6 +2,13 @@ export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
 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";
+/**
+ * Filename under the serve `--state-root` (not the per-slug SessionEngine
+ * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
+ * reads this path after hosted-execution and logs it on the activity span.
+ * Must match `AGENT_SERVE_ENGINE_HOSTED_EXECUTION_DIAG_PATH` basename.
+ */
+export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
 
 export type HostedAdmissionManagedAutomation = {
   automationUuid: string;
@@ -11,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";
@@ -100,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") ||