@cursor/july 0.1.42 → 0.1.45

package/src/internal/discovery.ts

@@ -20,6 +20,7 @@ import { pathToFileURL } from "node:url";
 import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
 import { resolveArtifactsMax } from "../artifacts.js";
 import { httpChannel } from "../channels.js";
+import type { OtelDefinition } from "../otel.js";
 import type { StorageDefinition } from "../storage.js";
 import {
   type AgentConcurrencyOptions,
@@ -300,6 +301,7 @@ export async function loadAgentProject(
   const abConfig = await loadABConfig(ctx, agentDir);
   const storage = await loadStorage(ctx, agentDir);
   const artifacts = await loadArtifacts(ctx, agentDir);
+  const otel = await loadOtel(ctx, agentDir);
   await appendArtifactTool(ctx, agentDir, agent, artifacts);
 
   if (agentDir !== rootDir) {
@@ -319,6 +321,7 @@ export async function loadAgentProject(
     abConfig,
     storage,
     artifacts,
+    otel,
     diagnostics,
   };
 }
@@ -373,6 +376,14 @@ async function loadAgent(
         message: "builtinTools is not supported on subagents; ignoring.",
       });
     }
+    if (config?.tools !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          "tools is not supported on subagents (they keep the harness task-tool toolset); ignoring.",
+      });
+    }
     const artifactsPath = await findModuleFile(agentDir, "artifacts");
     if (artifactsPath !== undefined) {
       ctx.diagnostics.push({
@@ -412,6 +423,46 @@ async function loadAgent(
   const localCwd = resolveAgentCwd(ctx, config?.local?.cwd);
   const localWorkspaceDir = resolveAgentCwd(ctx, config?.local?.workspaceDir);
   const localSandbox = config?.local?.sandbox === true;
+  // Built-in tool allowlist (top-level `tools`). `[]` is meaningful (no
+  // native built-in tools), so presence is keyed on the field, not on
+  // emptiness. "mcp" is always granted alongside a configured allowlist:
+  // it is transport, not capability — this kit's own server tools ride the
+  // SDK custom-tool MCP path, so omitting it silently breaks
+  // `agent/tools/`, and what MCP actually exposes stays controlled by the
+  // second layer (authored tools, mcp-connections, the harness cwd's
+  // ambient config).
+  const authoredAllowlist = config?.tools;
+  const allowedTools =
+    authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
+      ? authoredAllowlist
+      : [...authoredAllowlist, "mcp" as const];
+  // The allowlist states runtime-agnostic intent, but the SDK cannot
+  // enforce tool restrictions on cloud agents yet — a cloud-runtime agent
+  // that declares one must fail at serve start, never run unrestricted.
+  // (Hybrid per-send cloud sessions fail closed in the session engine.)
+  if (allowedTools !== undefined && runtime === "cloud") {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message:
+        'tools cannot be enforced on runtime: "cloud" yet (the Cursor SDK rejects tool restrictions on cloud agents). Remove `tools` or run the agent on the local runtime.',
+    });
+  }
+  // `execution: "agent"` tool scripts run through the shell tool. Shell is
+  // a real capability, so it is never injected — but an allowlist that
+  // strands authored scripts deserves a loud diagnostic, not silence.
+  if (
+    allowedTools !== undefined &&
+    !allowedTools.includes("shell") &&
+    tools.some((tool) => tool.execution === "agent")
+  ) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message:
+        '`tools` omits "shell" but this agent has execution: "agent" tools, which run as shell scripts; the model will not be able to run them.',
+    });
+  }
   if (localCwd !== undefined && localWorkspaceDir !== undefined) {
     ctx.diagnostics.push({
       severity: "warning",
@@ -452,6 +503,7 @@ async function loadAgent(
     runtime,
     cloud,
     local,
+    ...(allowedTools === undefined ? {} : { allowedTools }),
     hosting,
     concurrency,
     serving,
@@ -1718,6 +1770,22 @@ async function loadStorage(
   return definition as StorageDefinition | undefined;
 }
 
+// ============================================================================
+// OpenTelemetry (agent/otel.ts)
+// ============================================================================
+
+async function loadOtel(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<OtelDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "otel");
+  if (path === undefined) {
+    return undefined;
+  }
+  const definition = await importDefault(ctx, path, "otel");
+  return definition as OtelDefinition | undefined;
+}
+
 // ============================================================================
 // Artifacts (agent/artifacts.ts)
 // ============================================================================
@@ -1973,6 +2041,13 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
             agentTool: project.artifacts.agentTool === true,
             max: resolveArtifactsMax(project.artifacts),
           },
+    otel:
+      project.otel === undefined
+        ? undefined
+        : {
+            enabled: true as const,
+            serviceName: project.otel.serviceName,
+          },
     diagnostics: project.diagnostics,
   };
 }
@@ -1994,6 +2069,7 @@ async function importDefault(
     | "ab"
     | "storage"
     | "artifacts"
+    | "otel"
 ): Promise<unknown> {
   let mod: Record<string, unknown>;
   try {
@@ -2008,10 +2084,7 @@ async function importDefault(
   }
   const kind = getDefinitionKind(mod.default);
   if (kind !== expectedKind) {
-    const helper =
-      expectedKind === "ab"
-        ? "defineAB"
-        : `define${expectedKind[0]?.toUpperCase()}${expectedKind.slice(1)}`;
+    const helper = DEFINE_HELPER_NAME[expectedKind];
     ctx.diagnostics.push({
       severity: "error",
       path: displayPath(ctx, modulePath),
@@ -2025,6 +2098,37 @@ async function importDefault(
   return mod.default;
 }
 
+const DEFINE_HELPER_NAME: Record<
+  | "agent"
+  | "instructions"
+  | "tool"
+  | "skill"
+  | "connection"
+  | "channel"
+  | "http-channel"
+  | "schedule"
+  | "hook"
+  | "ab"
+  | "storage"
+  | "artifacts"
+  | "otel",
+  string
+> = {
+  agent: "defineAgent",
+  instructions: "defineInstructions",
+  tool: "defineTool",
+  skill: "defineSkill",
+  connection: "defineConnection",
+  channel: "defineChannel",
+  "http-channel": "httpChannel",
+  schedule: "defineSchedule",
+  hook: "defineHook",
+  ab: "defineAB",
+  storage: "defineStorage",
+  artifacts: "defineArtifacts",
+  otel: "defineOtel",
+};
+
 async function warnUnknownSlots(
   ctx: DiscoveryContext,
   agentDir: string

package/src/internal/distribution.ts

@@ -114,4 +114,5 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
   ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],
+  ["otel", "otel.js"],
 ];

package/src/internal/host-otel.ts

@@ -0,0 +1,252 @@
+/**
+ * Author-facing OpenTelemetry surface for {@link HostContext.otel}.
+ *
+ * Always present on `ctx.host`. Counters and histograms no-op when no meter
+ * is running. `setAttributes` still tags the open session when a collector
+ * is attached. `forSession` is engine-only so a tool cannot retarget another
+ * conversation's tags.
+ */
+
+import type { Counter, Histogram, Meter } from "@opentelemetry/api";
+import type { HostOtelApi, HostOtelAttributes } from "../types.js";
+import type { AttrValue } from "./otel/attrs.js";
+import { attrs } from "./otel/attrs.js";
+import type { OtelCollector } from "./otel/collector.js";
+
+const METRIC_NAME = /^[A-Za-z][A-Za-z0-9_./-]*$/;
+
+const RESERVED_METRICS = new Set([
+  "cursor.token.usage",
+  "cursor.tool.calls",
+  "cursor.cost.usage",
+  "agent_sdk.session.count",
+  "agent_sdk.turn.count",
+  "agent_sdk.subagent.count",
+  "agent_sdk.http.duration",
+]);
+
+const RESERVED_ATTRIBUTES = new Set([
+  "cursor.conversation.id",
+  "agent_sdk.agent",
+  "agent_sdk.turn_id",
+  "agent_sdk.framework",
+]);
+
+export interface CreateHostOtelApiOptions {
+  agentName: string;
+  meter?: Meter;
+  collector?: OtelCollector;
+  /** Session bound for join tags; prefer {@link HostOtelSessionApi.forSession}. */
+  sessionId?: string;
+}
+
+/** Engine-only binding. Not part of the public {@link HostOtelApi}. */
+export interface HostOtelSessionApi extends HostOtelApi {
+  forSession(sessionId: string): HostOtelSessionApi;
+}
+
+interface CachedInstrument {
+  kind: "counter" | "histogram";
+  instrument: Counter | Histogram;
+}
+
+interface SharedState {
+  agentName: string;
+  meter: Meter | undefined;
+  collector: OtelCollector | undefined;
+  instruments: Map<string, CachedInstrument>;
+  /** Used when no collector is attached so bound instances still share tags. */
+  sessionTags: Map<string, Record<string, AttrValue>>;
+}
+
+interface BoundState {
+  shared: SharedState;
+  sessionId: string | undefined;
+  localTags: Record<string, AttrValue>;
+}
+
+/** Build the host OpenTelemetry API for one agent process. */
+export function createHostOtelApi(
+  options: CreateHostOtelApiOptions
+): HostOtelSessionApi {
+  return createBoundHostOtelApi({
+    shared: {
+      agentName: options.agentName,
+      meter: options.meter,
+      collector: options.collector,
+      instruments: new Map(),
+      sessionTags: new Map(),
+    },
+    sessionId: options.sessionId,
+    localTags: {},
+  });
+}
+
+function createBoundHostOtelApi(state: BoundState): HostOtelSessionApi {
+  const api: HostOtelSessionApi = {
+    get enabled(): boolean {
+      return state.shared.meter !== undefined;
+    },
+
+    setAttributes(attributes) {
+      const cleaned = validateAttributes(attributes);
+      if (state.sessionId === undefined) {
+        Object.assign(state.localTags, cleaned);
+        return;
+      }
+      mergeSessionTags(state, state.sessionId, cleaned);
+      state.shared.collector?.setSessionAttributes(state.sessionId, cleaned);
+    },
+
+    increment(
+      name: string,
+      valueOrAttributes?: number | HostOtelAttributes,
+      maybeAttributes?: HostOtelAttributes
+    ) {
+      const value =
+        typeof valueOrAttributes === "number" ? valueOrAttributes : 1;
+      const attributes =
+        typeof valueOrAttributes === "number"
+          ? maybeAttributes
+          : valueOrAttributes;
+      counter(state.shared, name)?.add(
+        value,
+        emitAttributes(state, attributes)
+      );
+    },
+
+    record(name, value, attributes) {
+      histogram(state.shared, name)?.record(
+        value,
+        emitAttributes(state, attributes)
+      );
+    },
+
+    forSession(sessionId) {
+      const trimmed = sessionId.trim();
+      if (trimmed === "") {
+        throw new Error("host.otel.forSession requires a non-empty session id");
+      }
+      return createBoundHostOtelApi({
+        shared: state.shared,
+        sessionId: trimmed,
+        localTags: {},
+      });
+    },
+  };
+  return api;
+}
+
+function mergeSessionTags(
+  state: BoundState,
+  sessionId: string,
+  incoming: Record<string, AttrValue>
+): void {
+  const bag = state.shared.sessionTags.get(sessionId) ?? {};
+  Object.assign(bag, incoming);
+  state.shared.sessionTags.set(sessionId, bag);
+}
+
+function emitAttributes(
+  state: BoundState,
+  callSite: HostOtelAttributes | undefined
+): Record<string, AttrValue> {
+  return attrs({
+    ...sessionBag(state),
+    ...validateAttributes(callSite),
+    "agent_sdk.agent": state.shared.agentName,
+    ...(state.sessionId === undefined
+      ? {}
+      : { "cursor.conversation.id": state.sessionId }),
+  });
+}
+
+function sessionBag(state: BoundState): Record<string, AttrValue> {
+  if (state.sessionId === undefined) {
+    return state.localTags;
+  }
+  const fromCollector = state.shared.collector?.getSessionAttributes(
+    state.sessionId
+  );
+  const fromShared = state.shared.sessionTags.get(state.sessionId) ?? {};
+  return {
+    ...fromShared,
+    ...(fromCollector ?? {}),
+    ...state.localTags,
+  };
+}
+
+function counter(shared: SharedState, name: string): Counter | undefined {
+  validateMetricName(name);
+  if (shared.meter === undefined) {
+    return undefined;
+  }
+  const existing = shared.instruments.get(name);
+  if (existing !== undefined) {
+    if (existing.kind !== "counter") {
+      throw new Error(`host.otel metric "${name}" is already a histogram`);
+    }
+    return existing.instrument as Counter;
+  }
+  const instrument = shared.meter.createCounter(name);
+  shared.instruments.set(name, { kind: "counter", instrument });
+  return instrument;
+}
+
+function histogram(shared: SharedState, name: string): Histogram | undefined {
+  validateMetricName(name);
+  if (shared.meter === undefined) {
+    return undefined;
+  }
+  const existing = shared.instruments.get(name);
+  if (existing !== undefined) {
+    if (existing.kind !== "histogram") {
+      throw new Error(`host.otel metric "${name}" is already a counter`);
+    }
+    return existing.instrument as Histogram;
+  }
+  const instrument = shared.meter.createHistogram(name);
+  shared.instruments.set(name, { kind: "histogram", instrument });
+  return instrument;
+}
+
+function validateMetricName(name: string): void {
+  if (!METRIC_NAME.test(name)) {
+    throw new Error(
+      `host.otel metric name "${name}" must match [A-Za-z][A-Za-z0-9_./-]*`
+    );
+  }
+  if (RESERVED_METRICS.has(name)) {
+    throw new Error(`host.otel metric name "${name}" is reserved`);
+  }
+}
+
+function validateAttributes(
+  attributes: HostOtelAttributes | undefined
+): Record<string, AttrValue> {
+  if (attributes === undefined) {
+    return {};
+  }
+  const out: Record<string, AttrValue> = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined) {
+      continue;
+    }
+    if (RESERVED_ATTRIBUTES.has(key)) {
+      throw new Error(
+        `host.otel attribute "${key}" is reserved; the runtime always sets it`
+      );
+    }
+    if (
+      typeof value !== "string" &&
+      typeof value !== "number" &&
+      typeof value !== "boolean"
+    ) {
+      throw new Error(
+        `host.otel attribute "${key}" must be a string, number, or boolean`
+      );
+    }
+    out[key] = value;
+  }
+  return out;
+}

package/src/internal/init-project.ts

@@ -3,13 +3,14 @@
  */
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync, readFileSync } 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 {
   CLI_COMMAND_NAME,
   PACKAGE_NAME,
+  packageRootDir,
   packageVersion,
 } from "./distribution.js";
 import {
@@ -25,6 +26,7 @@ export interface InitProjectOptions {
   name?: string;
   /** Model id override written into agent.ts. */
   model?: string;
+  templateDir?: string;
 }
 
 export type InitFileAction = "create" | "exist";
@@ -44,6 +46,99 @@ export interface InitProjectResult {
   skipped: string[];
 }
 
+export function availableTemplates(): string[] {
+  const templatesDir = join(packageRootDir(), "templates");
+  try {
+    return readdirSync(templatesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export type TemplateResolution =
+  | { ok: true; name: string; dir: string }
+  | { ok: false; message: string };
+
+export function resolveTemplate(name: string): TemplateResolution {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    return {
+      ok: false,
+      message: "template name must match /^[a-z][a-z0-9-]*$/",
+    };
+  }
+  const available = availableTemplates();
+  if (!available.includes(name)) {
+    const detail =
+      available.length === 0
+        ? "no templates ship with this build"
+        : `available: ${available.join(", ")}`;
+    return {
+      ok: false,
+      message: `unknown template "${name}" (${detail})`,
+    };
+  }
+  return {
+    ok: true,
+    name,
+    dir: join(packageRootDir(), "templates", name),
+  };
+}
+
+export type InitTargetCheck = { ok: true } | { ok: false; message: string };
+
+/**
+ * Re-init must keep the mode the project was scaffolded with: template
+ * scaffolds stamp `cursorAgentTemplate` into package.json, and a mismatch
+ * here would silently mix default-scaffold files into a template project
+ * (or the reverse).
+ */
+export function checkInitTarget(
+  rootDir: string,
+  template: string | undefined
+): InitTargetCheck {
+  const pkgPath = join(rootDir, "package.json");
+  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;
+  }
+  if (marker === template) {
+    return { ok: true };
+  }
+  if (template === undefined) {
+    return {
+      ok: false,
+      message: `${rootDir} was scaffolded from the "${marker}" template; re-run with --template ${marker}`,
+    };
+  }
+  if (marker === undefined) {
+    return {
+      ok: false,
+      message: `${rootDir} already has a package.json without template provenance; re-run init without --template, or scaffold into a fresh directory`,
+    };
+  }
+  return {
+    ok: false,
+    message: `${rootDir} was scaffolded from the "${marker}" template, not "${template}"`,
+  };
+}
+
 const DEFAULT_MODEL: ModelSetting = {
   id: "grok-4.5",
   params: [
@@ -73,13 +168,15 @@ export async function initProject(
   options: InitProjectOptions
 ): Promise<InitProjectResult> {
   const rootDir = resolve(options.dir);
-  const name = options.name ?? basename(rootDir);
+  const projectName = basename(rootDir);
+  const name = options.name ?? projectName;
   const model = formatModelLiteral(options.model ?? DEFAULT_MODEL);
-  const agentDir = join(rootDir, "agent");
-  await mkdir(agentDir, { recursive: true });
 
   const files: InitFileEntry[] = [];
-  const write = async (rel: string, contents: string): Promise<void> => {
+  const write = async (
+    rel: string,
+    contents: string | Uint8Array
+  ): Promise<void> => {
     const abs = join(rootDir, rel);
     await mkdir(dirname(abs), { recursive: true });
     try {
@@ -95,6 +192,47 @@ export async function initProject(
     }
   };
 
+  if (options.templateDir !== undefined) {
+    const templateDir = options.templateDir;
+    const entries = await readdir(templateDir, {
+      recursive: true,
+      withFileTypes: true,
+    });
+    const relativePaths = entries
+      .filter((entry) => entry.isFile())
+      .map((entry) => relative(templateDir, join(entry.parentPath, entry.name)))
+      .sort();
+    for (const rel of relativePaths) {
+      const source = join(templateDir, rel);
+      if (rel === "package.json") {
+        const packageJson: {
+          name: string;
+          dependencies: Record<string, string>;
+          [key: string]: unknown;
+        } = JSON.parse(await readFile(source, "utf8"));
+        packageJson.name = projectName;
+        packageJson.dependencies[PACKAGE_NAME] = `^${packageVersion()}`;
+        packageJson.cursorAgentTemplate = basename(templateDir);
+        await write(rel, `${JSON.stringify(packageJson, null, 2)}\n`);
+      } else {
+        await write(rel, await readFile(source));
+      }
+    }
+    return {
+      rootDir,
+      files,
+      created: files
+        .filter((entry) => entry.action === "create")
+        .map((entry) => entry.path),
+      skipped: files
+        .filter((entry) => entry.action === "exist")
+        .map((entry) => entry.path),
+    };
+  }
+
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+
   await write(
     "package.json",
     `${JSON.stringify(
@@ -209,11 +347,15 @@ export default memoryHook();
 }
 
 export function isEexist(error: unknown): boolean {
+  return hasErrorCode(error, "EEXIST");
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
   return (
     error !== null &&
     typeof error === "object" &&
     "code" in error &&
-    (error as { code: string }).code === "EEXIST"
+    error.code === code
   );
 }
 
@@ -557,20 +699,20 @@ function initNextStepEntries(options: InitNextStepsOptions): Array<{
   if (cd !== undefined) {
     steps.push({ command: cd });
   }
-  if (!options.cliOnPath) {
-    steps.push({
-      command: 'export PATH="$PWD/node_modules/.bin:$PATH"',
-      note: "use the project-local agent-sdk bin",
-    });
-  }
   if (!options.signedIn) {
+    const login = options.cliOnPath
+      ? `${CLI_COMMAND_NAME} login`
+      : `npx ${PACKAGE_NAME} login`;
     steps.push({
-      command: `${CLI_COMMAND_NAME} login`,
+      command: login,
       note: "connect your Cursor account (powers model turns)",
     });
   }
+  const dev = options.cliOnPath
+    ? `${CLI_COMMAND_NAME} dev`
+    : `npx ${PACKAGE_NAME} dev`;
   steps.push({
-    command: `${CLI_COMMAND_NAME} dev`,
+    command: dev,
     note: "start the local playground",
   });
   return steps;
@@ -597,8 +739,9 @@ export function printInitGuide(): void {
   process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
 
 Scaffold a project, then open the playground:
-  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + puts agent-sdk on PATH
-  cd ./my-agent && ${CLI_COMMAND_NAME} dev
+  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
+  npx ${PACKAGE_NAME} init ./my-triage --template triage   # start from a template (agent-sdk templates: triage)
+  cd ./my-agent && agent-sdk dev        # or: npx ${PACKAGE_NAME} dev
 
 Recommended loop once the project exists (from the project directory):
   1. Edit agent/ + tools under agent/tools/