@cursor/july 0.1.36 → 0.1.38

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

@@ -464,10 +464,21 @@ export function cursorHostedFiles(
             redirect: "manual",
           }
         );
-        if (response.status === 404 || response.status === 403) {
-          // A presigned GET for a missing object surfaces as 403 on S3.
+        if (response.status === 404) {
           return undefined;
         }
+        // A 403 here is deliberately *not* absence. Absence was already
+        // settled above: the store refuses to presign a path with no live
+        // object, so reaching this point means the object existed moments
+        // ago. What produces a 403 after a good presign is an expired or
+        // clock-skewed signature, a policy change, or a delete that raced the
+        // GET — all transient or retryable, none of them "definitively gone".
+        //
+        // Reporting them as absence is how a store blip becomes data loss:
+        // `undefined` on a continuation read is taken as "unknown token", and
+        // the engine mints a fresh session under it, forking the thread. The
+        // delete race resolves itself on retry, where the presign returns 404
+        // and this correctly reads as a miss.
         if (!response.ok) {
           throw new Error(
             `cursorHostedFiles: download of "${key}" failed (HTTP ${response.status})`

package/src/internal/discovery.ts

@@ -45,7 +45,9 @@ import {
   type DiscoveredTool,
   type HookDefinition,
   type HttpChannelDefinition,
+  type InlineStdioConnectionConfig,
   type InstructionsDefinition,
+  isInlineStdioConnection,
   MAX_RUNNING_TURNS_LIMIT,
   type ModelSetting,
   normalizeCursorAccountServers,
@@ -75,6 +77,7 @@ import {
 } from "./hosting.js";
 import { toolInputJsonSchema } from "./json-schema.js";
 import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
+import { packageInlineStdioConnection } from "./package-inline-stdio.js";
 import { withIdentityPreamble } from "./workspace.js";
 
 const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
@@ -927,6 +930,19 @@ function hasAuthorizationHeader(
   );
 }
 
+function connectionHasSpawnOrRemote(connection: ConnectionDefinition): boolean {
+  if ("cursorAccount" in connection && connection.cursorAccount === true) {
+    return true;
+  }
+  if ("agent" in connection && !isBlank(connection.agent)) {
+    return true;
+  }
+  if ("url" in connection && !isBlank(connection.url)) {
+    return true;
+  }
+  return "command" in connection && !isBlank(connection.command);
+}
+
 function connectionTransport(
   connection: ConnectionDefinition
 ): ConnectionTransport | undefined {
@@ -1063,6 +1079,31 @@ async function loadConnections(
       continue;
     }
     const connection = definition as ConnectionDefinition;
+    if (
+      isInlineStdioConnection(connection) &&
+      connectionHasSpawnOrRemote(connection)
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "MCP connection `tools` cannot be combined with `command`, `url`, `agent`, or `cursorAccount`. Author TypeScript tools, or point at an existing server, not both.",
+      });
+      continue;
+    }
+    if (isInlineStdioConnection(connection)) {
+      const packed = await loadInlineStdioConnection(
+        ctx,
+        name,
+        entryPath,
+        connection
+      );
+      if (packed === undefined) {
+        continue;
+      }
+      connections.push(packed);
+      continue;
+    }
     if (
       "url" in connection &&
       connection.oauth === true &&
@@ -1095,7 +1136,7 @@ async function loadConnections(
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connections require a `url` (http/sse), a `command` (stdio), an `agent` (peer agent slug on the same serve host), or `cursorAccount: true` (the Cursor account's MCP connectors).",
+          "MCP connections require a `url` (http/sse), a `command` (stdio), `tools` (TypeScript packaged as stdio), an `agent` (peer agent slug on the same serve host), or `cursorAccount: true` (the Cursor account's MCP connectors).",
       });
       continue;
     }
@@ -1131,6 +1172,75 @@ async function loadConnections(
   return connections;
 }
 
+async function loadInlineStdioConnection(
+  ctx: DiscoveryContext,
+  name: string,
+  entryPath: string,
+  connection: InlineStdioConnectionConfig & {
+    description?: string;
+    hostOnly?: boolean;
+  }
+): Promise<DiscoveredConnection | undefined> {
+  const tools = connection.tools;
+  const names = Object.keys(tools);
+  if (names.length === 0) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: "MCP connection `tools` must declare at least one tool.",
+    });
+    return undefined;
+  }
+  for (const toolName of names) {
+    if (!NAME_PATTERN.test(toolName)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP tool name "${toolName}" must match ${NAME_PATTERN}.`,
+      });
+      return undefined;
+    }
+    const tool = tools[toolName];
+    if (tool === undefined || isBlank(tool.description)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP tool "${toolName}" requires a non-empty description.`,
+      });
+      return undefined;
+    }
+    if (typeof tool.execute !== "function") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP tool "${toolName}" requires an execute(input) function.`,
+      });
+      return undefined;
+    }
+  }
+  try {
+    const transport = await packageInlineStdioConnection({
+      name,
+      entryPath,
+      tools,
+      absWorkingDir: ctx.rootDir,
+    });
+    return {
+      name,
+      transport,
+      description: connection.description,
+      hostOnly: connection.hostOnly,
+    };
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `Failed to package inline stdio MCP connection: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+}
+
 // ============================================================================
 // Subagents
 // ============================================================================

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

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
+ * already holds `session.json` and `events.ndjson` unconditionally, through
+ * the session store; what this selects is the durable mirror *beyond* the
+ * pod's filesystem.
+ */
+
+import type { StorageDefinition } from "../storage.js";
+
+export interface FrameworkStorageSelectionInput {
+  /** `agent/storage.ts`, when the author wrote one. */
+  readonly authored: StorageDefinition | 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.
+ */
+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;
+}

package/src/internal/inline-stdio-define-stub.ts

@@ -0,0 +1,4 @@
+/** Bundled stand-in for `@anysphere/agent-serve/connections` / `@cursor/july/connections`. */
+export function defineConnection<T>(config: T): T {
+  return config;
+}

package/src/internal/inline-stdio-mcp.ts

@@ -0,0 +1,229 @@
+/**
+ * Generic newline-delimited JSON-RPC stdio MCP server for packaged
+ * `defineConnection({ tools })` modules. Bundled into `node -e` so a
+ * repo-less cloud VM can spawn it. Keep this file free of framework
+ * barrels and the official MCP SDK.
+ */
+
+const PROTOCOL_VERSION = "2025-03-26";
+
+type JsonRpcId = string | number | null;
+
+type JsonRpc = {
+  jsonrpc?: string;
+  id?: JsonRpcId;
+  method?: string;
+  params?: Record<string, unknown>;
+};
+
+type InlineTool = {
+  description: string;
+  inputSchema?: {
+    safeParse?: (value: unknown) => {
+      success: boolean;
+      data?: unknown;
+      error?: { issues?: Array<{ path: unknown[]; message: string }> };
+    };
+  };
+  execute: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+};
+
+export type InlineStdioCatalogEntry = {
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+export type InlineStdioDefinition = {
+  tools?: Record<string, InlineTool>;
+};
+
+function write(message: Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function stringifyResult(result: unknown): string {
+  if (typeof result === "string") {
+    return result;
+  }
+  return JSON.stringify(result);
+}
+
+function isMcpEnvelope(
+  result: unknown
+): result is { content: unknown[]; isError?: boolean } {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    "content" in result &&
+    Array.isArray((result as { content: unknown }).content)
+  );
+}
+
+function validateInput(
+  tool: InlineTool,
+  args: unknown
+):
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; message: string } {
+  const record =
+    typeof args === "object" && args !== null
+      ? (args as Record<string, unknown>)
+      : {};
+  const schema = tool.inputSchema;
+  if (schema === undefined || typeof schema.safeParse !== "function") {
+    return { ok: true, value: record };
+  }
+  const parsed = schema.safeParse(args ?? {});
+  if (parsed.success) {
+    const value =
+      typeof parsed.data === "object" && parsed.data !== null
+        ? (parsed.data as Record<string, unknown>)
+        : record;
+    return { ok: true, value };
+  }
+  const issues = parsed.error?.issues ?? [];
+  const message =
+    issues
+      .map((issue) => {
+        const path = issue.path.join(".");
+        return path === "" ? issue.message : `${path}: ${issue.message}`;
+      })
+      .join("; ") || "invalid input";
+  return { ok: false, message };
+}
+
+async function handle(
+  message: JsonRpc,
+  serverName: string,
+  tools: Record<string, InlineTool>,
+  catalog: Record<string, InlineStdioCatalogEntry>
+): Promise<void> {
+  const method = message.method;
+  if (typeof method !== "string" || !("id" in message)) {
+    return;
+  }
+  const id = message.id;
+  const params =
+    typeof message.params === "object" && message.params !== null
+      ? message.params
+      : {};
+
+  try {
+    if (method === "initialize") {
+      const requested = params.protocolVersion;
+      write({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion:
+            typeof requested === "string" ? requested : PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: serverName, version: "0.1.0" },
+        },
+      });
+      return;
+    }
+    if (method === "ping") {
+      write({ jsonrpc: "2.0", id, result: {} });
+      return;
+    }
+    if (method === "tools/list") {
+      write({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          tools: Object.entries(catalog).map(([name, entry]) => ({
+            name,
+            description: entry.description,
+            inputSchema: entry.inputSchema,
+          })),
+        },
+      });
+      return;
+    }
+    if (method === "tools/call") {
+      const name = params.name;
+      const tool = typeof name === "string" ? tools[name] : undefined;
+      if (tool === undefined) {
+        write({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: `Unknown tool: ${String(name)}` }],
+            isError: true,
+          },
+        });
+        return;
+      }
+      const checked = validateInput(tool, params.arguments);
+      if (!checked.ok) {
+        write({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: checked.message }],
+            isError: true,
+          },
+        });
+        return;
+      }
+      const result = await tool.execute(checked.value);
+      if (isMcpEnvelope(result)) {
+        write({ jsonrpc: "2.0", id, result });
+        return;
+      }
+      write({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: stringifyResult(result) }],
+        },
+      });
+      return;
+    }
+    write({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32601, message: `Method not found: ${method}` },
+    });
+  } catch (error) {
+    write({
+      jsonrpc: "2.0",
+      id,
+      error: {
+        code: -32603,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+export function serveInlineStdioMcp(
+  serverName: string,
+  definition: InlineStdioDefinition,
+  catalog: Record<string, InlineStdioCatalogEntry>
+): void {
+  const tools = definition.tools ?? {};
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).replace(/\r$/, "");
+      buffer = buffer.slice(newline + 1);
+      if (line.length > 0) {
+        try {
+          void handle(JSON.parse(line) as JsonRpc, serverName, tools, catalog);
+        } catch (error) {
+          process.stderr.write(
+            `${serverName}: failed to parse MCP message: ${
+              error instanceof Error ? error.message : String(error)
+            }\n`
+          );
+        }
+      }
+      newline = buffer.indexOf("\n");
+    }
+  });
+}

package/src/internal/package-inline-stdio.ts

@@ -0,0 +1,121 @@
+/**
+ * Package `defineConnection({ tools })` into a `node -e` stdio transport a
+ * repo-less cloud VM can spawn.
+ */
+
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+import type {
+  ConnectionTransport,
+  InlineStdioConnectionConfig,
+  JsonSchemaObject,
+} from "../types.js";
+import type { InlineStdioCatalogEntry } from "./inline-stdio-mcp.js";
+import { toolInputJsonSchema } from "./json-schema.js";
+
+const require = createRequire(import.meta.url);
+
+const CONNECTION_SPECIFIERS = new Set([
+  "@anysphere/agent-serve/connections",
+  "@cursor/july/connections",
+  "@cursor/agentkit/connections",
+]);
+
+function sibling(basename: string): string {
+  const dir = fileURLToPath(new URL(".", import.meta.url));
+  const ts = join(dir, `${basename}.ts`);
+  return existsSync(ts) ? ts : join(dir, `${basename}.js`);
+}
+
+function jsonSchemaCatalog(
+  tools: InlineStdioConnectionConfig["tools"]
+): Record<string, InlineStdioCatalogEntry> {
+  const catalog: Record<string, InlineStdioCatalogEntry> = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    catalog[name] = {
+      description: tool.description,
+      inputSchema: toolInputJsonSchema(tool.inputSchema) as JsonSchemaObject,
+    };
+  }
+  return catalog;
+}
+
+export async function packageInlineStdioConnection(options: {
+  name: string;
+  entryPath: string;
+  tools: InlineStdioConnectionConfig["tools"];
+  absWorkingDir: string;
+}): Promise<ConnectionTransport> {
+  const runtimePath = sibling("inline-stdio-mcp");
+  const stubPath = sibling("inline-stdio-define-stub");
+  const catalog = jsonSchemaCatalog(options.tools);
+  const result = await esbuild.build({
+    entryPoints: ["inline-stdio-entry"],
+    bundle: true,
+    write: false,
+    platform: "node",
+    format: "esm",
+    target: "node22",
+    minify: true,
+    legalComments: "none",
+    absWorkingDir: options.absWorkingDir,
+    alias: {
+      zod: require.resolve("zod"),
+    },
+    plugins: [
+      {
+        name: "inline-stdio-entry",
+        setup(build) {
+          build.onResolve({ filter: /^inline-stdio-entry$/ }, () => ({
+            path: "inline-stdio-entry",
+            namespace: "inline-stdio",
+          }));
+          build.onLoad({ filter: /.*/, namespace: "inline-stdio" }, () => ({
+            contents: `import definition from ${JSON.stringify(options.entryPath)};
+import { serveInlineStdioMcp } from ${JSON.stringify(runtimePath)};
+serveInlineStdioMcp(
+  ${JSON.stringify(options.name)},
+  definition,
+  ${JSON.stringify(catalog)}
+);
+`,
+            resolveDir: dirname(options.entryPath),
+            loader: "ts",
+          }));
+        },
+      },
+      {
+        name: "inline-stdio-connection-stub",
+        setup(build) {
+          build.onResolve({ filter: /.*/ }, (args) => {
+            if (CONNECTION_SPECIFIERS.has(args.path)) {
+              return { path: stubPath };
+            }
+            return undefined;
+          });
+        },
+      },
+    ],
+  });
+
+  const file = result.outputFiles?.[0];
+  if (file === undefined) {
+    throw new Error(
+      `Failed to package inline stdio MCP connection "${options.name}": esbuild produced no output.`
+    );
+  }
+  const source = file.text.replace(/^#!.*\r?\n/, "");
+  if (source.trim() === "") {
+    throw new Error(
+      `Failed to package inline stdio MCP connection "${options.name}": empty bundle.`
+    );
+  }
+  return {
+    type: "stdio",
+    command: "node",
+    args: ["--input-type=module", "-e", source],
+  };
+}

package/src/internal/session-engine.ts

@@ -80,6 +80,7 @@ import {
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
+import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
 import {
@@ -363,11 +364,17 @@ export class SessionEngine {
           `[agent-sdk] failed to persist events for ${sessionId}: ${describeError(error)}`
         )
     );
+    // Framework session state (records, event chunks, continuations) is
+    // mirrored to whatever this selects; see framework-storage-selection.ts
+    // for why the choice does not belong to the agent author.
+    const frameworkStorage = selectFrameworkStorageDefinition({
+      authored: options.project.storage,
+    });
     this.storage =
-      options.project.storage === undefined
+      frameworkStorage === undefined
         ? undefined
         : new StorageCoordinator({
-            definition: options.project.storage,
+            definition: frameworkStorage,
             agentName: options.project.name,
             projectRoot: options.project.rootDir,
             logger: this.logger,

package/src/types.ts

@@ -861,6 +861,18 @@ export function isSymbolicConnectionTransport(
   );
 }
 
+/** One TypeScript tool on `defineConnection({ tools })`. */
+export type InlineStdioToolConfig = {
+  description: string;
+  inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+  execute: (input: JsonObject) => unknown | Promise<unknown>;
+};
+
+/** `defineConnection({ tools })`. TypeScript in; stdio MCP out. */
+export type InlineStdioConnectionConfig = {
+  tools: Record<string, InlineStdioToolConfig>;
+};
+
 /**
  * Authored MCP connection config (`defineConnection(...)`).
  *
@@ -868,6 +880,10 @@ export function isSymbolicConnectionTransport(
  * `["*"]` to forward every connected HTTP/SSE connector; a concrete
  * `string[]` allowlists by connector name. Discovery normalizes the
  * wildcard forms to an unfiltered {@link ConnectionTransport}.
+ *
+ * `{ tools }` authors TypeScript handlers. Discovery packages them into a
+ * stdio MCP server the agent environment can spawn, including a repo-less
+ * cloud VM.
  */
 export type ConnectionConfig = (
   | Exclude<ConnectionTransport, { cursorAccount: true }>
@@ -883,6 +899,7 @@ export type ConnectionConfig = (
        */
       servers?: string[] | "*";
     }
+  | InlineStdioConnectionConfig
 ) & {
   /** Documentation only; shown in `info` output. */
   description?: string;
@@ -894,6 +911,16 @@ export type ConnectionConfig = (
   hostOnly?: boolean;
 };
 
+/** True when the connection authors tools instead of a spawn/URL/peer. */
+export function isInlineStdioConnection(
+  connection: ConnectionConfig
+): connection is InlineStdioConnectionConfig & {
+  description?: string;
+  hostOnly?: boolean;
+} {
+  return "tools" in connection && connection.tools !== undefined;
+}
+
 /**
  * An MCP connection is available to the agent (SDK `mcpServers`), host
  * (`ctx.host.mcp`), and channel/schedule handlers — unless `hostOnly`,