@cursor/july 0.1.42 → 0.1.43

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. */
@@ -448,7 +448,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 +500,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/index.ts

@@ -104,6 +104,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

@@ -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,

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,
   };
 }
@@ -1718,6 +1721,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 +1992,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 +2020,7 @@ async function importDefault(
     | "ab"
     | "storage"
     | "artifacts"
+    | "otel"
 ): Promise<unknown> {
   let mod: Record<string, unknown>;
   try {
@@ -2008,10 +2035,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 +2049,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"],
 ];