@cursor/july 0.1.97 → 0.1.100

package/src/channels/slack/reply-options.ts

@@ -0,0 +1,229 @@
+/**
+ * Resolve `slackChannel({ reply, toolLabels })` — and the deprecated
+ * `streaming` / `thinkingSteps` / `loadingMessages` flags — into one config
+ * the default event handlers read.
+ */
+
+import { SLACK_DEFAULT_LOADING_MESSAGES } from "./constants.js";
+import { defaultToolCardDetails } from "./tool-cards.js";
+import type {
+  SlackChannelOptions,
+  SlackReasoningCardOptions,
+  SlackReplyOptions,
+  SlackToolCall,
+  SlackToolCardGroup,
+  SlackToolLabels,
+  SlackToolResult,
+} from "./types.js";
+
+export type SlackReplyMode = "post" | "stream";
+
+export interface ResolvedSlackStatus {
+  reasoning: boolean;
+  /** `false`, or the line to show when tool calls start. */
+  tools: false | ((calls: readonly SlackToolCall[]) => string);
+  idle: string[];
+}
+
+export interface ResolvedSlackToolCards {
+  group: SlackToolCardGroup;
+  details?: (call: SlackToolCall) => string | undefined;
+  output?: (result: SlackToolResult) => string | undefined;
+}
+
+export interface ResolvedSlackReasoningCard {
+  title: string;
+  maxChars: number;
+}
+
+export interface ResolvedSlackReply {
+  mode: SlackReplyMode;
+  status: ResolvedSlackStatus;
+  toolCards: false | ResolvedSlackToolCards;
+  reasoningCard: false | ResolvedSlackReasoningCard;
+  toolLabel: (toolName: string) => string;
+  /** Author-facing notices about deprecated options that were honored. */
+  deprecations: string[];
+}
+
+export const DEFAULT_REASONING_CARD_TITLE = "Thinking";
+/** A modest share of `SLACK_MARKDOWN_TEXT_MAX_LEN`, which the whole streamed message shares. */
+export const DEFAULT_REASONING_CARD_MAX_CHARS = 1500;
+
+type ReplyInputs = Pick<
+  SlackChannelOptions,
+  "reply" | "toolLabels" | "streaming" | "thinkingSteps"
+> & { loadingMessages?: readonly string[] };
+
+function resolveToolLabel(
+  labels: SlackToolLabels | undefined
+): (toolName: string) => string {
+  if (labels === undefined) {
+    return (toolName) => toolName;
+  }
+  const lookup =
+    typeof labels === "function" ? labels : (name: string) => labels[name];
+  return (toolName) => {
+    const label = lookup(toolName);
+    return label === undefined || label === "" ? toolName : label;
+  };
+}
+
+function defaultToolStatusLine(
+  toolLabel: (toolName: string) => string
+): (calls: readonly SlackToolCall[]) => string {
+  return (calls) => {
+    const names = [...new Set(calls.map((call) => toolLabel(call.toolName)))];
+    return `Running ${names.join(", ")}…`;
+  };
+}
+
+function resolveIdle(idle: readonly string[] | undefined): string[] {
+  const cleaned = (idle ?? []).filter((line) => line.trim() !== "");
+  return cleaned.length > 0 ? cleaned : [...SLACK_DEFAULT_LOADING_MESSAGES];
+}
+
+function resolveReasoningCard(
+  option: boolean | SlackReasoningCardOptions | undefined
+): false | ResolvedSlackReasoningCard {
+  if (option === undefined || option === false) {
+    return false;
+  }
+  const options = option === true ? {} : option;
+  const title = options.title?.trim();
+  return {
+    title:
+      title === undefined || title === ""
+        ? DEFAULT_REASONING_CARD_TITLE
+        : title,
+    maxChars:
+      options.maxChars !== undefined && options.maxChars > 0
+        ? options.maxChars
+        : DEFAULT_REASONING_CARD_MAX_CHARS,
+  };
+}
+
+function resolveToolCards(
+  option: SlackReplyOptions & { mode: "stream" }
+): false | ResolvedSlackToolCards {
+  const cards = option.toolCards;
+  if (cards === undefined || cards === false) {
+    return false;
+  }
+  if (cards === true) {
+    return { group: "per-tool", details: defaultToolCardDetails };
+  }
+  const group = cards.group ?? "per-tool";
+  if (cards.collapsible === false) {
+    return { group };
+  }
+  return {
+    group,
+    details: cards.details ?? defaultToolCardDetails,
+    output: cards.output,
+  };
+}
+
+/**
+ * Map the deprecated flags onto a `reply` shape with their old defaults
+ * (streaming on, per-call cards on), so a config that only sets these keeps
+ * behaving as it did. `null` when none of them is set.
+ */
+function legacyReplyOptions(
+  options: ReplyInputs
+): { reply: SlackReplyOptions; deprecations: string[] } | null {
+  const idle = options.loadingMessages;
+  if (
+    options.streaming === undefined &&
+    options.thinkingSteps === undefined &&
+    idle === undefined
+  ) {
+    return null;
+  }
+  const deprecations: string[] = [];
+  const mode: SlackReplyMode = options.streaming === false ? "post" : "stream";
+  // What legacy streaming showed: one title-only card per call.
+  const cards = options.thinkingSteps === false ? false : LEGACY_CARDS;
+  const replacement =
+    mode === "post"
+      ? 'reply: { mode: "post" }'
+      : cards === false
+        ? 'reply: { mode: "stream" }'
+        : 'reply: { mode: "stream", toolCards: { group: "per-call", collapsible: false } }';
+  if (idle !== undefined) {
+    deprecations.push(
+      `slackChannel({ loadingMessages }) is deprecated; use reply: { mode: "${mode}", status: { idle: [...] } }.`
+    );
+  }
+  if (options.streaming !== undefined) {
+    deprecations.push(
+      `slackChannel({ streaming: ${String(options.streaming)} }) is deprecated; use ${replacement}.`
+    );
+  }
+  if (options.thinkingSteps !== undefined) {
+    deprecations.push(
+      mode === "post"
+        ? "slackChannel({ thinkingSteps }) has no effect in post mode; remove it."
+        : `slackChannel({ thinkingSteps: ${String(options.thinkingSteps)} }) is deprecated; use ${replacement}.`
+    );
+  }
+  const status = { idle };
+  if (mode === "post") {
+    return { reply: { mode, status }, deprecations };
+  }
+  return { reply: { mode, status, toolCards: cards }, deprecations };
+}
+
+const LEGACY_CARDS = { group: "per-call", collapsible: false } as const;
+
+export function resolveSlackReply(options: ReplyInputs): ResolvedSlackReply {
+  const deprecations: string[] = [];
+  let reply: SlackReplyOptions = { mode: "post" };
+  const legacy = legacyReplyOptions(options);
+  if (options.reply !== undefined) {
+    reply = options.reply;
+    if (legacy !== null) {
+      const ignored = (
+        ["streaming", "thinkingSteps", "loadingMessages"] as const
+      ).filter((key) => options[key] !== undefined);
+      deprecations.push(
+        `slackChannel({ ${ignored.join(", ")} }) is ignored because reply is set; remove the deprecated option${ignored.length === 1 ? "" : "s"}.`
+      );
+    }
+  } else if (legacy !== null) {
+    reply = legacy.reply;
+    deprecations.push(...legacy.deprecations);
+  }
+
+  const toolLabel = resolveToolLabel(options.toolLabels);
+  const statusInput = reply.status ?? {};
+  const status: ResolvedSlackStatus = {
+    reasoning: statusInput.reasoning !== false,
+    tools:
+      statusInput.tools === false
+        ? false
+        : typeof statusInput.tools === "function"
+          ? statusInput.tools
+          : defaultToolStatusLine(toolLabel),
+    idle: resolveIdle(statusInput.idle),
+  };
+
+  if (reply.mode === "post") {
+    return {
+      mode: "post",
+      status,
+      toolCards: false,
+      reasoningCard: false,
+      toolLabel,
+      deprecations,
+    };
+  }
+  return {
+    mode: "stream",
+    status,
+    toolCards: resolveToolCards(reply),
+    reasoningCard: resolveReasoningCard(reply.reasoningCard),
+    toolLabel,
+    deprecations,
+  };
+}

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

@@ -57,6 +57,7 @@ import {
   dispatchInteractiveFromPayload,
 } from "./interactive.js";
 import { createSlackLogger, type SlackLog } from "./log.js";
+import { resolveSlackReply } from "./reply-options.js";
 import {
   type SlackSocketModeHandle,
   type SlackSocketModeOptions,
@@ -128,7 +129,8 @@ export function slackChannel(
   const credentials =
     options.credentials ?? credentialsFromEnv(options.envPrefix);
   const envKeys = slackEnvKeys(options.envPrefix);
-  const loadingMessages = options.loadingMessages;
+  const reply = resolveSlackReply(options);
+  const loadingMessages = reply.status.idle;
   const policy = options.policy;
   const blockExternals = resolveSlackBlockExternals(policy);
   const defaultInbound = createDefaultOnInbound(loadingMessages, policy);
@@ -174,11 +176,13 @@ export function slackChannel(
       events,
       buildDefaultEvents({
         credentials,
+        reply: options.reply,
+        toolLabels: options.toolLabels,
         streaming: options.streaming,
         thinkingSteps: options.thinkingSteps,
+        loadingMessages: options.loadingMessages,
         suggestedPrompts: options.suggestedPrompts,
         suggestedPromptsTitle: options.suggestedPromptsTitle,
-        loadingMessages,
         getLog,
       })
     );
@@ -252,6 +256,7 @@ export function slackChannel(
       ...(channelPosts === undefined
         ? {}
         : { slackChannelPosts: [...channelPosts.allow] }),
+      deprecations: reply.deprecations,
     },
     async receive(input: ReceiveInput, { send }) {
       const target = input.target ?? {};

package/src/channels/slack/stream.ts

@@ -4,11 +4,36 @@
 
 export type StreamTaskStatus = "pending" | "in_progress" | "complete" | "error";
 
+/**
+ * One update to a task card. Slack keeps one card per `id`: `title` and
+ * `status` replace the previous values, `details` and `output` are appended
+ * to what the card already shows.
+ */
 export interface StreamTaskChunk {
   type: "task_update";
   id: string;
   title: string;
   status: StreamTaskStatus;
+  details?: string;
+  output?: string;
+}
+
+export interface StreamMarkdownChunk {
+  type: "markdown_text";
+  text: string;
+}
+
+/**
+ * A `chat.*Stream` chunk. Slack fixes a stream's mode at `chat.startStream`:
+ * one opened with bare `markdown_text` rejects every later `chunks` append
+ * (`streaming_mode_mismatch`), and vice versa. The live-delivery strategy
+ * therefore always speaks chunks, wrapping text as `markdown_text` chunks so
+ * tool-step `task_update`s can share the same message.
+ */
+export type StreamChunk = StreamMarkdownChunk | StreamTaskChunk;
+
+export function markdownChunk(text: string): StreamMarkdownChunk {
+  return { type: "markdown_text", text };
 }
 
 /**
@@ -36,28 +61,10 @@ export function computeStreamAppend(
   return "";
 }
 
-/** Build task_update chunks for tool calls. */
-export function buildTaskChunksForCalls(
-  calls: Array<{ callId: string; toolName: string }>,
-  status: StreamTaskStatus
-): StreamTaskChunk[] {
-  return calls.map((call) => ({
-    type: "task_update" as const,
-    id: call.callId,
-    title: call.toolName,
-    status,
-  }));
-}
-
-export function buildTaskChunkForResult(args: {
-  callId: string;
-  toolName: string;
-  isError: boolean;
-}): StreamTaskChunk {
-  return {
-    type: "task_update",
-    id: args.callId,
-    title: args.toolName,
-    status: args.isError ? "error" : "complete",
-  };
+/** Clamp to `max` characters, ending in an ellipsis when cut. */
+export function truncateCardText(text: string, max: number): string {
+  if (text.length <= max) {
+    return text;
+  }
+  return `${text.slice(0, max - 1)}…`;
 }

package/src/channels/slack/tool-cards.ts

@@ -0,0 +1,221 @@
+/**
+ * Task cards for tool calls inside the streamed reply. One card per key:
+ * the call id for `per-call`, the tool name for `per-tool`. A card's title
+ * counts its calls and its status follows the whole group; with one call
+ * per key that reduces to the plain per-call card.
+ */
+
+import { redactSecretTokens } from "./redact.js";
+import type { ResolvedSlackToolCards } from "./reply-options.js";
+import { type StreamTaskChunk, truncateCardText } from "./stream.js";
+import type {
+  SlackChannelState,
+  SlackToolCall,
+  SlackToolResult,
+  ToolCardCount,
+} from "./types.js";
+
+/** The argument the playground puts in a built-in tool's header. */
+const TOOL_PRIMARY_ARGS: Readonly<Record<string, readonly string[]>> = {
+  grep: ["pattern"],
+  glob: ["glob_pattern", "globPattern"],
+  read: ["path", "file_path", "target_file"],
+  shell: ["command", "cmd"],
+  task: ["description", "prompt"],
+};
+/** For other tools: the telling key, if any. */
+const GENERIC_PRIMARY_ARGS = [
+  "pattern",
+  "query",
+  "command",
+  "cmd",
+  "path",
+  "file",
+  "file_path",
+  "target_file",
+  "url",
+  "prompt",
+  "description",
+  "name",
+  "message",
+];
+const PATH_ARGS = new Set([
+  "path",
+  "file",
+  "file_path",
+  "target_file",
+  "target_directory",
+  "targetDirectory",
+]);
+const LINE_MAX = 80;
+const JSON_MAX = 120;
+
+function oneLine(text: string, max: number): string {
+  return truncateCardText(
+    redactSecretTokens(text).replace(/\s+/g, " ").trim(),
+    max
+  );
+}
+
+/** Clamp the middle so both ends stay visible; tail-biased to keep filenames. */
+function clampPath(text: string, max: number): string {
+  const one = redactSecretTokens(text).replace(/\s+/g, " ").trim();
+  if (one.length <= max) {
+    return one;
+  }
+  const budget = max - 1;
+  const head = Math.max(1, Math.floor(budget * 0.35));
+  const tail = Math.max(1, budget - head);
+  return `${one.slice(0, head)}…${one.slice(one.length - tail)}`;
+}
+
+/**
+ * Default tool-card line for a call, matching the playground's tool header:
+ * the grep pattern, the glob pattern, the file path, the shell command. Other
+ * tools show a lone string argument bare, else compact JSON. No key labels,
+ * no knobs like `headLimit`.
+ */
+export function defaultToolCardDetails(
+  call: SlackToolCall
+): string | undefined {
+  const args = call.args;
+  if (args === undefined || args === null) {
+    return undefined;
+  }
+  if (typeof args === "string") {
+    const line = oneLine(args, LINE_MAX);
+    return line === "" ? undefined : line;
+  }
+  if (typeof args !== "object" || Array.isArray(args)) {
+    return oneLine(JSON.stringify(args), JSON_MAX);
+  }
+  const record = args as Record<string, unknown>;
+  for (const key of TOOL_PRIMARY_ARGS[call.toolName] ?? GENERIC_PRIMARY_ARGS) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return PATH_ARGS.has(key)
+        ? clampPath(value, LINE_MAX)
+        : oneLine(value, LINE_MAX);
+    }
+  }
+  const entries = Object.entries(record);
+  if (entries.length === 0) {
+    return undefined;
+  }
+  const lone = entries.length === 1 ? entries[0]?.[1] : undefined;
+  if (typeof lone === "string" && lone.trim() !== "") {
+    return oneLine(lone, LINE_MAX);
+  }
+  return oneLine(JSON.stringify(record), JSON_MAX);
+}
+
+export interface ToolCards {
+  forCalls(
+    state: SlackChannelState,
+    calls: readonly SlackToolCall[]
+  ): StreamTaskChunk[];
+  forResult(state: SlackChannelState, result: SlackToolResult): StreamTaskChunk;
+}
+
+function tallyFor(state: SlackChannelState, key: string): ToolCardCount {
+  if (state.toolCardCounts === undefined) {
+    state.toolCardCounts = {};
+  }
+  const existing = state.toolCardCounts[key];
+  if (existing !== undefined) {
+    return existing;
+  }
+  const created: ToolCardCount = { started: 0, done: 0, errors: 0 };
+  state.toolCardCounts[key] = created;
+  return created;
+}
+
+/**
+ * Slack appends each update's text to the card verbatim, so a group's later
+ * batch of lines brings its own line break.
+ */
+function appendLines(
+  tally: ToolCardCount,
+  field: "details" | "output",
+  lines: readonly string[]
+): string | undefined {
+  if (lines.length === 0) {
+    return undefined;
+  }
+  const already = tally[field] ?? 0;
+  tally[field] = already + lines.length;
+  return `${already > 0 ? "\n" : ""}${lines.join("\n")}`;
+}
+
+function present(line: string | undefined): line is string {
+  return line !== undefined && line !== "";
+}
+
+export function createToolCards(
+  cards: ResolvedSlackToolCards,
+  toolLabel: (toolName: string) => string
+): ToolCards {
+  const keyOf = (call: { callId: string; toolName: string }): string =>
+    cards.group === "per-call" ? call.callId : `tool:${call.toolName}`;
+  const title = (toolName: string, started: number): string => {
+    const label = toolLabel(toolName);
+    return started > 1 ? `${label} ×${started}` : label;
+  };
+
+  return {
+    forCalls(state, calls) {
+      const groups = new Map<string, SlackToolCall[]>();
+      for (const call of calls) {
+        const key = keyOf(call);
+        groups.set(key, [...(groups.get(key) ?? []), call]);
+      }
+      return [...groups.entries()].map(([key, group]) => {
+        const tally = tallyFor(state, key);
+        tally.started += group.length;
+        const chunk: StreamTaskChunk = {
+          type: "task_update",
+          id: key,
+          title: title(group[0]!.toolName, tally.started),
+          status: "in_progress",
+        };
+        const details = appendLines(
+          tally,
+          "details",
+          group.map((call) => cards.details?.(call)).filter(present)
+        );
+        if (details !== undefined) {
+          chunk.details = details;
+        }
+        return chunk;
+      });
+    },
+
+    forResult(state, result) {
+      const tally = tallyFor(state, keyOf(result));
+      tally.done += 1;
+      if (result.isError) {
+        tally.errors += 1;
+      }
+      const chunk: StreamTaskChunk = {
+        type: "task_update",
+        id: keyOf(result),
+        title: title(result.toolName, tally.started),
+        status:
+          tally.done < tally.started
+            ? "in_progress"
+            : tally.errors > 0
+              ? "error"
+              : "complete",
+      };
+      const output = appendLines(
+        tally,
+        "output",
+        [cards.output?.(result)].filter(present)
+      );
+      if (output !== undefined) {
+        chunk.output = output;
+      }
+      return chunk;
+    },
+  };
+}