@cursor/july 0.1.24 → 0.1.26

package/src/internal/discovery.hosting.test.ts

@@ -0,0 +1,80 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import type { AgentHostingOptions } from "../types.js";
+import { loadAgentProject, projectInfo } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function loadWithHosting(hosting: AgentHostingOptions) {
+  const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-hosting-disc-"));
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "hi\n");
+  return loadAgentProject(rootDir, {
+    importModule: async () => ({
+      default: defineAgent({ model: "composer-2.5", hosting }),
+    }),
+  });
+}
+
+describe("loadAgentProject hosting", () => {
+  it("resolves the hosting block and surfaces it in projectInfo", async () => {
+    const project = await loadWithHosting({
+      egressDomains: ["api.example.com", "*.internal.example.com"],
+      secretNames: ["OPENAI_API_KEY"],
+    });
+    expect(project.diagnostics).toEqual([]);
+    expect(project.agent.hosting).toEqual({
+      egressDomains: ["api.example.com", "*.internal.example.com"],
+      secretNames: ["OPENAI_API_KEY"],
+    });
+    expect(projectInfo(project).hosting).toEqual(project.agent.hosting);
+  });
+
+  it("emits warning diagnostics (not errors) for grammar violations", async () => {
+    const project = await loadWithHosting({
+      // Uppercase, single-label, numeric TLD, double wildcard: all invalid.
+      egressDomains: ["API.example.com", "localhost", "a.b.123", "*.*.x.com"],
+      secretNames: ["lower_case", "CURSOR_API_KEY", "A".repeat(65)],
+    });
+    const warnings = project.diagnostics.filter(
+      (d) => d.severity === "warning"
+    );
+    expect(project.diagnostics).toHaveLength(warnings.length);
+    const messages = warnings.map((d) => d.message).join("\n");
+    expect(messages).toContain('Invalid egress domain "API.example.com"');
+    expect(messages).toContain('Invalid egress domain "localhost"');
+    expect(messages).toContain('Invalid egress domain "a.b.123"');
+    expect(messages).toContain('Invalid egress domain "*.*.x.com"');
+    expect(messages).toContain('Invalid secret name "lower_case"');
+    expect(messages).toContain("platform-managed");
+    expect(messages).toContain("too long");
+    // Invalid entries are still kept — the backend stays authoritative.
+    expect(project.agent.hosting?.egressDomains).toHaveLength(4);
+  });
+
+  it("warns when egressDomains exceeds the deploy cap", async () => {
+    const project = await loadWithHosting({
+      egressDomains: Array.from(
+        { length: 21 },
+        (_, i) => `svc${i}.example.com`
+      ),
+    });
+    expect(
+      project.diagnostics.some(
+        (d) => d.severity === "warning" && d.message.includes("capped at 20")
+      )
+    ).toBe(true);
+  });
+});

package/src/internal/discovery.identity.test.ts

@@ -0,0 +1,44 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineAgent } from "../index.js";
+import { loadAgentProject } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+describe("loadAgentProject identity preamble", () => {
+  it("prepends the resolved name into instructions", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-identity-"));
+    cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+    const agentDir = join(rootDir, "agent");
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+    await writeFile(
+      join(agentDir, "instructions.md"),
+      "Be brief and specific.\n"
+    );
+
+    const project = await loadAgentProject(rootDir, {
+      importModule: async () => ({
+        default: defineAgent({
+          name: "Benny",
+          model: "composer-2.5",
+        }),
+      }),
+    });
+
+    expect(project.agent.instructions).toBe(
+      [
+        "You are Benny. That is your name; use it when people ask who you are.",
+        "Be brief and specific.",
+      ].join("\n\n")
+    );
+  });
+});

package/src/internal/discovery.ts

@@ -18,6 +18,7 @@ import {
 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
+import { resolveArtifactsMax } from "../artifacts.js";
 import { httpChannel } from "../channels.js";
 import type { StorageDefinition } from "../storage.js";
 import {
@@ -27,6 +28,7 @@ import {
   type AgentProject,
   type AgentProjectInfo,
   type AgentRuntime,
+  type ArtifactsDefinition,
   type BuiltinToolsConfig,
   type ChannelDefinition,
   type ConnectionDefinition,
@@ -58,7 +60,11 @@ import {
 import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
 import { normalizePositiveInt } from "./bounded-int.js";
 import { getDefinitionKind } from "./brand.js";
-import { builtinTools } from "./builtin-tools/index.js";
+import {
+  artifactBuiltinTool,
+  builtinTools,
+  TAG_ARTIFACT_TOOL_NAME,
+} from "./builtin-tools/index.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import {
@@ -280,6 +286,8 @@ export async function loadAgentProject(
   const abs = await loadABs(ctx, agentDir);
   const abConfig = await loadABConfig(ctx, agentDir);
   const storage = await loadStorage(ctx, agentDir);
+  const artifacts = await loadArtifacts(ctx, agentDir);
+  await appendArtifactTool(ctx, agentDir, agent, artifacts);
 
   if (agentDir !== rootDir) {
     await warnUnknownSlots(ctx, agentDir);
@@ -297,6 +305,7 @@ export async function loadAgentProject(
     abs,
     abConfig,
     storage,
+    artifacts,
     diagnostics,
   };
 }
@@ -351,6 +360,14 @@ async function loadAgent(
         message: "builtinTools is not supported on subagents; ignoring.",
       });
     }
+    const artifactsPath = await findModuleFile(agentDir, "artifacts");
+    if (artifactsPath !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, artifactsPath),
+        message: "artifacts are not supported on subagents; ignoring.",
+      });
+    }
     return {
       name,
       ...(config?.description === undefined
@@ -1579,6 +1596,81 @@ async function loadStorage(
   return definition as StorageDefinition | undefined;
 }
 
+// ============================================================================
+// Artifacts (agent/artifacts.ts)
+// ============================================================================
+
+async function loadArtifacts(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<ArtifactsDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "artifacts");
+  if (path === undefined) {
+    return undefined;
+  }
+  const imported = await importDefault(ctx, path, "artifacts");
+  if (imported === undefined) {
+    return undefined;
+  }
+  const definition = imported as ArtifactsDefinition;
+  if (
+    definition.agentTool === true &&
+    Object.keys(definition.kinds ?? {}).length === 0
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        "artifacts.agentTool requires kinds: the tag_artifact tool needs at least one declared kind; its descriptions are the tool prompt.",
+    });
+  }
+  return definition;
+}
+
+/**
+ * Materialize the `tag_artifact` built-in when `defineArtifacts` set
+ * `agentTool: true`. Appended after `loadAgent` because the tool is
+ * generated from the artifacts kinds registry, not `AgentConfig.builtinTools`.
+ */
+async function appendArtifactTool(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  agent: ResolvedAgent,
+  artifacts: ArtifactsDefinition | undefined
+): Promise<void> {
+  const tool = artifactBuiltinTool(artifacts);
+  if (tool === undefined) {
+    return;
+  }
+  const artifactsPath = displayPath(
+    ctx,
+    (await findModuleFile(agentDir, "artifacts")) ??
+      join(agentDir, "artifacts.ts")
+  );
+  // TODO(artifacts-cloud): on cloud runtimes, ship tag_artifact as an
+  // execution: "agent" script and have the host fold its action.result
+  // stream events into artifact records — agent-tool calls already surface
+  // durably in the session stream.
+  if (agent.runtime === "cloud") {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: artifactsPath,
+      message:
+        "tag_artifact is an in-process server tool (like builtinTools) and is not available on cloud agents; it is skipped.",
+    });
+    return;
+  }
+  if (agent.tools.some((t) => t.name === TAG_ARTIFACT_TOOL_NAME)) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: artifactsPath,
+      message: `Authored tool "${TAG_ARTIFACT_TOOL_NAME}" shadows the built-in tool of the same name; the authored tool wins.`,
+    });
+    return;
+  }
+  agent.tools.push(tool);
+}
+
 function resolveABName(definition: unknown, fallback: string): string {
   if (
     typeof definition === "object" &&
@@ -1759,6 +1851,14 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       project.storage === undefined
         ? undefined
         : { name: project.storage.name },
+    artifacts:
+      project.artifacts === undefined
+        ? undefined
+        : {
+            kinds: Object.keys(project.artifacts.kinds ?? {}),
+            agentTool: project.artifacts.agentTool === true,
+            max: resolveArtifactsMax(project.artifacts),
+          },
     diagnostics: project.diagnostics,
   };
 }
@@ -1779,6 +1879,7 @@ async function importDefault(
     | "hook"
     | "ab"
     | "storage"
+    | "artifacts"
 ): Promise<unknown> {
   let mod: Record<string, unknown>;
   try {

package/src/internal/distribution.ts

@@ -107,6 +107,7 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["evals/reporters", "evals/reporters.js"],
   ["evals/loaders", "evals/loaders.js"],
   ["ab", "ab.js"],
+  ["artifacts", "artifacts.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
   ["storage/postgres-kv", "storage-backends/postgres-kv.js"],

package/src/internal/docs-site.test.ts

@@ -0,0 +1,66 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeAll, describe, expect, it } from "vitest";
+import { resolveDocsFile } from "./docs-site.js";
+
+describe("resolveDocsFile", () => {
+  let dist: string;
+
+  beforeAll(async () => {
+    dist = await mkdtemp(join(tmpdir(), "agent-serve-docs-"));
+    await mkdir(join(dist, "guides"), { recursive: true });
+    await mkdir(join(dist, "assets", "chunks"), { recursive: true });
+    await writeFile(join(dist, "index.html"), "<html>index</html>");
+    await writeFile(join(dist, "quickstart.html"), "<html>quickstart</html>");
+    await writeFile(join(dist, "guides", "slack.html"), "<html>slack</html>");
+    await writeFile(join(dist, "assets", "chunks", "app.js"), "js");
+    await writeFile(join(dist, "hashmap.json"), "{}");
+  });
+
+  it("serves the site index for the empty path", () => {
+    expect(resolveDocsFile("", dist)).toBe(join(dist, "index.html"));
+    expect(resolveDocsFile("/", dist)).toBe(join(dist, "index.html"));
+  });
+
+  it("resolves clean page URLs through the .html chain", () => {
+    expect(resolveDocsFile("quickstart", dist)).toBe(
+      join(dist, "quickstart.html")
+    );
+    expect(resolveDocsFile("guides/slack", dist)).toBe(
+      join(dist, "guides", "slack.html")
+    );
+    expect(resolveDocsFile("guides/slack/", dist)).toBe(
+      join(dist, "guides", "slack.html")
+    );
+  });
+
+  it("serves exact files (assets, json, explicit .html)", () => {
+    expect(resolveDocsFile("assets/chunks/app.js", dist)).toBe(
+      join(dist, "assets", "chunks", "app.js")
+    );
+    expect(resolveDocsFile("hashmap.json", dist)).toBe(
+      join(dist, "hashmap.json")
+    );
+    expect(resolveDocsFile("quickstart.html", dist)).toBe(
+      join(dist, "quickstart.html")
+    );
+  });
+
+  it("returns undefined for unknown pages", () => {
+    expect(resolveDocsFile("nope", dist)).toBeUndefined();
+    expect(resolveDocsFile("guides/nope", dist)).toBeUndefined();
+  });
+
+  it("rejects traversal out of the dist dir", () => {
+    expect(resolveDocsFile("../package.json", dist)).toBeUndefined();
+    expect(resolveDocsFile("..%2Fpackage.json", dist)).toBeUndefined();
+    expect(resolveDocsFile("guides/../../package.json", dist)).toBeUndefined();
+    expect(resolveDocsFile("..", dist)).toBeUndefined();
+  });
+
+  it("does not treat directories as files", () => {
+    // `guides` has no guides.html and no guides/index.html.
+    expect(resolveDocsFile("guides", dist)).toBeUndefined();
+  });
+});

package/src/internal/duration.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { isValidDuration, parseDuration } from "./duration.js";
+
+describe("parseDuration", () => {
+  it("parses short units", () => {
+    expect(parseDuration("30s")).toBe(30_000);
+    expect(parseDuration("5m")).toBe(5 * 60_000);
+    expect(parseDuration("2h")).toBe(2 * 3_600_000);
+    expect(parseDuration("1d")).toBe(86_400_000);
+  });
+
+  it("parses word units", () => {
+    expect(parseDuration("10 minutes")).toBe(10 * 60_000);
+    expect(parseDuration("1.5h")).toBe(90 * 60_000);
+  });
+
+  it("accepts bare numbers as milliseconds", () => {
+    expect(parseDuration(1500)).toBe(1500);
+    expect(parseDuration("1500")).toBe(1500);
+  });
+
+  it("rejects invalid input", () => {
+    expect(() => parseDuration("")).toThrow();
+    expect(() => parseDuration("abc")).toThrow();
+    expect(() => parseDuration("5x")).toThrow();
+    expect(isValidDuration("5m")).toBe(true);
+    expect(isValidDuration("nope")).toBe(false);
+  });
+});

package/src/internal/eval-judge-model.test.ts

@@ -0,0 +1,187 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EvalJudgeUnavailableError } from "../evals/judge.js";
+import {
+  assertJudgeBackendMatch,
+  callJudgeModel,
+  resolveJudgeModel,
+} from "./eval-judge-model.js";
+
+const create = vi.hoisted(() => vi.fn());
+const resolveApiKey = vi.hoisted(() => vi.fn());
+
+vi.mock("@cursor/sdk", () => ({ Agent: { create } }));
+
+vi.mock("./cursor/credentials.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("./cursor/credentials.js")>();
+  return { ...actual, resolveApiKey };
+});
+
+beforeEach(() => {
+  create.mockReset();
+  resolveApiKey.mockReset();
+  resolveApiKey.mockResolvedValue({
+    apiKey: "key_1",
+    source: "env",
+    backendUrl: "https://api2.cursor.sh",
+  });
+  create.mockResolvedValue({
+    send: async () => ({
+      wait: async () => ({ status: "completed", result: "CHOICE: Y" }),
+    }),
+    close: () => undefined,
+  });
+});
+
+describe("resolveJudgeModel", () => {
+  it("resolves innermost-first and ignores a blank env value", () => {
+    expect(
+      resolveJudgeModel({
+        call: "call-model",
+        evalLevel: "eval-model",
+        config: "config-model",
+        env: "env-model",
+      })
+    ).toBe("call-model");
+    expect(
+      resolveJudgeModel({ evalLevel: "eval-model", config: "config-model" })
+    ).toBe("eval-model");
+    expect(resolveJudgeModel({ config: "config-model" })).toBe("config-model");
+    expect(resolveJudgeModel({ env: "  env-model  " })).toBe("env-model");
+    expect(resolveJudgeModel({ env: "   " })).toBeUndefined();
+    expect(resolveJudgeModel({})).toBeUndefined();
+  });
+});
+
+describe("assertJudgeBackendMatch", () => {
+  it("allows a credential scoped to the backend the SDK will use", () => {
+    expect(() =>
+      assertJudgeBackendMatch(
+        "https://api2.cursor.sh",
+        "https://api2.cursor.sh"
+      )
+    ).not.toThrow();
+  });
+
+  it("ignores a trailing-slash difference", () => {
+    expect(() =>
+      assertJudgeBackendMatch(
+        "https://api2.cursor.sh/",
+        "https://api2.cursor.sh"
+      )
+    ).not.toThrow();
+  });
+
+  it("declines when the credential belongs to a different backend", () => {
+    // The SDK takes no backend option, so sending the key anyway would ship it
+    // (and the judge prompt) to a host it was not minted for.
+    expect(() =>
+      assertJudgeBackendMatch(
+        "https://staging.example.com",
+        "https://api2.cursor.sh"
+      )
+    ).toThrow(EvalJudgeUnavailableError);
+    expect(() =>
+      assertJudgeBackendMatch(
+        "https://staging.example.com",
+        "https://api2.cursor.sh"
+      )
+    ).toThrow(/does not read AGENT_SERVE_CURSOR_BACKEND_URL/);
+  });
+});
+
+describe("callJudgeModel", () => {
+  it("skips visibly when there are no credentials", async () => {
+    resolveApiKey.mockResolvedValue(undefined);
+    await expect(
+      callJudgeModel({ prompt: "grade this", model: "gpt-5.4-mini" })
+    ).rejects.toThrow(EvalJudgeUnavailableError);
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it("confines the grading session so an injected reply cannot reach the host", async () => {
+    await callJudgeModel({ prompt: "grade this", model: "gpt-5.4-mini" });
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const options = create.mock.calls[0]![0] as {
+      mcpServers: Record<string, unknown>;
+      local: {
+        cwd: string;
+        settingSources: string[];
+        sandboxOptions: { enabled: boolean };
+      };
+    };
+    // Grading embeds untrusted agent output, so the judge gets no MCP surface,
+    // no ambient settings, an empty scratch cwd, and a sandbox.
+    expect(options.mcpServers).toEqual({});
+    expect(options.local.settingSources).toEqual([]);
+    expect(options.local.sandboxOptions).toEqual({ enabled: true });
+    expect(options.local.cwd).toMatch(/agentkit-eval-judge-/);
+  });
+
+  it("never opens a session when the credential's backend disagrees", async () => {
+    resolveApiKey.mockResolvedValue({
+      apiKey: "key_1",
+      source: "login",
+      backendUrl: "https://staging.example.com",
+    });
+    await expect(
+      callJudgeModel({ prompt: "p", model: "gpt-5.4-mini" })
+    ).rejects.toThrow(EvalJudgeUnavailableError);
+    // The point of failing closed: the key never reaches the SDK.
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it("passes a bare model id through as a selection object", async () => {
+    await callJudgeModel({ prompt: "p", model: "gpt-5.4-mini" });
+    expect(create.mock.calls[0]![0]).toMatchObject({
+      apiKey: "key_1",
+      model: { id: "gpt-5.4-mini" },
+    });
+  });
+
+  it("preserves model params when given a selection object", async () => {
+    await callJudgeModel({
+      prompt: "p",
+      model: { id: "gpt-5.4-mini", params: [{ id: "effort", value: "low" }] },
+    });
+    expect(create.mock.calls[0]![0]).toMatchObject({
+      model: { id: "gpt-5.4-mini", params: [{ id: "effort", value: "low" }] },
+    });
+  });
+
+  it("returns the judge reply", async () => {
+    await expect(
+      callJudgeModel({ prompt: "p", model: "gpt-5.4-mini" })
+    ).resolves.toBe("CHOICE: Y");
+  });
+
+  it("surfaces a failed grading run as an error", async () => {
+    create.mockResolvedValue({
+      send: async () => ({
+        wait: async () => ({
+          status: "error",
+          error: { message: "provider unavailable" },
+        }),
+      }),
+      close: () => undefined,
+    });
+    await expect(
+      callJudgeModel({ prompt: "p", model: "gpt-5.4-mini" })
+    ).rejects.toThrow(/eval judge run failed: provider unavailable/);
+  });
+
+  it("closes the session even when grading throws", async () => {
+    const close = vi.fn();
+    create.mockResolvedValue({
+      send: async () => {
+        throw new Error("boom");
+      },
+      close,
+    });
+    await expect(
+      callJudgeModel({ prompt: "p", model: "gpt-5.4-mini" })
+    ).rejects.toThrow("boom");
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+});