@cursor/july 0.1.93 → 0.1.95

package/src/internal/discovery.ts

@@ -50,8 +50,10 @@ import {
   type InlineStdioConnectionConfig,
   type InstructionsDefinition,
   isInlineStdioConnection,
+  isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
   type ModelSetting,
+  normalizeConnectionEffects,
   normalizeCursorAccountServers,
   type ResolvedAgent,
   type ScheduleDefinition,
@@ -305,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);
@@ -423,6 +425,7 @@ async function loadAgent(
       tools: [],
       skills: [],
       connections: [],
+      hostConnections: [],
       subagents: [],
       seedFiles: [],
     };
@@ -434,6 +437,7 @@ async function loadAgent(
     ctx,
     await resolveMcpConnectionsDir(ctx, agentDir)
   );
+  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
   const seedFiles = await loadSeedFiles(ctx, agentDir);
   const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
   const runtime = resolveRuntime(ctx, agentDir, config?.runtime);
@@ -553,7 +557,7 @@ async function loadAgent(
       agentTools: tools.filter((tool) => tool.execution === "agent").length,
       skills: skills.length,
       seedFiles: seedFiles.length,
-      connections: connections.length,
+      connections: connections.length + hostConnections.length,
       subagents: subagents.length,
       hasCloudOptions: cloud !== undefined,
       hasLocalSandbox: localSandbox,
@@ -576,6 +580,7 @@ async function loadAgent(
     tools,
     skills,
     connections,
+    hostConnections,
     subagents,
     seedFiles,
   };
@@ -1143,6 +1148,26 @@ function hasAuthorizationHeader(
   );
 }
 
+function parseConnectionEffects(
+  effects: unknown
+): { ok: true; value: ToolEffect[] | undefined } | { ok: false } {
+  if (effects === undefined) {
+    return { ok: true, value: undefined };
+  }
+  const raw = typeof effects === "string" ? [effects] : effects;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { ok: false };
+  }
+  const parsed: ToolEffect[] = [];
+  for (const value of raw) {
+    if (!isToolEffect(value)) {
+      return { ok: false };
+    }
+    parsed.push(value);
+  }
+  return { ok: true, value: normalizeConnectionEffects(parsed) };
+}
+
 function connectionHasSpawnOrRemote(connection: ConnectionDefinition): boolean {
   if ("cursorAccount" in connection && connection.cursorAccount === true) {
     return true;
@@ -1265,6 +1290,49 @@ async function resolveMcpConnectionsDir(
   return preferred;
 }
 
+async function loadHostConnections(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  modelConnections: readonly DiscoveredConnection[]
+): Promise<DiscoveredConnection[]> {
+  const hostDir = join(agentDir, "host-connections");
+  const loaded = await loadConnections(ctx, hostDir);
+  const modelNames = new Set(
+    modelConnections.map((connection) => connection.name)
+  );
+  const hostConnections: DiscoveredConnection[] = [];
+  for (const connection of loaded) {
+    if (modelNames.has(connection.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message: `Host connection "${connection.name}" collides with agent/mcp-connections/${connection.name}. Rename one of them.`,
+      });
+      continue;
+    }
+    if (connection.advertiseTools === true) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message:
+          "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
+      });
+      continue;
+    }
+    if (connection.auth !== undefined) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message:
+          "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
+      });
+      continue;
+    }
+    hostConnections.push(connection);
+  }
+  return hostConnections;
+}
+
 async function loadConnections(
   ctx: DiscoveryContext,
   connectionsDir: string
@@ -1292,6 +1360,15 @@ async function loadConnections(
       continue;
     }
     const connection = definition as ConnectionDefinition;
+    if (Object.hasOwn(connection, "hostOnly")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "MCP connection `hostOnly` was removed. Files under `agent/mcp-connections/` are always visible to the model. Put privileged servers in `agent/host-connections/` so only host tools can call them.",
+      });
+      continue;
+    }
     if (
       isInlineStdioConnection(connection) &&
       connectionHasSpawnOrRemote(connection)
@@ -1336,24 +1413,37 @@ async function loadConnections(
       });
       continue;
     }
+    const parsedEffects = parseConnectionEffects(connection.effects);
+    if (!parsedEffects.ok) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          'MCP connection `effects` must be "read", "write", or a non-empty array of those.',
+      });
+      continue;
+    }
     if (
-      connection.advertiseTools === true &&
-      isInlineStdioConnection(connection)
+      parsedEffects.value !== undefined &&
+      connection.advertiseTools !== true
     ) {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
+          "MCP connection `effects` filters advertised tools; set `advertiseTools: true` or drop `effects`.",
       });
       continue;
     }
-    if (connection.advertiseTools === true && connection.hostOnly === true) {
+    if (
+      connection.advertiseTools === true &&
+      isInlineStdioConnection(connection)
+    ) {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connection `advertiseTools` puts the connection's tools in the model's toolset, which contradicts `hostOnly` (off the model entirely). Drop one of them.",
+          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
       });
       continue;
     }
@@ -1445,9 +1535,9 @@ async function loadConnections(
       name,
       transport,
       description: connection.description,
-      hostOnly: connection.hostOnly,
       auth: connection.auth,
       advertiseTools: connection.advertiseTools,
+      effects: parsedEffects.value,
     });
   }
   return connections;
@@ -1459,7 +1549,6 @@ async function loadInlineStdioConnection(
   entryPath: string,
   connection: InlineStdioConnectionConfig & {
     description?: string;
-    hostOnly?: boolean;
   }
 ): Promise<DiscoveredConnection | undefined> {
   const tools = connection.tools;
@@ -1510,7 +1599,6 @@ async function loadInlineStdioConnection(
       name,
       transport,
       description: connection.description,
-      hostOnly: connection.hostOnly,
     };
   } catch (error) {
     ctx.diagnostics.push({
@@ -1562,6 +1650,7 @@ async function warnUnsupportedSubagentSlots(
     ["tools", "tools"],
     ["skills", "skills"],
     ["mcp-connections", "MCP connections"],
+    ["host-connections", "host MCP connections"],
     ["connections", "MCP connections"],
     ["subagents", "nested subagents"],
     ["channels", "channels"],
@@ -1670,8 +1759,8 @@ function checkGrokBotRuntimeLimitations(
   }
   if (counts.connections > 0) {
     error(
-      displayPath(ctx, join(agentDir, "mcp-connections")),
-      "MCP connections are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
+      displayPath(ctx, agentDir),
+      "MCP connections (agent/mcp-connections/ or agent/host-connections/) are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
     );
   }
   if (counts.subagents > 0) {
@@ -2062,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;
 }
@@ -2256,6 +2368,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       description: tool.description,
       execution: tool.execution,
       needsApproval: tool.needsApproval,
+      effect: tool.effect,
       inputSchema: tool.inputSchema,
     })),
     skills: agent.skills.map((skill) => ({
@@ -2265,8 +2378,8 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
     connections: agent.connections.map((connection) => ({
       name: connection.name,
       transport: connectionTransportLabel(connection.transport),
-      hostOnly: connection.hostOnly,
       advertiseTools: connection.advertiseTools,
+      effects: connection.effects,
       cursorAccountServers:
         "cursorAccount" in connection.transport
           ? (connection.transport.servers ?? "*")
@@ -2448,6 +2561,7 @@ async function warnUnknownSlots(
     "tools",
     "skills",
     "mcp-connections",
+    "host-connections",
     // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
     "connections",
     "subagents",
@@ -2457,7 +2571,7 @@ async function warnUnknownSlots(
     "ab",
     "sandbox",
     "lib",
-    // Vite playground custom tool chips (examples/*/agent/playground/tools).
+    // Vite playground custom tool chips (agent/playground/tools).
     "playground",
   ]);
   for (const entry of await sortedEntries(agentDir)) {

package/src/internal/fixtures/units-server.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny stdio MCP server used by mcp-host tests.
+ *
+ * Exposed as the `units` connection so the host can list and call tools
+ * over a real stdio transport.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({
+  name: "weather-units",
+  version: "0.1.0",
+});
+
+server.tool(
+  "celsius_to_fahrenheit",
+  "Convert a temperature from Celsius to Fahrenheit.",
+  { value: z.number().describe("Temperature in °C") },
+  async ({ value }) => {
+    const fahrenheit = Math.round((value * 9) / 5 + 32);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ celsius: value, fahrenheit }),
+        },
+      ],
+    };
+  }
+);
+
+server.tool(
+  "fahrenheit_to_celsius",
+  "Convert a temperature from Fahrenheit to Celsius.",
+  { value: z.number().describe("Temperature in Fahrenheit") },
+  async ({ value }) => {
+    const celsius = Math.round(((value - 32) * 5) / 9);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ fahrenheit: value, celsius }),
+        },
+      ],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

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;
   }