@cursor/july 0.1.15 → 0.1.17

package/src/channels/slack/blocks.ts

@@ -0,0 +1,139 @@
+/**
+ * Block Kit building helpers shared by card-building agents.
+ */
+
+/** Slack cap for one section block's mrkdwn text. */
+export const SLACK_SECTION_MRKDWN_MAX = 3000;
+
+/** Slack caps for a native `table` block (one table per message). */
+export const SLACK_TABLE_MAX_ROWS = 100;
+export const SLACK_TABLE_MAX_COLUMNS = 20;
+
+/**
+ * Pack lines into as few mrkdwn section blocks as fit the 3000-char cap,
+ * preserving order. Long lists (a full service fleet, a file inventory)
+ * overflow a single section and make `chat.postMessage` refuse the whole
+ * card with `invalid_blocks`.
+ */
+export function mrkdwnSections(lines: readonly string[]): unknown[] {
+  const texts: string[] = [];
+  let current = "";
+  for (const raw of lines) {
+    // A single oversized line (one huge blob) hard-splits at the cap.
+    const parts: string[] = [];
+    for (
+      let i = 0;
+      i < Math.max(raw.length, 1);
+      i += SLACK_SECTION_MRKDWN_MAX
+    ) {
+      parts.push(raw.slice(i, i + SLACK_SECTION_MRKDWN_MAX));
+    }
+    for (const line of parts) {
+      const next = current === "" ? line : `${current}\n${line}`;
+      if (next.length > SLACK_SECTION_MRKDWN_MAX && current !== "") {
+        texts.push(current);
+        current = line;
+      } else {
+        current = next;
+      }
+    }
+  }
+  if (current !== "") {
+    texts.push(current);
+  }
+  return texts.map((text) => ({
+    type: "section",
+    text: { type: "mrkdwn", text },
+  }));
+}
+
+export type SlackTableAlign = "left" | "center" | "right";
+
+export type SlackTableColumnSetting = {
+  align?: SlackTableAlign;
+  is_wrapped?: boolean;
+};
+
+/** Cell types accepted by Slack's native `table` block. */
+export type SlackTableCell =
+  | { type: "raw_text"; text: string }
+  | {
+      type: "rich_text";
+      elements: Array<{
+        type: "rich_text_section";
+        elements: Array<
+          | { type: "text"; text: string }
+          | { type: "link"; url: string; text: string }
+        >;
+      }>;
+    };
+
+export type SlackTableBlock = {
+  type: "table";
+  rows: SlackTableCell[][];
+  column_settings?: SlackTableColumnSetting[];
+};
+
+/** Plain text cell (header or body). */
+export function slackRawTextCell(text: string): SlackTableCell {
+  return { type: "raw_text", text };
+}
+
+/** Linked cell via rich_text (preferred over mrkdwn `<url|label>` in tables). */
+export function slackLinkCell(args: {
+  url: string;
+  text: string;
+}): SlackTableCell {
+  return {
+    type: "rich_text",
+    elements: [
+      {
+        type: "rich_text_section",
+        elements: [{ type: "link", url: args.url, text: args.text }],
+      },
+    ],
+  };
+}
+
+/**
+ * Build a native Slack `table` block. First row is the header. Slack allows
+ * at most one table block per message, 100 rows, and 20 columns — callers
+ * should keep tables short.
+ */
+export function slackTableBlock(args: {
+  headers: readonly string[];
+  rows: readonly (readonly SlackTableCell[])[];
+  columnSettings?: readonly SlackTableColumnSetting[];
+}): SlackTableBlock | undefined {
+  if (args.headers.length === 0) {
+    return undefined;
+  }
+  if (args.headers.length > SLACK_TABLE_MAX_COLUMNS) {
+    throw new Error(
+      `slackTableBlock: ${args.headers.length} columns exceeds Slack cap of ${SLACK_TABLE_MAX_COLUMNS}`
+    );
+  }
+  // Header + body rows share the 100-row cap.
+  if (args.rows.length + 1 > SLACK_TABLE_MAX_ROWS) {
+    throw new Error(
+      `slackTableBlock: ${args.rows.length + 1} rows exceeds Slack cap of ${SLACK_TABLE_MAX_ROWS}`
+    );
+  }
+  const columnCount = args.headers.length;
+  for (const [index, row] of args.rows.entries()) {
+    if (row.length !== columnCount) {
+      throw new Error(
+        `slackTableBlock: row ${index} has ${row.length} cells; expected ${columnCount}`
+      );
+    }
+  }
+  const headerRow = args.headers.map((header) => slackRawTextCell(header));
+  const block: SlackTableBlock = {
+    type: "table",
+    rows: [headerRow, ...args.rows.map((row) => [...row])],
+  };
+  if (args.columnSettings !== undefined && args.columnSettings.length > 0) {
+    block.column_settings = [...args.columnSettings];
+  }
+  return block;
+}

package/src/channels/slack/defaults.ts

@@ -26,6 +26,37 @@ import type {
   SlackSuggestedPrompt,
 } from "./types.js";
 
+const SLACK_TURN_FAILURE_FALLBACK =
+  "I hit an error while handling your request. Please try again or rephrase.";
+const SLACK_TURN_FAILURE_MAX_CHARS = 400;
+
+/** Scrubbed turn.failed body for Slack (secrets / paths / URLs stripped). */
+export function formatSlackTurnFailureMessage(raw: string | undefined): string {
+  const scrubbed = scrubSlackErrorDetail(raw?.trim() ?? "");
+  if (scrubbed === "") {
+    return SLACK_TURN_FAILURE_FALLBACK;
+  }
+  if (/^I hit an error/i.test(scrubbed)) {
+    return scrubbed;
+  }
+  return `I hit an error while handling your request: ${scrubbed}`;
+}
+
+function scrubSlackErrorDetail(message: string): string {
+  const scrubbed = message
+    .replace(/https?:\/\/\S+/gi, "[url]")
+    .replace(/\b(crsr_|xox[baprs]-|sk-|Bearer\s+)\S+/gi, "[redacted]")
+    .replace(/\/(?:home|Users|var\/folders)\/\S+/g, "[path]")
+    .replace(/\b[A-Za-z]:(?:\\|\/)[^\s]+/g, "[path]")
+    .replace(/\\\\[^\s]+/g, "[path]")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (scrubbed.length <= SLACK_TURN_FAILURE_MAX_CHARS) {
+    return scrubbed;
+  }
+  return `${scrubbed.slice(0, SLACK_TURN_FAILURE_MAX_CHARS - 1)}…`;
+}
+
 function resolveLoadingMessages(
   loadingMessages: readonly string[] | undefined
 ): string[] {
@@ -434,10 +465,7 @@ export function buildDefaultEvents(
       if (state.channelId === null || state.threadTs === null) {
         return;
       }
-      // Do not echo engine/tool error text into Slack — it can leak
-      // paths, tokens, or other sensitive detail to workspace members.
-      const errorText =
-        "I hit an error while handling your request. Please try again or rephrase.";
+      const errorText = formatSlackTurnFailureMessage(event.data.message);
 
       let delivered = false;
       if (state.streamTs !== null && state.streamTs !== "") {

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.
@@ -111,7 +96,7 @@ function triggeringMergeMessage(
 }
 
 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/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";

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,162 @@ 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,
+    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,6 +3,9 @@
  *
  * 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";

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,
           });
         };
       }