@cursor/july 0.1.94 → 0.1.96

package/src/files-backends/cursor-hosted.ts

@@ -71,6 +71,19 @@ const AGENT_SERVE_FILES_PATH = "/v0/agent-serve-files";
 export const AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR =
   "AGENT_SERVE_STORE_SOURCE_ID";
 
+/**
+ * The deployment's **framework-level** file store, distinct from the
+ * user-level store above. The user store carries author-facing bytes
+ * (`ctx.host.files`, skills, memory, artifacts) and is browsable and
+ * mountable; the framework store carries engine-owned session state —
+ * session records, event transcripts, continuation index, and the SDK
+ * conversation mirror — and is never exposed to authors or models.
+ * Provisioned by the v2 deploy pipeline alongside the user store; v1
+ * deployments have only the user store.
+ */
+export const AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR =
+  "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
+
 /** Cap on the per-process etag cache; a miss costs a lookup, not correctness. */
 const MAX_REMEMBERED_ETAGS = 1_000;
 
@@ -101,6 +114,20 @@ export function isCursorHostedFilesAvailable(
   return sourceId !== undefined && sourceId !== "";
 }
 
+/**
+ * The framework-level store's source id, or `undefined` when the deployment
+ * has none (v1, self-hosted, or a v2 deploy predating framework-store
+ * provisioning). Same detection posture as
+ * {@link isCursorHostedFilesAvailable}: keyed on the id alone — a missing
+ * credential must fail loudly at use, not silently deselect the store.
+ */
+export function cursorFrameworkStoreSourceId(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  const sourceId = env[AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR]?.trim();
+  return sourceId === undefined || sourceId === "" ? undefined : sourceId;
+}
+
 /**
  * Local `serve`/`run` with a personal `CURSOR_API_KEY` can address
  * `/v0/agent-serve-files/user`. Hosted deployments have a store source id
@@ -127,6 +154,13 @@ export interface CursorHostedFilesOptions {
   baseUrl?: string;
   /** Bearer credential (default: `CURSOR_API_KEY`). */
   apiKey?: string;
+  /**
+   * Lazy credential, re-resolved on every call and preferred over
+   * {@link apiKey} — hosted freeze snapshots listen unsigned and bind the
+   * key file after serve start. Kept separate so `apiKey` stays a plain
+   * string.
+   */
+  resolveApiKey?: () => string | undefined;
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
   /** Test seam; defaults to global fetch. */
@@ -249,7 +283,11 @@ export function cursorHostedFiles(
           }
           out.push(toEntry(file, file.path));
         }
-        return out;
+        // The FileSink contract promises key order, and transcript-chunk
+        // consumers depend on it (chunk keys are zero-padded so key order
+        // is append order). The server happens to scan in order today; do
+        // not let that be the only thing holding the contract.
+        return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
       }
       // The unscoped listing was truncated (`complete: false`) and has no
       // continuation to follow. `list()` promises the whole scope, so rather
@@ -622,7 +660,8 @@ function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
 }
 
 function resolveApiKey(options: CursorHostedFilesOptions): string {
-  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  const configured = options.resolveApiKey?.() ?? options.apiKey;
+  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
     throw new Error(
       "cursorHostedFiles requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"

package/src/files.ts

@@ -184,6 +184,17 @@ export const agentStoreKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/memory/journal.jsonl`,
   memoryJournalRotated: (agent: string, stamp: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/memory/journal-${stamp}.jsonl`,
+  // SDK conversation mirror (the runner's SQLite store, exported through the
+  // store APIs): one manifest per SDK agent id plus its content-addressed
+  // checkpoint blobs. See internal/conversation-mirror.ts.
+  conversationManifest: (agent: string, sdkAgentId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/manifest.json`,
+  conversationBlob: (
+    agent: string,
+    sdkAgentId: string,
+    blobId: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/blobs/${encodeURIComponent(blobId)}`,
 } as const;
 
 /**

package/src/internal/advertise-tools.ts

@@ -27,6 +27,8 @@
  * `defineConnection({ effects })` filters the listing before names are
  * assigned: only tools whose MCP annotations classify as an intended
  * effect are advertised. Unclassified tools are omitted, not guessed.
+ * Tools whose `annotations.title` is `do-not-call` are dropped as well
+ * (vendor host-UI / MCP Apps helpers that still carry `readOnlyHint`).
  */
 
 import type {
@@ -134,8 +136,10 @@ export async function resolveAdvertisedTools(args: {
         { cause: error }
       );
     }
-    const intended = listed.filter((info) =>
-      matchesIntendedEffects(info.annotations, connection.effects)
+    const intended = listed.filter(
+      (info) =>
+        !isDoNotCallTool(info.annotations) &&
+        matchesIntendedEffects(info.annotations, connection.effects)
     );
     const exposed = exposeListedTools(intended, claimed);
     for (const { info, exposedName } of exposed) {
@@ -232,6 +236,18 @@ function exposeListedTools(
   }));
 }
 
+/**
+ * Vendors (Datadog MCP Apps) stamp host-UI-only helpers with this title.
+ * They still look like reads (`readOnlyHint: true`), so the effects
+ * filter would keep them. The model and agsh should not see them; the
+ * raw MCP listing stays intact for the host.
+ */
+const DO_NOT_CALL_TITLE = "do-not-call";
+
+function isDoNotCallTool(annotations: McpToolAnnotations | undefined): boolean {
+  return annotations?.title?.trim() === DO_NOT_CALL_TITLE;
+}
+
 function matchesIntendedEffects(
   annotations: McpToolAnnotations | undefined,
   effects: readonly ToolEffect[] | undefined

package/src/internal/bounded.ts

@@ -0,0 +1,28 @@
+/**
+ * Bounded-concurrency map, in input order. Local rather than
+ * `@anysphere/utils`: this published package cannot depend on monorepo
+ * internals.
+ */
+export async function mapBounded<T, R>(
+  items: readonly T[],
+  max: number,
+  run: (item: T) => Promise<R>
+): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let nextIndex = 0;
+  const workers = Array.from(
+    { length: Math.min(max, items.length) },
+    async () => {
+      for (;;) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= items.length) {
+          return;
+        }
+        out[index] = await run(items[index] as T);
+      }
+    }
+  );
+  await Promise.all(workers);
+  return out;
+}

package/src/internal/cli-deploy.ts

@@ -27,6 +27,7 @@ import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
 import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   type AgentkitDeployAccepted,
+  type AgentkitDeployComponent,
   type AgentkitDeployStatus,
   type AgentkitStopAccepted,
   AgentServeDeployClient,
@@ -48,6 +49,8 @@ import {
 import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
 import {
   type ChildAgentDir,
+  formatDiagnostics,
+  hasErrorDiagnostics,
   isAgentProjectDir,
   listChildAgentDirs,
   loadAgentProject,
@@ -294,10 +297,35 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     return targets;
   }
 
+  if (targets.length === 1) {
+    return deployOne(ctx, options, targets[0]!);
+  }
+
+  // Multi-agent parent: when every child declares `architecture: "v2"`,
+  // the v2 control plane models sibling agents as release components of
+  // ONE application, so deploy them together (one app, one component per
+  // child) instead of minting a separate application per child. Mixed and
+  // v1 parents keep the per-child sequential deploys.
+  const manifests: DeployManifest[] = [];
+  for (const target of targets) {
+    manifests.push(await readDeployManifest(target.dir));
+  }
+  if (manifests.every((manifest) => manifest.architecture === "v2")) {
+    return deployAgentsdkApplication(ctx, options, targets);
+  }
+  if (
+    !ctx.json &&
+    manifests.some((manifest) => manifest.architecture === "v2")
+  ) {
+    ctx.err(
+      `warning: agents under this parent mix architectures; deploying each separately (v2 children become standalone single-component applications).\n`
+    );
+  }
+
   // --path is per-agent (relative to the repo root). When deploying several
   // agents, ignore a shared --path so each target can infer its own path.
   let deployOptions = options;
-  if (targets.length > 1 && options.path !== undefined) {
+  if (options.path !== undefined) {
     if (!ctx.json) {
       ctx.err(
         `warning: ignoring --path ${JSON.stringify(options.path)} for a multi-agent deploy; each agent infers its own path from git.\n`
@@ -306,10 +334,6 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     deployOptions = { ...options, path: undefined };
   }
 
-  if (targets.length === 1) {
-    return deployOne(ctx, deployOptions, targets[0]!);
-  }
-
   // Multi-agent batch: deploy sequentially; --json emits an array.
   const jsonResults: unknown[] = [];
   let failures = 0;
@@ -477,6 +501,19 @@ async function resolveDeployTargets(
     return [match];
   }
 
+  // An all-v2 parent deploys as ONE application (siblings are components
+  // of a single app on the v2 control plane), so "deploy the parent" is
+  // unambiguous and needs no picker or --all. A child that is v1 — or
+  // fails to load — keeps the interactive picker below.
+  if (await allChildrenAreV2(children)) {
+    if (!ctx.json) {
+      ctx.err(
+        `Deploying all ${children.length} v2 agents under ${basename(dir)} as one application (pass --slug <name> to deploy a single agent standalone).\n`
+      );
+    }
+    return [...children];
+  }
+
   const chooser =
     options.chooseTargets ??
     ((agents) =>
@@ -508,6 +545,27 @@ function formatAgentList(agents: readonly DeployTarget[]): string {
   return agents.map((agent, i) => `  ${i + 1}) ${agent.slug}\n`).join("");
 }
 
+/**
+ * True when every child agent project loads and declares
+ * `architecture: "v2"`. Broken projects count as not-v2 so target
+ * resolution falls back to the picker instead of failing the whole deploy
+ * on a child the user might not even select.
+ */
+async function allChildrenAreV2(
+  children: readonly DeployTarget[]
+): Promise<boolean> {
+  for (const child of children) {
+    try {
+      if ((await readDeployManifest(child.dir)).architecture !== "v2") {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * TTY picker for multi-agent parents. Non-interactive callers get `[]`
  * so {@link resolveDeployTargets} can print the --slug/--all hint.
@@ -777,6 +835,100 @@ async function deployOne(
   return 0;
 }
 
+/**
+ * Multi-agent parent whose children all declare `architecture: "v2"`:
+ * deploy ONE application whose release carries a component per child. The
+ * application slug derives from the parent directory name; each component
+ * key is the child's slug and its path is the child directory relative to
+ * the repo root (a shared --path names the parent's directory in the repo).
+ */
+async function deployAgentsdkApplication(
+  ctx: DeployCliContext,
+  options: DeployCliOptions,
+  targets: readonly DeployTarget[]
+): Promise<number> {
+  const parentDir = resolve(options.dir ?? ".");
+  const slug = slugFromDirectoryName(basename(parentDir));
+  if (slug === undefined) {
+    ctx.err(
+      `Could not derive an application slug from the parent directory name ${JSON.stringify(basename(parentDir))} — rename it (deploy slugs use lowercase letters, digits, '-' or '_').\n`
+    );
+    return 1;
+  }
+
+  const needsGitInference =
+    options.repo === undefined ||
+    options.ref === undefined ||
+    options.path === undefined;
+  const inferred = needsGitInference
+    ? await inferDeployGitSource(parentDir, {
+        ...(options.git === undefined ? {} : { git: options.git }),
+      })
+    : {};
+  const gitRepoUrl = options.repo ?? inferred.gitRepoUrl;
+  const gitRef = options.ref ?? inferred.gitRef;
+  const parentPath = options.path ?? inferred.agentPath;
+
+  if (gitRepoUrl !== undefined && !gitRepoUrl.startsWith("https://")) {
+    ctx.err(
+      `Invalid --repo: ${gitRepoUrl} (expected an https:// git repository URL)\n`
+    );
+    return 1;
+  }
+  if (gitRepoUrl === undefined) {
+    ctx.err(
+      `Could not resolve an https:// git repository URL for this deploy.\n` +
+        `  Pass --repo https://github.com/<owner>/<repo> (inferred from origin when possible).\n`
+    );
+    return 1;
+  }
+  for (const repo of options.cursorEventsRepos ?? []) {
+    if (!isValidCursorEventRepo(repo)) {
+      ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
+      return 1;
+    }
+  }
+
+  const components: AgentkitDeployComponent[] = targets.map((target) => ({
+    componentKey: target.slug,
+    agentPath: [parentPath, basename(target.dir)]
+      .filter((part): part is string => part !== undefined && part !== "")
+      .join("/"),
+  }));
+
+  if (!ctx.json) {
+    ctx.err(
+      `Deploying "${slug}" as one v2 application with ${targets.length} components (slug from the parent directory name).\n` +
+        `  architecture: v2\n` +
+        `  source: ${gitRepoUrl}${gitRef === undefined ? "" : ` @ ${gitRef}`}\n` +
+        components
+          .map(
+            (component) =>
+              `  component: ${component.componentKey} (${component.agentPath ?? "."})\n`
+          )
+          .join("")
+    );
+  }
+
+  // Components bake sequentially on the control plane, so the default wait
+  // budget is per component; otherwise a 2+ component deploy routinely hits
+  // the client-side timeout while the server-side deploy is still fine. An
+  // explicitly passed timeout always wins.
+  const waitCtx =
+    options.timeoutMs === undefined
+      ? { ...ctx, timeoutMs: ctx.timeoutMs * targets.length }
+      : ctx;
+
+  return deployOneAgentsdk(waitCtx, undefined, {
+    slug,
+    gitRepoUrl,
+    gitRef,
+    agentPath: undefined,
+    components,
+    repositories: options.cursorEventsRepos,
+  });
+}
+
 /**
  * `architecture: "v2"` deploy: POST `/internal/agentkit/deployments` and
  * poll the matching GET. The v2 accept path starts freeze bake; it does
@@ -790,10 +942,17 @@ async function deployOneAgentsdk(
     gitRepoUrl: string;
     gitRef: string | undefined;
     agentPath: string | undefined;
+    components?: AgentkitDeployComponent[];
     repositories: string[] | undefined;
   }
 ): Promise<number> {
   const { slug } = args;
+  const componentsLine =
+    args.components === undefined
+      ? ""
+      : `  components:  ${args.components
+          .map((component) => component.componentKey)
+          .join(", ")}\n`;
   let accepted: AgentkitDeployAccepted;
   try {
     accepted = await ctx.client.deployAgentkit({
@@ -802,6 +961,7 @@ async function deployOneAgentsdk(
       gitRepoUrl: args.gitRepoUrl,
       gitRef: args.gitRef,
       agentPath: args.agentPath,
+      components: args.components,
       repositories: args.repositories,
     });
   } catch (error) {
@@ -817,7 +977,8 @@ async function deployOneAgentsdk(
       ctx.out(
         `Deploy accepted: ${slug} (team ${ctx.teamId}, v2)\n` +
           `  application: ${accepted.applicationId}\n` +
-          `  release:     ${accepted.releaseId}\n`
+          `  release:     ${accepted.releaseId}\n` +
+          componentsLine
       );
     }
     return 0;
@@ -851,7 +1012,12 @@ async function deployOneAgentsdk(
       `  status:       running\n` +
       `  architecture: v2\n` +
       `  application:  ${detail.applicationId}\n` +
-      `  release:      ${detail.releaseId}\n`
+      `  release:      ${detail.releaseId}\n` +
+      (args.components === undefined
+        ? ""
+        : `  components:   ${args.components
+            .map((component) => component.componentKey)
+            .join(", ")}\n`)
   );
   return 0;
 }
@@ -971,6 +1137,16 @@ interface DeployManifest {
  */
 async function readDeployManifest(dir: string): Promise<DeployManifest> {
   const project = await loadAgentProject(dir);
+  // Fail here, before anything is dispatched: a project with error
+  // diagnostics (e.g. agent/storage.ts on architecture v2) would only be
+  // refused later by `serve` inside the hosted build, wasting a bake.
+  if (hasErrorDiagnostics(project)) {
+    throw new Error(
+      `Refusing to deploy ${project.name} — it has errors:\n${formatDiagnostics(
+        project.diagnostics.filter((d) => d.severity === "error")
+      )}`
+    );
+  }
   return {
     hosting: project.agent.hosting,
     architecture: project.agent.architecture,