@cursor/july 0.1.1 → 0.1.3

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

@@ -19,8 +19,10 @@ import {
 import { pathToFileURL } from "node:url";
 import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
 import { httpChannel } from "../channels.js";
+import type { StorageDefinition } from "../storage.js";
 import {
   type AgentConfigDefinition,
+  type AgentHostingOptions,
   type AgentProject,
   type AgentProjectInfo,
   type ChannelDefinition,
@@ -51,8 +53,15 @@ import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
 import { getDefinitionKind } from "./brand.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
+import {
+  isReservedSecretName,
+  MAX_EGRESS_DOMAINS,
+  validateEgressDomain,
+  validateSecretName,
+} 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_-]*$/;
@@ -97,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(".")) {
@@ -131,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;
+}
 
-  if (results.length === 0) {
+/**
+ * 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}`);
+  }
+
+  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;
 }
 
@@ -233,6 +271,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);
 
   if (agentDir !== rootDir) {
     await warnUnknownSlots(ctx, agentDir);
@@ -248,7 +287,8 @@ export async function loadAgentProject(
     schedules,
     hooks,
     abs,
-    ...(abConfig === undefined ? {} : { abConfig }),
+    abConfig,
+    storage,
     diagnostics,
   };
 }
@@ -277,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
@@ -290,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 }),
@@ -324,6 +371,7 @@ async function loadAgent(
       : {
           cwd: localCwd,
         };
+  const hosting = resolveHosting(ctx, agentDir, config?.hosting);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -336,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,
@@ -344,6 +392,7 @@ async function loadAgent(
     runtime,
     cloud,
     local,
+    hosting,
     tools,
     skills,
     connections,
@@ -367,6 +416,59 @@ function resolveAgentCwd(
   return isAbsolute(trimmed) ? trimmed : resolve(ctx.rootDir, trimmed);
 }
 
+/**
+ * Validate the authored `hosting` block against the same grammar the
+ * backend enforces on deploy. Violations are warning diagnostics (reported
+ * by `agentkit validate`), not hard failures: the backend stays
+ * authoritative and `agentkit deploy` re-checks before any network call.
+ */
+function resolveHosting(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  hosting: AgentHostingOptions | undefined
+): AgentHostingOptions | undefined {
+  if (hosting === undefined) {
+    return undefined;
+  }
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  const warn = (message: string): void => {
+    ctx.diagnostics.push({ severity: "warning", path: agentPath, message });
+  };
+
+  const egressDomains = hosting.egressDomains ?? [];
+  for (const domain of egressDomains) {
+    const domainError = validateEgressDomain(domain);
+    if (domainError !== undefined) {
+      warn(`hosting.egressDomains: ${domainError}`);
+    }
+  }
+  if (egressDomains.length > MAX_EGRESS_DOMAINS) {
+    warn(
+      `hosting.egressDomains lists ${egressDomains.length} domains; deploys are capped at ${MAX_EGRESS_DOMAINS}.`
+    );
+  }
+
+  for (const name of hosting.secretNames ?? []) {
+    const nameError = validateSecretName(name);
+    if (nameError !== undefined) {
+      warn(`hosting.secretNames: ${nameError}`);
+    } else if (isReservedSecretName(name)) {
+      warn(
+        `hosting.secretNames: ${JSON.stringify(name)} is platform-reserved (CURSOR_*) and injected automatically; it cannot be set with \`secrets set\`.`
+      );
+    }
+  }
+
+  return {
+    ...(hosting.egressDomains === undefined
+      ? {}
+      : { egressDomains: [...hosting.egressDomains] }),
+    ...(hosting.secretNames === undefined
+      ? {}
+      : { secretNames: [...hosting.secretNames] }),
+  };
+}
+
 async function loadAgentConfig(
   ctx: DiscoveryContext,
   agentDir: string,
@@ -1323,6 +1425,22 @@ async function loadABConfig(
   }
 }
 
+// ============================================================================
+// Storage (agent/storage.ts)
+// ============================================================================
+
+async function loadStorage(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<StorageDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "storage");
+  if (path === undefined) {
+    return undefined;
+  }
+  const definition = await importDefault(ctx, path, "storage");
+  return definition as StorageDefinition | undefined;
+}
+
 function resolveABName(definition: unknown, fallback: string): string {
   if (
     typeof definition === "object" &&
@@ -1410,6 +1528,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
     cloud:
       agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
     local: agent.local,
+    hosting: agent.hosting,
     mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
     instructions:
       agent.instructions === undefined
@@ -1496,6 +1615,10 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
             durableSnapshots: project.abConfig?.persistSnapshots !== undefined,
           },
         }),
+    storage:
+      project.storage === undefined
+        ? undefined
+        : { name: project.storage.name },
     diagnostics: project.diagnostics,
   };
 }
@@ -1515,6 +1638,7 @@ async function importDefault(
     | "schedule"
     | "hook"
     | "ab"
+    | "storage"
 ): Promise<unknown> {
   let mod: Record<string, unknown>;
   try {

package/src/internal/distribution.ts

@@ -94,4 +94,5 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["hooks", "hooks.js"],
   ["evals", "evals.js"],
   ["ab", "ab.js"],
+  ["storage", "storage.js"],
 ];

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

@@ -62,9 +62,21 @@ export class EvalRunStore {
 
   constructor(
     private readonly projectRoot: string,
-    private readonly logger: (line: string) => void
+    private readonly logger: (line: string) => void,
+    /**
+     * Project-wide sink from `agent/storage.ts` (`defineStorage`),
+     * used when `evals.config.ts` sets no `persistRuns` of its own.
+     */
+    private readonly fallbackPersistence?: EvalRunPersistence
   ) {}
 
+  /** `evals.config.ts` `persistRuns` wins; `defineStorage` is fallback. */
+  private resolvePersist(
+    config: Partial<EvalConfigFile>
+  ): EvalRunPersistence | undefined {
+    return config.persistRuns ?? this.fallbackPersistence;
+  }
+
   async list(): Promise<{
     evals: Array<{
       id: string;
@@ -74,7 +86,7 @@ export class EvalRunStore {
     }>;
     config: EvalListConfig;
   }> {
-    await this.ensureHydrated();
+    await this.hydrate();
     const { evals, config } = await discoverEvals(this.projectRoot);
     return {
       evals: evals.map((e) => ({
@@ -85,18 +97,21 @@ export class EvalRunStore {
           : { description: e.definition.description }),
         ...(e.definition.tags === undefined ? {} : { tags: e.definition.tags }),
       })),
-      config: snapshotListConfig(config),
+      config: snapshotListConfig(
+        config,
+        this.resolvePersist(config) !== undefined
+      ),
     };
   }
 
   async get(runId: string): Promise<EvalRunSnapshot | undefined> {
-    await this.ensureHydrated();
+    await this.hydrate();
     return this.runs.get(runId);
   }
 
   /** Newest-first snapshots for playground rehydrate after navigation/reload. */
   async listRuns(): Promise<EvalRunSnapshot[]> {
-    await this.ensureHydrated();
+    await this.hydrate();
     return this.sortedRuns();
   }
 
@@ -109,7 +124,7 @@ export class EvalRunStore {
     runs: EvalRunSnapshot[];
     activeRunId?: string;
   }> {
-    await this.ensureHydrated();
+    await this.hydrate();
     const activeRunId = this.activeRunId;
     return {
       runs: this.sortedRuns(),
@@ -122,7 +137,7 @@ export class EvalRunStore {
   }
 
   async start(input: StartEvalRunInput = {}): Promise<EvalRunSnapshot> {
-    await this.ensureHydrated();
+    await this.hydrate();
     if (this.activeRunId !== undefined) {
       const active = this.runs.get(this.activeRunId);
       if (active !== undefined && active.status === "running") {
@@ -160,12 +175,15 @@ export class EvalRunStore {
         done: 0,
       },
       cases,
-      config: snapshotRunConfig(config),
+      config: snapshotRunConfig(
+        config,
+        this.resolvePersist(config) !== undefined
+      ),
     };
     this.runs.set(runId, snapshot);
     this.activeRunId = runId;
     await this.pruneOldRuns(config);
-    await this.enqueuePersist(snapshot, config.persistRuns);
+    await this.enqueuePersist(snapshot, this.resolvePersist(config));
     this.logger(
       `[agent-serve] eval run ${runId}: starting ${cases.length} case(s)`
     );
@@ -189,7 +207,14 @@ export class EvalRunStore {
     );
   }
 
-  private async ensureHydrated(): Promise<void> {
+  /**
+   * Hydrate playground eval history from durable persistence
+   * (`evals.config.ts` `persistRuns`, else the `defineStorage`
+   * fallback). Called eagerly from the serve startup restore step —
+   * alongside session restore — and lazily as a safety net by every read.
+   * Idempotent; concurrent callers share one pass.
+   */
+  async hydrate(): Promise<void> {
     if (this.hydrated) {
       return;
     }
@@ -202,7 +227,7 @@ export class EvalRunStore {
   private async hydrateFromPersistence(): Promise<void> {
     try {
       const { config } = await discoverEvals(this.projectRoot);
-      const persist = config.persistRuns;
+      const persist = this.resolvePersist(config);
       if (persist === undefined) {
         this.hydrated = true;
         return;
@@ -260,7 +285,7 @@ export class EvalRunStore {
         continue;
       }
       this.runs.delete(stale.runId);
-      await this.persistDelete(stale.runId, config.persistRuns);
+      await this.persistDelete(stale.runId, this.resolvePersist(config));
     }
   }
 
@@ -375,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;
           }
@@ -384,7 +410,7 @@ export class EvalRunStore {
           this.applyCaseResult(runId, result);
           const run = this.runs.get(runId);
           if (run !== undefined) {
-            void this.enqueuePersist(run, opts.config.persistRuns);
+            void this.enqueuePersist(run, this.resolvePersist(opts.config));
           }
         },
       });
@@ -394,7 +420,7 @@ export class EvalRunStore {
       }
       run.status = "completed";
       run.finishedAt = new Date().toISOString();
-      await this.enqueuePersist(run, opts.config.persistRuns);
+      await this.enqueuePersist(run, this.resolvePersist(opts.config));
       this.logger(
         `[agent-serve] eval run ${runId}: done — ${run.summary.passed} passed, ${run.summary.failed} failed`
       );
@@ -406,7 +432,7 @@ export class EvalRunStore {
       run.status = "failed";
       run.finishedAt = new Date().toISOString();
       run.error = error instanceof Error ? error.message : String(error);
-      await this.enqueuePersist(run, opts.config.persistRuns);
+      await this.enqueuePersist(run, this.resolvePersist(opts.config));
       this.logger(`[agent-serve] eval run ${runId}: failed — ${run.error}`);
     } finally {
       if (this.activeRunId === runId) {
@@ -467,21 +493,25 @@ function markInterruptedRun(run: EvalRunSnapshot): void {
   }
 }
 
-function snapshotListConfig(config: Partial<EvalConfigFile>): EvalListConfig {
+function snapshotListConfig(
+  config: Partial<EvalConfigFile>,
+  durableRuns: boolean
+): EvalListConfig {
   return {
     ...(config.maxConcurrency === undefined
       ? {}
       : { maxConcurrency: config.maxConcurrency }),
     ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
     maxPlaygroundRuns: resolveEvalMaxPlaygroundRuns(config.maxPlaygroundRuns),
-    durableRuns: config.persistRuns !== undefined,
+    durableRuns,
   };
 }
 
 function snapshotRunConfig(
-  config: Partial<EvalConfigFile>
+  config: Partial<EvalConfigFile>,
+  durableRuns: boolean
 ): EvalRunSnapshot["config"] {
-  const list = snapshotListConfig(config);
+  const list = snapshotListConfig(config, durableRuns);
   return {
     ...(list.maxConcurrency === undefined
       ? {}

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,