@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/slack.ts

@@ -0,0 +1,1286 @@
+/**
+ * Slack Bolt event handlers for the Shipwright agent.
+ *
+ * All dependencies are injected — no global config reads, no hardcoded
+ * runClaude import. Call createSlackApp() with the runner returned by
+ * createRunClaude() and your injected config values.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ErrorCapturingClient } from "@app-vitals/agent-lib/sentry";
+import type { App } from "@slack/bolt";
+import type { WebAPIPlatformError } from "@slack/web-api";
+import {
+  type AgentAccountStatusRef,
+  agentAccountStatusRef,
+} from "./agent-account-status-ref.ts";
+import {
+  type AgentSlackMembershipRef,
+  agentSlackMembershipRef,
+} from "./agent-slack-membership-ref.ts";
+import {
+  type AgentTrialExpiryRef,
+  agentTrialExpiryRef,
+} from "./agent-trial-expiry-ref.ts";
+import {
+  type ChatTokenReporter,
+  NoopChatTokenReporter,
+} from "./chat-token-reporter.ts";
+import type { ClaudeRunResult, ProgressCallback } from "./claude.ts";
+import {
+  ClaudeRunError,
+  ClaudeTimeoutError,
+  reportClaudeError,
+} from "./claude.ts";
+import {
+  formatPlanLink,
+  markdownToBlocks,
+  markdownToSlack,
+  richTextToMarkdown,
+} from "./format.ts";
+import { type Marker, parseMarkers } from "./markers.ts";
+import { threadKey as defaultThreadKey } from "./sessions.ts";
+import { SlackProgress } from "./slack-progress.ts";
+import { ThreadStatusTracker } from "./slack-thread-status-tracker.ts";
+import type { VoiceConfig } from "./voice.ts";
+import { synthesizeSpeech, transcribeAudio } from "./voice.ts";
+
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024; // 10MB
+
+function isInvalidBlocksError(err: unknown): boolean {
+  const e = err as Partial<WebAPIPlatformError>;
+  return (
+    e.code === "slack_webapi_platform_error" &&
+    e.data?.error === "invalid_blocks"
+  );
+}
+
+export interface SlackFile {
+  name: string;
+  mimetype: string;
+  size: number;
+  url_private?: string;
+}
+
+export async function downloadFile(
+  file: SlackFile,
+  botToken: string,
+): Promise<string | null> {
+  if (file.size > MAX_FILE_SIZE_BYTES) {
+    console.warn(
+      `[slack] skipping ${file.name} (${file.size} bytes) — exceeds 10MB limit`,
+    );
+    return null;
+  }
+  const url = file.url_private;
+  if (!url) return null;
+
+  let resp: Response;
+  try {
+    resp = await fetch(url, {
+      headers: { Authorization: `Bearer ${botToken}` },
+    });
+  } catch (err) {
+    console.warn(`[slack] file fetch error for ${file.name}:`, err);
+    return null;
+  }
+
+  if (!resp.ok) {
+    console.warn(
+      `[slack] file download failed for ${file.name}: ${resp.status}`,
+    );
+    return null;
+  }
+
+  const buffer = Buffer.from(await resp.arrayBuffer());
+  const tmpPath = join(tmpdir(), `shipwright-agent-${Date.now()}-${file.name}`);
+  await writeFile(tmpPath, buffer);
+  return tmpPath;
+}
+
+interface SlackConfig {
+  botToken: string;
+  appToken: string;
+  signingSecret: string;
+}
+
+/**
+ * Whether the agent has the credentials required to start its Slack Bolt App.
+ *
+ * Bolt's Socket Mode constructor throws "Must provide an App-Level Token" when
+ * `appToken` is empty, so the agent must skip Slack startup (offline mode)
+ * unless BOTH the bot token and the app-level token are present. Whitespace-only
+ * values are treated as absent.
+ */
+export function hasSlackCredentials(cfg: {
+  botToken: string;
+  appToken: string;
+}): boolean {
+  return cfg.botToken.trim() !== "" && cfg.appToken.trim() !== "";
+}
+
+type AppFactory = (cfg: {
+  token: string;
+  appToken: string;
+  socketMode: true;
+  signingSecret: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt App type is complex
+}) => any;
+
+const defaultAppFactory: AppFactory = (cfg) =>
+  new (require("@slack/bolt").App)(cfg);
+
+const noopSentryClient: ErrorCapturingClient = {
+  captureException: () => {},
+};
+
+type FileDownloaderFn = (
+  file: SlackFile,
+  botToken: string,
+) => Promise<string | null>;
+
+type ConversationsRepliesFn = (
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt client type is complex
+  client: any,
+  channel: string,
+  ts: string,
+) => Promise<{ messages?: { user?: string; text?: string; ts?: string }[] }>;
+
+export type TranscribeAudioFn = typeof transcribeAudio;
+export type SynthesizeSpeechFn = typeof synthesizeSpeech;
+type GetSessionFn = (key: string) => Promise<string | undefined>;
+
+export type ClaudeRunner = (
+  message: string,
+  sessionKey?: string,
+  onProgress?: ProgressCallback,
+  extraEnv?: Record<string, string>,
+) => Promise<ClaudeRunResult>;
+
+type ResolveUserFn = (
+  userId: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt client is complex
+  client: any,
+) => Promise<string>;
+
+type ResolveUserEmailFn = (
+  userId: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt client is complex
+  client: any,
+) => Promise<string | undefined>;
+
+/**
+ * The single shared Slack membership gate used by all three event handlers
+ * (message, app_mention, reaction_added) — SMR-4.1.
+ *
+ * Fails OPEN (allow) while the membership ref has never synced, or when
+ * restrict is false, so a persistent config-sync failure or a deliberately
+ * unrestricted config never blocks Slack access. Once restrict is true and
+ * the ref has synced, only a case-insensitive match against the synced
+ * member email list is allowed — an undefined email (resolution failed or
+ * absent) is rejected, never treated as a wildcard.
+ */
+export function isAllowedSlackSender(
+  email: string | undefined,
+  membershipRef: AgentSlackMembershipRef,
+): boolean {
+  if (!membershipRef.hasSynced()) return true;
+  const { restrict, emails } = membershipRef.get();
+  if (!restrict) return true;
+  if (!email) return false;
+  const lowered = email.toLowerCase();
+  return emails.some((e) => e.toLowerCase() === lowered);
+}
+
+/**
+ * The message posted (once per inbound event, no dedup) when isTrialExpired()
+ * rejects a Slack message/mention/reaction — ATE-3.1. Unlike
+ * shouldRejectSlackSender (which silently drops the message), the caller
+ * always replies with this so the user isn't met with unexplained silence.
+ */
+const TRIAL_EXPIRED_NOTICE = "This trial has ended — contact us to continue.";
+
+/**
+ * The shared trial-expiry gate used by all three event handlers (message,
+ * app_mention, reaction_added) — ATE-3.1. Runs before shouldRejectSlackSender
+ * and before any Claude session is invoked.
+ *
+ * Fails OPEN (not expired) while the ref has never synced, or when no trial
+ * is configured (trialExpiresAt null), so a persistent config-sync failure
+ * never locks a paying customer out of their own agent. Only a
+ * trialExpiresAt strictly in the past counts as expired — a trial expiring
+ * at exactly `now` is not yet locked out.
+ */
+export function isTrialExpired(
+  trialExpiryRef: AgentTrialExpiryRef,
+  now: () => Date = () => new Date(),
+): boolean {
+  if (!trialExpiryRef.hasSynced()) return false;
+  const trialExpiresAt = trialExpiryRef.get();
+  if (!trialExpiresAt) return false;
+  return trialExpiresAt.getTime() < now().getTime();
+}
+
+/**
+ * The message posted (once per inbound event) when isAccountPaused() rejects a
+ * Slack message/mention/reaction — SSP-8.3.
+ */
+export const ACCOUNT_PAUSED_NOTICE =
+  "This agent is paused because its account is not active — contact us to resume.";
+
+/**
+ * The shared account-status gate used by all three event handlers — SSP-8.3.
+ * Paused when the owning account is 'suspended' or 'trial_expired'. Fails OPEN
+ * while the ref has never synced, and for agents with no account (null) or an
+ * active account. Self-heals on the next config sync after reactivation.
+ */
+export function isAccountPaused(
+  accountStatusRef: AgentAccountStatusRef,
+): boolean {
+  if (!accountStatusRef.hasSynced()) return false;
+  const status = accountStatusRef.get();
+  return status === "suspended" || status === "trial_expired";
+}
+
+/**
+ * Returns the notice to reply with when an inbound event must be rejected
+ * (trial ended, or account paused), or null when the event may proceed.
+ */
+function gateNotice(
+  trialExpiryRef: AgentTrialExpiryRef,
+  accountStatusRef: AgentAccountStatusRef,
+): string | null {
+  if (isTrialExpired(trialExpiryRef)) return TRIAL_EXPIRED_NOTICE;
+  if (isAccountPaused(accountStatusRef)) return ACCOUNT_PAUSED_NOTICE;
+  return null;
+}
+
+/**
+ * Resolves the sender's email and checks it against isAllowedSlackSender(),
+ * logging a debug line for rejected senders. Returns true when the handler
+ * should return early (reject) — shared by all three event handlers so the
+ * resolve/check/log sequence isn't repeated per handler.
+ */
+async function shouldRejectSlackSender(
+  userId: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt client type is complex
+  client: any,
+  resolveUserEmailFn: ResolveUserEmailFn,
+  membershipRef: AgentSlackMembershipRef,
+): Promise<boolean> {
+  const senderEmail = await resolveUserEmailFn(userId, client).catch(
+    () => undefined,
+  );
+  if (isAllowedSlackSender(senderEmail, membershipRef)) return false;
+  console.log(`[slack] rejected sender (not a member): user=${userId}`);
+  return true;
+}
+
+// Normalizes text for the speak-marker fallback's duplicate-content check:
+// lowercased, trimmed, trailing punctuation stripped, internal whitespace
+// collapsed. Deliberately simple — not fuzzy matching, just enough to catch
+// the common "Here is the answer. [speak:Here is the answer]" pattern where
+// the marker text is a near-verbatim echo of the already-posted reply.
+function normalizeForComparison(text: string | undefined): string {
+  if (!text) return "";
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[.!?]+$/, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export async function dispatchMarkers(
+  markers: Marker[],
+  {
+    client,
+    channel,
+    postedTs,
+    threadTs,
+    workspace,
+    synthesizeSpeechFn,
+    voiceConfig = {},
+    postedText,
+  }: {
+    // biome-ignore lint/suspicious/noExplicitAny: Bolt client type is complex
+    client: any;
+    channel: string;
+    postedTs?: string;
+    threadTs?: string;
+    workspace?: string;
+    synthesizeSpeechFn?: SynthesizeSpeechFn;
+    voiceConfig?: VoiceConfig;
+    // The already-posted visible reply text (e.g. `cleaned`/`formatted`), if
+    // any. Used so the speak-marker text fallback can skip posting when it
+    // would just duplicate content the user already sees.
+    postedText?: string;
+  },
+): Promise<void> {
+  for (const marker of markers) {
+    if (marker.type === "silent") continue;
+
+    if (marker.type === "react") {
+      if (postedTs) {
+        for (const emoji of marker.emojis) {
+          await client.reactions
+            .add({ channel, timestamp: postedTs, name: emoji })
+            .catch((err: unknown) =>
+              console.warn("[markers] react failed:", err),
+            );
+        }
+      }
+    } else if (marker.type === "upload") {
+      const absPath = marker.path.startsWith("/")
+        ? marker.path
+        : workspace
+          ? join(workspace, marker.path)
+          : marker.path;
+      if (existsSync(absPath)) {
+        await client.files
+          .uploadV2({
+            channel_id: channel,
+            thread_ts: threadTs,
+            file: await readFile(absPath),
+            filename: absPath.split("/").pop() ?? "file",
+          })
+          .catch((err: unknown) =>
+            console.warn("[markers] upload failed:", err),
+          );
+      } else {
+        console.warn(`[markers] upload: file not found: ${absPath}`);
+      }
+    } else if (marker.type === "plan") {
+      const { text, blocks } = formatPlanLink(marker.url);
+      await client.chat
+        .postMessage({ channel, thread_ts: threadTs, text, blocks })
+        .catch((err: unknown) =>
+          console.warn("[markers] plan link post failed:", err),
+        );
+    } else if (marker.type === "speak") {
+      if (!synthesizeSpeechFn) {
+        console.warn(
+          "[markers] speak marker found but synthesizeSpeechFn not injected — skipping",
+        );
+        continue;
+      }
+      const postSpeakTextFallback = () => {
+        const normalizedPosted = normalizeForComparison(postedText);
+        if (
+          normalizedPosted.length > 0 &&
+          normalizedPosted === normalizeForComparison(marker.text)
+        ) {
+          console.warn(
+            "[markers] speak text fallback skipped — duplicates already-posted reply",
+          );
+          return Promise.resolve();
+        }
+        return client.chat
+          .postMessage({ channel, thread_ts: threadTs, text: marker.text })
+          .catch((err: unknown) =>
+            console.warn("[markers] speak text fallback post failed:", err),
+          );
+      };
+
+      try {
+        const audioPath = await synthesizeSpeechFn(marker.text, voiceConfig);
+        if (audioPath) {
+          await client.files
+            .uploadV2({
+              channel_id: channel,
+              thread_ts: threadTs,
+              file: await readFile(audioPath),
+              filename: audioPath.split("/").pop() ?? "response.mp3",
+            })
+            .catch((err: unknown) =>
+              console.warn("[markers] speak upload failed:", err),
+            );
+        } else {
+          console.warn(
+            "[markers] speak synthesis returned null — posting text fallback",
+          );
+          await postSpeakTextFallback();
+        }
+      } catch (err) {
+        console.warn(
+          "[markers] speak synthesis failed — posting text fallback:",
+          err,
+        );
+        await postSpeakTextFallback();
+      }
+    }
+  }
+}
+
+function _classifyError(err: unknown): { lead: string; known: boolean } {
+  if (err instanceof ClaudeTimeoutError) {
+    return {
+      lead: `:hourglass_flowing_sand: Session timed out after ${Math.round(err.timeoutMs / 60_000)} minutes. Please retry.`,
+      known: true,
+    };
+  }
+  if (err instanceof ClaudeRunError) {
+    const status = err.apiErrorStatus;
+    const detail = err.resultMessage;
+    if (status === 429 && /usage limit/i.test(detail)) {
+      return {
+        lead: ":warning: I've hit the org's monthly Claude usage limit. Please try again later or contact the agent owner.",
+        known: true,
+      };
+    }
+    if (status === 429) {
+      return {
+        lead: ":warning: Rate-limited by Anthropic — try again in a moment.",
+        known: true,
+      };
+    }
+    if (status === 529) {
+      return {
+        lead: ":warning: Anthropic's API is overloaded. This is usually transient — try again in ~30s. Status: https://status.claude.com",
+        known: true,
+      };
+    }
+    if (status === 500 || status === 502 || status === 503 || status === 504) {
+      return {
+        lead: `:warning: Anthropic API hiccup (${status}). This is server-side and usually transient — please retry. Status: https://status.claude.com`,
+        known: true,
+      };
+    }
+    if (status === 401 || status === 403) {
+      return {
+        lead: `:warning: Auth failure with Anthropic (${status}). The agent's API key or OAuth token may need to be refreshed.`,
+        known: true,
+      };
+    }
+    return {
+      lead: `:warning: Claude returned an error${status ? ` (${status})` : ""}.`,
+      known: false,
+    };
+  }
+  return { lead: ":warning: Something went wrong.", known: false };
+}
+
+function _detailLine(err: unknown): string {
+  if (err instanceof ClaudeRunError) return err.resultMessage;
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  return String(err);
+}
+
+export function formatRunErrorForSlack(err: unknown): string {
+  const { lead, known } = _classifyError(err);
+  const detail = _detailLine(err);
+  const stack =
+    !known && err instanceof Error && err.stack ? err.stack : undefined;
+  const stackBlock = stack ? `\n\n\`\`\`\n${stack}\n\`\`\`` : "";
+  return `${lead}\n\n_Detail:_ ${detail}${stackBlock}`;
+}
+
+const defaultConversationsRepliesFn: ConversationsRepliesFn = async (
+  client,
+  channel,
+  ts,
+) => client.conversations.replies({ channel, ts, limit: 200 });
+
+async function buildPromptWithFiles(
+  text: string,
+  files: SlackFile[] | undefined,
+  fileDownloaderFn: FileDownloaderFn,
+  botToken: string,
+  transcribeAudioFn: TranscribeAudioFn,
+  voiceConfig: VoiceConfig,
+): Promise<string> {
+  if (!files?.length) return text;
+  const fileParts: string[] = [];
+  for (const file of files) {
+    try {
+      const filePath = await fileDownloaderFn(file, botToken);
+      if (filePath) {
+        if (file.mimetype.startsWith("audio/")) {
+          try {
+            const transcript = await transcribeAudioFn(filePath, voiceConfig);
+            fileParts.push(
+              transcript
+                ? `[voice transcript: ${transcript}]`
+                : `[file: ${filePath}]`,
+            );
+          } catch (err) {
+            console.warn("[voice] transcription error:", err);
+            fileParts.push(`[file: ${filePath}]`);
+          }
+        } else {
+          fileParts.push(`[file: ${filePath}]`);
+        }
+      }
+    } catch (err) {
+      console.warn(`[slack] file download error for ${file.name}:`, err);
+    }
+  }
+  return fileParts.length ? `${fileParts.join("\n")}\n${text}`.trim() : text;
+}
+
+/**
+ * Starts a run's progress tracking. enter() on ThreadStatusTracker is
+ * ALWAYS called by every handler (every enter() needs a matching exit(), or
+ * the refcount leaks upward forever) — every message gets its own
+ * independent stream lifecycle regardless of the refcount; the boolean only
+ * picks the seed card's title ("Queued…" when another message on this
+ * thread is already in flight, "Thinking…" otherwise).
+ */
+async function startProgress(
+  progress: SlackProgress,
+  isFirstInThread: boolean,
+): Promise<void> {
+  await progress.start({ queued: !isFirstInThread });
+}
+
+/**
+ * The finish()-side counterpart of startProgress() — see its doc comment.
+ * `wasSuppressed` (STS2-3.1) signals the run's reply was suppressed (e.g. a
+ * [silent] marker) so finish() titles the stream's fallback completion card
+ * "Ack" instead of "Done" — see SlackProgressFinishOptions. Defaults to
+ * `false`, matching prior behavior for callers that don't compute silence.
+ */
+async function finishProgress(
+  progress: SlackProgress,
+  isLastInThread: boolean,
+  wasSuppressed = false,
+): Promise<void> {
+  await progress.finish({
+    stillInFlight: !isLastInThread,
+    silent: wasSuppressed,
+  });
+}
+
+export function createSlackApp(
+  runner: ClaudeRunner,
+  formatter: (text: string) => string = markdownToSlack,
+  getThreadKey: typeof defaultThreadKey = defaultThreadKey,
+  appFactory: AppFactory = defaultAppFactory,
+  slackConfig: SlackConfig = { botToken: "", appToken: "", signingSecret: "" },
+  sentryClient: ErrorCapturingClient = noopSentryClient,
+  fileDownloaderFn: FileDownloaderFn = downloadFile,
+  voiceConfig: VoiceConfig = {},
+  transcribeAudioFn: TranscribeAudioFn = transcribeAudio,
+  synthesizeSpeechFn: SynthesizeSpeechFn = synthesizeSpeech,
+  resolveUserFn: ResolveUserFn = async (userId) => userId,
+  botUserId: string | undefined = undefined,
+  conversationsRepliesFn: ConversationsRepliesFn = defaultConversationsRepliesFn,
+  getSessionFn: GetSessionFn = async () => undefined,
+  blocksConverter: typeof markdownToBlocks = markdownToBlocks,
+  chatTokenReporter: ChatTokenReporter = new NoopChatTokenReporter(),
+  resolveUserEmailFn: ResolveUserEmailFn = async () => undefined,
+  membershipRef: AgentSlackMembershipRef = agentSlackMembershipRef,
+  trialExpiryRef: AgentTrialExpiryRef = agentTrialExpiryRef,
+  accountStatusRef: AgentAccountStatusRef = agentAccountStatusRef,
+): App {
+  const app = appFactory({
+    token: slackConfig.botToken,
+    appToken: slackConfig.appToken,
+    socketMode: true,
+    signingSecret: slackConfig.signingSecret,
+  });
+
+  // Per-thread refcount gating SlackProgress.start()/finish() — see
+  // slack-thread-status-tracker.ts for why this exists. Closure-scoped (one
+  // instance per createSlackApp() call), never module-level, so multiple app
+  // instances (e.g. in tests) stay isolated from each other's refcount state.
+  const threadStatusTracker = new ThreadStatusTracker();
+
+  // Registry of live streams: SlackProgress.streamKey() ("channel:ts") ->
+  // the instance itself (AGS-1.1). Populated when startStream() succeeds
+  // (i.e. progress.streamKey() first becomes defined, right after start())
+  // and cleared unconditionally when the stream closes, success or failure
+  // (right after finish()) — so it never leaks entries for completed runs.
+  // Closure-scoped (one instance per createSlackApp() call), same lifecycle
+  // as threadStatusTracker above — never module-level.
+  const liveStreams = new Map<string, SlackProgress>();
+
+  function registerStream(progress: SlackProgress): void {
+    const key = progress.streamKey();
+    if (key) liveStreams.set(key, progress);
+  }
+
+  function unregisterStream(progress: SlackProgress): void {
+    const key = progress.streamKey();
+    if (key) liveStreams.delete(key);
+  }
+
+  // The bot's own workspace team ID — chat.startStream()'s recipient_team_id
+  // requires it for every non-DM stream (STS-2.1; see SlackProgress.isDM).
+  // Resolved once via client.auth.test() here at app construction and cached
+  // in this closure for the life of this createSlackApp() instance — mirrors
+  // threadStatusTracker/liveStreams above (closure-scoped, never
+  // module-level, so multiple app instances in tests stay isolated).
+  // Kicked off eagerly (not lazily per-message) so the round-trip overlaps
+  // Bolt's own startup instead of adding latency to the first non-DM
+  // message. Resolves to undefined — never throws, never rejects — when the
+  // app's client lacks `auth.test` entirely (e.g. a test/mock appFactory) or
+  // the call itself fails; callers then just omit recipient_team_id, same as
+  // a DM payload.
+  const teamIdPromise: Promise<string | undefined> =
+    typeof app.client?.auth?.test === "function"
+      ? app.client.auth.test().then(
+          (resp: { team_id?: string }) => resp?.team_id,
+          (err: unknown) => {
+            console.warn(
+              "[slack] auth.test() failed — recipient_team_id unavailable for non-DM Thinking Steps streams:",
+              err instanceof Error ? err.message : String(err),
+            );
+            return undefined;
+          },
+        )
+      : Promise.resolve(undefined);
+
+  // DMs: respond to every message.
+  // Channels: respond only if bot has already replied in this thread.
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt callback params
+  app.message(async ({ message, say, client }: any) => {
+    if (message.subtype && message.subtype !== "file_share") return;
+    const msg = message as {
+      text?: string;
+      channel: string;
+      ts: string;
+      thread_ts?: string;
+      channel_type?: string;
+      files?: SlackFile[];
+      user?: string;
+      blocks?: Array<{ type: string; elements?: unknown[] }>;
+    };
+
+    const isDM = msg.channel_type === "im";
+    const hasText = !!msg.text?.trim();
+    const hasFiles = !!msg.files?.length;
+    const hasRichText = !!msg.blocks?.some((b) => b.type === "rich_text");
+
+    if (!hasText && !hasRichText && !hasFiles) return;
+
+    if (!isDM) {
+      if (!msg.thread_ts) return;
+      if (!(await getSessionFn(getThreadKey(msg.channel, msg.thread_ts))))
+        return;
+    }
+
+    const gateMsg = gateNotice(trialExpiryRef, accountStatusRef);
+    if (gateMsg) {
+      await say({
+        text: gateMsg,
+        thread_ts: msg.thread_ts ?? msg.ts,
+      });
+      return;
+    }
+
+    if (
+      msg.user &&
+      (await shouldRejectSlackSender(
+        msg.user,
+        client,
+        resolveUserEmailFn,
+        membershipRef,
+      ))
+    ) {
+      return;
+    }
+
+    const sessionKey = getThreadKey(msg.channel, msg.thread_ts ?? msg.ts);
+    const replyTs = msg.thread_ts ?? msg.ts;
+
+    // recipient_team_id is only meaningful (and only fetched) for non-DM
+    // threads — see teamIdPromise's doc comment and SlackProgress.isDM
+    // (STS-2.1).
+    const recipientTeamId = isDM ? undefined : await teamIdPromise;
+    const progress = new SlackProgress({
+      client,
+      channel: msg.channel,
+      threadTs: replyTs,
+      isDM,
+      recipientUserId: msg.user,
+      recipientTeamId,
+    });
+    // enter()/exit() are ALWAYS called (every enter() needs a matching
+    // exit(), or the refcount leaks upward forever) — see startProgress()'s
+    // doc comment for what the boolean gates (AC #5).
+    await startProgress(progress, threadStatusTracker.enter(sessionKey));
+    // Registers the stream (no-op when startStream() failed to open one —
+    // streamKey() is undefined either way) so agent_session_stopped can look
+    // this instance up (AGS-1.1).
+    registerStream(progress);
+
+    const rawText =
+      msg.text || (hasRichText ? richTextToMarkdown(msg.blocks ?? []) : "");
+
+    let prompt = await buildPromptWithFiles(
+      rawText,
+      msg.files,
+      fileDownloaderFn,
+      slackConfig.botToken,
+      transcribeAudioFn,
+      voiceConfig,
+    );
+
+    if (msg.user) {
+      const name = await resolveUserFn(msg.user, client);
+      prompt = `[${name}]: ${prompt}`;
+    }
+
+    if (!isDM && msg.thread_ts) {
+      prompt = `[Thread message — respond normally, or use [silent] if no response is needed]\n${prompt}`;
+    }
+
+    // Set inside the try block below (STS2-3.1) — hoisted so finishProgress()
+    // in the finally block can title the stream's completion card "Ack"
+    // rather than the generic "Done" when the reply was suppressed.
+    let wasSuppressed = false;
+    try {
+      const runResult = await runner(prompt, sessionKey, progress.onProgress, {
+        SLACK_CHANNEL_ID: msg.channel,
+        SLACK_THREAD_TS: replyTs,
+      });
+      if (runResult.streamIncomplete) {
+        // Clean process exit, but the stream never emitted a terminal
+        // `result` event — treat this the same as a genuine failure rather
+        // than silently posting nothing and logging it as a normal
+        // markers-only response (see CSU-1.1 review).
+        throw new ClaudeRunError(
+          "claude stream ended without a terminal result event",
+          undefined,
+          "stream incomplete — no terminal result event",
+          runResult.sessionId,
+          runResult.modelUsage,
+        );
+      }
+      const { result, usage, totalCostUsd, modelUsage } = runResult;
+      await chatTokenReporter.recordSession(usage, totalCostUsd, modelUsage);
+      const { cleaned, markers } = parseMarkers(result);
+
+      const isSilent = markers.some((m) => m.type === "silent");
+      const dmOverride = isSilent && isDM && cleaned.trim().length > 0;
+      const shouldSuppress = isSilent && !dmOverride;
+      wasSuppressed = shouldSuppress;
+
+      if (dmOverride) {
+        console.log("[slack] ignoring [silent] marker in DM — posting reply");
+      }
+      if (shouldSuppress) {
+        console.log(
+          `[slack] silent response — not posting (cleaned: ${cleaned.length} chars)`,
+        );
+      }
+
+      let postedTs: string | undefined;
+      if (!shouldSuppress && cleaned.trim().length > 0) {
+        const delivered = await progress.deliverContent(cleaned);
+        if (!delivered) {
+          const blocks = blocksConverter(cleaned);
+          let sayResult: unknown;
+          if (blocks) {
+            try {
+              sayResult = await say({
+                text: blocks.text,
+                blocks: blocks.blocks,
+                thread_ts: msg.thread_ts ?? msg.ts,
+              });
+            } catch (err: unknown) {
+              if (!isInvalidBlocksError(err)) throw err;
+              console.warn("[slack] invalid_blocks — retrying with plain text");
+              sayResult = await say({
+                text: blocks.text || formatter(cleaned),
+                thread_ts: msg.thread_ts ?? msg.ts,
+              });
+            }
+          } else {
+            sayResult = await say({
+              text: formatter(cleaned),
+              thread_ts: msg.thread_ts ?? msg.ts,
+            });
+          }
+          postedTs = (sayResult as { ts?: string } | undefined)?.ts;
+        }
+      } else if (!shouldSuppress) {
+        console.log("[slack] markers-only response — skipping text post");
+      }
+
+      await dispatchMarkers(markers, {
+        client,
+        channel: msg.channel,
+        postedTs,
+        threadTs: msg.thread_ts ?? msg.ts,
+        synthesizeSpeechFn,
+        voiceConfig,
+        postedText: shouldSuppress ? undefined : cleaned,
+      });
+    } catch (err) {
+      console.error("[slack] error:", err);
+      reportClaudeError(sentryClient, err);
+      // Mark the Thinking Steps card status:"error" (STS2-4.1 AC #1) BEFORE the
+      // say() below — a UI-state signal only; reportClaudeError(sentryClient, err)
+      // above remains the single log point for this error. Ordering matters: if
+      // say() throws (rate limit, invalid_auth, channel_not_found), this must
+      // still run so finishProgress() doesn't send a "Done" card for a run that
+      // both errored and failed to notify the user (matches reaction_added).
+      progress.reportError();
+      // Wrap the error notification in its own try/catch: a failed say()
+      // (rate limit, invalid_auth, channel_not_found) must not escape the
+      // handler and skip the finally block's finishProgress().
+      try {
+        await say({
+          text: formatRunErrorForSlack(err),
+          thread_ts: msg.thread_ts ?? msg.ts,
+        });
+      } catch (sayErr) {
+        console.error("[slack] failed to post error notification:", sayErr);
+      }
+    } finally {
+      // exit() is ALWAYS called (matching the always-called enter() above)
+      // — see finishProgress()'s doc comment for what it gates.
+      await finishProgress(
+        progress,
+        threadStatusTracker.exit(sessionKey),
+        wasSuppressed,
+      );
+      // Clears the registry entry unconditionally — success or failure —
+      // so it never leaks a stale instance for a run that's already done
+      // (AGS-1.1).
+      unregisterStream(progress);
+    }
+  });
+
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt callback params
+  app.event("app_mention", async ({ event, say, client }: any) => {
+    const ev = event as {
+      text: string;
+      channel: string;
+      ts: string;
+      thread_ts?: string;
+      user?: string;
+      files?: SlackFile[];
+    };
+    const sessionKey = getThreadKey(ev.channel, ev.thread_ts ?? ev.ts);
+    const replyTs = ev.thread_ts ?? ev.ts;
+
+    // Drop @mention if bot is already participating in this thread —
+    // the message handler covers it and would double-respond otherwise.
+    if (ev.thread_ts && (await getSessionFn(sessionKey))) {
+      return;
+    }
+
+    const gateMsg = gateNotice(trialExpiryRef, accountStatusRef);
+    if (gateMsg) {
+      await say({ text: gateMsg, thread_ts: replyTs });
+      return;
+    }
+
+    if (
+      ev.user &&
+      (await shouldRejectSlackSender(
+        ev.user,
+        client,
+        resolveUserEmailFn,
+        membershipRef,
+      ))
+    ) {
+      return;
+    }
+
+    // app_mention never fires for a DM (mentions in a DM arrive as a plain
+    // message event, handled above) — always a channel/group thread, so
+    // recipient_team_id is always fetched here (STS-2.1).
+    const progress = new SlackProgress({
+      client,
+      channel: ev.channel,
+      threadTs: replyTs,
+      isDM: false,
+      recipientUserId: ev.user,
+      recipientTeamId: await teamIdPromise,
+    });
+    // enter() is ALWAYS called — see startProgress()'s doc comment for
+    // what it gates (STS2-1.1 AC #5).
+    await startProgress(progress, threadStatusTracker.enter(sessionKey));
+    // Registers the stream so agent_session_stopped can look this instance
+    // up (AGS-1.1) — see the app.message handler's identical comment above.
+    registerStream(progress);
+
+    let prompt = await buildPromptWithFiles(
+      ev.text,
+      ev.files,
+      fileDownloaderFn,
+      slackConfig.botToken,
+      transcribeAudioFn,
+      voiceConfig,
+    );
+
+    if (ev.user) {
+      const name = await resolveUserFn(ev.user as string, client);
+      prompt = `[${name}]: ${prompt}`;
+    }
+
+    if (event.thread_ts && !(await getSessionFn(sessionKey))) {
+      try {
+        const repliesResult = await conversationsRepliesFn(
+          client,
+          event.channel as string,
+          event.thread_ts as string,
+        );
+        const messages = repliesResult.messages ?? [];
+        const historyLines = await Promise.all(
+          messages
+            .filter(
+              (m) =>
+                m.text &&
+                m.text.trim() !== "" &&
+                m.user &&
+                (!botUserId || m.user !== botUserId) &&
+                m.ts !== (event.ts as string),
+            )
+            .map(async (m) => {
+              const name = await resolveUserFn(m.user as string, client);
+              return `[${name}]: ${m.text}`;
+            }),
+        );
+        if (historyLines.length > 0) {
+          prompt = `[Thread context]\n${historyLines.join("\n")}\n[end thread context]\n\n${prompt}`;
+        }
+      } catch (err) {
+        console.warn("[slack] failed to fetch thread history:", err);
+      }
+    }
+
+    // Set inside the try block below (STS2-3.1) — hoisted so finishProgress()
+    // in the finally block can title the stream's completion card "Ack"
+    // rather than the generic "Done" when the reply was suppressed.
+    let wasSuppressed = false;
+    try {
+      const runResult = await runner(prompt, sessionKey, progress.onProgress, {
+        SLACK_CHANNEL_ID: ev.channel,
+        SLACK_THREAD_TS: replyTs,
+      });
+      if (runResult.streamIncomplete) {
+        // Clean process exit, but the stream never emitted a terminal
+        // `result` event — treat this the same as a genuine failure rather
+        // than silently posting nothing and logging it as a normal
+        // markers-only response (see CSU-1.1 review).
+        throw new ClaudeRunError(
+          "claude stream ended without a terminal result event",
+          undefined,
+          "stream incomplete — no terminal result event",
+          runResult.sessionId,
+          runResult.modelUsage,
+        );
+      }
+      const { result, usage, totalCostUsd, modelUsage } = runResult;
+      await chatTokenReporter.recordSession(usage, totalCostUsd, modelUsage);
+      const { cleaned, markers } = parseMarkers(result);
+
+      const isSilent = markers.some((m) => m.type === "silent");
+      wasSuppressed = isSilent;
+      if (isSilent) {
+        console.log(
+          `[slack] silent response — not posting (channel mention, cleaned: ${cleaned.length} chars)`,
+        );
+      }
+
+      let postedMentionTs: string | undefined;
+      if (!isSilent && cleaned.trim().length > 0) {
+        const delivered = await progress.deliverContent(cleaned);
+        if (!delivered) {
+          const blocks = blocksConverter(cleaned);
+          let sayResult: unknown;
+          if (blocks) {
+            try {
+              sayResult = await say({
+                text: blocks.text,
+                blocks: blocks.blocks,
+                thread_ts: replyTs,
+              });
+            } catch (err: unknown) {
+              if (!isInvalidBlocksError(err)) throw err;
+              console.warn("[slack] invalid_blocks — retrying with plain text");
+              sayResult = await say({
+                text: blocks.text || formatter(cleaned),
+                thread_ts: replyTs,
+              });
+            }
+          } else {
+            sayResult = await say({
+              text: formatter(cleaned),
+              thread_ts: replyTs,
+            });
+          }
+          postedMentionTs = (sayResult as { ts?: string } | undefined)?.ts;
+        }
+      } else if (!isSilent) {
+        console.log("[slack] markers-only response — skipping text post");
+      }
+
+      await dispatchMarkers(markers, {
+        client,
+        channel: ev.channel,
+        postedTs: postedMentionTs,
+        threadTs: replyTs,
+        synthesizeSpeechFn,
+        voiceConfig,
+        postedText: isSilent ? undefined : cleaned,
+      });
+    } catch (err) {
+      console.error("[slack] error:", err);
+      reportClaudeError(sentryClient, err);
+      // Mark the Thinking Steps card status:"error" (STS2-4.1 AC #1) BEFORE the
+      // say() below — a UI-state signal only; reportClaudeError(sentryClient, err)
+      // above remains the single log point for this error. Ordering matters: if
+      // say() throws (rate limit, invalid_auth, channel_not_found), this must
+      // still run so finishProgress() doesn't send a "Done" card for a run that
+      // both errored and failed to notify the user (matches reaction_added).
+      progress.reportError();
+      // Wrap the error notification in its own try/catch: a failed say()
+      // (rate limit, invalid_auth, channel_not_found) must not escape the
+      // handler and skip the finally block's finishProgress().
+      try {
+        await say({ text: formatRunErrorForSlack(err), thread_ts: replyTs });
+      } catch (sayErr) {
+        console.error("[slack] failed to post error notification:", sayErr);
+      }
+    } finally {
+      // See finishProgress()'s doc comment.
+      await finishProgress(
+        progress,
+        threadStatusTracker.exit(sessionKey),
+        wasSuppressed,
+      );
+      unregisterStream(progress);
+    }
+  });
+
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt callback params
+  app.event("reaction_added", async ({ event, client }: any) => {
+    const ev = event as {
+      reaction: string;
+      item: { type: string; channel: string; ts: string };
+      item_user: string;
+      user: string;
+    };
+
+    if (ev.item.type !== "message") return;
+    if (!botUserId || ev.item_user !== botUserId) return;
+    if (!ev.item.channel.startsWith("D")) return;
+
+    const gateMsg = gateNotice(trialExpiryRef, accountStatusRef);
+    if (gateMsg) {
+      await client.chat.postMessage({
+        channel: ev.item.channel,
+        text: gateMsg,
+      });
+      return;
+    }
+
+    if (
+      await shouldRejectSlackSender(
+        ev.user,
+        client,
+        resolveUserEmailFn,
+        membershipRef,
+      )
+    ) {
+      return;
+    }
+
+    const sessionKey = getThreadKey(ev.item.channel, ev.item.ts);
+    const name = await resolveUserFn(ev.user, client).catch(() => ev.user);
+    const prompt = `[${name} reacted with :${ev.reaction}: to your message]`;
+
+    // Gated above (`ev.item.channel.startsWith("D")`) — this handler only
+    // ever fires for DMs, so recipient_team_id/recipient_user_id are never
+    // fetched or needed here (STS-2.1).
+    const progress = new SlackProgress({
+      client,
+      channel: ev.item.channel,
+      threadTs: ev.item.ts,
+      isDM: true,
+    });
+    // enter() is ALWAYS called — see startProgress()'s doc comment for
+    // what it gates (STS2-1.1 AC #5).
+    await startProgress(progress, threadStatusTracker.enter(sessionKey));
+    // Registers the stream so agent_session_stopped can look this instance
+    // up (AGS-1.1) — see the app.message handler's identical comment above.
+    registerStream(progress);
+
+    // Set inside the try block below (STS2-3.1) — hoisted so finishProgress()
+    // in the finally block can title the stream's completion card "Ack"
+    // rather than the generic "Done" when the reply was suppressed.
+    let wasSuppressed = false;
+    try {
+      const runResult = await runner(prompt, sessionKey, progress.onProgress, {
+        SLACK_CHANNEL_ID: ev.item.channel,
+        SLACK_THREAD_TS: ev.item.ts,
+      });
+      if (runResult.streamIncomplete) {
+        // Clean process exit, but the stream never emitted a terminal
+        // `result` event — treat this the same as a genuine failure rather
+        // than silently posting nothing and logging it as a normal
+        // markers-only response (see CSU-1.1 review).
+        throw new ClaudeRunError(
+          "claude stream ended without a terminal result event",
+          undefined,
+          "stream incomplete — no terminal result event",
+          runResult.sessionId,
+          runResult.modelUsage,
+        );
+      }
+      const { result, usage, totalCostUsd, modelUsage } = runResult;
+      await chatTokenReporter.recordSession(usage, totalCostUsd, modelUsage);
+      const { cleaned, markers } = parseMarkers(result);
+
+      const isSilent = markers.some((m) => m.type === "silent");
+      wasSuppressed = isSilent;
+      if (isSilent) {
+        console.log("[slack] reaction_added: silent response — not posting");
+        return;
+      }
+
+      let postResult: unknown;
+      if (cleaned.trim().length > 0) {
+        const delivered = await progress.deliverContent(cleaned);
+        if (!delivered) {
+          const blocks = blocksConverter(cleaned);
+          if (blocks) {
+            try {
+              postResult = await client.chat.postMessage({
+                channel: ev.item.channel,
+                text: blocks.text,
+                blocks: blocks.blocks,
+              });
+            } catch (err: unknown) {
+              if (isInvalidBlocksError(err)) {
+                console.warn(
+                  "[slack] invalid_blocks — retrying with plain text",
+                );
+                postResult = await client.chat
+                  .postMessage({
+                    channel: ev.item.channel,
+                    text: blocks.text || formatter(cleaned),
+                  })
+                  .catch((err2: unknown) => {
+                    console.warn(
+                      "[slack] reaction_added: postMessage failed:",
+                      err2,
+                    );
+                    return undefined;
+                  });
+              } else {
+                console.warn(
+                  "[slack] reaction_added: postMessage failed:",
+                  err,
+                );
+                postResult = undefined;
+              }
+            }
+          } else {
+            postResult = await client.chat
+              .postMessage({
+                channel: ev.item.channel,
+                text: formatter(cleaned),
+              })
+              .catch((err: unknown) => {
+                console.warn(
+                  "[slack] reaction_added: postMessage failed:",
+                  err,
+                );
+                return undefined;
+              });
+          }
+        }
+      }
+
+      const postedTs = (postResult as { ts?: string } | undefined)?.ts;
+      await dispatchMarkers(markers, {
+        client,
+        channel: ev.item.channel,
+        postedTs,
+        threadTs: ev.item.ts,
+        synthesizeSpeechFn,
+        postedText: cleaned,
+        voiceConfig,
+      });
+    } catch (err) {
+      console.error("[slack] reaction_added error:", err);
+      // Mark the Thinking Steps card status:"error" (STS2-4.1 AC #1) — a
+      // UI-state signal only, not a second log path.
+      progress.reportError();
+    } finally {
+      // See finishProgress()'s doc comment.
+      await finishProgress(
+        progress,
+        threadStatusTracker.exit(sessionKey),
+        wasSuppressed,
+      );
+      unregisterStream(progress);
+    }
+  });
+
+  // Slack's native Stop/session-cancellation event for the Agent Sessions
+  // API (AGS-1.1). Without subscribing to this, the agent has no way to know
+  // when Slack has externally halted a stream, so it keeps trying to
+  // append/finalize into a stream Slack already discarded server-side
+  // (message_not_in_streaming_state) — which cascades into a permanently
+  // stuck "is working" status, since finish()'s stopStream() call fails with
+  // no fallback to reset it. Mirrors openclaw's applySlackStreamStop /
+  // markSlackStreamsStopped pattern (extensions/slack/src/streaming.ts,
+  // monitor/events/agent.ts).
+  //
+  // biome-ignore lint/suspicious/noExplicitAny: Bolt callback params
+  app.event("agent_session_stopped", async ({ event, client }: any) => {
+    const ev = event as { channel?: string; streaming_message_ts?: string };
+
+    // Look up the matching live stream and mark it externally-stopped —
+    // any further appendStream/stopStream call against it becomes a no-op
+    // instead of a failed API call. An unknown/already-cleared channel:ts
+    // (stream already closed via its own success/failure path, or a
+    // duplicate delivery of the same event) is a safe no-op — never throws.
+    // Also recovers the run's actual thread_ts (distinct from the stream's
+    // own streaming_message_ts) for the direct status reset below, when a
+    // match was found. On a registry miss threadTs stays undefined — we
+    // deliberately do NOT fall back to ev.streaming_message_ts, which is the
+    // stream's own message ts, a distinct value the Agent Sessions API does
+    // not accept as a thread identifier (see SlackProgress.getThreadTs()).
+    let threadTs: string | undefined;
+    if (ev.channel && ev.streaming_message_ts) {
+      const key = `${ev.channel}:${ev.streaming_message_ts}`;
+      const progress = liveStreams.get(key);
+      if (progress) {
+        threadTs = progress.getThreadTs();
+        progress.markExternallyStopped();
+        liveStreams.delete(key);
+      }
+    }
+
+    // Independent of the stream's own close path: a direct status reset,
+    // since it's a separate API call from the stream itself and should
+    // succeed even when the stream is already dead server-side (the actual
+    // fix for the stuck "is working" status — matches openclaw's own
+    // handler comment: "Recover stale processing if the turn's earlier
+    // active write failed. An unauthorized Stop may clear the indicator
+    // cosmetically until the still-running turn ends.").
+    //
+    // On a registry miss (duplicate/late event for an already-cleared run) we
+    // still fire the reset so the "is working" indicator can't stick, but omit
+    // thread_ts entirely rather than send the wrong (streaming_message_ts)
+    // value.
+    if (ev.channel) {
+      try {
+        await client.agents.sessions.setStatus({
+          channel_id: ev.channel,
+          status: "active",
+          ...(threadTs !== undefined ? { thread_ts: threadTs } : {}),
+        });
+      } catch (err) {
+        console.warn(
+          "[slack] agent_session_stopped: setStatus(active) failed:",
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+  });
+
+  return app;
+}