@cursor/july 0.1.16 → 0.1.17

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

package/src/channels/slack/types.ts

@@ -175,6 +175,83 @@ export type SlackMessageHandler = (
   | undefined
   | Promise<SlackDispatchDecision | null | undefined>;
 
+/**
+ * Host probes into a Slack thread's continuation. Optional on dispatch
+ * deps; the serve host wires them at channel start.
+ */
+export interface SlackContinuationProbes {
+  /**
+   * 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>;
+}
+
+/**
+ * A Block Kit action click (Socket Mode `block_actions` payload) that the
+ * framework does not own — the built-in tool-approval Approve/Deny actions
+ * are routed to `resolveApproval` before author handlers see anything.
+ */
+export interface SlackBlockAction {
+  /** `action_id` of the clicked element. */
+  actionId: string;
+  /** `block_id` of the actions row holding the element (Slack always sets one). */
+  blockId: string;
+  /**
+   * Element `value` payload; empty string when absent (button-style
+   * elements only — select/overflow `selected_option`s are not read).
+   */
+  value: string;
+  /** Plain-text label of the clicked element, when present. */
+  label?: string;
+  channelId: string;
+  /**
+   * Thread of the message carrying the element (the message's own ts when
+   * it is a top-level post — clicks on a thread root stay in its thread).
+   */
+  threadTs: string;
+  /** The message carrying the clicked element. */
+  messageTs: string;
+  /** That message's blocks, for `chat.update` resolution cards. */
+  messageBlocks?: unknown[];
+  /** Slack user who clicked. */
+  userId: string;
+  userName?: string;
+  teamId?: string;
+  /**
+   * Slack `action_ts` — unique per click; block-action dispatch dedupes on
+   * it. Empty when the payload omitted it (malformed; never dispatched).
+   */
+  actionTs: string;
+}
+
+/**
+ * Author handler for {@link SlackBlockAction} clicks. Return a
+ * {@link SlackDispatchDecision} to dispatch a turn on the click's thread —
+ * the click is dispatched like an inbound message from the clicking user
+ * (thread-scoped continuation, `<slack_context>` naming the clicker) — or
+ * `null` to ignore the click.
+ */
+export type SlackBlockActionHandler = (
+  ctx: SlackBinding,
+  action: SlackBlockAction
+) =>
+  | SlackDispatchDecision
+  | null
+  | undefined
+  | Promise<SlackDispatchDecision | null | undefined>;
+
 /**
  * Opt-in channel watch: dispatch on posts in explicitly allowlisted
  * channels without requiring an @mention. There is deliberately no
@@ -371,6 +448,18 @@ export interface SlackChannelOptions {
    * only — rejected on `cursorAccount: true`.
    */
   interactivity?: boolean;
+  /**
+   * Handler for Block Kit actions the framework does not own (the built-in
+   * tool-approval Approve/Deny clicks are routed to `resolveApproval`
+   * first). Return a {@link SlackDispatchDecision} — typically with a
+   * thread-scoped auth via `buildSlackAuthContext` so replies in the same
+   * thread continue the session — to dispatch a turn on the click's
+   * thread, or `null` to ignore the click. Setting this implies
+   * interactive routing; the Slack app manifest still needs
+   * `interactivity` enabled (`buildSlackManifest({ interactivity: true })`).
+   * Socket Mode only — rejected on `cursorAccount: true`.
+   */
+  onBlockAction?: SlackBlockActionHandler;
   /**
    * Suggested prompts shown when an assistant thread starts (and optionally
    * after a turn completes).

package/src/connections.ts

@@ -30,8 +30,10 @@
  * to be signed in (`agent-serve login` or `CURSOR_API_KEY`):
  *
  * ```ts
- * // agent/mcp-connections/cursor.ts — every connected server
+ * // agent/mcp-connections/cursor.ts — every connected server (no allowlist)
  * export default defineConnection({ cursorAccount: true });
+ * // equivalent explicit form:
+ * export default defineConnection({ cursorAccount: true, servers: "*" });
  *
  * // or restrict to specific connectors by name
  * export default defineConnection({ cursorAccount: true, servers: ["Linear"] });
@@ -86,6 +88,7 @@ export type {
   HostMcpRegistry,
   HostMcpToolInfo,
 } from "./types.js";
+export { normalizeCursorAccountServers } from "./types.js";
 
 export function defineConnection(
   config: ConnectionConfig