@cursor/july 0.1.62 → 0.1.68

package/src/internal/init-project.ts

@@ -3,10 +3,16 @@
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import type { ModelSetting } from "../types.js";
+import {
+  canonicalTemplateName,
+  isTemplateName,
+  readCursorAgentTemplate,
+  type TemplateName,
+} from "./cursor-agent-template.js";
 import {
   CLI_COMMAND_NAME,
   PACKAGE_NAME,
@@ -64,7 +70,7 @@ type TemplateEntry = {
   overlay?: string;
 };
 
-const TEMPLATES: Readonly<Record<string, TemplateEntry>> = {
+const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agentic-owners": { dir: "agentic-owners" },
   demo: { dir: "demo" },
   "pr-autofixer": { dir: "pr-autofixer" },
@@ -73,10 +79,6 @@ const TEMPLATES: Readonly<Record<string, TemplateEntry>> = {
   "triage-jira": { dir: "triage", overlay: "jira" },
 };
 
-function canonicalTemplateName(name: string): string {
-  return name === "triage" ? "triage-linear" : name;
-}
-
 export function availableTemplates(): string[] {
   return Object.keys(TEMPLATES).sort();
 }
@@ -93,13 +95,13 @@ export function resolveTemplate(name: string): TemplateResolution {
     };
   }
   const resolved = canonicalTemplateName(name);
-  const entry = TEMPLATES[resolved];
-  if (entry === undefined) {
+  if (!isTemplateName(resolved)) {
     return {
       ok: false,
       message: `unknown template "${name}" (available: ${availableTemplates().join(", ")})`,
     };
   }
+  const entry = TEMPLATES[resolved];
   const dir = join(packageRootDir(), "templates", entry.dir);
   return {
     ok: true,
@@ -128,18 +130,7 @@ export function checkInitTarget(
   if (!existsSync(pkgPath)) {
     return { ok: true };
   }
-  let marker: string | undefined;
-  try {
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
-      cursorAgentTemplate?: unknown;
-    };
-    marker =
-      typeof pkg.cursorAgentTemplate === "string"
-        ? pkg.cursorAgentTemplate
-        : undefined;
-  } catch {
-    marker = undefined;
-  }
+  const marker = readCursorAgentTemplate(rootDir);
   if (marker === template) {
     return { ok: true };
   }

package/src/internal/mcp-host.ts

@@ -29,6 +29,18 @@ interface OpenedConnection {
   close: () => Promise<void>;
 }
 
+/**
+ * A non-caching view of one connection: every operation opens a fresh
+ * client and closes it afterwards. See {@link McpHost.oneOff}.
+ */
+export interface HostMcpOneOff {
+  listTools(): Promise<HostMcpToolInfo[]>;
+  callTool(
+    toolName: string,
+    args?: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+}
+
 export class McpHost implements HostMcpRegistry {
   private readonly byName = new Map<string, DiscoveredConnection>();
   private readonly clients = new Map<string, Promise<OpenedConnection>>();
@@ -54,18 +66,47 @@ export class McpHost implements HostMcpRegistry {
   async listTools(connectionName: string): Promise<HostMcpToolInfo[]> {
     return this.withClient(connectionName, async (client) => {
       const listed = await client.listTools();
-      return listed.tools.map((tool) => ({
-        name: tool.name,
-        ...(tool.description === undefined
-          ? {}
-          : { description: tool.description }),
-        ...(tool.inputSchema === undefined
-          ? {}
-          : { inputSchema: tool.inputSchema as JsonObject }),
-      }));
+      return listed.tools.map(toToolInfo);
     });
   }
 
+  /**
+   * A one-off view of a connection that is not (or not exactly) in the
+   * registry — e.g. a registered connection with per-session auth headers
+   * substituted in. Every operation opens a fresh client and closes it
+   * afterwards: the registry's cached per-name client would leak one
+   * session's identity into another, and stateless streamable-HTTP
+   * servers answer a fresh initialize cheaply. Results ride the same
+   * mapping as registry calls.
+   */
+  oneOff(connection: DiscoveredConnection): HostMcpOneOff {
+    const withFreshClient = async <T>(
+      run: (client: Client) => Promise<T>
+    ): Promise<T> => {
+      const opened = await openConnection(connection);
+      try {
+        return await run(opened.client);
+      } finally {
+        await opened.close();
+      }
+    };
+    return {
+      listTools: () =>
+        withFreshClient(async (client) => {
+          const listed = await client.listTools();
+          return listed.tools.map(toToolInfo);
+        }),
+      callTool: (toolName, args = {}) =>
+        withFreshClient(async (client) => {
+          const result = await client.callTool({
+            name: toolName,
+            arguments: args,
+          });
+          return normalizeCallResult(result);
+        }),
+    };
+  }
+
   async callTool(
     connectionName: string,
     toolName: string,
@@ -172,6 +213,22 @@ export function isStaleMcpSessionError(error: unknown): boolean {
   return code === 404;
 }
 
+function toToolInfo(tool: {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}): HostMcpToolInfo {
+  return {
+    name: tool.name,
+    ...(tool.description === undefined
+      ? {}
+      : { description: tool.description }),
+    ...(tool.inputSchema === undefined
+      ? {}
+      : { inputSchema: tool.inputSchema as JsonObject }),
+  };
+}
+
 async function openConnection(
   connection: DiscoveredConnection
 ): Promise<OpenedConnection> {

package/src/internal/sdk-runner.ts

@@ -55,6 +55,7 @@ export type RunnerPrewarmRequest = Pick<
   | "sandbox"
   | "tools"
   | "mcpServers"
+  | "perSendMcpServers"
   | "subagents"
   | "model"
 >;
@@ -159,6 +160,28 @@ export function isAuthErrorMessage(message: string | undefined): boolean {
   return /authentication error|try logging out and back in/i.test(message);
 }
 
+/** Cloud `wait()` copy for `stream_expired` / a missing start-state blob. */
+function isStreamExpiredErrorMessage(message: string | undefined): boolean {
+  if (message === undefined) {
+    return false;
+  }
+  return /run stream is no longer available|\[stream_expired\]/i.test(message);
+}
+
+function retryReason(
+  message: string | undefined,
+  isFirstTurn: boolean
+): string | undefined {
+  if (isStreamExpiredErrorMessage(message)) {
+    return "cloud run stream expired";
+  }
+  // First-turn auth is the credential; a fresh handle cannot fix it.
+  if (!isFirstTurn && isAuthErrorMessage(message)) {
+    return "authentication failure";
+  }
+  return undefined;
+}
+
 export class CursorSdkRunner implements AgentRunner {
   private readonly agents = new Map<string, CachedAgentHandle>();
   private readonly stores = new Map<string, Promise<LocalAgentStore>>();
@@ -187,26 +210,23 @@ export class CursorSdkRunner implements AgentRunner {
     const outcome = await this.runTurnAttempt(tracked);
     if (
       outcome.status !== "error" ||
-      !isAuthErrorMessage(outcome.errorMessage) ||
       sawUpdate ||
-      request.isFirstTurn ||
       request.signal?.aborted === true
     ) {
       return outcome;
     }
-    // The turn died on an authentication failure before producing any output
-    // — the signature of a handle whose exchanged access token expired (the
-    // failed attempt already evicted it). Retrying once on a fresh handle is
-    // safe here because nothing streamed and no tool ran. First turns are
-    // excluded: their token was exchanged moments ago, so the credential
-    // itself is the problem and a retry cannot succeed.
+    const reason = retryReason(outcome.errorMessage, request.isFirstTurn);
+    if (reason === undefined) {
+      return outcome;
+    }
+    // Log the original error even when the retry succeeds so the expiry
+    // still shows up in Datadog.
     this.log(
-      `[agent-sdk] session ${request.sessionId}: retrying the turn on a fresh SDK agent handle after an authentication failure`
+      `[agent-sdk] session ${request.sessionId}: ${reason}: ${outcome.errorMessage}; retrying the turn`
     );
     try {
       return await this.runTurnAttempt(tracked);
     } catch {
-      // The retry was best effort; report the original failure.
       return outcome;
     }
   }
@@ -235,6 +255,12 @@ export class CursorSdkRunner implements AgentRunner {
             // Stream mapping must never reject into the SDK transport.
           }
         },
+        // The SDK builds this send's MCP session from exactly this set, so
+        // a turn always runs on the headers the engine evaluated for it —
+        // never on the ones a previous turn opened the cached handle with.
+        ...(request.runtime === "local" && request.perSendMcpServers === true
+          ? { mcpServers: request.mcpServers as AgentOptions["mcpServers"] }
+          : {}),
         ...(request.runtime === "local"
           ? {
               local: {
@@ -270,6 +296,14 @@ export class CursorSdkRunner implements AgentRunner {
       if (request.onSdkAgentId !== undefined) {
         await request.onSdkAgentId(agent.agentId);
       }
+      // Readable on the handle as soon as send resolves, long before wait().
+      if (
+        request.onRequestId !== undefined &&
+        run.requestId !== undefined &&
+        run.requestId !== ""
+      ) {
+        await request.onRequestId(run.requestId);
+      }
       try {
         const result = await run.wait();
         let outcome = toTurnOutcome(result);
@@ -401,7 +435,12 @@ export class CursorSdkRunner implements AgentRunner {
     return {
       model: toModelSelection(request.model ?? DEFAULT_MODEL),
       apiKey: this.requireApiKey(),
-      ...(Object.keys(request.mcpServers).length > 0
+      // Per-send servers ride each agent.send instead (fresh per-session
+      // auth headers every turn). Keeping them out of the create/resume
+      // options also keeps the local executor cache key — which hashes
+      // these options — stable while credentials rotate.
+      ...(Object.keys(request.mcpServers).length > 0 &&
+      request.perSendMcpServers !== true
         ? { mcpServers: request.mcpServers as AgentOptions["mcpServers"] }
         : {}),
       ...(subagents === undefined ? {} : { agents: subagents }),

package/src/internal/server.ts

@@ -70,12 +70,14 @@ import {
   scmEventToGitHubPayload,
   scmMetadataToOriginPayload,
 } from "./cursor-event-relay.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import {
   type CursorSlackAgentRegistration,
   CursorSlackRelay,
   createCursorSlackApiCaller,
   formatCursorSlackEventLog,
 } from "./cursor-slack-relay.js";
+import { buildAgentDeployManifest } from "./deploy-manifest.js";
 import {
   formatDiagnostics,
   hasErrorDiagnostics,
@@ -1111,6 +1113,23 @@ function mountAgentRoutes(
     handler: () => jsonResponse(projectInfo(project)),
   });
 
+  // Hosted-only: the control plane's provision flow reads the deploy manifest
+  // from the running engine (same derivation as `july manifest`) right after
+  // the health probe, so every deploy surface — CLI, UI, redeploy — gets its
+  // declarations from the installed code without a client-side extraction
+  // step. `auth: "none"` mirrors `/v1/health`: hosted engines are reachable
+  // only through the anyrun port proxy (network token) or the alias route
+  // (alias token), and the route is not registered outside hosted mode, so
+  // self-hosted `july serve` never exposes the manifest unauthenticated.
+  if (process.env[AGENT_SERVE_GENERATION_ENV_VAR] !== undefined) {
+    router.add({
+      method: "GET",
+      pattern: `${base}/v1/manifest`,
+      auth: "none",
+      handler: () => jsonResponse(buildAgentDeployManifest(project)),
+    });
+  }
+
   // Playground Logs tab: recent ServeOptions.logger lines (channels, sessions,
   // webhook capture). `after` is an exclusive index cursor for polling.
   router.add({