@cursor/july 0.1.62 → 0.1.73

package/src/channels/github/checks.ts

@@ -0,0 +1,179 @@
+/**
+ * Generic CI checks (GitHub Checks API) for agent authors.
+ *
+ * `createGitHubCheck` opens a merge-box check run on a commit and returns a
+ * handle for updating and concluding it, so an agent can report its own CI
+ * result (name, summary, and a "Details" link — e.g. the agent session run).
+ * Works with any client exposing `getOctokit()` (`ctx.github`,
+ * `ctx.host.github`), and is also reachable as `ctx.github.createCheck(...)`.
+ *
+ * Posting checks needs `checks:write`. With `cursorAccount`, declare
+ * `githubChannel({ checks: true })` so the hosted lease is minted on the
+ * `contents-write` tier; GitHub App / PAT credentials need the equivalent
+ * permission.
+ */
+
+import type { Octokit } from "@octokit/rest";
+import {
+  type GitHubCheckRunConclusion,
+  type GitHubCheckRunStatus,
+  wrapOctokitError,
+} from "./api.js";
+
+/** Any client that can hand out an authenticated Octokit. */
+export interface GitHubCheckClient {
+  getOctokit(): Promise<Octokit>;
+}
+
+/** Output shown on the check page (both fields required by GitHub). */
+export interface GitHubCheckOutput {
+  /** Heading on the check page. */
+  title: string;
+  /** Markdown body (supports links, e.g. `[View session](…)`). */
+  summary: string;
+}
+
+export interface GitHubCheckCreateInput {
+  /** Client used for every API call on the returned handle. */
+  github: GitHubCheckClient;
+  /** Repository owner login, e.g. `"acme"`. */
+  owner: string;
+  /** Repository name, e.g. `"widgets"`. */
+  repo: string;
+  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
+  name: string;
+  /** Commit the check attaches to (usually the PR head SHA). */
+  sha: string;
+  /** Initial status. Defaults to `"in_progress"`. */
+  status?: "queued" | "in_progress";
+  /** "Details" link on the check, e.g. the agent session run URL. */
+  detailsUrl?: string;
+  /** Title + markdown summary shown on the check page. */
+  output?: GitHubCheckOutput;
+}
+
+export interface GitHubCheckUpdateInput {
+  status?: GitHubCheckRunStatus;
+  conclusion?: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  output?: GitHubCheckOutput;
+}
+
+export interface GitHubCheckConcludeInput {
+  /** Final result shown in the merge box. */
+  conclusion: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  output?: GitHubCheckOutput;
+}
+
+/** A created check run. All methods throw `GitHubApiError` on API failure. */
+export interface GitHubCheck {
+  /** Check run id (for reuse across process restarts). */
+  readonly id: number;
+  /** GitHub web URL of the check run page, when returned by the API. */
+  readonly url: string | undefined;
+  /** Patch status / output / details link while the check is running. */
+  update(input: GitHubCheckUpdateInput): Promise<void>;
+  /** Complete the check with a conclusion (sets `completed_at`). */
+  conclude(input: GitHubCheckConcludeInput): Promise<void>;
+}
+
+/**
+ * Create a CI check run on a commit and return a handle for later updates.
+ *
+ * ```ts
+ * const check = await createGitHubCheck({
+ *   github: ctx.github,
+ *   owner: ctx.repository.owner,
+ *   repo: ctx.repository.name,
+ *   name: "Cursor Security Review",
+ *   sha: pr.headSha,
+ *   detailsUrl: sessionUrl,
+ *   output: { title: "Running…", summary: `[View session](${sessionUrl})` },
+ * });
+ * // …do the work…
+ * await check.conclude({ conclusion: "success", output: { … } });
+ * ```
+ */
+export async function createGitHubCheck(
+  input: GitHubCheckCreateInput
+): Promise<GitHubCheck> {
+  const octokit = await input.github.getOctokit();
+  let created: { id: number; html_url?: string | null };
+  try {
+    const response = await octokit.rest.checks.create({
+      owner: input.owner,
+      repo: input.repo,
+      name: input.name,
+      head_sha: input.sha,
+      status: input.status ?? "in_progress",
+      started_at: new Date().toISOString(),
+      details_url: input.detailsUrl,
+      output: input.output,
+    });
+    created = response.data;
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/check-runs`
+    );
+  }
+  return resumeGitHubCheck({
+    github: input.github,
+    owner: input.owner,
+    repo: input.repo,
+    name: input.name,
+    checkRunId: created.id,
+    url: typeof created.html_url === "string" ? created.html_url : undefined,
+  });
+}
+
+/**
+ * Rebuild a {@link GitHubCheck} handle for an existing check run id (e.g.
+ * after a process restart). No API call is made until the first update.
+ */
+export function resumeGitHubCheck(input: {
+  github: GitHubCheckClient;
+  owner: string;
+  repo: string;
+  name: string;
+  checkRunId: number;
+  url?: string;
+}): GitHubCheck {
+  const patch = async (update: GitHubCheckUpdateInput): Promise<void> => {
+    const octokit = await input.github.getOctokit();
+    try {
+      await octokit.rest.checks.update({
+        owner: input.owner,
+        repo: input.repo,
+        check_run_id: input.checkRunId,
+        name: input.name,
+        status: update.status,
+        conclusion: update.conclusion,
+        completed_at:
+          update.status === "completed" ? new Date().toISOString() : undefined,
+        details_url: update.detailsUrl,
+        output: update.output,
+      });
+    } catch (error) {
+      throw wrapOctokitError(
+        error,
+        "PATCH",
+        `/repos/${input.owner}/${input.repo}/check-runs/${input.checkRunId}`
+      );
+    }
+  };
+  return {
+    id: input.checkRunId,
+    url: input.url,
+    update: patch,
+    conclude: (conclude) =>
+      patch({
+        status: "completed",
+        conclusion: conclude.conclusion,
+        detailsUrl: conclude.detailsUrl,
+        output: conclude.output,
+      }),
+  };
+}

package/src/channels/github/cursor-account.ts

@@ -119,22 +119,25 @@ export function parseCursorGithubRepoScope(
 
 /**
  * Hosted `cursorAccount` mints `checks:write` on the `contents-write` tier.
- * Enabling `progress.commitStatus` opts a `pr-write` (or omitted) channel up
- * to that tier so github-proxy / `/github-token` can post Checks API runs.
- * `"read"` cannot post merge-box checks.
+ * Enabling `progress.commitStatus` or `checks: true` opts a `pr-write` (or
+ * omitted) channel up to that tier so github-proxy / `/github-token` can
+ * post Checks API runs. `"read"` cannot post merge-box checks.
  */
 export function cursorGithubPermissionsForChannel(
-  options: Pick<GitHubChannelOptions, "progress">,
+  options: Pick<GitHubChannelOptions, "progress" | "checks">,
   authored: CursorGithubPermissions | undefined = "pr-write"
 ): CursorGithubPermissions {
   const base = authored ?? "pr-write";
   const commitStatus = options.progress?.commitStatus;
-  if (commitStatus === undefined || commitStatus === false) {
+  const wantsChecks =
+    options.checks === true ||
+    (commitStatus !== undefined && commitStatus !== false);
+  if (!wantsChecks) {
     return base;
   }
   if (base === "read") {
     throw new Error(
-      'progress.commitStatus needs checks:write; cursorAccount permissions: "read" cannot post merge-box checks. Use "pr-write" or "contents-write".'
+      'progress.commitStatus / checks need checks:write; cursorAccount permissions: "read" cannot post merge-box checks. Use "pr-write" or "contents-write".'
     );
   }
   return "contents-write";

package/src/channels/github/index.ts

@@ -43,6 +43,7 @@
 export * from "./api.js";
 export * from "./auth.js";
 export * from "./binding.js";
+export * from "./checks.js";
 export * from "./defaults.js";
 export * from "./events.js";
 export * from "./forward.js";

package/src/channels/github/types.ts

@@ -546,6 +546,14 @@ export interface GitHubChannelOptions {
    * and sticky banner are opt-in via `commitStatus` / `banner`.
    */
   progress?: GitHubProgressConfig;
+  /**
+   * Declare that this channel posts its own CI checks
+   * (`ctx.github.createCheck` / `createGitHubCheck`). With `cursorAccount`,
+   * opts the minted token up to `permissions: "contents-write"` so the
+   * hosted lease includes `checks:write` — same opt-up as
+   * `progress.commitStatus`. Has no effect on App / PAT credentials.
+   */
+  checks?: boolean;
   /**
    * When false, skip posting assistant / error comments back to GitHub.
    * Defaults to true.

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

@@ -21,10 +21,11 @@ import type { SlackChannelPostsOptions, SlackMessage } from "./types.js";
 
 const CHANNEL_ID_PATTERN = /^[CG][A-Z0-9]+$/;
 
-/** Allowlist over channel ids and `#names` (names resolve lazily). */
+/** Allowlist over channel ids and `#names` (names resolve lazily), or `*`. */
 export class SlackChannelAllowlist {
   private readonly ids = new Set<string>();
   private readonly names = new Set<string>();
+  private all = false;
 
   constructor(entries: readonly string[]) {
     for (const raw of entries) {
@@ -32,7 +33,9 @@ export class SlackChannelAllowlist {
       if (entry === "") {
         continue;
       }
-      if (entry.startsWith("#")) {
+      if (entry === "*") {
+        this.all = true;
+      } else if (entry.startsWith("#")) {
         this.names.add(entry.slice(1).toLowerCase());
       } else if (CHANNEL_ID_PATTERN.test(entry)) {
         this.ids.add(entry);
@@ -44,7 +47,7 @@ export class SlackChannelAllowlist {
   }
 
   matches(channelId: string): boolean {
-    return this.ids.has(channelId);
+    return this.all || this.ids.has(channelId);
   }
 
   unresolvedNames(): string[] {

package/src/channels/slack/dispatch.ts

@@ -142,6 +142,13 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    * dropped at parse time (loop safety).
    */
   botMentionGate?: SlackBotMentionGate;
+  /**
+   * When false, do not write `assistant.threads.setStatus` on a coalesced
+   * follow-up. Defaults to `true`. Channels that report progress their own
+   * way turn this off: the chip has no owner to clear it once the default
+   * `message.completed` handler is replaced, so it lingers past the turn.
+   */
+  followUpStatus?: boolean;
   /**
    * When false, skip the built-in `eval` directive. Defaults to true when
    * `host.evals` is present.
@@ -195,6 +202,8 @@ export async function dispatchInboundMessage(args: {
   log?: SlackLog;
   eventId?: string;
   evalCommandsEnabled?: boolean;
+  /** See {@link SlackInboundDispatchDeps.followUpStatus}. Defaults to `true`. */
+  followUpStatus?: boolean;
   /**
    * cursorAccount agent display name — stripped before parsing `eval …`
    * (`OncallBuddy eval list`).
@@ -477,8 +486,9 @@ export async function dispatchInboundMessage(args: {
         event_id: args.eventId,
       }
     );
-    // Coalesce admits leave the active turn running; follow-ups drain into one
-    // boundary turn when it finishes (no mid-turn tool/hook inject).
+    // Coalesce admits leave the active turn running: the follow-up is queued
+    // for the carrier to inject at the next tool boundary, and anything it
+    // does not reach in time drains into the boundary turn instead.
     if (session.coalesced === true) {
       log.info("session busy; coalescing follow-up", {
         kind,
@@ -487,8 +497,32 @@ export async function dispatchInboundMessage(args: {
         continuation,
         event_id: args.eventId,
       });
+      // Queue it for mid-turn injection too. The carrier drains this at the
+      // running turn's next tool boundary; whatever it does not reach in time
+      // still drains into the boundary turn, deduped by sourceTs.
+      try {
+        await args.host.slackNudges?.append({
+          continuationKey: continuation,
+          sourceTs: message.ts,
+          text: media.userText,
+          ...(message.author?.userName === undefined
+            ? {}
+            : { author: message.author.userName }),
+        });
+      } catch (nudgeError) {
+        log.warn("nudge append failed", {
+          error:
+            nudgeError instanceof Error
+              ? nudgeError.message
+              : String(nudgeError),
+          continuation,
+          event_id: args.eventId,
+        });
+      }
       try {
-        await binding.thread.startTyping(FOLLOWUP_TYPING);
+        if (args.followUpStatus !== false) {
+          await binding.thread.startTyping(FOLLOWUP_TYPING);
+        }
       } catch (typingError) {
         log.error(
           `follow-up typing failed: ${
@@ -581,6 +615,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}
@@ -623,6 +658,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}
@@ -659,6 +695,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: false,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}

package/src/channels/slack/manifest.ts

@@ -29,8 +29,8 @@ export interface SlackAppManifest {
       display_name: string;
       always_online: boolean;
     };
-    assistant_view?: {
-      assistant_description: string;
+    agent_view?: {
+      agent_description: string;
       suggested_prompts: Array<{ title: string; message: string }>;
     };
     app_home?: {
@@ -69,6 +69,7 @@ const BOT_SCOPES = [
   "channels:history",
   "chat:write",
   "files:read",
+  "files:write",
   "groups:history",
   "im:history",
   "im:read",
@@ -134,9 +135,9 @@ export function buildSlackManifest(
       : options.name;
   const botName = options.botDisplayName ?? toBotDisplayName(options.name, env);
   const description = options.description ?? defaultDescription(options.name);
-  const includeAssistant = options.assistant !== false;
+  const includeAgentView = options.assistant !== false;
 
-  const botScopes = includeAssistant
+  const botScopes = includeAgentView
     ? [...BOT_SCOPES]
     : BOT_SCOPES.filter((scope) => scope !== "assistant:write");
 
@@ -163,14 +164,12 @@ export function buildSlackManifest(
         messages_tab_enabled: true,
         messages_tab_read_only_enabled: false,
       },
-      ...(includeAssistant
+      agent_view: includeAgentView
         ? {
-            assistant_view: {
-              assistant_description: description,
-              suggested_prompts: suggested,
-            },
+            agent_description: description,
+            suggested_prompts: suggested,
           }
-        : {}),
+        : undefined,
     },
     oauth_config: {
       scopes: {

package/src/channels/slack/nudge-store.ts

@@ -202,6 +202,24 @@ export class SlackNudgeStore {
     return (await this.listPending(continuationKey)).length > 0;
   }
 
+  /**
+   * How many follow-ups have reached the agent on this thread. Monotonic
+   * within a continuation, so a caller can spot a delivery by comparing two
+   * readings — unlike {@link hasUndelivered}, which races the carrier: both
+   * run at the same tool boundary, and a queued nudge drained before the
+   * first reading never looks pending at all.
+   */
+  async deliveredCount(continuationKey: string): Promise<number> {
+    if (continuationKey.trim() === "") {
+      return 0;
+    }
+    try {
+      return (await readdir(this.deliveredDir(continuationKey))).length;
+    } catch {
+      return 0;
+    }
+  }
+
   /**
    * Atomically move all pending nudges to delivered and return them.
    * Already-delivered source ts values are dropped (exactly-once).
@@ -238,6 +256,44 @@ export class SlackNudgeStore {
     return delivered;
   }
 
+  /**
+   * Settle a follow-up the caller is handling itself, so the carrier cannot
+   * inject it again. Used by the boundary drain: a follow-up the carrier did
+   * not reach becomes the next turn's prompt, and without this its pending
+   * record survives into that turn and gets injected on top of the ask it
+   * already is.
+   */
+  async markDelivered(
+    continuationKey: string,
+    sourceTs: string
+  ): Promise<void> {
+    const key = continuationKey.trim();
+    const ts = sourceTs.trim();
+    if (key === "" || ts === "") {
+      return;
+    }
+    const pending = await this.listPending(key);
+    const record = pending.find((item) => item.sourceTs === ts);
+    await mkdir(this.deliveredDir(key), { recursive: true });
+    const dest = this.deliveredPath(key, ts);
+    const tmp = `${dest}.${process.pid}.tmp`;
+    try {
+      await writeFile(
+        tmp,
+        `${JSON.stringify(record ?? { continuationKey: key, sourceTs: ts })}\n`,
+        "utf8"
+      );
+      await rename(tmp, dest);
+    } catch {
+      await rm(tmp, { force: true }).catch(() => {});
+    }
+    if (record !== undefined) {
+      await rm(join(this.pendingDir(key), `${record.id}.json`), {
+        force: true,
+      }).catch(() => {});
+    }
+  }
+
   async clear(continuationKey: string): Promise<void> {
     await rm(this.continuationDir(continuationKey), {
       recursive: true,

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

@@ -219,6 +219,7 @@ export function slackChannel<const Name extends string = string>(
   const mentionsEnabled = engagement.mentions !== false;
   const directMessagesEnabled = engagement.directMessages !== false;
   const evalCommandsEnabled = options.evalCommands !== false;
+  const followUpStatus = options.followUpStatus !== false;
   const channelPosts = engagement.channelPosts;
   if (channelPosts !== undefined) {
     const entries = channelPosts.allow.filter((entry) => entry.trim() !== "");
@@ -296,6 +297,7 @@ export function slackChannel<const Name extends string = string>(
       mentionsEnabled,
       directMessagesEnabled,
       evalCommandsEnabled,
+      followUpStatus,
       // cursorAccount: backend router already refuses externals.
       blockExternals: cursorAccount ? false : blockExternals,
       ...(args.hasContinuationSession === undefined
@@ -484,6 +486,7 @@ export function slackChannel<const Name extends string = string>(
                   artifacts: args.artifacts,
                   log: getLog(),
                   evalCommandsEnabled,
+                  followUpStatus,
                   blockExternals,
                   ...(args.hasContinuationSession === undefined
                     ? {}

package/src/channels/slack/types.ts

@@ -330,11 +330,18 @@ export type SlackBlockActionHandler = (
  */
 export interface SlackChannelPostsOptions {
   /**
-   * Channels to watch: ids (`C…` / `G…`) or `#names`. Must be non-empty
-   * (empty is a definition error). `#names` are resolved to ids via
-   * `conversations.list` when the channel starts; the bot must be a member
-   * of each watched channel to receive its messages. Socket Mode only —
-   * `cursorAccount: true` rejects `engagement.channelPosts`.
+   * Channels to watch: ids (`C…` / `G…`), `#names`, or `"*"` for every
+   * channel the bot is in. Must be non-empty (empty is a definition error).
+   * `#names` are resolved to ids via `conversations.list` when the channel
+   * starts; the bot must be a member of each watched channel to receive its
+   * messages. Socket Mode only — `cursorAccount: true` rejects
+   * `engagement.channelPosts`.
+   *
+   * `"*"` suits agents whose handler decides per message (a thread the agent
+   * is already in, say) rather than per channel. Every delivered message then
+   * reaches {@link SlackChannelOptions.onChannelPost}, and each one costs a
+   * `users.info` external-sender check first unless
+   * {@link SlackAccessPolicy.blockExternals} is off.
    */
   allow: string[];
   /**
@@ -571,6 +578,16 @@ export interface SlackChannelOptions {
    * Defaults to `true`.
    */
   thinkingSteps?: boolean;
+  /**
+   * Write Slack's assistant status chip ("Saw your follow-up…") when a
+   * follow-up coalesces into a running turn. Defaults to `true`.
+   *
+   * Set to `false` on channels that report progress themselves: the chip is
+   * cleared by the default `message.completed` handler, so a channel that
+   * replaces that handler has nothing to take it down and it outlives the
+   * turn.
+   */
+  followUpStatus?: boolean;
   /**
    * Opt in to Slack delivery for human-in-the-loop tool approvals.
    *
@@ -634,7 +651,7 @@ export interface SlackManifestOptions {
   env: "dev" | "prod";
   /** Optional short description shown in the Slack app. */
   description?: string;
-  /** Include `assistant_view` + `assistant:write` for typing status. */
+  /** Include `agent_view` + `assistant:write` for typing status. */
   assistant?: boolean;
   /**
    * Enable Slack interactivity (needed for Approve/Deny cards).
@@ -646,7 +663,7 @@ export interface SlackManifestOptions {
    * channel watch (`engagement.channelPosts`). Defaults to `false`.
    */
   channelPosts?: boolean;
-  /** Seed suggested prompts into the manifest `assistant_view`. */
+  /** Seed suggested prompts into the manifest `agent_view`. */
   suggestedPrompts?: Array<{ title: string; message: string }>;
   /**
    * Emit `settings.managed_app_settings`. Defaults to `true` — Cursor

package/src/connections.ts

@@ -4,7 +4,8 @@
  * A connection gives tools from an external MCP server. The filename
  * becomes the connection (server) name. Available to the agent (SDK
  * `mcpServers`), host (`ctx.host.mcp`), and channel/schedule handlers.
- * Pass `hostOnly: true` to keep it off the model (still on `host.mcp`).
+ * Pass `advertiseTools: true` for named tools on local turns. Pass
+ * `hostOnly: true` to keep it off the model (still on `host.mcp`).
  *
  * ```ts
  * import { defineConnection } from "@anysphere/agent-serve/connections";
@@ -42,13 +43,24 @@
  * to be signed in (`agent-serve login` or `CURSOR_API_KEY`):
  *
  * ```ts
- * // agent/mcp-connections/cursor.ts — every connected server (no allowlist)
- * export default defineConnection({ cursorAccount: true });
+ * // agent/mcp-connections/account.ts — every connected server (no allowlist)
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   advertiseTools: true,
+ * });
  * // equivalent explicit form:
- * export default defineConnection({ cursorAccount: true, servers: "*" });
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   servers: "*",
+ *   advertiseTools: true,
+ * });
  *
  * // or restrict to specific connectors by name
- * export default defineConnection({ cursorAccount: true, servers: ["Linear"] });
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   servers: ["Linear"],
+ *   advertiseTools: true,
+ * });
  * ```
  *
  * A **peer MCP connection** addresses another agent mounted on the same serve

package/src/index.ts

@@ -132,6 +132,8 @@ export type {
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
 export type {
+  DurableSessionRecord,
+  DurableSessionSummary,
   StorageABTable,
   StorageCasTable,
   StorageConfig,
@@ -144,8 +146,11 @@ export type {
 } from "./storage.js";
 export {
   defineStorage,
+  isDurableSessionRecordKey,
+  parseDurableSessionRecord,
   STORAGE_KEY_ROOT,
   storageKeys,
+  summarizeDurableSessionRecord,
 } from "./storage.js";
 export { defineTool } from "./tools.js";
 export type * from "./types.js";