@cursor/july 0.1.39 → 0.1.41

package/src/channels/slack/defaults.ts

@@ -155,6 +155,25 @@ export function buildDefaultEvents(
   const getLog = options.getLog ?? (() => defaultSlackLog);
   const strategy = createStreamDeliveryStrategy({ botToken, getLog });
 
+  const clearWorkingStatus = async (
+    channelId: string,
+    threadTs: string
+  ): Promise<void> => {
+    const result = await setThreadStatus({
+      botToken,
+      channelId,
+      threadTs,
+      status: "",
+    });
+    if (!result.ok) {
+      getLog().warn("assistant.threads.setStatus not-ok", {
+        error: result.error,
+        channel: channelId,
+        thread_ts: threadTs,
+      });
+    }
+  };
+
   return {
     async "turn.started"(event, channel) {
       const log = getLog();
@@ -366,15 +385,6 @@ export function buildDefaultEvents(
         return;
       }
 
-      const clearStatus = async (): Promise<void> => {
-        await setThreadStatus({
-          botToken,
-          channelId: state.channelId!,
-          threadTs: state.threadTs!,
-          status: "",
-        });
-      };
-
       // Empty final text: still close any open stream / clear the skeleton
       // and clear typing.
       if (event.data.text === "") {
@@ -386,7 +396,7 @@ export function buildDefaultEvents(
           });
           channel.state.streamTs = null;
         }
-        await clearStatus();
+        await clearWorkingStatus(state.channelId, state.threadTs);
         return;
       }
 
@@ -405,7 +415,7 @@ export function buildDefaultEvents(
           sessionId: event.sessionId,
         });
         if (delivered) {
-          await clearStatus();
+          await clearWorkingStatus(state.channelId, state.threadTs);
           return;
         }
       }
@@ -439,7 +449,7 @@ export function buildDefaultEvents(
         );
       }
 
-      await clearStatus();
+      await clearWorkingStatus(state.channelId, state.threadTs);
     },
 
     async "turn.completed"(event, channel) {
@@ -453,6 +463,17 @@ export function buildDefaultEvents(
 
       await strategy.cleanupOrphan({ channel });
 
+      // Always drop the assistant chip. message.completed already clears
+      // after a normal reply, but a tool-call-only finish (or a missed
+      // final assistant message) never hits that path — leaving
+      // "Working…" stuck until Slack expires it.
+      if (channel.state.channelId !== null && channel.state.threadTs !== null) {
+        await clearWorkingStatus(
+          channel.state.channelId,
+          channel.state.threadTs
+        );
+      }
+
       if (
         suggestedPrompts.length === 0 ||
         channel.state.channelId === null ||
@@ -518,12 +539,7 @@ export function buildDefaultEvents(
           );
         }
       }
-      await setThreadStatus({
-        botToken,
-        channelId: state.channelId,
-        threadTs: state.threadTs,
-        status: "",
-      });
+      await clearWorkingStatus(state.channelId, state.threadTs);
     },
   };
 }

package/src/channels/slack/dispatch.ts

@@ -10,6 +10,11 @@ import type {
 } from "../../types.js";
 import { buildSlackBinding, slackContinuationKey } from "./api.js";
 import { firstLineTitle, maybeSetThreadTitle } from "./assistant.js";
+import {
+  appendSlackAttachmentAnnotations,
+  prepareSlackAttachments,
+  SLACK_ATTACHMENT_ONLY_PROMPT,
+} from "./attachments.js";
 import type { SlackBotMentionGate } from "./bot-mentions.js";
 import type { ChannelPostWatcher } from "./channel-watch.js";
 import {
@@ -23,6 +28,7 @@ import {
   parseAppMentionEvent,
   parseChannelMessageEvent,
   parseDirectMessageEvent,
+  parseReactionAddedEvent,
 } from "./inbound.js";
 import { defaultSlackLog, type SlackLog } from "./log.js";
 import { isWholeMessageStop } from "./stop.js";
@@ -31,6 +37,7 @@ import {
   loadSlackThreadDeltaBlock,
 } from "./thread-context.js";
 import type {
+  SlackBotToken,
   SlackChannelState,
   SlackContinuationProbes,
   SlackCredentials,
@@ -41,6 +48,55 @@ import type {
 
 const FOLLOWUP_TYPING = "Saw your follow-up…";
 
+function slackUserText(message: SlackMessage, override?: string): string {
+  if (override !== undefined) {
+    return override;
+  }
+  if (message.markdown.trim().length > 0) {
+    return message.markdown;
+  }
+  if (message.files !== undefined && message.files.length > 0) {
+    return SLACK_ATTACHMENT_ONLY_PROMPT;
+  }
+  return message.markdown;
+}
+
+async function slackTurnMedia(args: {
+  message: SlackMessage;
+  decision: SlackDispatchDecision;
+  botToken: SlackBotToken | undefined;
+  log: SlackLog;
+}): Promise<{
+  userText: string;
+  workspaceFiles?: SlackDispatchDecision["workspaceFiles"];
+  images?: SlackDispatchDecision["images"];
+}> {
+  const prepared =
+    args.message.files !== undefined && args.message.files.length > 0
+      ? await prepareSlackAttachments({
+          botToken: args.botToken,
+          files: args.message.files,
+          log: args.log,
+        })
+      : undefined;
+
+  const workspaceFiles = {
+    ...args.decision.workspaceFiles,
+    ...prepared?.workspaceFiles,
+  };
+  const images = [...(args.decision.images ?? []), ...(prepared?.images ?? [])];
+
+  return {
+    userText: appendSlackAttachmentAnnotations(
+      slackUserText(args.message, args.decision.message),
+      prepared?.annotations ?? []
+    ),
+    workspaceFiles:
+      Object.keys(workspaceFiles).length > 0 ? workspaceFiles : undefined,
+    images: images.length > 0 ? images : undefined,
+  };
+}
+
 /** Blank per-session adapter state. */
 export function emptySlackChannelState(
   patch: Partial<SlackChannelState> = {}
@@ -68,6 +124,7 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
   waitUntil: (promise: Promise<unknown>) => void;
   onAppMention: SlackMessageHandler;
   onDirectMessage: SlackMessageHandler;
+  onReactionAdded?: SlackMessageHandler;
   credentials: SlackCredentials | undefined;
   eventIds: EventIdDedupe;
   host: HostContext;
@@ -117,7 +174,12 @@ function triggeringMergeMessage(
 }
 
 export async function dispatchInboundMessage(args: {
-  kind: "app_mention" | "direct_message" | "channel_post" | "block_action";
+  kind:
+    | "app_mention"
+    | "direct_message"
+    | "channel_post"
+    | "reaction_added"
+    | "block_action";
   message: SlackMessage;
   handler: SlackMessageHandler;
   send: SendMessageFn;
@@ -302,7 +364,22 @@ export async function dispatchInboundMessage(args: {
     return;
   }
 
-  const userText = decision.message ?? message.markdown;
+  const media = await slackTurnMedia({
+    message,
+    decision,
+    botToken: args.credentials?.botToken,
+    log,
+  });
+  if (message.files !== undefined && message.files.length > 0) {
+    log.info("slack attachments prepared", {
+      kind,
+      channel: message.channelId,
+      thread_ts: message.threadTs,
+      images: media.images?.length ?? 0,
+      workspace_files: Object.keys(media.workspaceFiles ?? {}).length,
+      event_id: args.eventId,
+    });
+  }
   const excludeThreadTimestamps = [
     message.ts,
     ...(decision.excludeThreadTimestamps ?? []),
@@ -347,6 +424,7 @@ export async function dispatchInboundMessage(args: {
       ...(afterTs === undefined ? {} : { after_ts: afterTs }),
     });
   }
+
   const prompt = [
     formatSlackContextBlock({
       userId: message.author?.userId ?? "",
@@ -360,7 +438,7 @@ export async function dispatchInboundMessage(args: {
     ...(threadContext === undefined ? [] : [threadContext]),
     ...(decision.context ?? []),
     "",
-    userText,
+    media.userText,
   ]
     .filter((part) => part.length > 0)
     .join("\n");
@@ -378,7 +456,8 @@ export async function dispatchInboundMessage(args: {
     }) as unknown as JsonValue,
     title: decision.title ?? `slack:${message.channelId}:${message.threadTs}`,
     workspaceDir: decision.workspaceDir,
-    workspaceFiles: decision.workspaceFiles,
+    workspaceFiles: media.workspaceFiles,
+    images: media.images,
     cloud: decision.cloud,
     sdkAgentId: decision.sdkAgentId,
   };
@@ -443,8 +522,8 @@ export async function dispatchInboundMessage(args: {
 
 /**
  * Parse an Events API body (or Socket Mode `events_api` payload) and dispatch
- * app_mention / DM handlers. Deduplicates by `event_id` when present. Returns
- * true when a handler was scheduled.
+ * app_mention / DM / reaction handlers. Deduplicates by `event_id` when
+ * present. Returns true when a handler was scheduled.
  */
 export function dispatchInboundFromEventBody(
   body: unknown,
@@ -566,6 +645,42 @@ export function dispatchInboundFromEventBody(
     return true;
   }
 
+  const reaction = parseReactionAddedEvent(body);
+  if (reaction !== null && deps.onReactionAdded !== undefined) {
+    deps.waitUntil(
+      dispatchInboundMessage({
+        kind: "reaction_added",
+        message: reaction,
+        handler: deps.onReactionAdded,
+        send: deps.send,
+        credentials: deps.credentials,
+        host: deps.host,
+        artifacts: deps.artifacts,
+        log,
+        evalCommandsEnabled: false,
+        cursorAgentName: deps.cursorAgentName,
+        blockExternals: deps.blockExternals,
+        ...(deps.hasContinuationSession === undefined
+          ? {}
+          : { hasContinuationSession: deps.hasContinuationSession }),
+        ...(deps.isContinuationBusy === undefined
+          ? {}
+          : { isContinuationBusy: deps.isContinuationBusy }),
+        ...(deps.getContinuationLastBotMessageTs === undefined
+          ? {}
+          : {
+              getContinuationLastBotMessageTs:
+                deps.getContinuationLastBotMessageTs,
+            }),
+        ...(deps.interruptContinuation === undefined
+          ? {}
+          : { interruptContinuation: deps.interruptContinuation }),
+        ...(eventId === undefined ? {} : { eventId }),
+      })
+    );
+    return true;
+  }
+
   if (deps.channelWatch !== undefined) {
     // Parse keeps bot-authored posts; the watcher enforces the per-channel
     // policy (includeBotPosts, own-post loop safety) with skip logging.

package/src/channels/slack/inbound.ts

@@ -2,6 +2,7 @@
  * Parse Slack Events API payloads into structured inbound messages.
  */
 
+import { parseSlackFileRefs } from "./attachments.js";
 import { parseDelegationMetadata } from "./bot-mentions.js";
 import { slackApiMessageBody } from "./message-body.js";
 import type { SlackAuthor, SlackMessage } from "./types.js";
@@ -69,6 +70,7 @@ function buildSlackMessage(
   const body = slackApiMessageBody(event);
   const threadTs = asString(event.thread_ts) ?? ts;
   const author = parseAuthor(event);
+  const files = parseSlackFileRefs(event);
   return {
     text,
     body,
@@ -78,6 +80,7 @@ function buildSlackMessage(
     channelId,
     ...(teamId === undefined ? {} : { teamId }),
     ...(author === undefined ? {} : { author }),
+    files,
   };
 }
 
@@ -155,6 +158,63 @@ export function parseDirectMessageEvent(body: unknown): SlackMessage | null {
   return buildSlackMessage(event, asString(root.team_id));
 }
 
+/**
+ * Parse a message `reaction_added` event into a synthetic Slack message.
+ * The reacted-to timestamp becomes the thread root so normal hydration loads
+ * the complete thread before the dedicated handler dispatches a turn.
+ */
+export function parseReactionAddedEvent(body: unknown): SlackMessage | null {
+  const root = asRecord(body);
+  if (root === null || root.type !== "event_callback") {
+    return null;
+  }
+  const event = asRecord(root.event);
+  if (event === null || event.type !== "reaction_added") {
+    return null;
+  }
+  const item = asRecord(event.item);
+  if (item === null || item.type !== "message") {
+    return null;
+  }
+  const userId = asString(event.user);
+  const reaction = asString(event.reaction);
+  const channelId = asString(item.channel);
+  const threadTs = asString(item.ts);
+  if (
+    userId === undefined ||
+    userId === "" ||
+    reaction === undefined ||
+    reaction === "" ||
+    channelId === undefined ||
+    channelId === "" ||
+    threadTs === undefined ||
+    threadTs === ""
+  ) {
+    return null;
+  }
+  const ts = asString(event.event_ts) ?? threadTs;
+  const text = `Slack user <@${userId}> added :${reaction}: to this thread.`;
+  const itemUserId = asString(event.item_user);
+  const teamId = asString(root.team_id);
+  return {
+    text,
+    body: text,
+    markdown: slackTextToMarkdown(text),
+    ts,
+    threadTs,
+    channelId,
+    ...(teamId === undefined ? {} : { teamId }),
+    author: {
+      userId,
+      isBot: false,
+    },
+    reaction: {
+      name: reaction,
+      ...(itemUserId === undefined ? {} : { itemUserId }),
+    },
+  };
+}
+
 /** Parsed `message.channels` / `message.groups` event for channel watch. */
 export type SlackChannelMessageEvent =
   | { kind: "post"; message: SlackMessage }

package/src/channels/slack/index.ts

@@ -21,6 +21,7 @@
 export * from "./api.js";
 export * from "./approvals.js";
 export * from "./assistant.js";
+export * from "./attachments.js";
 export * from "./auth.js";
 export * from "./blocks.js";
 export * from "./bot-mentions.js";

package/src/channels/slack/live-delivery.ts

@@ -183,9 +183,23 @@ export function createStreamDeliveryStrategy(
       await stopChatStream({ botToken, channel: channelId, ts: streamTs });
     },
 
-    async cleanupOrphan() {
-      // The stream path closes its message in message.completed / turn.failed;
-      // there is nothing to clean up after turn.completed.
+    async cleanupOrphan({ channel }) {
+      // message.completed / turn.failed already stop the stream. If the
+      // turn ended without a final assistant message, close it here so
+      // Slack does not leave the live reply in a streaming state.
+      const streamTs = channel.state.streamTs;
+      const channelId =
+        channel.state.streamChannelId ?? channel.state.channelId;
+      if (
+        streamTs === null ||
+        streamTs === "" ||
+        channelId === null ||
+        channelId === ""
+      ) {
+        return;
+      }
+      await stopChatStream({ botToken, channel: channelId, ts: streamTs });
+      channel.state.streamTs = null;
     },
 
     async fail({ channel, channelId, streamTs, errorText }) {

package/src/channels/slack/manifest.ts

@@ -66,6 +66,7 @@ const BOT_SCOPES = [
   "assistant:write",
   "channels:history",
   "chat:write",
+  "files:read",
   "groups:history",
   "im:history",
   "im:read",

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

@@ -187,6 +187,11 @@ export function slackChannel<const Name extends string = string>(
         "slackChannel({ cursorAccount: true }) does not support onBlockAction — interactive Block Kit clicks are not relayed over the Cursor Slack connection. Block actions are Socket Mode only."
       );
     }
+    if (options.onReactionAdded !== undefined) {
+      throw new Error(
+        "slackChannel({ cursorAccount: true }) does not support onReactionAdded because the Cursor Slack relay does not forward reaction events. Reaction handling is Socket Mode only."
+      );
+    }
   }
   const accountTransport = cursorAccount
     ? createPendingSlackApiTransport()
@@ -202,6 +207,7 @@ export function slackChannel<const Name extends string = string>(
   const defaultInbound = createDefaultOnInbound(loadingMessages, policy);
   const onAppMention = options.onAppMention ?? defaultInbound;
   const onDirectMessage = options.onDirectMessage ?? defaultInbound;
+  const onReactionAdded = options.onReactionAdded;
   const onChannelPost =
     options.onChannelPost ??
     createDefaultOnChannelPost(loadingMessages, policy);
@@ -277,6 +283,7 @@ export function slackChannel<const Name extends string = string>(
       waitUntil: args.waitUntil,
       onAppMention,
       onDirectMessage,
+      ...(onReactionAdded === undefined ? {} : { onReactionAdded }),
       credentials,
       eventIds,
       host: args.host,

package/src/channels/slack/types.ts

@@ -89,6 +89,13 @@ export interface SlackAuthor {
   botId?: string;
 }
 
+export interface SlackReactionAddedInfo {
+  /** Slack reaction name without surrounding colons. */
+  name: string;
+  /** User id of the message author, when Slack includes it. */
+  itemUserId?: string;
+}
+
 /**
  * Delegation metadata carried on bot-to-bot mention posts (Slack message
  * `metadata`, event type {@link SLACK_DELEGATION_METADATA_EVENT_TYPE}).
@@ -104,6 +111,22 @@ export interface SlackDelegationInfo {
   originSessionId?: string;
 }
 
+/** File upload on an inbound Slack message (see {@link SlackMessage.files}). */
+export interface SlackMessageFile {
+  id: string;
+  name?: string;
+  title?: string;
+  mimetype?: string;
+  filetype?: string;
+  mode?: string;
+  size?: number;
+  /**
+   * When set (cursorAccount relay), bytes were already downloaded by the
+   * Cursor backend — skip a second `files.info` / private URL fetch.
+   */
+  dataBase64?: string;
+}
+
 export interface SlackMessage {
   /** Raw top-level `text` exactly as Slack sent it. Often empty on bot posts. */
   text: string;
@@ -121,8 +144,15 @@ export interface SlackMessage {
   channelId: string;
   teamId?: string;
   author?: SlackAuthor;
+  /** Present only for a synthetic message dispatched from `reaction_added`. */
+  reaction?: SlackReactionAddedInfo;
   /** Parsed delegation metadata when the post carried it (bot mentions). */
   delegation?: SlackDelegationInfo;
+  /**
+   * Slack file uploads on this message (top-level + forwarded shares).
+   * Downloaded during dispatch into vision images / workspace files.
+   */
+  files?: SlackMessageFile[];
 }
 
 export interface SlackDispatchDecision {
@@ -144,8 +174,17 @@ export interface SlackDispatchDecision {
    * Relative path → contents written into the session workspace before the
    * first turn (new sessions only). Prefer this for host-prepared files like
    * `pr.txt` so default skill materialization stays on the session cwd.
+   * Values may be utf8 strings or `{ encoding: "base64", data }` blobs.
    */
-  workspaceFiles?: Record<string, string>;
+  workspaceFiles?: Record<
+    string,
+    string | { encoding: "base64"; data: string; mimeType?: string }
+  >;
+  /**
+   * Base64 images attached to this turn for vision (Cursor SDK `images`).
+   * Populated automatically from Slack file uploads during inbound dispatch.
+   */
+  images?: Array<{ data: string; mimeType: string }>;
   /** Session display title (new sessions only). */
   title?: string;
   /**
@@ -497,6 +536,13 @@ export interface SlackChannelOptions {
   engagement?: SlackEngagementOptions;
   onAppMention?: SlackMessageHandler;
   onDirectMessage?: SlackMessageHandler;
+  /**
+   * Handler for Socket Mode `reaction_added` events on messages. The Slack
+   * app must subscribe to `reaction_added` and have `reactions:read`.
+   * The handler receives a synthetic message whose thread timestamp is the
+   * reacted-to message and whose {@link SlackMessage.reaction} names the emoji.
+   */
+  onReactionAdded?: SlackMessageHandler;
   /**
    * Handler for watched channel posts (same contract as `onAppMention`:
    * return `null` to skip, or a {@link SlackDispatchDecision} to dispatch).

package/src/index.ts

@@ -91,6 +91,13 @@ export {
   UnknownSessionError,
   UnknownToolError,
 } from "./internal/session-engine.js";
+export { createMemoryKv, memoryCasTable } from "./kv/memory-kv.js";
+export {
+  LedgerCasExhaustedError,
+  LedgerFencedError,
+  SessionLedger,
+  supportsSessionLedgerKv,
+} from "./ledger.js";
 export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
 export {
   agentStoreMemoryBackend,
@@ -116,6 +123,7 @@ export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
 export type {
   StorageABTable,
+  StorageCasTable,
   StorageConfig,
   StorageContext,
   StorageDefinition,
@@ -140,6 +148,7 @@ export {
   isSymbolicConnectionTransport,
   MAX_RUNNING_TURNS_LIMIT,
   normalizeCursorAccountServers,
+  supportsKvCas,
 } from "./types.js";
 
 /**

package/src/internal/cli-ax.ts

@@ -46,6 +46,7 @@ import {
   initNextCommands,
   initProject,
   installScaffoldDependencies,
+  linkCliOntoPath,
   printInitGuide,
 } from "./init-project.js";
 import { offerInstallCursorSkills } from "./install-cursor-skills.js";
@@ -297,6 +298,10 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
     const install = await installScaffoldDependencies(result.rootDir, {
       stdio: "pipe",
     });
+    const linked = install.ok
+      ? await linkCliOntoPath(result.rootDir, { stdio: "pipe" })
+      : undefined;
+    const cliOnPath = linked?.ok === true;
     process.stdout.write(
       `${JSON.stringify(
         {
@@ -308,10 +313,17 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
           installError: install.ok
             ? null
             : install.stderr.trim() || `npm install exited ${install.exitCode}`,
+          cliOnPath,
+          cliLinkError:
+            install.ok && linked !== undefined && !linked.ok
+              ? linked.stderr.trim() ||
+                `npm install -g exited ${linked.exitCode}`
+              : null,
           next: initNextCommands({
             rootDir: result.rootDir,
             cwd,
             signedIn,
+            cliOnPath,
           }),
         },
         null,
@@ -333,12 +345,23 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
   });
   if (!install.ok) {
     process.stderr.write(
-      `\nnpm install failed (exit ${install.exitCode}). Fix the install, then run ${CLI_COMMAND_NAME} dev.\n`
+      `\nnpm install failed (exit ${install.exitCode}). Fix the install, then retry init.\n`
     );
     return install.exitCode || 1;
   }
   process.stdout.write("\n");
 
+  process.stdout.write(`Installing ${CLI_COMMAND_NAME} on your PATH\n\n`);
+  const linked = await linkCliOntoPath(result.rootDir, { stdio: "inherit" });
+  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`
+    );
+  } else {
+    process.stdout.write("\n");
+  }
+
   // Personal Cursor skills so coding agents can pick up create-agent / debug / …
   try {
     await offerInstallCursorSkills();
@@ -362,6 +385,7 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
       rootDir: result.rootDir,
       cwd,
       signedIn,
+      cliOnPath,
     })
   );
   return loginExit;