@cursor/july 0.1.42 → 0.1.45

package/src/channels/github/progress.ts

@@ -0,0 +1,243 @@
+/**
+ * Opt-in PR progress surfaces: commit status + sticky banner comment.
+ */
+
+import {
+  createGitHubCommitStatus,
+  createGitHubIssueComment,
+  GitHubApiError,
+  updateGitHubIssueComment,
+} from "./api.js";
+import type { GitHubBindingConfig } from "./binding.js";
+import { formatGitHubOutboundComment } from "./binding.js";
+import type { GitHubChannelState } from "./state.js";
+
+/** GitHub commit-status descriptions are capped at 140 characters. */
+const STATUS_DESCRIPTION_MAX = 140;
+
+export type GitHubProgressPhase = "pending" | "success" | "failure";
+
+export interface GitHubProgressPhaseCopy {
+  pending?: string;
+  success?: string;
+  failure?: string;
+}
+
+export interface GitHubCommitStatusProgress extends GitHubProgressPhaseCopy {
+  /** Commit status context (unique per check in the merge box). */
+  context: string;
+}
+
+export type GitHubBannerProgress = GitHubProgressPhaseCopy;
+
+export interface GitHubProgressConfig {
+  /** When false, skip the eyes reaction on turn.started. Defaults to true. */
+  reactions?: boolean;
+  /**
+   * Opt-in commit status on the PR head. Omit or `false` keeps today's
+   * behavior (no statuses from default events). With `cursorAccount`,
+   * needs `permissions: "contents-write"` (push-equivalent).
+   */
+  commitStatus?: false | GitHubCommitStatusProgress;
+  /**
+   * Opt-in sticky PR/issue timeline comment. Created on first pending,
+   * PATCHed on later phases. Omit or `false` disables.
+   */
+  banner?: false | GitHubBannerProgress;
+}
+
+export interface GitHubProgressOptions extends GitHubBindingConfig {
+  botName?: string;
+  progress?: GitHubProgressConfig;
+}
+
+export function resolveCommitStatusProgress(
+  progress: GitHubProgressConfig | undefined
+): GitHubCommitStatusProgress | null {
+  if (progress?.commitStatus === undefined || progress.commitStatus === false) {
+    return null;
+  }
+  return progress.commitStatus;
+}
+
+export function resolveBannerProgress(
+  progress: GitHubProgressConfig | undefined
+): GitHubBannerProgress | null {
+  if (progress?.banner === undefined || progress.banner === false) {
+    return null;
+  }
+  return progress.banner;
+}
+
+export function progressPhaseCopy(input: {
+  copy: GitHubProgressPhaseCopy | undefined;
+  phase: GitHubProgressPhase;
+  label: string;
+}): string {
+  const custom = input.copy?.[input.phase];
+  if (custom !== undefined && custom.trim() !== "") {
+    return custom;
+  }
+  switch (input.phase) {
+    case "pending":
+      return `${input.label} running`;
+    case "success":
+      return `${input.label} finished`;
+    case "failure":
+      return `${input.label} failed`;
+  }
+}
+
+function clipStatusDescription(text: string): string {
+  if (text.length <= STATUS_DESCRIPTION_MAX) {
+    return text;
+  }
+  return `${text.slice(0, STATUS_DESCRIPTION_MAX - 1)}…`;
+}
+
+function progressLabel(
+  options: GitHubProgressOptions,
+  context?: string
+): string {
+  const bot = options.botName?.trim();
+  if (bot !== undefined && bot !== "") {
+    return bot;
+  }
+  if (context !== undefined && context.trim() !== "") {
+    return context;
+  }
+  return "Agent";
+}
+
+/**
+ * Post or update opt-in progress surfaces for a turn phase.
+ * Soft-fails on API errors (same posture as eyes / reply delivery).
+ */
+export async function applyGitHubProgress(input: {
+  phase: GitHubProgressPhase;
+  channel: { state: GitHubChannelState };
+  options: GitHubProgressOptions;
+}): Promise<void> {
+  const commitStatus = resolveCommitStatusProgress(input.options.progress);
+  const banner = resolveBannerProgress(input.options.progress);
+  if (commitStatus === null && banner === null) {
+    return;
+  }
+
+  const tasks: Array<Promise<void>> = [];
+  if (commitStatus !== null) {
+    tasks.push(
+      postCommitStatus({
+        phase: input.phase,
+        channel: input.channel,
+        options: input.options,
+        commitStatus,
+      })
+    );
+  }
+  if (banner !== null) {
+    tasks.push(
+      upsertBanner({
+        phase: input.phase,
+        channel: input.channel,
+        options: input.options,
+        banner,
+        context: commitStatus?.context,
+      })
+    );
+  }
+  await Promise.all(tasks);
+}
+
+async function postCommitStatus(input: {
+  phase: GitHubProgressPhase;
+  channel: { state: GitHubChannelState };
+  options: GitHubProgressOptions;
+  commitStatus: GitHubCommitStatusProgress;
+}): Promise<void> {
+  const state = input.channel.state;
+  if (
+    state.owner === "" ||
+    state.repo === "" ||
+    state.headSha === null ||
+    state.headSha === ""
+  ) {
+    return;
+  }
+  const description = clipStatusDescription(
+    progressPhaseCopy({
+      copy: input.commitStatus,
+      phase: input.phase,
+      label: progressLabel(input.options, input.commitStatus.context),
+    })
+  );
+  try {
+    await createGitHubCommitStatus({
+      api: input.options.api,
+      credentials: input.options.credentials,
+      installationId: state.installationId ?? undefined,
+      owner: state.owner,
+      repo: state.repo,
+      sha: state.headSha,
+      state: input.phase,
+      context: input.commitStatus.context,
+      description,
+    });
+  } catch {
+    // Soft-fail: missing token / permission is fine.
+  }
+}
+
+async function upsertBanner(input: {
+  phase: GitHubProgressPhase;
+  channel: { state: GitHubChannelState };
+  options: GitHubProgressOptions;
+  banner: GitHubBannerProgress;
+  context?: string;
+}): Promise<void> {
+  const state = input.channel.state;
+  const issueNumber = state.issueNumber ?? state.pullRequestNumber;
+  if (state.owner === "" || state.repo === "" || issueNumber === null) {
+    return;
+  }
+  const body = formatGitHubOutboundComment(
+    progressPhaseCopy({
+      copy: input.banner,
+      phase: input.phase,
+      label: progressLabel(input.options, input.context),
+    })
+  );
+  const resource = {
+    api: input.options.api,
+    credentials: input.options.credentials,
+    installationId: state.installationId ?? undefined,
+    owner: state.owner,
+    repo: state.repo,
+  };
+  try {
+    if (state.progressBannerCommentId !== null) {
+      try {
+        await updateGitHubIssueComment({
+          ...resource,
+          body,
+          commentId: state.progressBannerCommentId,
+        });
+        return;
+      } catch (error) {
+        if (!(error instanceof GitHubApiError) || error.status !== 404) {
+          return;
+        }
+        // Comment gone; clear sticky id and recreate below.
+        state.progressBannerCommentId = null;
+      }
+    }
+    const posted = await createGitHubIssueComment({
+      ...resource,
+      body,
+      issueNumber,
+    });
+    state.progressBannerCommentId = posted.id;
+  } catch {
+    // Soft-fail.
+  }
+}

package/src/channels/github/state.ts

@@ -11,6 +11,8 @@ export interface GitHubChannelState extends GitHubBindingState {
   headSha: string | null;
   baseRef: string | null;
   headRef: string | null;
+  /** Sticky progress banner comment id (issue/PR timeline). */
+  progressBannerCommentId: number | null;
 }
 
 export function emptyGitHubChannelState(
@@ -32,6 +34,7 @@ export function emptyGitHubChannelState(
     headSha: null,
     baseRef: null,
     headRef: null,
+    progressBannerCommentId: null,
     ...overrides,
   };
 }

package/src/channels/github/types.ts

@@ -9,7 +9,7 @@ import type {
 } from "../../types.js";
 import type { GitHubApiOptions } from "./api.js";
 import type { GitHubHandle, GitHubThread } from "./binding.js";
-import type { GitHubProgressConfig } from "./defaults.js";
+import type { GitHubProgressConfig } from "./progress.js";
 import type { GitHubChannelState } from "./state.js";
 
 /** A credential value: a literal or a lazy resolver fetched on demand. */
@@ -171,6 +171,8 @@ export type GitHubPullRequestPayload = {
     type?: string;
   } | null;
   installation?: { id?: number } | null;
+  /** Present on `labeled` / `unlabeled` pull_request deliveries. */
+  label?: { name: string } | null;
 };
 
 /** Normalized `pull_request` event handed to {@link GitHubPullRequestHook}. */
@@ -188,6 +190,8 @@ export interface GitHubPullRequestEvent {
   /** True when the PR was merged (from the webhook payload). */
   merged: boolean;
   authorLogin?: string;
+  /** Label added/removed on `labeled` / `unlabeled` actions. */
+  label?: { name: string };
 }
 
 /** Normalized `issues` event. */
@@ -448,7 +452,7 @@ export interface GitHubChannelOptions {
          * Token capability tier:
          * - `"read"` — PR/issue/status read
          * - `"pr-write"` (default) — comments / PR+issue write, no `contents:write`
-         * - `"contents-write"` — also push code (host-held; prefer only when needed)
+         * - `"contents-write"` — push code and create commit statuses (host-held)
          */
         permissions?: "read" | "pr-write" | "contents-write";
       };
@@ -500,10 +504,14 @@ export interface GitHubChannelOptions {
   onEvent?: GitHubEventHook;
   /**
    * Override / extend default stream-event handlers (eyes reaction, reply
-   * posting). Handlers you provide replace the matching defaults.
+   * posting, opt-in commit status / banner). Handlers you provide replace
+   * the matching defaults.
    */
   events?: ChannelEventHandlers<GitHubChannelState>;
-  /** Acknowledgement progress surfaces (reactions). */
+  /**
+   * Acknowledgement progress surfaces. Reactions default on; commit status
+   * and sticky banner are opt-in via `commitStatus` / `banner`.
+   */
   progress?: GitHubProgressConfig;
   /**
    * When false, skip posting assistant / error comments back to GitHub.

package/src/channels/slack/slack-channel.ts

@@ -117,6 +117,10 @@ export function resolveDedicatedSlackHostBinding(
 /**
  * Create a Slack channel. Author as `agent/channels/slack.ts` default export.
  *
+ * Missing credentials are not an error: without a token pair (or a
+ * signed-in host for `cursorAccount`) the channel mounts idle and logs
+ * `channel idle`, so serving an agent never blocks on Slack setup.
+ *
  * When `cursorAccount` is on, `agentName` must be a single token (no
  * whitespace) — string literals with spaces fail at the type level;
  * runtime values are still checked by {@link assertSlackCursorAgentName}.

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";
@@ -104,6 +105,12 @@ export {
   fileMemoryBackend,
   memoryHook,
 } from "./memory.js";
+export type {
+  OtelConfig,
+  OtelDefinition,
+  OtelExporterConfig,
+} from "./otel.js";
+export { defineOtel } from "./otel.js";
 export type { PromptTag } from "./prompt.js";
 export { prompt } from "./prompt.js";
 export type {

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,
@@ -41,6 +41,7 @@ import {
   startRemoteEvalRun,
 } from "./evals-client.js";
 import {
+  checkInitTarget,
   formatInitNextSteps,
   formatInitScaffoldSummary,
   initNextCommands,
@@ -48,6 +49,7 @@ import {
   installScaffoldDependencies,
   linkCliOntoPath,
   printInitGuide,
+  resolveTemplate,
 } from "./init-project.js";
 import { offerInstallCursorSkills } from "./install-cursor-skills.js";
 import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
@@ -131,6 +133,7 @@ export interface AxCliOptions {
   out?: string;
   /** Scaffold target directory for `init`. */
   initTarget?: string;
+  template?: string;
   /** Tool name for `call`. */
   toolName?: string;
   /** JSON input for `call`. */
@@ -288,9 +291,23 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
     printInitGuide();
     return 0;
   }
+  let templateDir: string | undefined;
+  if (options.template !== undefined) {
+    const template = resolveTemplate(options.template);
+    if (!template.ok) {
+      process.stderr.write(`${template.message}\n`);
+      return 1;
+    }
+    templateDir = template.dir;
+  }
   const cwd = options.cwd ?? process.cwd();
   const dir = resolve(cwd, target);
-  const result = await initProject({ dir });
+  const targetCheck = checkInitTarget(dir, options.template);
+  if (!targetCheck.ok) {
+    process.stderr.write(`${targetCheck.message}\n`);
+    return 1;
+  }
+  const result = await initProject({ dir, templateDir });
   let signedIn = (await resolveApiKey()) !== undefined;
 
   // Machine-readable path: install deps (piped), never block on browser login.
@@ -307,6 +324,7 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
         {
           ok: install.ok,
           directory: result.rootDir,
+          template: options.template ?? null,
           created: result.created,
           skipped: result.skipped,
           installed: install.ok,
@@ -356,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",