@cursor/july 0.1.43 → 0.1.45

package/src/channels.ts

@@ -383,3 +383,41 @@ export function allowAll(): AuthPolicy {
     principalType: "user",
   });
 }
+
+/**
+ * `Symbol.for` so the marker survives duplicated copies of the framework in
+ * one process (e.g. a monorepo agent resolving its own `@cursor/july`).
+ */
+const PUBLIC_ENDPOINT_MARKER = Symbol.for("agent-serve.public-endpoint");
+
+/**
+ * Like {@link allowAll}, but ALSO declares the channel publicly reachable on
+ * Cursor's managed hosting: `deploy` collects every channel whose auth chain
+ * contains this policy and the platform serves that channel's routes
+ * (`/v1/channels/<id>/…`) through the stable alias WITHOUT
+ * `X-Agent-Alias-Token`.
+ *
+ * Use it for webhook senders that cannot attach custom headers (Linear,
+ * Stripe, …) — **the handler must authenticate deliveries itself**, e.g. by
+ * verifying the provider's HMAC signature over the raw body. Everything
+ * else (sessions, MCP, playground) stays behind platform auth.
+ *
+ * Locally this admits every caller, exactly like `allowAll()`.
+ */
+export function publicEndpoint(): AuthPolicy {
+  const policy: AuthPolicy = () => ({
+    authenticator: "public-endpoint",
+    principalId: "anonymous",
+    principalType: "user",
+  });
+  return Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const });
+}
+
+/** True when a policy was created by {@link publicEndpoint}. */
+export function isPublicEndpointPolicy(policy: AuthPolicy): boolean {
+  return (
+    (policy as { [PUBLIC_ENDPOINT_MARKER]?: unknown })[
+      PUBLIC_ENDPOINT_MARKER
+    ] === true
+  );
+}

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   PATCH,
   POST,
   PUT,
+  publicEndpoint,
 } from "./channels.js";
 export { defineConnection } from "./connections.js";
 export { defineHook } from "./hooks.js";

package/src/internal/cli-ax.ts

@@ -23,7 +23,7 @@ import { lookupSessionContinuation, runChat } from "./chat-client.js";
 import { cmdLogin } from "./cli-cursor.js";
 import { resolveDeployAuth } from "./cli-deploy.js";
 import { resolveApiKey } from "./cursor/credentials.js";
-import { CLI_COMMAND_NAME } from "./distribution.js";
+import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
 import {
   discoverEvals,
   type EvalRunResult,
@@ -374,7 +374,7 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
   const cliOnPath = linked.ok;
   if (!cliOnPath) {
     process.stderr.write(
-      `\nCould not put ${CLI_COMMAND_NAME} on PATH (${linked.stderr.trim() || `exit ${linked.exitCode}`}). Next steps include a PATH export for node_modules/.bin.\n\n`
+      `\nCould not put ${CLI_COMMAND_NAME} on PATH (${linked.stderr.trim() || `exit ${linked.exitCode}`}). Next steps use npx ${PACKAGE_NAME} instead.\n\n`
     );
   } else {
     process.stdout.write("\n");

package/src/internal/cli-deploy.ts

@@ -10,6 +10,7 @@
  */
 
 import { basename, resolve } from "node:path";
+import { isPublicEndpointPolicy } from "../channels.js";
 import {
   type AgentHostingOptions,
   isCursorAccountTransport,
@@ -633,7 +634,8 @@ async function deployOne(
   // truth for egress domains and expected secret names; flags override or
   // augment it. Directories without an agent project (static placeholder
   // deploys) simply have no manifest. The same load supplies the
-  // cursorAccount connection refs for the post-deploy connector auth.
+  // cursorAccount connection refs for the post-deploy connector auth and
+  // the channels declared public via `publicEndpoint()`.
   const manifest = isAgent ? await readDeployManifest(dir) : undefined;
   const hosting = manifest?.hosting;
   const egressAllowedDomains = [
@@ -642,6 +644,21 @@ async function deployOne(
       ...(options.allowDomains ?? []),
     ]),
   ];
+  const publicRoutePaths = (manifest?.publicChannelIds ?? []).map(
+    (channelId) => `/v1/channels/${channelId}`
+  );
+  if (!ctx.json && manifest?.httpChannelPublicEndpoint === true) {
+    ctx.err(
+      `warning: publicEndpoint() on the built-in HTTP channel has no effect on hosting — only custom channels (/v1/channels/…) can be public; the session API always requires the alias token.\n`
+    );
+  }
+  if (!ctx.json && publicRoutePaths.length > 0) {
+    // Security-relevant surface change: say exactly what will be reachable
+    // without the alias token before the deploy is accepted.
+    ctx.err(
+      `  public: ${publicRoutePaths.join(", ")} (served WITHOUT the alias token — these channels authenticate requests themselves)\n`
+    );
+  }
 
   // Today's only source shape: the control plane builds from a git ref (or
   // serves the static placeholder). See DeploySource for the artifact seam.
@@ -655,6 +672,8 @@ async function deployOne(
       ? {}
       : { cursorEventRepos: options.cursorEventsRepos }),
     ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
+    publicRoutePaths:
+      publicRoutePaths.length === 0 ? undefined : publicRoutePaths,
   };
 
   let accepted: DeployAccepted;
@@ -716,6 +735,7 @@ async function deployOne(
     ctx.err(`Deployment ${slug} ended ${detail.status}${errorDetail}\n`);
     return 1;
   }
+  const deployedPublicRoutes = detail.publicRoutePaths ?? [];
   ctx.out(
     `Deployed ${slug} (team ${ctx.teamId})\n` +
       `  status:      running\n` +
@@ -723,7 +743,12 @@ async function deployOne(
       `  kind:        ${detail.deploymentKind}\n` +
       `  alias:       ${aliasUrl}\n` +
       `  playground:  ${aliasUrl}/playground (sign in with the alias token)\n` +
-      `               open: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
+      `               open: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n` +
+      // Paste-ready webhook URLs: these subtrees skip the alias token, so
+      // the channel handler must verify deliveries (webhook signatures).
+      deployedPublicRoutes
+        .map((path) => `  public:      ${aliasUrl}${path} (no alias token)\n`)
+        .join("")
   );
 
   await runPostDeployConnectorAuth(ctx, options, {
@@ -828,11 +853,23 @@ interface DeployManifest {
     name: string;
     servers: string[] | undefined;
   }>;
+  /**
+   * Channels whose authored auth chain contains `publicEndpoint()`: their
+   * `/v1/channels/<id>` subtree is served through the stable alias WITHOUT
+   * `X-Agent-Alias-Token` (the channel authenticates deliveries itself).
+   */
+  publicChannelIds: string[];
+  /**
+   * `publicEndpoint()` on the built-in HTTP channel — a no-op on hosting
+   * (only `/v1/channels/…` subtrees can be public); surfaced as a warning.
+   */
+  httpChannelPublicEndpoint: boolean;
 }
 
 /**
  * Read the deploy-relevant bits of the project manifest at `dir` in one
- * load: the `hosting` block plus the agent's cursorAccount connections.
+ * load: the `hosting` block, the agent's cursorAccount connections, and the
+ * channels declared public via `publicEndpoint()`.
  */
 async function readDeployManifest(dir: string): Promise<DeployManifest> {
   const project = await loadAgentProject(dir);
@@ -843,6 +880,14 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
         ? [{ name: connection.name, servers: connection.transport.servers }]
         : []
     ),
+    publicChannelIds: project.channels
+      .filter((channel) =>
+        (channel.definition.auth ?? []).some(isPublicEndpointPolicy)
+      )
+      .map((channel) => channel.id),
+    httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(
+      isPublicEndpointPolicy
+    ),
   };
 }
 
@@ -985,6 +1030,16 @@ export async function cmdDeploymentStatus(
   ) {
     lines.push(`  egress:      ${detail.egressAllowedDomains.join(", ")}`);
   }
+  if (
+    detail.publicRoutePaths !== undefined &&
+    detail.publicRoutePaths.length > 0
+  ) {
+    // Served through the alias WITHOUT X-Agent-Alias-Token (the channel
+    // authenticates deliveries itself).
+    for (const path of detail.publicRoutePaths) {
+      lines.push(`  public:      ${aliasUrl}${path} (no alias token)`);
+    }
+  }
   if (detail.secretNames !== undefined && detail.secretNames.length > 0) {
     lines.push(`  secrets:     ${detail.secretNames.join(", ")}`);
   }

package/src/internal/deploy-client.ts

@@ -69,6 +69,12 @@ export type DeploySource = {
    * deploys — the backend 400s when set on a static deploy.
    */
   egressAllowedDomains?: string[];
+  /**
+   * `/v1/channels/…` subtrees the stable alias serves WITHOUT
+   * `X-Agent-Alias-Token` (channels authored with `publicEndpoint()`).
+   * Only valid on repo-backed deploys.
+   */
+  publicRoutePaths?: string[];
 };
 
 const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
@@ -158,6 +164,8 @@ export interface Deployment {
   cursorEventRepos?: string[];
   /** Normalized egress allowlist for the engine pod. */
   egressAllowedDomains?: string[];
+  /** Channel subtrees the alias serves without `X-Agent-Alias-Token`. */
+  publicRoutePaths?: string[];
   /** Service-account id (`sa_…`); null on legacy rows. */
   serviceAccountId?: string | number | null;
   /**
@@ -297,6 +305,7 @@ const deploymentSchema = z.object({
   lastReconciledAt: z.string().nullable().optional(),
   cursorEventRepos: z.array(z.string()).optional(),
   egressAllowedDomains: z.array(z.string()).optional(),
+  publicRoutePaths: z.array(z.string()).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(),
@@ -441,6 +450,8 @@ export class AgentServeDeployClient {
       ...(args.source.egressAllowedDomains === undefined
         ? {}
         : { egressAllowedDomains: args.source.egressAllowedDomains }),
+      // JSON.stringify drops undefined keys.
+      publicRoutePaths: args.source.publicRoutePaths,
     };
     const raw = await this.request({
       method: "POST",

package/src/internal/discovery.ts

@@ -376,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({
@@ -415,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",
@@ -455,6 +503,7 @@ async function loadAgent(
     runtime,
     cloud,
     local,
+    ...(allowedTools === undefined ? {} : { allowedTools }),
     hosting,
     concurrency,
     serving,

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

@@ -699,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;
@@ -739,9 +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
+  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 && ${CLI_COMMAND_NAME} dev
+  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/