@cursor/july 0.1.1

package/src/channels/slack/approvals.ts

@@ -0,0 +1,198 @@
+/**
+ * Slack Block Kit cards for human-in-the-loop tool approvals.
+ */
+
+import type { ApprovalDecision } from "../../types.js";
+
+export const SLACK_APPROVE_ACTION_ID = "agent_serve_approve";
+export const SLACK_DENY_ACTION_ID = "agent_serve_deny";
+
+export interface SlackApprovalActionValue {
+  sessionId: string;
+  callId: string;
+}
+
+export function encodeApprovalActionValue(
+  payload: SlackApprovalActionValue
+): string {
+  return JSON.stringify(payload);
+}
+
+export function parseApprovalActionValue(
+  raw: string
+): SlackApprovalActionValue | null {
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (
+      typeof value !== "object" ||
+      value === null ||
+      typeof (value as SlackApprovalActionValue).sessionId !== "string" ||
+      typeof (value as SlackApprovalActionValue).callId !== "string"
+    ) {
+      return null;
+    }
+    const sessionId = (value as SlackApprovalActionValue).sessionId;
+    const callId = (value as SlackApprovalActionValue).callId;
+    if (sessionId === "" || callId === "") {
+      return null;
+    }
+    return { sessionId, callId };
+  } catch {
+    return null;
+  }
+}
+
+export function decisionFromActionId(
+  actionId: string
+): ApprovalDecision | null {
+  if (actionId === SLACK_APPROVE_ACTION_ID) {
+    return "approve";
+  }
+  if (actionId === SLACK_DENY_ACTION_ID) {
+    return "deny";
+  }
+  return null;
+}
+
+const REDACTED = "[REDACTED]";
+const SENSITIVE_KEY =
+  /(?:pass(?:word|wd)?|secret|token|api[_-]?key|authorization|credential|private[_-]?key|access[_-]?key)/i;
+
+/** Strip likely secrets before args are shown in Slack cards. */
+export function redactSensitiveValues(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSensitiveValues(item));
+  }
+  if (typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(
+      value as Record<string, unknown>
+    )) {
+      out[key] = SENSITIVE_KEY.test(key)
+        ? REDACTED
+        : redactSensitiveValues(nested);
+    }
+    return out;
+  }
+  return value;
+}
+
+const SLACK_FIELD_MRDKWN_MAX = 2000;
+const SLACK_ARGS_LABEL = "*Args (redacted)*\n```";
+
+/** Max arg body that fits a section `fields` mrkdwn entry (2000 chars incl. label + fences). */
+const SLACK_ARGS_DISPLAY_MAX =
+  SLACK_FIELD_MRDKWN_MAX - SLACK_ARGS_LABEL.length - "```".length - 1;
+
+/**
+ * Full redacted JSON for Slack display. Never silently truncates without
+ * noting that execution still uses the complete args.
+ */
+export function formatArgsForSlackDisplay(value: unknown): string {
+  if (value === undefined || value === null) {
+    return "";
+  }
+  const redacted = redactSensitiveValues(value);
+  const text =
+    typeof redacted === "string" ? redacted : JSON.stringify(redacted, null, 2);
+  if (text.length <= SLACK_ARGS_DISPLAY_MAX) {
+    return text;
+  }
+  const suffix = `\n(${text.length} chars total; execution uses full args)`;
+  const bodyBudget = Math.max(0, SLACK_ARGS_DISPLAY_MAX - suffix.length - 1);
+  const out = `${text.slice(0, bodyBudget)}…${suffix}`;
+  return out.length <= SLACK_ARGS_DISPLAY_MAX
+    ? out
+    : out.slice(0, SLACK_ARGS_DISPLAY_MAX);
+}
+
+export function buildApprovalBlocks(args: {
+  sessionId: string;
+  callId: string;
+  toolName: string;
+  args?: unknown;
+}): unknown[] {
+  const value = encodeApprovalActionValue({
+    sessionId: args.sessionId,
+    callId: args.callId,
+  });
+  const argsText = formatArgsForSlackDisplay(args.args);
+  const fields: Array<{ type: "mrkdwn"; text: string }> = [
+    {
+      type: "mrkdwn",
+      text: `*Tool*\n\`${args.toolName}\``,
+    },
+  ];
+  if (argsText !== "") {
+    fields.push({
+      type: "mrkdwn",
+      text: `*Args (redacted)*\n\`\`\`${argsText}\`\`\``,
+    });
+  }
+
+  return [
+    {
+      type: "header",
+      text: {
+        type: "plain_text",
+        text: "Approval required",
+        emoji: true,
+      },
+    },
+    {
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: "A tool call is parked until someone in this thread approves or denies it.",
+      },
+    },
+    {
+      type: "section",
+      fields,
+    },
+    {
+      type: "actions",
+      block_id: `approval_${args.callId}`.slice(0, 255),
+      elements: [
+        {
+          type: "button",
+          action_id: SLACK_APPROVE_ACTION_ID,
+          text: { type: "plain_text", text: "Approve", emoji: true },
+          style: "primary",
+          value,
+        },
+        {
+          type: "button",
+          action_id: SLACK_DENY_ACTION_ID,
+          text: { type: "plain_text", text: "Deny", emoji: true },
+          style: "danger",
+          value,
+        },
+      ],
+    },
+  ];
+}
+
+export function buildResolvedApprovalBlocks(args: {
+  toolName: string;
+  decision: ApprovalDecision;
+  byUserId?: string;
+}): unknown[] {
+  const verb = args.decision === "approve" ? "Approved" : "Denied";
+  const by =
+    args.byUserId === undefined || args.byUserId === ""
+      ? ""
+      : ` by <@${args.byUserId}>`;
+  return [
+    {
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: `*${verb}*${by} — \`${args.toolName}\``,
+      },
+    },
+  ];
+}

package/src/channels/slack/assistant.ts

@@ -0,0 +1,76 @@
+/**
+ * Assistant thread UX: titles and suggested prompts.
+ */
+
+import { setSuggestedPrompts, setThreadTitle, truncateTitle } from "./api.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type { SlackBotToken, SlackSuggestedPrompt } from "./types.js";
+
+export function firstNonEmptyLine(text: string): string | undefined {
+  for (const line of text.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+  }
+  return undefined;
+}
+
+export function firstLineTitle(text: string): string {
+  return truncateTitle(firstNonEmptyLine(text) ?? "Conversation");
+}
+
+export async function maybeSetThreadTitle(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  title: string;
+  log?: SlackLog;
+}): Promise<boolean> {
+  const log = args.log ?? defaultSlackLog;
+  const result = await setThreadTitle({
+    botToken: args.botToken,
+    channelId: args.channelId,
+    threadTs: args.threadTs,
+    title: args.title,
+  });
+  if (!result.ok) {
+    log.warn("setTitle not-ok", {
+      error: result.error,
+      channel: args.channelId,
+      thread_ts: args.threadTs,
+    });
+    return false;
+  }
+  return true;
+}
+
+export async function maybeSetSuggestedPrompts(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  prompts: SlackSuggestedPrompt[];
+  title?: string;
+  log?: SlackLog;
+}): Promise<boolean> {
+  const log = args.log ?? defaultSlackLog;
+  if (args.prompts.length === 0) {
+    return false;
+  }
+  const result = await setSuggestedPrompts({
+    botToken: args.botToken,
+    channelId: args.channelId,
+    threadTs: args.threadTs,
+    prompts: args.prompts,
+    ...(args.title === undefined ? {} : { title: args.title }),
+  });
+  if (!result.ok) {
+    log.warn("setSuggestedPrompts not-ok", {
+      error: result.error,
+      channel: args.channelId,
+      thread_ts: args.threadTs,
+    });
+    return false;
+  }
+  return true;
+}

package/src/channels/slack/auth.ts

@@ -0,0 +1,112 @@
+/**
+ * Slack auth helpers — AuthContext builders for thread-scoped sessions.
+ */
+
+import { samePrincipal } from "../../internal/auth.js";
+import type { AuthContext } from "../../types.js";
+import type { SlackBinding, SlackMessage } from "./types.js";
+
+/**
+ * Build a thread-scoped principal so any participant in the same Slack
+ * thread can continue the session. The triggering user is preserved in
+ * attributes for message context.
+ */
+export function buildSlackAuthContext(args: {
+  channelId: string;
+  threadTs: string;
+  teamId?: string;
+  userId?: string;
+  userName?: string;
+  isBot?: boolean;
+  /**
+   * Engagement surface that started the session (e.g. `"channel_post"` for
+   * the opt-in channel watch). Recorded as an attribute; the principal stays
+   * thread-scoped so an @mention in the same thread continues the session.
+   */
+  engagement?: string;
+}): AuthContext {
+  const team = args.teamId ?? "unknown";
+  const principalId = `slack:${team}:${args.channelId}:${args.threadTs}`;
+  const attributes: Record<string, string> = {
+    channel_id: args.channelId,
+    thread_ts: args.threadTs,
+  };
+  if (args.teamId !== undefined) {
+    attributes.team_id = args.teamId;
+  }
+  if (args.userId !== undefined) {
+    attributes.user_id = args.userId;
+  }
+  if (args.userName !== undefined) {
+    attributes.user_name = args.userName;
+  }
+  if (args.isBot === true) {
+    attributes.author_type = "bot";
+  }
+  if (args.engagement !== undefined) {
+    attributes.engagement = args.engagement;
+  }
+  return {
+    authenticator: "slack",
+    principalId,
+    principalType: "user",
+    attributes,
+  };
+}
+
+/**
+ * Auth for a Slack user clicking an interactive Approve/Deny button.
+ * Uses the clicker's identity for {@link SessionEngine.resolveApproval},
+ * not the stored session principal (which would bypass ownership checks).
+ */
+export function buildSlackInteractiveApprovalAuth(args: {
+  sessionAuth: AuthContext;
+  channelId: string;
+  threadTs: string;
+  teamId?: string;
+  clickingUserId: string;
+}): AuthContext {
+  const clickerAuth = buildSlackAuthContext({
+    channelId: args.channelId,
+    threadTs: args.threadTs,
+    teamId: args.teamId,
+    userId: args.clickingUserId,
+  });
+  if (samePrincipal(args.sessionAuth, clickerAuth)) {
+    return clickerAuth;
+  }
+  const userSuffix = `:${args.clickingUserId}`;
+  if (
+    args.clickingUserId !== "" &&
+    args.sessionAuth.principalId.endsWith(userSuffix)
+  ) {
+    return {
+      ...clickerAuth,
+      principalId: args.sessionAuth.principalId,
+    };
+  }
+  return clickerAuth;
+}
+
+export function defaultSlackAuth(
+  message: SlackMessage,
+  ctx: SlackBinding,
+  options?: { engagement?: string }
+): AuthContext | null {
+  if (message.author === undefined) {
+    return null;
+  }
+  return buildSlackAuthContext({
+    channelId: ctx.slack.channelId,
+    threadTs: ctx.slack.threadTs,
+    ...(message.teamId === undefined ? {} : { teamId: message.teamId }),
+    userId: message.author.userId,
+    ...(message.author.userName === undefined
+      ? {}
+      : { userName: message.author.userName }),
+    isBot: message.author.isBot,
+    ...(options?.engagement === undefined
+      ? {}
+      : { engagement: options.engagement }),
+  });
+}

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

@@ -0,0 +1,219 @@
+/**
+ * Opt-in channel watch: dispatch on posts in allowlisted channels.
+ *
+ * Filtering rules (the anti-slop guarantees):
+ * - Only explicitly allowlisted channels are watched — no wildcard.
+ * - Top-level posts only by default; thread replies never dispatch unless
+ *   `posts: "all"` is configured.
+ * - Posts that @mention the bot are skipped here (the `app_mention` path
+ *   owns them), and bot-authored posts are dropped upstream in parsing.
+ * - An optional debounce window lets rapid edits settle: edits update the
+ *   pending text, deleting the post cancels the dispatch.
+ */
+
+import type { WebClient } from "@slack/web-api";
+import type { SlackChannelMessageEvent } from "./inbound.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type { SlackChannelPostsOptions, SlackMessage } from "./types.js";
+
+const CHANNEL_ID_PATTERN = /^[CG][A-Z0-9]+$/;
+
+/** Allowlist over channel ids and `#names` (names resolve lazily). */
+export class SlackChannelAllowlist {
+  private readonly ids = new Set<string>();
+  private readonly names = new Set<string>();
+
+  constructor(entries: readonly string[]) {
+    for (const raw of entries) {
+      const entry = raw.trim();
+      if (entry === "") {
+        continue;
+      }
+      if (entry.startsWith("#")) {
+        this.names.add(entry.slice(1).toLowerCase());
+      } else if (CHANNEL_ID_PATTERN.test(entry)) {
+        this.ids.add(entry);
+      } else {
+        // Bare name without "#" — treat as a name for forgiving authoring.
+        this.names.add(entry.toLowerCase());
+      }
+    }
+  }
+
+  matches(channelId: string): boolean {
+    return this.ids.has(channelId);
+  }
+
+  unresolvedNames(): string[] {
+    return [...this.names];
+  }
+
+  /** Fold resolved `name → id` pairs into the id set. */
+  applyResolvedNames(resolved: ReadonlyMap<string, string>): void {
+    for (const name of this.names) {
+      const id = resolved.get(name);
+      if (id !== undefined) {
+        this.ids.add(id);
+      }
+    }
+  }
+}
+
+/**
+ * Resolve channel `#names` to ids via `conversations.list`. Best-effort:
+ * returns whatever resolved; the caller logs names that stayed unresolved.
+ */
+export async function resolveChannelNames(
+  client: WebClient,
+  names: readonly string[],
+  log: SlackLog = defaultSlackLog
+): Promise<Map<string, string>> {
+  const wanted = new Set(names.map((name) => name.toLowerCase()));
+  const resolved = new Map<string, string>();
+  if (wanted.size === 0) {
+    return resolved;
+  }
+  let cursor: string | undefined;
+  for (let page = 0; page < 20 && resolved.size < wanted.size; page += 1) {
+    const response = await client.conversations.list({
+      types: "public_channel,private_channel",
+      exclude_archived: true,
+      limit: 200,
+      ...(cursor === undefined ? {} : { cursor }),
+    });
+    for (const channel of response.channels ?? []) {
+      const name = channel.name?.toLowerCase();
+      if (name !== undefined && wanted.has(name) && channel.id !== undefined) {
+        resolved.set(name, channel.id);
+      }
+    }
+    cursor = response.response_metadata?.next_cursor || undefined;
+    if (cursor === undefined) {
+      break;
+    }
+  }
+  for (const name of wanted) {
+    if (!resolved.has(name)) {
+      log.error("channel watch: could not resolve channel name", {
+        name: `#${name}`,
+      });
+    }
+  }
+  return resolved;
+}
+
+export interface ChannelPostWatcher {
+  /** Handle a parsed channel message event. Returns true when consumed. */
+  handle(event: SlackChannelMessageEvent, eventId?: string): boolean;
+  /** Cancel pending debounced dispatches. */
+  stop(): void;
+}
+
+export function createChannelPostWatcher(args: {
+  options: SlackChannelPostsOptions;
+  allowlist: SlackChannelAllowlist;
+  /** Bot user id (from `auth.test`) so bot mentions route via app_mention. */
+  getBotUserId: () => string | undefined;
+  dispatch: (message: SlackMessage, eventId?: string) => void;
+  log?: SlackLog;
+}): ChannelPostWatcher {
+  const log = args.log ?? defaultSlackLog;
+  const includeReplies = args.options.posts === "all";
+  const debounceMs = args.options.debounceMs ?? 0;
+  const pending = new Map<
+    string,
+    {
+      timer: ReturnType<typeof setTimeout>;
+      message: SlackMessage;
+      eventId?: string;
+    }
+  >();
+
+  const pendingKey = (channelId: string, ts: string): string =>
+    `${channelId}:${ts}`;
+
+  function skip(reason: string, message: SlackMessage): true {
+    log.debug(`channel watch skip (${reason})`, {
+      channel: message.channelId,
+      message_ts: message.ts,
+      thread_ts: message.threadTs,
+    });
+    return true;
+  }
+
+  function fire(message: SlackMessage, eventId: string | undefined): void {
+    log.info("channel watch dispatch", {
+      channel: message.channelId,
+      message_ts: message.ts,
+      thread_ts: message.threadTs,
+      event_id: eventId,
+    });
+    args.dispatch(message, eventId);
+  }
+
+  return {
+    handle(event, eventId) {
+      if (event.kind === "deleted") {
+        const key = pendingKey(event.channelId, event.ts);
+        const entry = pending.get(key);
+        if (entry !== undefined) {
+          clearTimeout(entry.timer);
+          pending.delete(key);
+          log.info("channel watch cancel (post deleted)", {
+            channel: event.channelId,
+            message_ts: event.ts,
+          });
+        }
+        return true;
+      }
+
+      const message = event.message;
+      if (!args.allowlist.matches(message.channelId)) {
+        return skip("channel not allowlisted", message);
+      }
+
+      if (event.kind === "edited") {
+        const entry = pending.get(pendingKey(message.channelId, message.ts));
+        if (entry !== undefined) {
+          entry.message = { ...entry.message, ...message };
+        }
+        // Edits never (re-)dispatch on their own.
+        return true;
+      }
+
+      if (!includeReplies && message.ts !== message.threadTs) {
+        return skip("thread reply (posts: top-level)", message);
+      }
+      const botUserId = args.getBotUserId();
+      if (botUserId !== undefined && message.text.includes(`<@${botUserId}>`)) {
+        return skip("bot mention (app_mention path owns it)", message);
+      }
+
+      if (debounceMs <= 0) {
+        fire(message, eventId);
+        return true;
+      }
+      const key = pendingKey(message.channelId, message.ts);
+      const existing = pending.get(key);
+      if (existing !== undefined) {
+        clearTimeout(existing.timer);
+      }
+      const entry = {
+        timer: setTimeout(() => {
+          pending.delete(key);
+          fire(entry.message, entry.eventId);
+        }, debounceMs),
+        message,
+        ...(eventId === undefined ? {} : { eventId }),
+      };
+      pending.set(key, entry);
+      return true;
+    },
+    stop() {
+      for (const entry of pending.values()) {
+        clearTimeout(entry.timer);
+      }
+      pending.clear();
+    },
+  };
+}

package/src/channels/slack/constants.ts

@@ -0,0 +1,30 @@
+/** Defaults for the Slack channel pack. */
+
+export const SLACK_CHANNEL_ID = "slack";
+export const SLACK_TYPING_MIN_GROWTH = 4;
+export const SLACK_TYPING_MIN_INTERVAL_MS = 5_000;
+/**
+ * Slack `assistant.threads.setStatus` limits each `loading_messages[]`
+ * entry to under 51 characters. `status` is often mirrored into that array,
+ * so keep both at 50.
+ */
+export const SLACK_STATUS_MAX_LEN = 50;
+export const SLACK_LOADING_MESSAGE_MAX_LEN = 50;
+export const SLACK_TITLE_MAX_LEN = 80;
+
+/** Rotating assistant status lines (Slack `loading_messages`). */
+export const SLACK_DEFAULT_LOADING_MESSAGES = [
+  "Thinking…",
+  "Working on it…",
+  "Almost there…",
+] as const;
+
+/** Slack API errors that mean a feature is unavailable for this app. */
+export const SLACK_UNSUPPORTED_ERRORS: Set<string> = new Set([
+  "method_not_found",
+  "not_allowed",
+  "missing_scope",
+  "not_enabled",
+  "feature_not_enabled",
+  "unknown_method",
+]);