@cursor/july 0.1.17 → 0.1.18

package/src/internal/builtin-tools/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Built-in tools (`AgentConfig.builtinTools`): framework-provided
+ * model-facing tools, materialized as ordinary server tools at discovery
+ * time so turns, direct calls, `info`, and the playground treat them
+ * exactly like authored tools.
+ */
+
+import type {
+  BuiltinToolsConfig,
+  DiscoveredTool,
+  ToolDefinition,
+} from "../../types.js";
+import { toolInputJsonSchema } from "../json-schema.js";
+import { reminderTools } from "./reminders.js";
+
+/** Resolve the enabled built-in tools, in stable catalog order. */
+export function builtinTools(
+  config: BuiltinToolsConfig | undefined
+): DiscoveredTool[] {
+  const tools: DiscoveredTool[] = [];
+  if (config?.reminders === true) {
+    tools.push(...toDiscovered(reminderTools));
+  }
+  return tools;
+}
+
+function toDiscovered(
+  byName: Record<string, ToolDefinition>
+): DiscoveredTool[] {
+  return Object.entries(byName).map(([name, definition]) => ({
+    name,
+    description: definition.description,
+    inputSchema: toolInputJsonSchema(definition.inputSchema),
+    execution: "server",
+    needsApproval:
+      definition.needsApproval === true ||
+      typeof definition.needsApproval === "function",
+    definition,
+  }));
+}

package/src/internal/builtin-tools/reminders.ts

@@ -0,0 +1,158 @@
+/**
+ * Built-in reminder tools (`builtinTools: { reminders: true }`): durable
+ * wakes bound to the current conversation over `host.reminders`. The
+ * framework's reminder fire prompt tells the model to call
+ * `reminders_cancel` by name, so these tool names must not change.
+ */
+
+import { z } from "zod";
+import { defineTool } from "../../tools.js";
+import type {
+  ReminderHostApi,
+  ReminderInfo,
+  ToolContext,
+  ToolDefinition,
+} from "../../types.js";
+import { parseDuration } from "../duration.js";
+
+/** Floor for model-armed recurring wakes: each fire spends a model turn. */
+const MIN_EVERY_MS = 60_000;
+
+function api(ctx: ToolContext): ReminderHostApi {
+  const reminders = ctx.host.reminders;
+  if (reminders === undefined) {
+    throw new Error("Reminders are disabled on this host.");
+  }
+  return reminders;
+}
+
+function conversation(ctx: ToolContext): {
+  channelId: string;
+  continuationToken: string;
+} {
+  const token = ctx.session.continuationKey;
+  if (token == null) {
+    throw new Error(
+      "This session is not bound to a followable conversation; reminders cannot wake it."
+    );
+  }
+  return { channelId: ctx.session.channelId, continuationToken: token };
+}
+
+/** Reminders visible to this conversation (tokens are channel-local). */
+async function listMine(
+  ctx: ToolContext,
+  status?: ReminderInfo["status"]
+): Promise<ReminderInfo[]> {
+  const conv = conversation(ctx);
+  const all = await api(ctx).list({
+    status,
+    continuationToken: conv.continuationToken,
+  });
+  return all.filter((r) => r.channelId === conv.channelId);
+}
+
+function toResult(r: ReminderInfo) {
+  return {
+    reminderId: r.id,
+    purpose: r.purpose,
+    schedule: `${r.scheduleKind} ${r.scheduleValue}`,
+    nextFireAt: r.nextFireAt,
+    until: r.untilPrompt,
+  };
+}
+
+const create = defineTool({
+  description:
+    "Set a reminder for yourself in this conversation. When it fires, your prompt returns here as a follow-up turn. Use it to re-check state that needs time to settle. One-shot (delay) or recurring (every).",
+  inputSchema: z.object({
+    prompt: z
+      .string()
+      .min(1)
+      .describe(
+        "What to do when you wake. Keep it generic ('re-check CI and report only if the status changed') and re-read live state on wake instead of replaying stale details."
+      ),
+    delay: z
+      .string()
+      .optional()
+      .describe(
+        'One-shot: wake once after this duration, e.g. "20m" or "2h". Provide exactly one of delay or every.'
+      ),
+    every: z
+      .string()
+      .optional()
+      .describe(
+        'Recurring: wake at this interval, e.g. "30m", until cancelled or the stop condition is met. Provide exactly one of delay or every.'
+      ),
+    purpose: z
+      .string()
+      .min(1)
+      .max(64)
+      .optional()
+      .describe(
+        'Short slug naming the reminder, e.g. "ci_recheck". Defaults to "follow_up".'
+      ),
+    until: z
+      .string()
+      .optional()
+      .describe(
+        "Recurring only: plain-language stop condition you will honor by calling reminders_cancel, e.g. 'Cancel once CI is green or the PR is merged.'"
+      ),
+  }),
+  async execute(input, ctx) {
+    if ((input.delay !== undefined) === (input.every !== undefined)) {
+      throw new Error("Provide exactly one of delay or every.");
+    }
+    if (
+      input.every !== undefined &&
+      parseDuration(input.every) < MIN_EVERY_MS
+    ) {
+      throw new Error('Recurring reminders must use every >= "1m".');
+    }
+    const conv = conversation(ctx);
+    const reminder = await api(ctx).create({
+      purpose: input.purpose ?? "follow_up",
+      channelId: conv.channelId,
+      continuationToken: conv.continuationToken,
+      prompt: input.prompt,
+      delay: input.delay,
+      every: input.every,
+      until: input.until,
+    });
+    return toResult(reminder);
+  },
+});
+
+const list = defineTool({
+  description:
+    "List the armed reminders bound to this conversation. Check before arming duplicates.",
+  inputSchema: z.object({}),
+  async execute(_input, ctx) {
+    return { reminders: (await listMine(ctx, "armed")).map(toResult) };
+  },
+});
+
+const cancel = defineTool({
+  description:
+    "Cancel one of this conversation's reminders by id, the moment its stop condition is met or it is no longer needed.",
+  inputSchema: z.object({
+    id: z
+      .string()
+      .min(1)
+      .describe("Reminder id from reminders_create or reminders_list."),
+  }),
+  async execute(input, ctx) {
+    const mine = (await listMine(ctx)).find((r) => r.id === input.id);
+    if (mine === undefined) {
+      throw new Error(`No reminder "${input.id}" in this conversation.`);
+    }
+    const cancelled = await api(ctx).cancel(input.id);
+    return { reminderId: input.id, status: cancelled?.status ?? "cancelled" };
+  },
+});
+
+export const reminderTools: Record<string, ToolDefinition> = {
+  reminders_create: create,
+  reminders_list: list,
+  reminders_cancel: cancel,
+};

package/src/internal/cli-slack.ts

@@ -198,6 +198,9 @@ async function runManifest(options: SlackCliOptions): Promise<number> {
   const name = options.name ?? basename(dir);
   const pair = buildSlackManifestPair({
     name,
+    // These files are pasted into api.slack.com by hand, so they must not
+    // carry the manager-token-only managed_app_settings block.
+    managedByCursor: false,
     ...(options.channelPosts === true ? { channelPosts: true } : {}),
   });
 
@@ -488,6 +491,14 @@ interface ConnectWaitTarget {
   notConnectedAt?: string;
 }
 
+/** "Name (T0123ABCD)", or the bare id when the backend has no name. */
+function formatWorkspace(workspace: SlackConnectedWorkspace): string {
+  const name = workspace.slackTeamName ?? "";
+  return name === ""
+    ? workspace.slackTeamId
+    : `${name} (${workspace.slackTeamId})`;
+}
+
 function matchConnectedWorkspace(
   workspaces: SlackConnectedWorkspace[],
   wait: ConnectWaitTarget
@@ -522,7 +533,9 @@ async function runConnectFlow(
     return renderSlackApiError(error, ctx.err);
   }
   ctx.err(
-    `\nConnect your Slack workspace to Cursor — approve in the browser:\n\n  ${url}\n\n(waiting for the Slack consent to complete, up to ${Math.round(ctx.pollTimeoutMs / 60_000)} minutes)\n`
+    `\nConnect your Slack workspace to Cursor — approve in the browser:\n\n  ${url}\n\n` +
+      `After approving in Slack you land on cursor.com, which links the workspace to your Cursor account — sign in there if the browser is not already signed in as you.\n\n` +
+      `(waiting for the Slack consent to complete, up to ${Math.round(ctx.pollTimeoutMs / 60_000)} minutes)\n`
   );
   ctx.openBrowserImpl(url);
   const deadline = Date.now() + ctx.pollTimeoutMs;
@@ -559,7 +572,7 @@ async function runConnectFlow(
     }
     if (Date.now() >= deadline) {
       ctx.err(
-        `Timed out waiting for the Slack workspace connection. The consent link stays valid for ~10 minutes — approve it and re-run \`${CLI} slack create\`.\n`
+        `Timed out waiting for the Slack workspace connection. The consent link stays valid for ~10 minutes — approve it, finish the sign-in on cursor.com, then re-run \`${CLI} slack create\`.\n`
       );
       return 1;
     }
@@ -611,7 +624,7 @@ export async function cmdSlackCreate(
         status.workspaces
           .map(
             (candidate) =>
-              `  - ${candidate.slackTeamId} (Slack user ${candidate.slackUserId}, connected ${candidate.connectedAt})\n`
+              `  - ${formatWorkspace(candidate)} (Slack user ${candidate.slackUserId}, connected ${candidate.connectedAt})\n`
           )
           .join("") +
         `Pass --slack-team <id> to pick one.\n`
@@ -647,8 +660,8 @@ export async function cmdSlackCreate(
   });
   const manifestJson = JSON.stringify(manifest);
 
-  // One connect-and-retry for not_connected / insufficient_scopes (both
-  // are fixed by a fresh consent grant).
+  // One connect-and-retry for not_connected / insufficient_scopes /
+  // manager_reauth_required (all fixed by a fresh consent grant).
   let result: SlackAppProvisionResult;
   let connectRetried = false;
   for (;;) {
@@ -667,12 +680,14 @@ export async function cmdSlackCreate(
       if (
         error instanceof SlackProvisionApiError &&
         (error.code === "not_connected" ||
-          error.code === "insufficient_scopes") &&
+          error.code === "insufficient_scopes" ||
+          error.code === "manager_reauth_required") &&
         !connectRetried
       ) {
         connectRetried = true;
-        // Both codes arrive holding a row that GET /status already lists, so
-        // the poll waits for a fresh grant instead of re-matching that row.
+        // All three codes arrive holding a row that GET /status already
+        // lists, so the poll waits for a fresh grant instead of re-matching
+        // that row.
         const wait: ConnectWaitTarget = {
           slackTeamId: workspace.slackTeamId,
           notConnectedAt: workspace.connectedAt,
@@ -681,6 +696,10 @@ export async function cmdSlackCreate(
           ctx.err(
             `The Slack connection is missing scopes provisioning needs; approving the consent link again grants them.\n`
           );
+        } else if (error.code === "manager_reauth_required") {
+          ctx.err(
+            `Slack revoked Cursor's authorization for workspace ${workspace.slackTeamId}; re-approving the consent link restores it.\n`
+          );
         } else {
           ctx.err(
             `The Slack workspace is not connected to Cursor; starting the connect flow.\n`
@@ -1119,8 +1138,7 @@ function renderCreateProvisionError(
       );
       return 1;
     default:
-      err(`${error.message}\n`);
-      return 1;
+      return renderSlackApiError(error, err);
   }
 }
 
@@ -1128,11 +1146,17 @@ function renderSlackApiError(
   error: unknown,
   err: (text: string) => void
 ): number {
-  if (error instanceof SlackProvisionApiError) {
-    err(`${error.message}\n`);
-    return 1;
+  if (!(error instanceof SlackProvisionApiError)) {
+    throw error;
   }
-  throw error;
+  err(
+    error.code === "manager_reauth_required"
+      ? // There is no standalone connect command: create runs the consent
+        // flow before provisioning.
+        `${error.message}\nRe-approve the Slack consent by re-running \`${CLI} slack create\`, which reconnects the workspace first.\n`
+      : `${error.message}\n`
+  );
+  return 1;
 }
 
 async function fileExists(path: string): Promise<boolean> {

package/src/internal/cursor-event-relay.ts

@@ -18,6 +18,29 @@ import {
 
 export { RelayOffsetStore };
 
+/**
+ * Comment snapshot from scm-events compact metadata. Carries what the GitHub
+ * channel's `issue_comment` / `pull_request_review_comment` Zod schemas
+ * require so relayed comment wakes parse without re-fetching the comment.
+ */
+export type CursorScmCommentMeta = {
+  id: number;
+  body: string;
+  htmlUrl: string;
+  authorLogin?: string;
+  /**
+   * GitHub `user.type` ("User", "Bot", …). Carried onto the stubbed
+   * `comment.user` / `sender` so `isGitHubAppBotAuthor` keeps recognizing
+   * the agent's own comments on the relay path (self/bot-loop gate).
+   */
+  authorType?: string;
+  /** Review comments only. */
+  path?: string;
+  line?: number;
+  pullRequestReviewId?: number;
+  inReplyToId?: number;
+};
+
 /** PR snapshot from scm-events compact metadata (Sand-style; no raw body). */
 export type CursorScmPullRequestMeta = {
   number: number;
@@ -53,6 +76,11 @@ export interface CursorScmEvent {
    * stub a Zod-valid GitHub `pull_request` webhook body.
    */
   pullRequest?: CursorScmPullRequestMeta;
+  /**
+   * Comment snapshot when the backend saw `body.comment`. Enough to stub a
+   * Zod-valid `issue_comment` / `pull_request_review_comment` webhook body.
+   */
+  comment?: CursorScmCommentMeta;
   /** GitHub-side event time from the payload, when present. */
   occurredAtMs?: number;
 }
@@ -114,6 +142,8 @@ export function formatCursorScmEventLog(event: {
  * Minimal GitHub webhook body from an SCM-events metadata envelope.
  * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
  * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
+ * When `comment` is present, emits a Zod-valid `comment` object so relayed
+ * `issue_comment` / `pull_request_review_comment` deliveries dispatch.
  */
 export function scmMetadataToGitHubPayload(event: {
   repo: string;
@@ -121,6 +151,7 @@ export function scmMetadataToGitHubPayload(event: {
   prNumber?: number;
   prUrl?: string;
   pullRequest?: CursorScmPullRequestMeta;
+  comment?: CursorScmCommentMeta;
 }): Record<string, unknown> {
   const slash = event.repo.indexOf("/");
   const owner = slash === -1 ? "" : event.repo.slice(0, slash);
@@ -143,6 +174,42 @@ export function scmMetadataToGitHubPayload(event: {
   };
   payload.action = event.action;
 
+  const commentMeta = event.comment;
+  if (commentMeta !== undefined) {
+    const comment: Record<string, unknown> = {
+      id: commentMeta.id,
+      body: commentMeta.body,
+      html_url: commentMeta.htmlUrl,
+    };
+    if (commentMeta.authorLogin !== undefined) {
+      const author: Record<string, unknown> = {
+        login: commentMeta.authorLogin,
+      };
+      if (commentMeta.authorType !== undefined) {
+        // Without user.type the isGitHubAppBotAuthor gate fails open and the
+        // agent's own relayed comments could wake it again (bot loop).
+        author.type = commentMeta.authorType;
+      }
+      comment.user = author;
+      // The comment author is the closest thing the envelope has to the
+      // webhook sender; channels use it for self/bot-loop gates.
+      payload.sender = { ...author };
+    }
+    if (commentMeta.path !== undefined) {
+      comment.path = commentMeta.path;
+    }
+    if (commentMeta.line !== undefined) {
+      comment.line = commentMeta.line;
+    }
+    if (commentMeta.pullRequestReviewId !== undefined) {
+      comment.pull_request_review_id = commentMeta.pullRequestReviewId;
+    }
+    if (commentMeta.inReplyToId !== undefined) {
+      comment.in_reply_to_id = commentMeta.inReplyToId;
+    }
+    payload.comment = comment;
+  }
+
   const title = prMeta?.title;
   const headRef = prMeta?.headRef;
   const headSha = prMeta?.headSha;

package/src/internal/discovery.ts

@@ -26,6 +26,8 @@ import {
   type AgentHostingOptions,
   type AgentProject,
   type AgentProjectInfo,
+  type AgentRuntime,
+  type BuiltinToolsConfig,
   type ChannelDefinition,
   type ConnectionDefinition,
   type ConnectionTransport,
@@ -56,6 +58,7 @@ 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 { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import {
@@ -341,6 +344,13 @@ async function loadAgent(
   // warn that they exist.
   if (!options.isRoot) {
     await warnUnsupportedSubagentSlots(ctx, agentDir);
+    if (config?.builtinTools !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: "builtinTools is not supported on subagents; ignoring.",
+      });
+    }
     return {
       name,
       ...(config?.description === undefined
@@ -401,6 +411,8 @@ async function loadAgent(
     });
   }
 
+  appendBuiltinTools(ctx, agentDir, tools, config?.builtinTools, runtime);
+
   return {
     name,
     description: config?.description,
@@ -1161,6 +1173,46 @@ async function warnUnsupportedSubagentSlots(
   }
 }
 
+/**
+ * Append enabled built-in tools after authored tools. Authored tools with
+ * the same name win; built-ins are server tools, so cloud runtimes get a
+ * warning instead of tools.
+ */
+function appendBuiltinTools(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  tools: DiscoveredTool[],
+  config: BuiltinToolsConfig | undefined,
+  runtime: AgentRuntime
+): void {
+  const builtin = builtinTools(config);
+  if (builtin.length === 0) {
+    return;
+  }
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  if (runtime === "cloud") {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: agentPath,
+      message:
+        "builtinTools are in-process server tools and are not available on cloud agents; they are skipped.",
+    });
+    return;
+  }
+  const authored = new Set(tools.map((tool) => tool.name));
+  for (const tool of builtin) {
+    if (authored.has(tool.name)) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: agentPath,
+        message: `Authored tool "${tool.name}" shadows the built-in tool of the same name; the authored tool wins.`,
+      });
+      continue;
+    }
+    tools.push(tool);
+  }
+}
+
 function warnCloudRuntimeLimitations(
   ctx: DiscoveryContext,
   agentDir: string,

package/src/internal/reminder-runner.ts

@@ -336,6 +336,36 @@ export class ReminderRunner {
     return n;
   }
 
+  /**
+   * Re-key armed reminders when a channel rotates a session's continuation
+   * token (the built-in HTTP channel rotates after every follow-up). Without
+   * this, a reminder armed before the rotation misses its session at fire
+   * time and disarms as `session_gone`.
+   */
+  async rekeyContinuation(
+    channelId: string,
+    oldToken: string,
+    newToken: string
+  ): Promise<number> {
+    const armed = await this.store.listArmed();
+    let n = 0;
+    for (const record of armed) {
+      if (
+        record.channelId !== channelId ||
+        record.continuationToken !== oldToken
+      ) {
+        continue;
+      }
+      await this.persist({
+        ...record,
+        continuationToken: newToken,
+        updatedAt: new Date().toISOString(),
+      });
+      n += 1;
+    }
+    return n;
+  }
+
   /** Fire one reminder immediately (dev / hillclimb). */
   async dispatch(reminderId: string): Promise<{
     reminderId: string;