@cursor/july 0.1.93 → 0.1.95

package/src/internal/conversation-mirror.ts

@@ -0,0 +1,330 @@
+/**
+ * Durable mirror for the SDK runner's conversation store.
+ *
+ * The Cursor SDK keeps each local conversation in SQLite under the engine's
+ * state root (`runner/index.db` + `runner/agents/agent-<hash>/store.db`).
+ * That disk dies with the pod: on architecture v2, session **records** and
+ * event chunks survive replacement through the control-plane storage mirror
+ * (framework-storage-selection.ts), but the conversation itself was never
+ * hydrated anywhere — a replacement pod resumed every thread as a fresh
+ * conversation.
+ *
+ * This module mirrors the conversation through the SDK's own store APIs —
+ * the agent document (which carries `sdkMetadata.blobEncryptionKey`, without
+ * which the checkpoint blobs cannot be decrypted) plus its content-addressed
+ * checkpoint blobs — into the deployment's shared file storage. On
+ * Cursor-managed hosting that is the Agent Store reached over
+ * `/v0/agent-serve-files` presigned URLs: the store is **not mounted** as a
+ * filesystem in the engine VM (the FUSE mount at
+ * {@link DEPLOYMENT_STORE_MOUNT_PATH} exists only on cloud-runtime VMs), so
+ * the mirror moves bytes through the {@link FileSink} contract instead.
+ *
+ * Going through the store APIs rather than copying `store.db` files sidesteps
+ * WAL consistency and the shared `index.db` (per-session raw copies would
+ * clobber other sessions' rows); checkpoint blobs are content-addressed, so
+ * repeat persists upload only what is new.
+ *
+ * Timing: the runner hydrates before `Agent.resume` (so a follow-up landing
+ * on a fresh pod — including a v2 hosted-execution delivery — finds the
+ * conversation before the turn runs) and persists after each local turn
+ * settles, **awaited**, because a hosted pod can be parked immediately after
+ * the execution reply.
+ *
+ * Run rows and run events are deliberately not mirrored: they are per-pod
+ * bookkeeping (turn numbers, stream offsets), and the durable session event
+ * stream already lives in the control-plane storage mirror.
+ */
+
+import type { LocalAgentDocument, LocalAgentStore } from "@cursor/sdk";
+import { agentStoreKeys, type FileSink } from "../files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "../files-backends/cursor-hosted.js";
+import type { AgentProject } from "../types.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+
+/**
+ * Persist/restore one SDK conversation between a {@link LocalAgentStore} and
+ * durable file storage. Implemented by {@link createConversationMirror};
+ * consumed by the SDK runner.
+ */
+export interface ConversationMirror {
+  /**
+   * Restore `sdkAgentId`'s conversation into `store` when the store does not
+   * already hold it. Resolves `true` when a conversation was restored,
+   * `false` on a definitive miss (never persisted, or already local — the
+   * caller falls through to its fresh-conversation path). A sink **failure**
+   * propagates: an outage must fail the turn (retryable) rather than
+   * silently fork the thread onto a fresh conversation.
+   */
+  hydrate(store: LocalAgentStore, sdkAgentId: string): Promise<boolean>;
+  /**
+   * Mirror `sdkAgentId`'s conversation from `store` to the sink
+   * (last write wins). No-op until the conversation has a checkpoint.
+   */
+  persist(store: LocalAgentStore, sdkAgentId: string): Promise<void>;
+}
+
+/** Wire shape at {@link agentStoreKeys.conversationManifest}. */
+interface ConversationManifestV1 {
+  v: 1;
+  /** The SDK agent document, verbatim apart from `activeRunId` (nulled). */
+  agent: LocalAgentDocument;
+  /** Checkpoint blob ids present under the conversation's blob prefix. */
+  blobIds: string[];
+  persistedAtMs: number;
+}
+
+export interface CreateConversationMirrorOptions {
+  sink: FileSink;
+  /** Agent name baked into every minted key. */
+  agentName: string;
+  logger?: (line: string) => void;
+}
+
+/** Build a {@link ConversationMirror} over a {@link FileSink}. */
+export function createConversationMirror(
+  options: CreateConversationMirrorOptions
+): ConversationMirror {
+  const { sink, agentName } = options;
+  const logger = options.logger ?? (() => {});
+  /** Blob ids known to be in the sink, per SDK agent id (upload dedupe). */
+  const mirrored = new Map<string, Set<string>>();
+  /**
+   * Per-conversation serialization so a persist cannot interleave with a
+   * hydrate (or another persist) for the same conversation.
+   */
+  const chains = new Map<string, Promise<unknown>>();
+
+  function serialize<T>(sdkAgentId: string, run: () => Promise<T>): Promise<T> {
+    const previous = chains.get(sdkAgentId) ?? Promise.resolve();
+    const next = previous.then(run, run);
+    chains.set(
+      sdkAgentId,
+      next.catch(() => {})
+    );
+    return next;
+  }
+
+  async function mirroredBlobIds(sdkAgentId: string): Promise<Set<string>> {
+    const cached = mirrored.get(sdkAgentId);
+    if (cached !== undefined) {
+      return cached;
+    }
+    // Seed from the previous manifest so a fresh pod does not re-upload the
+    // whole history on its first persist. A miss (or parse failure) seeds
+    // empty — re-uploading is wasteful, never wrong.
+    const seeded = new Set<string>();
+    try {
+      const manifest = await readManifest(sink, agentName, sdkAgentId);
+      for (const blobId of manifest?.blobIds ?? []) {
+        seeded.add(blobId);
+      }
+    } catch (error) {
+      logger(
+        `[agent-sdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`
+      );
+    }
+    mirrored.set(sdkAgentId, seeded);
+    return seeded;
+  }
+
+  return {
+    persist(store, sdkAgentId): Promise<void> {
+      return serialize(sdkAgentId, async () => {
+        const document = await store.agents.get({ agentId: sdkAgentId });
+        if (document === null || document.latestCheckpoint == null) {
+          // Nothing restorable yet (no conversation, or no checkpoint).
+          return;
+        }
+        const uploaded = await mirroredBlobIds(sdkAgentId);
+        const blobIds = await listCheckpointBlobIds(store, sdkAgentId);
+        for (const blobId of blobIds) {
+          if (uploaded.has(blobId)) {
+            continue;
+          }
+          const bytes = await store.checkpoints.get({
+            agentId: sdkAgentId,
+            blobId,
+          });
+          if (bytes === null) {
+            continue;
+          }
+          await sink.put(
+            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
+            bytes
+          );
+          // Content-addressed: once in the sink, never re-uploaded.
+          uploaded.add(blobId);
+        }
+        const manifest: ConversationManifestV1 = {
+          v: 1,
+          // The referenced run is pod-local bookkeeping and is not mirrored;
+          // a hydrated store must not point at a run row it does not hold.
+          agent: { ...document, activeRunId: null },
+          blobIds: blobIds.filter((blobId) => uploaded.has(blobId)),
+          persistedAtMs: Date.now(),
+        };
+        // Manifest last: it only ever references blobs already uploaded.
+        await sink.put(
+          agentStoreKeys.conversationManifest(agentName, sdkAgentId),
+          new TextEncoder().encode(JSON.stringify(manifest))
+        );
+      });
+    },
+
+    hydrate(store, sdkAgentId): Promise<boolean> {
+      return serialize(sdkAgentId, async () => {
+        const existing = await store.agents.get({ agentId: sdkAgentId });
+        if (existing !== null) {
+          return false;
+        }
+        const manifest = await readManifest(sink, agentName, sdkAgentId);
+        if (manifest === undefined) {
+          return false;
+        }
+        const rootBlobId = manifest.agent.latestCheckpoint?.rootBlobId;
+        const restored = new Set<string>();
+        for (const blobId of manifest.blobIds) {
+          const body = await sink.get(
+            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId)
+          );
+          const bytes =
+            body === undefined
+              ? undefined
+              : body instanceof Uint8Array
+                ? body
+                : body.body;
+          if (bytes === undefined) {
+            // Definitive absence (never uploaded, or deleted). A missing
+            // root blob makes the conversation unrestorable — fall through
+            // to the caller's fresh-conversation path rather than creating
+            // an agent row whose checkpoint cannot load.
+            if (blobId === rootBlobId) {
+              logger(
+                `[agent-sdk] conversation mirror: the root checkpoint blob for ${sdkAgentId} is missing from the sink; treating the conversation as unrestorable`
+              );
+              return false;
+            }
+            continue;
+          }
+          if (
+            (await store.checkpoints.get({ agentId: sdkAgentId, blobId })) ===
+            null
+          ) {
+            await store.checkpoints.create({
+              agentId: sdkAgentId,
+              blobId,
+              data: bytes,
+            });
+          }
+          restored.add(blobId);
+        }
+        if (rootBlobId !== undefined && !restored.has(rootBlobId)) {
+          logger(
+            `[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`
+          );
+          return false;
+        }
+        await store.agents.create({
+          agent: { ...manifest.agent, activeRunId: null },
+        });
+        mirrored.set(sdkAgentId, restored);
+        logger(
+          `[agent-sdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`
+        );
+        return true;
+      });
+    },
+  };
+}
+
+async function readManifest(
+  sink: FileSink,
+  agentName: string,
+  sdkAgentId: string
+): Promise<ConversationManifestV1 | undefined> {
+  const body = await sink.get(
+    agentStoreKeys.conversationManifest(agentName, sdkAgentId)
+  );
+  if (body === undefined) {
+    return undefined;
+  }
+  const bytes = body instanceof Uint8Array ? body : body.body;
+  const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    (parsed as { v?: unknown }).v !== 1
+  ) {
+    throw new Error(
+      `conversation mirror: unsupported manifest for ${sdkAgentId}`
+    );
+  }
+  const manifest = parsed as ConversationManifestV1;
+  if (
+    manifest.agent === null ||
+    typeof manifest.agent !== "object" ||
+    manifest.agent.agentId !== sdkAgentId ||
+    !Array.isArray(manifest.blobIds)
+  ) {
+    throw new Error(
+      `conversation mirror: malformed manifest for ${sdkAgentId}`
+    );
+  }
+  return manifest;
+}
+
+async function listCheckpointBlobIds(
+  store: LocalAgentStore,
+  sdkAgentId: string
+): Promise<string[]> {
+  const blobIds: string[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await store.checkpoints.list({
+      filter: { agentIds: [sdkAgentId], cursor },
+    });
+    blobIds.push(...page.items);
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return blobIds;
+}
+
+/**
+ * Whether (and over which sink) this serve process mirrors conversations.
+ *
+ * Selected for architecture-v2 agents on Cursor-managed hosting — the same
+ * generation signal as framework-storage-selection.ts, plus a provisioned
+ * deployment file store. Self-hosted v2 keeps everything on the state root
+ * (the operator owns the disk), and v1 keeps today's behavior while it runs.
+ */
+export function selectConversationMirror(input: {
+  project: AgentProject;
+  logger?: (line: string) => void;
+  env?: Record<string, string | undefined>;
+}): ConversationMirror | undefined {
+  if (input.project.agent.architecture !== "v2") {
+    return undefined;
+  }
+  const env = input.env ?? process.env;
+  if (
+    env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined ||
+    !isCursorHostedFilesAvailable(env as NodeJS.ProcessEnv)
+  ) {
+    return undefined;
+  }
+  return createConversationMirror({
+    sink: cursorHostedFiles({
+      // Full chain (env → key file → stored login): frozen engines listen
+      // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
+      // is constructed.
+      apiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+    agentName: input.project.name,
+    logger: input.logger,
+  });
+}

package/src/internal/convert-automation/convert-workflow.ts

@@ -6,9 +6,10 @@
  * clock — `exportedAt` comes from the caller.
  */
 
+import { envPrefixFromName } from "../../channels/slack/credentials.js";
 import { CLI_COMMAND_NAME, PACKAGE_NAME } from "../distribution.js";
 import { MEMORY_TS } from "../init-scaffold.js";
-import { pascalCase, SlugRegistry, slugify } from "./slug.js";
+import { SlugRegistry, slugify } from "./slug.js";
 import type {
   ActionJson,
   ConvertedFile,
@@ -998,11 +999,11 @@ function emitSlackChannel(
       "The Slack trigger marked triggering messages with a completion reaction; agentsdk has no completion-reaction option, so that signal is lost unless agent/instructions.md tells the agent to add the reaction itself via Slack tools."
     );
   }
-  if (socketMode) {
-    out.setupSteps.push(
-      `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app (not the Cursor connection): run \`${CLI_COMMAND_NAME} slack create --channel-posts\`, then finish in the dashboard wizard.`
-    );
-  }
+  out.setupSteps.push(
+    socketMode
+      ? `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app: run \`${CLI_COMMAND_NAME} slack create --channel-posts\`, then finish in the dashboard wizard.`
+      : `Slack mentions need a dedicated Socket Mode Slack app: run \`${CLI_COMMAND_NAME} slack create\`, then finish in the dashboard wizard.`
+  );
 
   const header = [
     `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";`,
@@ -1069,26 +1070,37 @@ function emitSlackChannel(
     }
     body = [
       "//",
-      "// This channel needs a dedicated Socket Mode Slack app (not the Cursor",
-      `// connection): run \`${CLI_COMMAND_NAME} slack create --channel-posts\`.`,
-      "export default slackChannel({",
-      ...engagement,
-      "});",
+      `// Run \`${CLI_COMMAND_NAME} slack create --channel-posts\` for a dedicated Slack app.`,
+      ...slackChannelExport(automation.name, engagement),
     ];
   } else {
-    const agentName = pascalCase(automation.name, "ExportedAgent");
     body = [
       "//",
-      `// Mention this agent in Slack with \`@Cursor ${agentName} ...\`.`,
-      "export default slackChannel({",
-      "  cursorAccount: true,",
-      `  agentName: ${JSON.stringify(agentName)},`,
-      "});",
+      `// Run \`${CLI_COMMAND_NAME} slack create\` for a dedicated Slack app.`,
+      ...slackChannelExport(automation.name, []),
     ];
   }
   out.files.push({ path, contents: `${[...header, ...body].join("\n")}\n` });
 }
 
+/**
+ * `slack create` writes `<DIR>_SLACK_*` from the project directory. Convert
+ * names that directory from the automation (`Nightly Triage` →
+ * `nightly-triage` → `NIGHTLY_TRIAGE`). Emit the same prefix so minted
+ * tokens bind.
+ */
+function slackChannelExport(name: string, optionLines: string[]): string[] {
+  const prefix = envPrefixFromName(slugify(name, "automation"));
+  const options = [
+    ...(prefix === "" ? [] : [`  envPrefix: ${JSON.stringify(prefix)},`]),
+    ...optionLines,
+  ];
+  if (options.length === 0) {
+    return ["export default slackChannel();"];
+  }
+  return ["export default slackChannel({", ...options, "});"];
+}
+
 function slackChannelList(
   trigger: SlackChannelsTriggerJson | undefined
 ): string[] {

package/src/internal/convert-automation/slug.ts

@@ -9,15 +9,6 @@ export function slugify(name: string, fallback: string): string {
   return slug === "" ? fallback : slug;
 }
 
-/** Single-token PascalCase (Slack cursorAccount agentName). */
-export function pascalCase(name: string, fallback: string): string {
-  const words = name.split(/[^a-zA-Z0-9]+/).filter((word) => word !== "");
-  if (words.length === 0) {
-    return fallback;
-  }
-  return words.map((word) => word[0]?.toUpperCase() + word.slice(1)).join("");
-}
-
 /** Dedupes slugs with numeric suffixes: `linear`, `linear-2`, `linear-3`, … */
 export class SlugRegistry {
   private readonly used = new Set<string>();

package/src/internal/cursor/account-mcp.ts

@@ -85,7 +85,10 @@ export function collectCursorAccountConnections(
   const bySlug = new Map<string, CursorAccountConnectionRef[]>();
   for (const { slug, project } of mounts) {
     const refs: CursorAccountConnectionRef[] = [];
-    for (const connection of project.agent.connections) {
+    for (const connection of [
+      ...project.agent.connections,
+      ...(project.agent.hostConnections ?? []),
+    ]) {
       if (!isCursorAccountTransport(connection.transport)) {
         continue;
       }

package/src/internal/deferred-channel-session.ts

@@ -0,0 +1,61 @@
+import type { ChannelSession } from "../types.js";
+
+const deferredSessions = new WeakSet<ChannelSession>();
+
+/**
+ * Authored code touched a member of the deferred handle that needs the live
+ * session. This is deterministic (the session never exists during admission),
+ * so the admission route surfaces it as a non-retryable 422 rather than a
+ * retryable failure.
+ */
+export class DeferredChannelSessionError extends Error {
+  constructor(member: string) {
+    super(
+      `ChannelSession.${member} is not available on a send() captured ` +
+        "during hosted admission: the control plane allocates the session " +
+        "(and runs the turn) only after this delivery is acknowledged, so " +
+        "the handle cannot observe it yet. Move work that needs the live " +
+        "session into the session turn instead."
+    );
+  }
+}
+
+function unavailable(member: string): never {
+  throw new DeferredChannelSessionError(member);
+}
+
+/**
+ * Inert `ChannelSession` returned by the hosted-admission `send` stub: every
+ * member fails loudly via {@link DeferredChannelSessionError}. Caveat: new
+ * OPTIONAL members added to `ChannelSession` slip through this factory
+ * silently (reads return `undefined`) until a throwing getter is added here.
+ */
+export function createDeferredChannelSession(): ChannelSession {
+  const session: ChannelSession = {
+    get id(): string {
+      return unavailable("id");
+    },
+    get continuationToken(): string | null {
+      return unavailable("continuationToken");
+    },
+    get isNew(): boolean {
+      return unavailable("isNew");
+    },
+    get coalesced(): boolean | undefined {
+      return unavailable("coalesced");
+    },
+    get info(): ChannelSession["info"] {
+      return unavailable("info");
+    },
+    getEventStream: async () => unavailable("getEventStream()"),
+    waitForCompletion: async () => unavailable("waitForCompletion()"),
+    setContinuationToken: async () => unavailable("setContinuationToken()"),
+  };
+  deferredSessions.add(session);
+  return session;
+}
+
+/** True when `send()` returned a hosted-admission capture handle. */
+export function isDeferredChannelSession(session: ChannelSession): boolean {
+  return deferredSessions.has(session);
+}

package/src/internal/deploy-client.ts

@@ -224,6 +224,16 @@ export interface AgentkitDeployAccepted {
   status: string;
 }
 
+/**
+ * One release component of a v2 multi-component deploy: a stable key (the
+ * child agent's slug) plus that agent's directory relative to the repo
+ * root.
+ */
+export interface AgentkitDeployComponent {
+  componentKey: string;
+  agentPath?: string;
+}
+
 /** Customer-visible v2 deploy status (`GET /internal/agentkit/deployments/:slug`). */
 export type AgentkitCustomerStatus =
   | "pending"
@@ -576,7 +586,9 @@ export class AgentServeDeployClient {
   /**
    * Create or redeploy onto the v2 control plane
    * (`POST /internal/agentkit/deployments`). 202 means accepted; poll
-   * {@link getAgentkitDeploy} until a terminal status.
+   * {@link getAgentkitDeploy} until a terminal status. `components` deploys
+   * one application with several release components (one per agent
+   * directory); it is mutually exclusive with `agentPath`.
    */
   async deployAgentkit(args: {
     teamId: number;
@@ -584,12 +596,22 @@ export class AgentServeDeployClient {
     gitRepoUrl: string;
     gitRef?: string;
     agentPath?: string;
+    components?: AgentkitDeployComponent[];
     repositories?: string[];
   }): Promise<AgentkitDeployAccepted> {
     const slugError = validateDeploymentSlug(args.slug);
     if (slugError !== undefined) {
       throw new DeployApiError(slugError, 400);
     }
+    for (const component of args.components ?? []) {
+      const keyError = validateDeploymentSlug(component.componentKey);
+      if (keyError !== undefined) {
+        throw new DeployApiError(
+          `Invalid component key ${JSON.stringify(component.componentKey)}: use lowercase letters, digits, '-' or '_' (max 64 chars)`,
+          400
+        );
+      }
+    }
     const raw = await this.request({
       method: "POST",
       path: "/internal/agentkit/deployments",
@@ -599,6 +621,7 @@ export class AgentServeDeployClient {
         gitRepoUrl: args.gitRepoUrl,
         gitRef: args.gitRef,
         agentPath: args.agentPath,
+        components: args.components,
         repositories:
           args.repositories !== undefined && args.repositories.length > 0
             ? args.repositories

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 }),