@cursor/july 0.1.2 → 0.1.3

package/src/internal/deploy-client.ts

@@ -27,6 +27,18 @@ export type DeploymentStatus =
   | "stopping"
   | "stopped";
 
+/** Customer-safe deploy progress (no hosting phase / infra names). */
+export type DeploymentProgress =
+  | "queued"
+  | "preparing"
+  | "building"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopping"
+  | "stopped"
+  | "degraded";
+
 export const TERMINAL_DEPLOY_STATUSES: ReadonlySet<DeploymentStatus> = new Set([
   "running",
   "degraded",
@@ -118,6 +130,11 @@ export interface Deployment {
   agentPath?: string;
   desiredState?: string;
   status: DeploymentStatus;
+  /**
+   * Customer-safe deploy progress (no hosting internals). Present on newer
+   * backends; older responses omit it.
+   */
+  progress?: DeploymentProgress;
   generation: number;
   observedGeneration?: number | null;
   engineGeneration?: number | null;
@@ -131,7 +148,8 @@ export interface Deployment {
   cursorEventRepos?: string[];
   /** Normalized egress allowlist for the engine pod. */
   egressAllowedDomains?: string[];
-  serviceAccountId?: number | null;
+  /** Service-account id (`sa_…`); null on legacy rows. */
+  serviceAccountId?: string | number | null;
   /** Masked pod credential; the raw key is never returned. */
   podCredentialMaskedKey?: string | null;
   /** Names of the secrets set on the deployment (values never returned). */
@@ -196,6 +214,19 @@ const deploymentSchema = z.object({
     "stopping",
     "stopped",
   ]),
+  progress: z
+    .enum([
+      "queued",
+      "preparing",
+      "building",
+      "finalizing",
+      "running",
+      "failed",
+      "stopping",
+      "stopped",
+      "degraded",
+    ])
+    .optional(),
   generation: z.number(),
   observedGeneration: z.number().nullable().optional(),
   engineGeneration: z.number().nullable().optional(),
@@ -207,8 +238,9 @@ const deploymentSchema = z.object({
   lastReconciledAt: z.string().nullable().optional(),
   cursorEventRepos: z.array(z.string()).optional(),
   egressAllowedDomains: z.array(z.string()).optional(),
-  // Null on legacy rows that predate service-account-backed deploys.
-  serviceAccountId: z.number().nullable().optional(),
+  // String ids (`sa_…`) in prod; older mocks/fixtures used numbers. Null on
+  // legacy rows that predate service-account-backed deploys.
+  serviceAccountId: z.union([z.string(), z.number()]).nullable().optional(),
   podCredentialMaskedKey: z.string().nullable().optional(),
   secretNames: z.array(z.string()).optional(),
 });
@@ -552,13 +584,22 @@ function mapErrorResponse(
         `${serverError ?? "Not authorized"} — deploying needs team-admin permission and the cloud-agent entitlement on that team.`,
         403
       );
-    case 404:
+    case 404: {
+      // Fastify's route-not-found envelope means we hit the wrong host
+      // (api2 vs api.cursor.com), not a missing deployment / closed gate.
+      if (/Route \S+ not found/i.test(bodyText)) {
+        return new DeployApiError(
+          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
+          404
+        );
+      }
       return new DeployApiError(
         context.slug === undefined
           ? `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`
           : `Deployment${slugPart} was not found — check the slug and --team, or the agent_serve_mvp feature gate may not be enabled for your team.`,
         404
       );
+    }
     case 409:
       return new DeployApiError(
         `A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`,

package/src/internal/deploy-source.ts

@@ -0,0 +1,133 @@
+/**
+ * Infer `agentkit deploy` git source fields from a local checkout.
+ *
+ * From an agent directory inside a git repo with an `origin` remote, the
+ * CLI can fill `--repo` / `--ref` / `--path` so `agentkit deploy` (no
+ * flags) is enough. Explicit flags always win.
+ */
+
+import { execFile } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** Injectable git runner (cwd + args → stdout, or undefined on failure). */
+export type GitRunner = (
+  args: readonly string[],
+  cwd: string
+) => Promise<string | undefined>;
+
+export interface InferredDeploySource {
+  gitRepoUrl?: string;
+  gitRef?: string;
+  /** Agent directory relative to the repo root (posix). Omitted at root. */
+  agentPath?: string;
+}
+
+const defaultGitRunner: GitRunner = async (args, cwd) => {
+  try {
+    const { stdout } = await execFileAsync("git", [...args], { cwd });
+    const trimmed = stdout.trim();
+    return trimmed === "" ? undefined : trimmed;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Normalize a git remote URL to the https form the control plane accepts
+ * (`https://host/owner/repo`, no `.git` suffix). Returns undefined for
+ * unrecognized shapes.
+ */
+export function httpsGitRepoUrlFromRemote(remote: string): string | undefined {
+  let url = remote.trim();
+  if (url === "") {
+    return undefined;
+  }
+  if (url.startsWith("git@")) {
+    // git@host:owner/repo.git → https://host/owner/repo.git
+    url = `https://${url.slice("git@".length).replace(":", "/")}`;
+  } else if (url.startsWith("ssh://git@")) {
+    url = `https://${url.slice("ssh://git@".length)}`;
+  } else if (!/^https?:\/\//i.test(url)) {
+    return undefined;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const path = parsed.pathname
+    .replace(/\.git$/i, "")
+    .replace(/\/+$/, "")
+    .replace(/^\/+/, "");
+  if (path === "" || !path.includes("/")) {
+    return undefined;
+  }
+  // Use hostname (not host) so ssh://git@github.com:22/… does not keep :22.
+  return `https://${parsed.hostname}/${path}`;
+}
+
+/**
+ * Path of `dir` relative to `gitRoot`, using `/` separators. Undefined when
+ * `dir` is outside the root; omitted (undefined) when `dir` *is* the root
+ * so the control plane treats the agent as living at the repo root.
+ */
+export function agentPathRelativeToGitRoot(
+  dir: string,
+  gitRoot: string
+): string | undefined {
+  const absDir = resolve(dir);
+  const absRoot = resolve(gitRoot);
+  const rel = relative(absRoot, absDir);
+  if (rel === "") {
+    return undefined;
+  }
+  // Outside the repo (or a Windows drive mismatch) → cannot infer.
+  if (rel.startsWith("..") || rel.split(sep).includes("..")) {
+    return undefined;
+  }
+  return rel.split(sep).join("/");
+}
+
+/**
+ * Probe the git checkout containing `dir` for deploy source fields.
+ * Missing pieces stay undefined (static deploy / server defaults).
+ */
+export async function inferDeployGitSource(
+  dir: string,
+  options?: { git?: GitRunner }
+): Promise<InferredDeploySource> {
+  const git = options?.git ?? defaultGitRunner;
+  const absDir = resolve(dir);
+
+  const gitRoot = await git(["rev-parse", "--show-toplevel"], absDir);
+  if (gitRoot === undefined) {
+    return {};
+  }
+
+  const remote = await git(["remote", "get-url", "origin"], gitRoot);
+  const gitRepoUrl =
+    remote === undefined ? undefined : httpsGitRepoUrlFromRemote(remote);
+
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], gitRoot);
+  let gitRef: string | undefined;
+  if (branch !== undefined && branch !== "HEAD") {
+    gitRef = branch;
+  } else {
+    // Detached HEAD — pin the exact commit so the control plane still
+    // has something concrete to build.
+    gitRef = await git(["rev-parse", "HEAD"], gitRoot);
+  }
+
+  const agentPath = agentPathRelativeToGitRoot(absDir, gitRoot);
+
+  return {
+    gitRepoUrl,
+    gitRef,
+    agentPath,
+  };
+}

package/src/internal/discovery.ts

@@ -61,6 +61,7 @@ import {
 } from "./hosting.js";
 import { toolInputJsonSchema } from "./json-schema.js";
 import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
+import { withIdentityPreamble } from "./workspace.js";
 
 const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
 const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -105,23 +106,26 @@ export async function isAgentProjectDir(dir: string): Promise<boolean> {
   return hasFlatLayoutMarkers(resolved);
 }
 
+/** One immediate child agent directory under a multi-agent parent. */
+export interface ChildAgentDir {
+  slug: string;
+  dir: string;
+}
+
 /**
- * Discover the agent projects directly under `rootDir` (one level deep):
- * each immediate child directory that is itself an agent project becomes a
- * mounted agent, keyed by a slug derived from its directory name. Used for
- * multi-agent serving, where one server hosts many agents under
- * `/<slug>/...`. Throws when no child projects are found.
+ * List agent projects directly under `rootDir` (one level deep) without
+ * loading them. Empty when the path is missing or has no child agents.
+ * Slug rules match {@link loadAgentProjects} / multi-agent serve.
  */
-export async function loadAgentProjects(
-  rootDir: string,
-  options: LoadAgentProjectOptions = {}
-): Promise<Array<{ slug: string; project: AgentProject }>> {
+export async function listChildAgentDirs(
+  rootDir: string
+): Promise<ChildAgentDir[]> {
   const resolved = resolve(rootDir);
   if (!(await isDirectory(resolved))) {
-    throw new Error(`Agent projects directory does not exist: ${resolved}`);
+    return [];
   }
 
-  const results: Array<{ slug: string; project: AgentProject }> = [];
+  const results: ChildAgentDir[] = [];
   const seenSlugs = new Set<string>();
   for (const entry of await sortedEntries(resolved)) {
     if (!entry.isDirectory() || entry.name.startsWith(".")) {
@@ -139,14 +143,40 @@ export async function loadAgentProjects(
       throw new Error(`Duplicate agent slug "${slug}" under ${resolved}.`);
     }
     seenSlugs.add(slug);
-    results.push({ slug, project: await loadAgentProject(childDir, options) });
+    results.push({ slug, dir: childDir });
+  }
+  return results;
+}
+
+/**
+ * Discover the agent projects directly under `rootDir` (one level deep):
+ * each immediate child directory that is itself an agent project becomes a
+ * mounted agent, keyed by a slug derived from its directory name. Used for
+ * multi-agent serving, where one server hosts many agents under
+ * `/<slug>/...`. Throws when no child projects are found.
+ */
+export async function loadAgentProjects(
+  rootDir: string,
+  options: LoadAgentProjectOptions = {}
+): Promise<Array<{ slug: string; project: AgentProject }>> {
+  const resolved = resolve(rootDir);
+  if (!(await isDirectory(resolved))) {
+    throw new Error(`Agent projects directory does not exist: ${resolved}`);
   }
 
-  if (results.length === 0) {
+  const children = await listChildAgentDirs(resolved);
+  if (children.length === 0) {
     throw new Error(
       `No agent projects found directly under ${resolved}. Each agent should be a subdirectory with its own agent/ directory (or flat-layout markers).`
     );
   }
+  const results: Array<{ slug: string; project: AgentProject }> = [];
+  for (const child of children) {
+    results.push({
+      slug: child.slug,
+      project: await loadAgentProject(child.dir, options),
+    });
+  }
   return results;
 }
 
@@ -287,12 +317,19 @@ async function loadAgent(
   options: { name: string; isRoot: boolean }
 ): Promise<ResolvedAgent> {
   const config = await loadAgentConfig(ctx, agentDir, options.isRoot);
-  const instructions = await loadInstructions(
+  const name = config?.name ?? options.name;
+  const authoredInstructions = await loadInstructions(
     ctx,
     agentDir,
     config,
     options.isRoot
   );
+  // Root agents without authored instructions stay undefined (diagnostic
+  // already recorded). Subagents still get the identity line alone.
+  const instructions =
+    authoredInstructions === undefined && options.isRoot
+      ? undefined
+      : withIdentityPreamble(name, authoredInstructions);
 
   // Subagents run as Cursor SDK custom subagents (prompt + description +
   // model); their other slots are inert today, so don't load them — just
@@ -300,7 +337,7 @@ async function loadAgent(
   if (!options.isRoot) {
     await warnUnsupportedSubagentSlots(ctx, agentDir);
     return {
-      name: config?.name ?? options.name,
+      name,
       ...(config?.description === undefined
         ? {}
         : { description: config.description }),
@@ -347,7 +384,7 @@ async function loadAgent(
   }
 
   return {
-    name: config?.name ?? options.name,
+    name,
     description: config?.description,
     // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
     model: isValidModelSetting(config?.model) ? config.model : DEFAULT_MODEL,

package/src/internal/eval-run-store.ts

@@ -400,7 +400,8 @@ export class EvalRunStore {
           }
           if (
             event.type === "message.completed" &&
-            typeof event.data?.text === "string"
+            typeof event.data?.text === "string" &&
+            event.data.parentCallId === undefined
           ) {
             c.finalText = event.data.text;
           }

package/src/internal/eval-runner.ts

@@ -76,6 +76,8 @@ export interface RunEvalsOptions extends EvalSelectionOptions {
   baseUrl: string;
   timeoutMs?: number;
   bearerToken?: string;
+  /** Extra request headers (e.g. hosted engineAccess). */
+  headers?: Record<string, string>;
   verbose?: boolean;
   onEvent?: (event: SessionEvent) => void;
   /** Fired when a case begins executing (after concurrency slot acquired). */
@@ -240,6 +242,7 @@ export async function runDiscoveredEvals(
       baseUrl: options.baseUrl,
       defaultTimeoutMs,
       bearerToken: options.bearerToken,
+      headers: options.headers,
       verbose: Boolean(options.verbose),
       onEvent: (event) => {
         options.onCaseEvent?.(discovered.id, event);
@@ -268,6 +271,7 @@ async function runOneEval(
     baseUrl: string;
     defaultTimeoutMs: number;
     bearerToken?: string;
+    headers?: Record<string, string>;
     verbose: boolean;
     onEvent?: (event: SessionEvent) => void;
   }
@@ -330,6 +334,7 @@ async function runOneEval(
         // Keep defineEval traffic out of live defineAB enrollment/metrics.
         purpose: "eval",
         bearerToken: opts.bearerToken,
+        headers: opts.headers,
         workspaceDir: options.workspaceDir,
         workspaceFiles: options.workspaceFiles,
         timeoutMs,