@cursor/july 0.1.16 → 0.1.18

package/src/channels/slack/dispatch.ts

@@ -25,6 +25,7 @@ import {
 } from "./thread-context.js";
 import type {
   SlackChannelState,
+  SlackContinuationProbes,
   SlackCredentials,
   SlackDispatchDecision,
   SlackMessage,
@@ -55,7 +56,7 @@ export function emptySlackChannelState(
   };
 }
 
-export interface SlackInboundDispatchDeps {
+export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
   send: SendMessageFn;
   waitUntil: (promise: Promise<unknown>) => void;
   onAppMention: SlackMessageHandler;
@@ -70,22 +71,6 @@ export interface SlackInboundDispatchDeps {
   directMessagesEnabled?: boolean;
   /** Opt-in channel watch; absent = channel posts are ignored. */
   channelWatch?: ChannelPostWatcher;
-  /**
-   * When set, full-thread hydration runs only for cold-start turns (no
-   * existing session). Warm turns load a `<slack_thread_delta>` instead.
-   */
-  hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
-  /** True when a turn is already running for this Slack continuation. */
-  isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
-  /**
-   * Warm-delta watermark from session channel state (`lastBotMessageTs`).
-   * When absent, delta falls back to the last matching bot post in-thread.
-   */
-  getContinuationLastBotMessageTs?: (
-    continuationToken: string
-  ) => Promise<string | undefined>;
-  /** Cancel the active turn + clear coalesced nudges for this continuation. */
-  interruptContinuation?: (continuationToken: string) => Promise<boolean>;
   /**
    * When false, skip the built-in `eval` directive. Defaults to true when
    * `host.evals` is present.
@@ -106,12 +91,14 @@ function triggeringMergeMessage(
     ...(message.author?.botId === undefined
       ? {}
       : { bot_id: message.author.botId }),
-    text: message.text,
+    // Flattened body, so this stand-in matches what the real API record
+    // reduces to and is not dropped as empty by the thread-context filters.
+    text: message.body,
   };
 }
 
 export async function dispatchInboundMessage(args: {
-  kind: "app_mention" | "direct_message" | "channel_post";
+  kind: "app_mention" | "direct_message" | "channel_post" | "block_action";
   message: SlackMessage;
   handler: SlackMessageHandler;
   send: SendMessageFn;

package/src/channels/slack/inbound.ts

@@ -2,6 +2,7 @@
  * Parse Slack Events API payloads into structured inbound messages.
  */
 
+import { slackApiMessageBody } from "./message-body.js";
 import type { SlackAuthor, SlackMessage } from "./types.js";
 
 type JsonRecord = Record<string, unknown>;
@@ -62,11 +63,15 @@ function buildSlackMessage(
     return null;
   }
   const text = asString(event.text) ?? "";
+  // Alert feeds post an empty top-level `text` with the notification in
+  // `attachments` / `blocks`, so `body` (not `text`) is the message content.
+  const body = slackApiMessageBody(event);
   const threadTs = asString(event.thread_ts) ?? ts;
   const author = parseAuthor(event);
   return {
     text,
-    markdown: slackTextToMarkdown(text),
+    body,
+    markdown: slackTextToMarkdown(body),
     ts,
     threadTs,
     channelId,

package/src/channels/slack/index.ts

@@ -22,6 +22,7 @@ export * from "./api.js";
 export * from "./approvals.js";
 export * from "./assistant.js";
 export * from "./auth.js";
+export * from "./blocks.js";
 export * from "./channel-watch.js";
 export * from "./constants.js";
 export * from "./credentials.js";
@@ -37,6 +38,7 @@ export * from "./interactive.js";
 export * from "./links.js";
 export * from "./log.js";
 export * from "./manifest.js";
+export * from "./message-body.js";
 export * from "./nudge-carrier.js";
 export * from "./nudge-store.js";
 export * from "./pr-ref.js";

package/src/channels/slack/init.ts

@@ -81,6 +81,9 @@ ${envPrefixLine}  // Streaming and thinking steps default to true.
 
   const pair = buildSlackManifestPair({
     name,
+    // Scaffolded for hand-import at api.slack.com; managed_app_settings is
+    // settable only with the manager app's user token.
+    managedByCursor: false,
     ...(options.description === undefined
       ? {}
       : { description: options.description }),

package/src/channels/slack/interactive.ts

@@ -1,17 +1,33 @@
 /**
- * Socket Mode interactive payloads (Block Kit Approve/Deny).
+ * Socket Mode interactive payloads (Block Kit clicks).
+ *
+ * Built-in tool-approval Approve/Deny actions resolve parked calls
+ * ({@link dispatchInteractiveFromPayload}); everything else can be routed
+ * to an author handler ({@link dispatchBlockAction} via
+ * `slackChannel({ onBlockAction })`).
  */
 
 import type {
   ApprovalDecision,
   AuthContext,
   ChannelSession,
+  HostContext,
   PendingApproval,
+  SendMessageFn,
 } from "../../types.js";
+import { updateMessage } from "./api.js";
 import { decisionFromActionId, parseApprovalActionValue } from "./approvals.js";
 import { buildSlackInteractiveApprovalAuth } from "./auth.js";
+import { dispatchInboundMessage } from "./dispatch.js";
 import { defaultSlackLog, type SlackLog } from "./log.js";
-import type { SlackCredentials } from "./types.js";
+import type {
+  SlackBlockAction,
+  SlackBlockActionHandler,
+  SlackBotToken,
+  SlackContinuationProbes,
+  SlackCredentials,
+  SlackMessage,
+} from "./types.js";
 
 export interface SlackInteractiveDispatchDeps {
   credentials: SlackCredentials | undefined;
@@ -35,7 +51,7 @@ export async function dispatchInteractiveFromPayload(
   deps: SlackInteractiveDispatchDeps
 ): Promise<boolean> {
   const log = deps.log ?? defaultSlackLog;
-  const parsed = parseBlockActionsPayload(payload);
+  const parsed = parseSlackBlockAction(payload);
   if (parsed === null) {
     return false;
   }
@@ -124,16 +140,14 @@ export async function dispatchInteractiveFromPayload(
   return true;
 }
 
-interface ParsedBlockAction {
-  actionId: string;
-  value: string;
-  channelId: string;
-  threadTs: string;
-  userId: string;
-  messageTs: string;
-}
-
-function parseBlockActionsPayload(payload: unknown): ParsedBlockAction | null {
+/**
+ * Parse a Socket Mode `block_actions` payload into a {@link SlackBlockAction}.
+ * Returns null for non-`block_actions` payloads (view submissions, shortcuts)
+ * and malformed bodies.
+ */
+export function parseSlackBlockAction(
+  payload: unknown
+): SlackBlockAction | null {
   if (typeof payload !== "object" || payload === null) {
     return null;
   }
@@ -150,10 +164,7 @@ function parseBlockActionsPayload(payload: unknown): ParsedBlockAction | null {
     return null;
   }
   const action = first as Record<string, unknown>;
-  if (
-    typeof action.action_id !== "string" ||
-    typeof action.value !== "string"
-  ) {
+  if (typeof action.action_id !== "string") {
     return null;
   }
 
@@ -169,6 +180,10 @@ function parseBlockActionsPayload(payload: unknown): ParsedBlockAction | null {
     typeof record.user === "object" && record.user !== null
       ? (record.user as Record<string, unknown>)
       : {};
+  const team =
+    typeof record.team === "object" && record.team !== null
+      ? (record.team as Record<string, unknown>)
+      : {};
 
   const channelId = typeof channel.id === "string" ? channel.id : "";
   const messageTs = typeof message.ts === "string" ? message.ts : "";
@@ -182,13 +197,163 @@ function parseBlockActionsPayload(payload: unknown): ParsedBlockAction | null {
         ? (record.container as { thread_ts: string }).thread_ts
         : messageTs;
   const userId = typeof user.id === "string" ? user.id : "";
+  const userName =
+    typeof user.username === "string"
+      ? user.username
+      : typeof user.name === "string"
+        ? user.name
+        : undefined;
+  const teamId =
+    typeof team.id === "string"
+      ? team.id
+      : typeof user.team_id === "string"
+        ? user.team_id
+        : undefined;
+  const label =
+    typeof action.text === "object" &&
+    action.text !== null &&
+    typeof (action.text as { text?: unknown }).text === "string"
+      ? (action.text as { text: string }).text
+      : undefined;
+  const actionTs = typeof action.action_ts === "string" ? action.action_ts : "";
+  const messageBlocks = Array.isArray(message.blocks)
+    ? message.blocks
+    : undefined;
 
   return {
     actionId: action.action_id,
-    value: action.value,
+    blockId: typeof action.block_id === "string" ? action.block_id : "",
+    value: typeof action.value === "string" ? action.value : "",
+    label,
     channelId,
     threadTs,
-    userId,
     messageTs,
+    messageBlocks,
+    userId,
+    userName,
+    teamId,
+    actionTs,
   };
 }
+
+/**
+ * Swap the clicked message's actions row for a context note (`chat.update`).
+ * Strips only the row the click came from (`action.blockId`); every other
+ * block survives. Soft: false when the payload carried no message blocks or
+ * the update failed — callers treat the dispatched turn as the durable
+ * record and the card as best-effort UI.
+ */
+export async function resolveBlockActionCard(args: {
+  botToken: SlackBotToken | undefined;
+  action: SlackBlockAction;
+  note: string;
+}): Promise<boolean> {
+  const { action, note } = args;
+  if (action.messageBlocks === undefined) {
+    return false;
+  }
+  const clicked = (block: unknown): boolean =>
+    typeof block === "object" &&
+    block !== null &&
+    (block as { type?: unknown }).type === "actions" &&
+    (block as { block_id?: unknown }).block_id === action.blockId;
+  const result = await updateMessage({
+    botToken: args.botToken,
+    channel: action.channelId,
+    ts: action.messageTs,
+    text: note,
+    blocks: [
+      ...action.messageBlocks.filter((block) => !clicked(block)),
+      { type: "context", elements: [{ type: "mrkdwn", text: note }] },
+    ],
+  });
+  return result.ok;
+}
+
+export interface SlackBlockActionDispatchDeps extends SlackContinuationProbes {
+  handler: SlackBlockActionHandler;
+  send: SendMessageFn;
+  credentials: SlackCredentials | undefined;
+  host: HostContext;
+  log?: SlackLog;
+}
+
+/**
+ * The click as an inbound-message stand-in: the synthetic ts is the click's
+ * `action_ts` (unique per click, never a real thread message), so ask-dedupe
+ * claims and `<slack_thread>` exclusions stay per-click.
+ */
+function blockActionAsMessage(action: SlackBlockAction): SlackMessage {
+  const text = `[clicked: ${action.label ?? action.actionId}]`;
+  return {
+    text,
+    body: text,
+    markdown: text,
+    ts: action.actionTs,
+    threadTs: action.threadTs,
+    channelId: action.channelId,
+    teamId: action.teamId,
+    author: {
+      userId: action.userId,
+      userName: action.userName,
+      isBot: false,
+    },
+  };
+}
+
+/**
+ * Route a non-approval `block_actions` payload to the author handler and
+ * dispatch its decision as a turn on the click's thread. Returns true when
+ * the payload was a block action (dispatched or deliberately skipped).
+ */
+export async function dispatchBlockAction(
+  payload: unknown,
+  deps: SlackBlockActionDispatchDeps
+): Promise<boolean> {
+  const log = deps.log ?? defaultSlackLog;
+  const action = parseSlackBlockAction(payload);
+  if (action === null) {
+    return false;
+  }
+  if (action.channelId === "" || action.threadTs === "") {
+    log.warn("block action skipped (no conversation)", {
+      action_id: action.actionId,
+      user: action.userId,
+    });
+    return true;
+  }
+  // Slack stamps every real click; without one the synthetic message ts
+  // would alias another click's dedupe claim.
+  if (action.actionTs === "") {
+    log.warn("block action skipped (no action_ts)", {
+      action_id: action.actionId,
+      user: action.userId,
+    });
+    return true;
+  }
+
+  log.info("block action", {
+    action_id: action.actionId,
+    channel: action.channelId,
+    thread_ts: action.threadTs,
+    message_ts: action.messageTs,
+    user: action.userId,
+  });
+
+  await dispatchInboundMessage({
+    kind: "block_action",
+    message: blockActionAsMessage(action),
+    handler: (ctx) => deps.handler(ctx, action),
+    send: deps.send,
+    credentials: deps.credentials,
+    host: deps.host,
+    log,
+    // Click text is synthetic — never treat it as a stop/eval directive.
+    evalCommandsEnabled: false,
+    hasContinuationSession: deps.hasContinuationSession,
+    isContinuationBusy: deps.isContinuationBusy,
+    getContinuationLastBotMessageTs: deps.getContinuationLastBotMessageTs,
+    interruptContinuation: deps.interruptContinuation,
+  });
+  return true;
+}

package/src/channels/slack/manifest.ts

@@ -3,10 +3,21 @@
  *
  * Import at https://api.slack.com/apps -> Create New App -> From a manifest.
  * Always Socket Mode — no Events Request URL.
+ *
+ * Mirrored by backend/server/src/agentServe/agentServeSlackManifest.ts (the
+ * backend cannot import this published package); keep the twins in lockstep.
  */
 
 import type { SlackManifestOptions } from "./types.js";
 
+/**
+ * Where Slack points users who open a Cursor-provisioned app's settings
+ * page. Manifest builders know neither the team slug nor the deployment
+ * id, so this is the dashboard tab root rather than a per-agent deep link.
+ */
+export const SLACK_EXTERNAL_APP_MANAGEMENT_URL =
+  "https://cursor.com/dashboard/deployed-agents";
+
 export interface SlackAppManifest {
   display_information: {
     name: string;
@@ -43,6 +54,10 @@ export interface SlackAppManifest {
     socket_mode_enabled: boolean;
     token_rotation_enabled: boolean;
     is_mcp_enabled: boolean;
+    managed_app_settings?: {
+      is_install_from_slack_disabled: boolean;
+      external_app_management_url: string;
+    };
   };
 }
 
@@ -64,6 +79,17 @@ const BOT_SCOPES = [
 
 const BOT_EVENTS = ["app_mention", "message.im"] as const;
 
+/** Slack's display_information.description bound. */
+const MAX_DESCRIPTION_LENGTH = 140;
+const DESCRIPTION_SUFFIX = " — an AI agent built with Cursor";
+
+/** Marketplace review rejects managed apps whose manifest omits a description. */
+function defaultDescription(name: string): string {
+  const room = MAX_DESCRIPTION_LENGTH - DESCRIPTION_SUFFIX.length;
+  // Spread splits by code point: truncation cannot halve a surrogate pair.
+  return `${[...name].slice(0, room).join("")}${DESCRIPTION_SUFFIX}`;
+}
+
 function appSlug(name: string): string {
   const base = name
     .toLowerCase()
@@ -104,6 +130,7 @@ export function buildSlackManifest(
       ? `${options.name} (dev)`
       : options.name;
   const botName = options.botDisplayName ?? toBotDisplayName(options.name, env);
+  const description = options.description ?? defaultDescription(options.name);
   const includeAssistant = options.assistant !== false;
 
   const botScopes = includeAssistant
@@ -121,9 +148,7 @@ export function buildSlackManifest(
   return {
     display_information: {
       name: displayName,
-      ...(options.description === undefined
-        ? {}
-        : { description: options.description }),
+      description,
     },
     features: {
       bot_user: {
@@ -138,9 +163,7 @@ export function buildSlackManifest(
       ...(includeAssistant
         ? {
             assistant_view: {
-              assistant_description:
-                options.description ??
-                `${options.name} agent served by agent-serve`,
+              assistant_description: description,
               suggested_prompts: suggested,
             },
           }
@@ -165,6 +188,14 @@ export function buildSlackManifest(
       socket_mode_enabled: true,
       token_rotation_enabled: false,
       is_mcp_enabled: false,
+      ...(options.managedByCursor === false
+        ? {}
+        : {
+            managed_app_settings: {
+              is_install_from_slack_disabled: true,
+              external_app_management_url: SLACK_EXTERNAL_APP_MANAGEMENT_URL,
+            },
+          }),
     },
   };
 }

package/src/channels/slack/message-body.ts

@@ -0,0 +1,90 @@
+/**
+ * Flatten a Slack message payload into readable text.
+ *
+ * Works on both raw Events API payloads and `conversations.*` API records.
+ * Alert feeds (Datadog, PagerDuty, …) post with an empty top-level `text`
+ * and put the whole notification in `attachments` / Block Kit `blocks`, so
+ * anything reading `text` alone sees an empty message.
+ */
+
+type JsonRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): JsonRecord | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as JsonRecord;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Pull readable text out of Slack attachment / Block Kit payloads. */
+export function slackApiMessageBody(message: JsonRecord): string {
+  const parts: string[] = [];
+  const text = asString(message.text);
+  if (text !== undefined && text.trim() !== "") {
+    parts.push(text);
+  }
+
+  const attachments = Array.isArray(message.attachments)
+    ? message.attachments
+    : [];
+  for (const attachment of attachments) {
+    const rec = asRecord(attachment);
+    if (rec === null) {
+      continue;
+    }
+    for (const key of [
+      "pretext",
+      "title",
+      "text",
+      "fallback",
+      "footer",
+    ] as const) {
+      const value = asString(rec[key]);
+      if (value !== undefined && value.trim() !== "") {
+        parts.push(value);
+      }
+    }
+    const titleLink = asString(rec.title_link);
+    if (titleLink !== undefined && titleLink.trim() !== "") {
+      parts.push(titleLink);
+    }
+  }
+
+  const blocks = Array.isArray(message.blocks) ? message.blocks : [];
+  for (const block of blocks) {
+    const rec = asRecord(block);
+    if (rec === null) {
+      continue;
+    }
+    const blockText = asRecord(rec.text);
+    const blockTextValue = asString(blockText?.text);
+    if (blockTextValue !== undefined && blockTextValue.trim() !== "") {
+      parts.push(blockTextValue);
+    }
+    const fields = Array.isArray(rec.fields) ? rec.fields : [];
+    for (const field of fields) {
+      const fieldRec = asRecord(field);
+      const fieldText = asString(fieldRec?.text);
+      if (fieldText !== undefined && fieldText.trim() !== "") {
+        parts.push(fieldText);
+      }
+    }
+  }
+
+  // Dedupe identical chunks (Datadog often repeats text/fallback across fields).
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed === "" || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    deduped.push(trimmed);
+  }
+  return deduped.join("\n");
+}

package/src/channels/slack/setup.ts

@@ -1,7 +1,10 @@
 /**
  * Slack setup guide printed by `agent-serve slack setup`.
  *
- * Mirrors the Cursor skill at skills/setup-slack/SKILL.md.
+ * Mirrors the Cursor skill at skills/setup-slack/SKILL.md: connection
+ * decision first (Cursor-hosted vs dedicated Socket Mode app), then the
+ * dedicated-app phases. {@link SLACK_SETUP_PHASES} stays the dedicated-app
+ * checklist — its ids key `.agent-serve/slack/setup-status.json`.
  */
 
 export interface SlackSetupPhase {
@@ -75,8 +78,19 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
 
 export function formatSlackSetupGuide(): string {
   const lines: string[] = [
-    "agent-serve — Slack setup (Socket Mode)",
+    "agent-serve — Slack setup",
     "",
+    "Two connections exist; decide before running the phases below.",
+    "",
+    "  A) Cursor-hosted connection (recommended default, zero Slack admin):",
+    '     slackChannel({ cursorAccount: true, agentName: "MyAgent" })',
+    "     Sign in (agent-serve login / CURSOR_API_KEY), serve, then mention",
+    '     "@Cursor MyAgent ..." in the linked workspace. No app, no tokens.',
+    "  B) Dedicated Slack app (Socket Mode) — the phases below. Choose it",
+    "     when you need your own bot user, channel watching",
+    "     (engagement.channelPosts), or approval buttons / interactivity.",
+    "",
+    "Phases 0-5 cover connection B only.",
     "Goal: importable dev + prod Slack apps over Socket Mode (no public URL).",
     "App-Level Token (xapp-...) + Bot Token (xoxb-...) required.",
     "",

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

@@ -45,7 +45,10 @@ import {
   type SlackInboundDispatchDeps,
 } from "./dispatch.js";
 import { createEventIdDedupe } from "./event-id-dedupe.js";
-import { dispatchInteractiveFromPayload } from "./interactive.js";
+import {
+  dispatchBlockAction,
+  dispatchInteractiveFromPayload,
+} from "./interactive.js";
 import { createSlackLogger, type SlackLog } from "./log.js";
 import {
   type SlackSocketModeHandle,
@@ -120,6 +123,11 @@ export function slackChannel<const Name extends string = string>(
         "slackChannel({ cursorAccount: true }) does not support interactivity — interactive Block Kit clicks are not relayed over the Cursor Slack connection. Interactivity is Socket Mode only."
       );
     }
+    if (options.onBlockAction !== undefined) {
+      throw new Error(
+        "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."
+      );
+    }
   }
   const accountTransport = cursorAccount
     ? createPendingSlackApiTransport()
@@ -151,7 +159,9 @@ export function slackChannel<const Name extends string = string>(
   const eventIds = createEventIdDedupe();
   const toolApprovals = options.toolApprovals === true;
   const interactivity = options.interactivity === true;
-  const routeInteractive = toolApprovals || interactivity;
+  const onBlockAction = options.onBlockAction;
+  const routeInteractive =
+    toolApprovals || interactivity || onBlockAction !== undefined;
 
   const runtime: { log: SlackLog } = {
     log: createSlackLogger(options.logger),
@@ -408,12 +418,33 @@ export function slackChannel<const Name extends string = string>(
       };
       if (routeInteractive) {
         socketOptions.onInteractive = async (payload) => {
-          await dispatchInteractiveFromPayload(payload, {
+          // Framework tool-approval Approve/Deny clicks resolve first;
+          // anything else (including approval-shaped clicks whose value
+          // fails to parse) falls through to the author's block-action hook.
+          const handledAsApproval = await dispatchInteractiveFromPayload(
+            payload,
+            {
+              credentials,
+              getSession: args.getSession,
+              resolveApproval: args.resolveApproval,
+              waitUntil: args.waitUntil,
+              log: getLog(),
+            }
+          );
+          if (handledAsApproval || onBlockAction === undefined) {
+            return;
+          }
+          await dispatchBlockAction(payload, {
+            handler: onBlockAction,
+            send: args.send,
             credentials,
-            getSession: args.getSession,
-            resolveApproval: args.resolveApproval,
-            waitUntil: args.waitUntil,
+            host: args.host,
             log: getLog(),
+            hasContinuationSession: args.hasContinuationSession,
+            isContinuationBusy: args.isContinuationBusy,
+            getContinuationLastBotMessageTs:
+              args.getContinuationLastBotMessageTs,
+            interruptContinuation: args.interruptContinuation,
           });
         };
       }