@cursor/july 0.1.1

package/src/channels/slack/credentials.ts

@@ -0,0 +1,90 @@
+/**
+ * Per-agent Slack credential resolution.
+ *
+ * Multi-agent serve needs one Slack app (and token pair) per agent. Use
+ * `envPrefix: "MY_AGENT"` so the pack reads `MY_AGENT_SLACK_BOT_TOKEN` /
+ * `MY_AGENT_SLACK_APP_TOKEN` instead of the shared globals.
+ */
+
+import type { SlackBotToken, SlackCredentials } from "./types.js";
+
+/** Normalize an agent directory / display name into an env prefix. */
+export function envPrefixFromName(name: string): string {
+  return name
+    .trim()
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toUpperCase();
+}
+
+/** Env var names for a Slack token pair. */
+export function slackEnvKeys(prefix?: string): {
+  bot: string;
+  app: string;
+} {
+  if (prefix === undefined || prefix.trim() === "") {
+    return { bot: "SLACK_BOT_TOKEN", app: "SLACK_APP_TOKEN" };
+  }
+  const normalized = envPrefixFromName(prefix);
+  return {
+    bot: `${normalized}_SLACK_BOT_TOKEN`,
+    app: `${normalized}_SLACK_APP_TOKEN`,
+  };
+}
+
+/**
+ * Credentials that read `{PREFIX}_SLACK_BOT_TOKEN` / `{PREFIX}_SLACK_APP_TOKEN`
+ * (or the unprefixed globals when `prefix` is omitted). Resolvers return `""`
+ * when unset so multi-agent serve does not fall through to a shared token.
+ */
+export function credentialsFromEnv(prefix?: string): SlackCredentials {
+  const keys = slackEnvKeys(prefix);
+  return {
+    botToken: () => process.env[keys.bot]?.trim() ?? "",
+    appToken: () => process.env[keys.app]?.trim() ?? "",
+  };
+}
+
+async function readExplicitToken(
+  explicit: SlackBotToken | undefined
+): Promise<string | undefined> {
+  if (explicit === undefined) {
+    return undefined;
+  }
+  const value = typeof explicit === "function" ? await explicit() : explicit;
+  // API transports (objects) carry no raw token to resolve.
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/**
+ * Resolve a bot token string without throwing. When `credentials.botToken`
+ * is set (string or resolver), only that value is used — no global fallback
+ * — so a per-agent prefix cannot accidentally bind every mounted agent to
+ * one app. When omitted, falls back to `SLACK_BOT_TOKEN`. API transports
+ * resolve to `undefined` (they execute calls without a local token).
+ */
+export async function tryResolveBotToken(
+  credentials: SlackCredentials | undefined
+): Promise<string | undefined> {
+  if (credentials?.botToken !== undefined) {
+    return readExplicitToken(credentials.botToken);
+  }
+  return readExplicitToken(process.env.SLACK_BOT_TOKEN);
+}
+
+/**
+ * Resolve an app-level token without throwing. Same per-agent rules as
+ * {@link tryResolveBotToken}.
+ */
+export async function tryResolveAppToken(
+  credentials: SlackCredentials | undefined
+): Promise<string | undefined> {
+  if (credentials?.appToken !== undefined) {
+    return readExplicitToken(credentials.appToken);
+  }
+  return readExplicitToken(process.env.SLACK_APP_TOKEN);
+}

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

@@ -0,0 +1,166 @@
+/**
+ * Cursor-account mode for the Slack channel pack: instead of a dedicated
+ * Slack app (Socket Mode + `xoxb`/`xapp` tokens), the channel rides the
+ * signed-in Cursor account's Slack connection. Inbound events are relayed
+ * by the serve host from `/v0/slack-events` (see
+ * `internal/cursor-slack-relay.ts`); outbound Web API calls run through a
+ * {@link SlackApiTransport} bound to the backend proxy.
+ *
+ * This file is the seam between the channel definition (authored at
+ * `defineChannel` time) and the serve-time relay: `slackChannel()` registers
+ * a runtime ref here, and the server discovers it, binds the transport, and
+ * dispatches relayed envelopes through the pack's normal inbound path.
+ */
+
+import type { HostContext, SendMessageFn } from "../../types.js";
+import { dispatchInboundMessage } from "./dispatch.js";
+import type { EventIdDedupe } from "./event-id-dedupe.js";
+import { slackTextToMarkdown } from "./inbound.js";
+import type { SlackLog } from "./log.js";
+import type {
+  SlackApiTransport,
+  SlackChannelOptions,
+  SlackCredentials,
+  SlackMessage,
+  SlackMessageHandler,
+} from "./types.js";
+
+/**
+ * Transport placeholder created at `slackChannel()` definition time and
+ * bound to the real backend proxy caller when the serve host starts its
+ * relay. Calls before binding soft-fail Slack-style.
+ */
+export interface PendingSlackApiTransport extends SlackApiTransport {
+  bind(impl: SlackApiTransport["call"]): void;
+}
+
+export function createPendingSlackApiTransport(): PendingSlackApiTransport {
+  let bound: SlackApiTransport["call"] | undefined;
+  return {
+    kind: "api-transport",
+    label: "cursor-account",
+    bind(impl) {
+      bound = impl;
+    },
+    async call(method, args) {
+      if (bound === undefined) {
+        return { ok: false, error: "cursor_slack_relay_not_started" };
+      }
+      return bound(method, args);
+    },
+  };
+}
+
+/**
+ * One routed Slack event from `/v0/slack-events` (mirror of the backend's
+ * SlackAgentEventEnvelope, minus server-only fields).
+ */
+export interface CursorSlackEnvelope {
+  eventName: string;
+  slackTeamId: string;
+  channelId: string;
+  channelType?: string;
+  threadTs: string;
+  messageTs: string;
+  slackUserId?: string;
+  text: string;
+  agentName: string;
+  consumerId: string;
+  /**
+   * How the backend routed the event: leading agent name or owned thread.
+   */
+  matchedBy: "name" | "thread";
+  eventId?: string;
+  receivedAtMs: number;
+}
+
+/** Serve-time runtime handle for one cursor-account Slack channel. */
+export interface SlackCursorAccountRuntime {
+  options: SlackChannelOptions;
+  /** The channel's live credentials (botToken slot holds the transport). */
+  credentials: SlackCredentials;
+  transport: PendingSlackApiTransport;
+  eventIds: EventIdDedupe;
+  onAppMention: SlackMessageHandler;
+  onDirectMessage: SlackMessageHandler;
+  getLog: () => SlackLog;
+}
+
+const runtimeByDefinition = new WeakMap<object, SlackCursorAccountRuntime>();
+
+export function registerSlackCursorAccountRuntime(
+  definition: object,
+  runtime: SlackCursorAccountRuntime
+): void {
+  runtimeByDefinition.set(definition, runtime);
+}
+
+/**
+ * Recover the cursor-account runtime for a channel definition, if it was
+ * created via `slackChannel({ cursorAccount: true })`.
+ */
+export function getSlackCursorAccountRuntime(
+  definition: object
+): SlackCursorAccountRuntime | undefined {
+  return runtimeByDefinition.get(definition);
+}
+
+/**
+ * Dispatch one relayed envelope through the pack's normal inbound path
+ * (same handlers, session continuation, and reply delivery as Socket Mode).
+ */
+export async function dispatchCursorSlackEnvelope(args: {
+  runtime: SlackCursorAccountRuntime;
+  envelope: CursorSlackEnvelope;
+  send: SendMessageFn;
+  host: HostContext;
+}): Promise<void> {
+  const { runtime, envelope } = args;
+  const log = runtime.getLog();
+
+  if (
+    envelope.eventId !== undefined &&
+    envelope.eventId.length > 0 &&
+    !runtime.eventIds.tryHandle(envelope.eventId)
+  ) {
+    log.debug("cursor-account inbound dedupe drop", {
+      event_id: envelope.eventId,
+    });
+    return;
+  }
+
+  const message: SlackMessage = {
+    text: envelope.text,
+    markdown: slackTextToMarkdown(envelope.text),
+    ts: envelope.messageTs,
+    threadTs: envelope.threadTs,
+    channelId: envelope.channelId,
+    teamId: envelope.slackTeamId,
+    ...(envelope.slackUserId === undefined
+      ? {}
+      : {
+          author: { userId: envelope.slackUserId, isBot: false },
+        }),
+  };
+
+  // DMs to @Cursor route as direct messages; everything else (explicit
+  // `@Cursor <agent> …` mentions and claimed-thread replies) dispatches on
+  // the mention handler — a claimed-thread reply is addressed to the agent
+  // by construction. Mentions/DM disable toggles are rejected at
+  // `slackChannel({ cursorAccount: true })` construction so the backend
+  // never consumes events the host would drop.
+  const isDm =
+    envelope.channelType === "im" || envelope.channelId.startsWith("D");
+  const kind = isDm ? "direct_message" : "app_mention";
+  const handler = isDm ? runtime.onDirectMessage : runtime.onAppMention;
+  await dispatchInboundMessage({
+    kind,
+    message,
+    handler,
+    send: args.send,
+    credentials: runtime.credentials,
+    host: args.host,
+    log,
+    ...(envelope.eventId === undefined ? {} : { eventId: envelope.eventId }),
+  });
+}

package/src/channels/slack/defaults.ts

@@ -0,0 +1,450 @@
+/**
+ * Default inbound handlers and stream-event sinks for the Slack channel.
+ */
+
+import type { ChannelEventHandlers } from "../../types.js";
+import {
+  appendChatStream,
+  postMessage,
+  setThreadStatus,
+  truncateTypingStatus,
+} from "./api.js";
+import { firstNonEmptyLine, maybeSetSuggestedPrompts } from "./assistant.js";
+import { defaultSlackAuth } from "./auth.js";
+import {
+  SLACK_DEFAULT_LOADING_MESSAGES,
+  SLACK_TYPING_MIN_GROWTH,
+  SLACK_TYPING_MIN_INTERVAL_MS,
+} from "./constants.js";
+import { createStreamDeliveryStrategy } from "./live-delivery.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import { buildTaskChunkForResult, buildTaskChunksForCalls } from "./stream.js";
+import type {
+  SlackChannelState,
+  SlackCredentials,
+  SlackMessageHandler,
+  SlackSuggestedPrompt,
+} from "./types.js";
+
+const defaultOnInbound: SlackMessageHandler = async (ctx, message) => {
+  await ctx.thread.startTyping("Thinking…");
+  const auth = defaultSlackAuth(message, ctx);
+  return auth === null ? null : { auth };
+};
+
+export const defaultOnAppMention: SlackMessageHandler = defaultOnInbound;
+export const defaultOnDirectMessage: SlackMessageHandler = defaultOnInbound;
+
+/**
+ * Default watched-channel-post handler: same thread-scoped principal as
+ * mentions (so a later @mention continues the session), tagged with an
+ * `engagement: "channel_post"` attribute for auth policies.
+ */
+export const defaultOnChannelPost: SlackMessageHandler = async (
+  ctx,
+  message
+) => {
+  await ctx.thread.startTyping("Thinking…");
+  const auth = defaultSlackAuth(message, ctx, { engagement: "channel_post" });
+  return auth === null ? null : { auth };
+};
+
+export interface BuildDefaultEventsOptions {
+  credentials?: SlackCredentials;
+  streaming?: boolean;
+  thinkingSteps?: boolean;
+  suggestedPrompts?: SlackSuggestedPrompt[];
+  suggestedPromptsTitle?: string;
+  /** Resolved per-call so channel onStart can rebind the server logger. */
+  getLog?: () => SlackLog;
+}
+
+/**
+ * Build default stream-event handlers (typing, streaming, replies).
+ * Streaming / thinking default to ON.
+ *
+ * Tool-approval cards are a separate primitive — compose with
+ * `buildToolApprovalEvents` or set `toolApprovals: true` on `slackChannel`.
+ */
+export function buildDefaultEvents(
+  options: BuildDefaultEventsOptions = {}
+): ChannelEventHandlers<SlackChannelState> {
+  const credentials = options.credentials;
+  const streaming = options.streaming !== false;
+  const thinkingSteps = options.thinkingSteps !== false;
+  const suggestedPrompts = options.suggestedPrompts ?? [];
+  const suggestedPromptsTitle = options.suggestedPromptsTitle;
+  const botToken = credentials?.botToken;
+  const getLog = options.getLog ?? (() => defaultSlackLog);
+  const strategy = createStreamDeliveryStrategy({ botToken, getLog });
+
+  return {
+    async "turn.started"(event, channel) {
+      const log = getLog();
+      channel.state.pendingToolCallMessage = null;
+      channel.state.lastReasoningTypingAtMs = null;
+      channel.state.lastReasoningTypingStatus = null;
+      channel.state.streamTs = null;
+      channel.state.streamChannelId = null;
+      channel.state.lastPostedText = null;
+      channel.state.approvalMessageByCallId = {};
+
+      const state = channel.state;
+      if (state.channelId === null || state.threadTs === null) {
+        return;
+      }
+
+      log.info("turn.started", {
+        session: event.sessionId,
+        turn: event.turnId,
+        channel: state.channelId,
+        thread_ts: state.threadTs,
+      });
+
+      await setThreadStatus({
+        botToken,
+        channelId: state.channelId,
+        threadTs: state.threadTs,
+        status: "Working…",
+        loadingMessages: [...SLACK_DEFAULT_LOADING_MESSAGES],
+      });
+
+      // Retry streaming each turn unless a prior call proved the feature
+      // unsupported for this workspace/app. Thinking stays on setStatus
+      // (Cursor-account proxy pins agent username/icon on that method).
+      if (!streaming || state.streamingUnavailable === true) {
+        return;
+      }
+
+      await strategy.start({
+        channel,
+        channelId: state.channelId,
+        threadTs: state.threadTs,
+        sessionId: event.sessionId,
+      });
+    },
+
+    async "message.appended"(event, channel) {
+      if (!streaming || channel.state.streamingUnavailable === true) {
+        return;
+      }
+      const streamTs = channel.state.streamTs;
+      const channelId =
+        channel.state.streamChannelId ?? channel.state.channelId;
+      if (
+        streamTs === null ||
+        streamTs === "" ||
+        channelId === null ||
+        channelId === ""
+      ) {
+        return;
+      }
+
+      await strategy.append({
+        channel,
+        channelId,
+        streamTs,
+        text: event.data.text,
+        sessionId: event.sessionId,
+      });
+    },
+
+    async "reasoning.appended"(event, channel) {
+      const line = firstNonEmptyLine(event.data.text);
+      if (line === undefined) {
+        return;
+      }
+      const status = truncateTypingStatus(line);
+      const previous = channel.state.lastReasoningTypingStatus;
+      const grew =
+        previous !== null &&
+        status.startsWith(previous) &&
+        status.length >= previous.length + SLACK_TYPING_MIN_GROWTH;
+      const now = Date.now();
+      const lastAt = channel.state.lastReasoningTypingAtMs;
+      if (
+        !grew &&
+        lastAt !== null &&
+        now - lastAt >= 0 &&
+        now - lastAt < SLACK_TYPING_MIN_INTERVAL_MS
+      ) {
+        return;
+      }
+      if (channel.state.channelId === null || channel.state.threadTs === null) {
+        return;
+      }
+      await setThreadStatus({
+        botToken,
+        channelId: channel.state.channelId,
+        threadTs: channel.state.threadTs,
+        status,
+        loadingMessages: [status, ...SLACK_DEFAULT_LOADING_MESSAGES],
+      });
+      channel.state.lastReasoningTypingAtMs = now;
+      channel.state.lastReasoningTypingStatus = status;
+    },
+
+    async "actions.requested"(event, channel) {
+      const pending = channel.state.pendingToolCallMessage;
+      channel.state.pendingToolCallMessage = null;
+      const names = event.data.calls.map((call) => call.toolName);
+
+      const statusText =
+        pending !== null
+          ? truncateTypingStatus(pending)
+          : truncateTypingStatus(`Running ${names.join(", ")}…`);
+
+      if (
+        strategy.inlineToolSteps &&
+        thinkingSteps &&
+        streaming &&
+        channel.state.streamingUnavailable !== true &&
+        channel.state.streamTs !== null &&
+        channel.state.streamTs !== ""
+      ) {
+        const channelId =
+          channel.state.streamChannelId ?? channel.state.channelId;
+        if (channelId !== null && channelId !== "") {
+          const chunks = buildTaskChunksForCalls(
+            event.data.calls,
+            "in_progress"
+          );
+          const result = await appendChatStream({
+            botToken,
+            channel: channelId,
+            ts: channel.state.streamTs,
+            chunks,
+          });
+          if (result.ok) {
+            if (
+              channel.state.channelId !== null &&
+              channel.state.threadTs !== null
+            ) {
+              await setThreadStatus({
+                botToken,
+                channelId: channel.state.channelId,
+                threadTs: channel.state.threadTs,
+                status: statusText,
+              });
+            }
+            return;
+          }
+        }
+      }
+
+      if (channel.state.channelId !== null && channel.state.threadTs !== null) {
+        await setThreadStatus({
+          botToken,
+          channelId: channel.state.channelId,
+          threadTs: channel.state.threadTs,
+          status: statusText,
+        });
+      }
+    },
+
+    async "action.result"(event, channel) {
+      if (
+        !strategy.inlineToolSteps ||
+        !thinkingSteps ||
+        !streaming ||
+        channel.state.streamingUnavailable === true ||
+        channel.state.streamTs === null ||
+        channel.state.streamTs === ""
+      ) {
+        return;
+      }
+      const channelId =
+        channel.state.streamChannelId ?? channel.state.channelId;
+      if (channelId === null || channelId === "") {
+        return;
+      }
+      const chunk = buildTaskChunkForResult({
+        callId: event.data.callId,
+        toolName: event.data.toolName,
+        isError: event.data.isError,
+      });
+      await appendChatStream({
+        botToken,
+        channel: channelId,
+        ts: channel.state.streamTs,
+        chunks: [chunk],
+      });
+    },
+
+    async "message.completed"(event, channel) {
+      const log = getLog();
+      if (event.data.finishReason === "tool_call") {
+        channel.state.pendingToolCallMessage =
+          firstNonEmptyLine(event.data.text) ?? null;
+        return;
+      }
+      channel.state.pendingToolCallMessage = null;
+
+      const state = channel.state;
+      if (state.channelId === null || state.threadTs === null) {
+        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 === "") {
+        if (state.streamTs !== null && state.streamTs !== "") {
+          await strategy.finalizeEmpty({
+            channel,
+            channelId: state.streamChannelId ?? state.channelId,
+            streamTs: state.streamTs,
+          });
+          channel.state.streamTs = null;
+        }
+        await clearStatus();
+        return;
+      }
+
+      const canStream =
+        streaming &&
+        state.streamingUnavailable !== true &&
+        state.streamTs !== null &&
+        state.streamTs !== "";
+
+      if (canStream && state.streamTs !== null) {
+        const { delivered } = await strategy.finalize({
+          channel,
+          channelId: state.streamChannelId ?? state.channelId,
+          streamTs: state.streamTs,
+          text: event.data.text,
+          sessionId: event.sessionId,
+        });
+        if (delivered) {
+          await clearStatus();
+          return;
+        }
+      }
+
+      try {
+        const posted = await postMessage({
+          botToken,
+          channel: state.channelId,
+          text: event.data.text,
+          threadTs: state.threadTs,
+        });
+        channel.state.lastPostedText = event.data.text;
+        log.info("reply delivered via postMessage", {
+          channel: state.channelId,
+          thread_ts: state.threadTs,
+          message_ts: posted.ts,
+          session: event.sessionId,
+          chars: event.data.text.length,
+        });
+      } catch (error) {
+        log.error(
+          `postMessage failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          {
+            channel: state.channelId,
+            thread_ts: state.threadTs,
+            session: event.sessionId,
+          }
+        );
+      }
+
+      await clearStatus();
+    },
+
+    async "turn.completed"(event, channel) {
+      const log = getLog();
+      log.info("turn.completed", {
+        session: event.sessionId,
+        turn: event.turnId,
+        channel: channel.state.channelId,
+        thread_ts: channel.state.threadTs,
+      });
+
+      await strategy.cleanupOrphan({ channel });
+
+      if (
+        suggestedPrompts.length === 0 ||
+        channel.state.channelId === null ||
+        channel.state.threadTs === null
+      ) {
+        return;
+      }
+      await maybeSetSuggestedPrompts({
+        botToken,
+        channelId: channel.state.channelId,
+        threadTs: channel.state.threadTs,
+        prompts: suggestedPrompts,
+        ...(suggestedPromptsTitle === undefined
+          ? {}
+          : { title: suggestedPromptsTitle }),
+        log,
+      });
+    },
+
+    async "turn.failed"(event, channel) {
+      const log = getLog();
+      const state = channel.state;
+      log.error("turn.failed", {
+        session: event.sessionId,
+        turn: event.turnId,
+        error: event.data.message,
+        channel: state.channelId,
+        thread_ts: state.threadTs,
+      });
+      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.";
+
+      let delivered = false;
+      if (state.streamTs !== null && state.streamTs !== "") {
+        ({ delivered } = await strategy.fail({
+          channel,
+          channelId: state.streamChannelId ?? state.channelId,
+          streamTs: state.streamTs,
+          errorText,
+          sessionId: event.sessionId,
+        }));
+      }
+      if (!delivered) {
+        try {
+          await postMessage({
+            botToken,
+            channel: state.channelId,
+            text: errorText,
+            threadTs: state.threadTs,
+          });
+        } catch (error) {
+          log.error(
+            `turn.failed postMessage failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+            {
+              channel: state.channelId,
+              thread_ts: state.threadTs,
+              session: event.sessionId,
+            }
+          );
+        }
+      }
+      await setThreadStatus({
+        botToken,
+        channelId: state.channelId,
+        threadTs: state.threadTs,
+        status: "",
+      });
+    },
+  };
+}