slack-term 1.14.0 → 1.16.0

package/ts/profiles.ts

@@ -5,12 +5,20 @@
 //   Local (cwd):  .slack-cli/workspace   — set with: slack workspace use <name>
 //   Global (home): ~/.slack-cli/workspace — set with: slack workspace use -g <name>
 //
-// Resolution order:
-//   1. --workspace=<name> flag or SLACK_WORKSPACE env var
-//   2. Local lockfile  (.slack-cli/workspace in cwd)
-//   3. Global lockfile (~/.slack-cli/workspace)
-//   4. No profiles → fall back to SLACK_MCP_XOXP_TOKEN
-//   5. Otherwise → throw (no silent defaults)
+// Token resolution order (no --workspace flag):
+//   1. process.env SLACK_TOKEN or SLACK_BOT_TOKEN
+//   2. process.env SLACK_MCP_XOXP_TOKEN (legacy, yields to profiles if any exist)
+//   3. Dir walk from cwd→$HOME: .slack-term/.env.local, then .env.local (modern env-file names only)
+//      Note: cli.ts loadDotenvFiles() has already loaded cwd/.env.local into process.env (#1 catches
+//      that case), so the walk's extra value is finding .slack-term/ variants and parent-dir files.
+//   4. ~/.slack-term/.env.local (global slack-term config)
+//   5. profiles.json via SLACK_WORKSPACE / lockfiles
+//   6. throw with auth help
+//
+//  --workspace flag skips #2-4 and goes straight to profiles.json.
+//
+// Note: lockfiles and profiles.json use .slack-cli/ (older name); new per-dir token storage
+// uses .slack-term/ (current project name). Both coexist intentionally.
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -71,6 +79,80 @@ function writeLockfile(path: string, name: string): void {
   writeFileSync(path, name + "\n");
 }
 
+function parseEnvVars(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    result[key] = val;
+  }
+  return result;
+}
+
+function readEnvFile(filePath: string): Record<string, string> {
+  if (!existsSync(filePath)) return {};
+  try {
+    return parseEnvVars(readFileSync(filePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Walk from startDir up to $HOME checking .slack-term/.env.local then .env.local.
+ * Returns first value found for any of the given keys. */
+function walkDirEnv(startDir: string, keys: string[]): string | undefined {
+  const homeDir = home();
+  let dir = startDir;
+
+  while (true) {
+    for (const subdir of [join(dir, ".slack-term", ".env.local"), join(dir, ".env.local")]) {
+      const vars = readEnvFile(subdir);
+      for (const key of keys) {
+        if (vars[key]) return vars[key];
+      }
+    }
+    if (dir === homeDir) break;
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+
+  // Global slack-term config — separate from the walk, checked after $HOME
+  const globalVars = readEnvFile(join(homeDir, ".slack-term", ".env.local"));
+  for (const key of keys) {
+    if (globalVars[key]) return globalVars[key];
+  }
+
+  return undefined;
+}
+
+/** Write or update KEY=VALUE entries in an env file (creates file and parent dirs as needed). */
+export function saveToEnvFile(filePath: string, updates: Record<string, string>): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const content = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+  const lines = content ? content.split("\n") : [];
+  for (const [key, value] of Object.entries(updates)) {
+    const idx = lines.findIndex((l) => {
+      const t = l.trim();
+      return t.startsWith(key + "=") || t.startsWith(key + " =");
+    });
+    const newLine = `${key}=${value}`;
+    if (idx !== -1) {
+      lines[idx] = newLine;
+    } else {
+      lines.push(newLine);
+    }
+  }
+  writeFileSync(filePath, lines.join("\n").trimEnd() + "\n");
+}
+
 export function listProfiles(): { name: string; profile: Profile; current: boolean }[] {
   const store = load();
   const local = readLockfile(localLockfilePath());
@@ -117,34 +199,52 @@ export function resolveToken(workspaceFlag?: string): string {
   const store = load();
   const profiles = store.profiles;
   const names = Object.keys(profiles);
-  const envToken = process.env.SLACK_MCP_XOXP_TOKEN;
-
-  // Conflict: env token and profiles are mutually exclusive — prefer profiles
-  if (envToken && names.length > 0) {
-    if (!(globalThis as Record<string, unknown>).__slackEnvWarnShown) {
-      (globalThis as Record<string, unknown>).__slackEnvWarnShown = true;
-      console.error(
-        "Warning: SLACK_MCP_XOXP_TOKEN is set but workspace profiles exist - using profiles.\n" +
-        "  Run: unset SLACK_MCP_XOXP_TOKEN  (and remove from ~/.zshrc or ~/.bashrc)",
-      );
+
+  // --workspace flag: skip env-file walk, go straight to profiles.json
+  if (workspaceFlag) {
+    const profile = profiles[workspaceFlag];
+    if (!profile) {
+      throw new Error(`Workspace "${workspaceFlag}" not found. Available: ${names.join(", ") || "(none)"}`);
+    }
+    return profile.token;
+  }
+
+  // SLACK_TOKEN always wins — intended as an explicit per-project override.
+  if (process.env.SLACK_TOKEN) return process.env.SLACK_TOKEN;
+
+  // SLACK_BOT_TOKEN and SLACK_MCP_XOXP_TOKEN: only used when no profiles exist.
+  // Bot tokens in shell env or .env files must not shadow workspace profiles.
+  const legacyEnvToken = process.env.SLACK_BOT_TOKEN ?? process.env.SLACK_MCP_XOXP_TOKEN;
+  if (legacyEnvToken && names.length === 0) return legacyEnvToken;
+  if (legacyEnvToken && names.length > 0) {
+    // Warn only when the token differs from what's in .env.local (same value = not a real conflict)
+    const envFileToken = walkDirEnv(process.cwd(), ["SLACK_BOT_TOKEN", "SLACK_MCP_XOXP_TOKEN"]);
+    if (legacyEnvToken !== envFileToken) {
+      if (!(globalThis as Record<string, unknown>).__slackEnvWarnShown) {
+        (globalThis as Record<string, unknown>).__slackEnvWarnShown = true;
+        console.error(
+          "Warning: SLACK_MCP_XOXP_TOKEN / SLACK_BOT_TOKEN is set but workspace profiles exist — using profiles.\n" +
+          "  Migrate to SLACK_TOKEN=... or remove from your shell config.",
+        );
+      }
     }
-  } else if (envToken) {
-    return envToken;
   }
 
-  // Explicit per-command selection
-  const selected = workspaceFlag ?? process.env.SLACK_WORKSPACE;
+  // Dir walk: only SLACK_TOKEN from env files can override profiles.
+  // SLACK_BOT_TOKEN in .env files yields to profiles (same as shell env).
+  const walked = walkDirEnv(process.cwd(), ["SLACK_TOKEN"]);
+  if (walked) return walked;
+
+  // profiles.json via SLACK_WORKSPACE env var or lockfiles
+  const selected = process.env.SLACK_WORKSPACE;
   if (selected) {
     const profile = profiles[selected];
     if (!profile) {
-      throw new Error(
-        `Workspace "${selected}" not found. Available: ${names.join(", ") || "(none)"}`,
-      );
+      throw new Error(`Workspace "${selected}" not found. Available: ${names.join(", ") || "(none)"}`);
     }
     return profile.token;
   }
 
-  // Local lockfile (cwd)
   const localName = readLockfile(localLockfilePath());
   if (localName) {
     const profile = profiles[localName];
@@ -152,7 +252,6 @@ export function resolveToken(workspaceFlag?: string): string {
     return profile.token;
   }
 
-  // Global lockfile (~/.slack-cli/workspace)
   const globalName = readLockfile(globalLockfilePath());
   if (globalName) {
     const profile = profiles[globalName];
@@ -160,29 +259,59 @@ export function resolveToken(workspaceFlag?: string): string {
     return profile.token;
   }
 
-  // No profiles and no env token
-  if (names.length === 0) {
-    throw new Error("No profiles configured. Run: slack auth login");
+  if (names.length > 0) {
+    throw new Error(
+      `Workspace not selected (${names.join(", ")} available).\n` +
+      `  Select locally:  slack workspace use <name>          (writes .slack-cli/workspace)\n` +
+      `  Select globally: slack workspace use -g <name>       (writes ~/.slack-cli/workspace)`,
+    );
   }
 
-  // Profiles exist but none selected — never silently pick one
   throw new Error(
-    `Workspace not selected (${names.join(", ")} available).\n` +
-    `  Select locally:  slack workspace use <name>          (writes .slack-cli/workspace)\n` +
-    `  Select globally: slack workspace use -g <name>       (writes ~/.slack-cli/workspace)`,
+    "No Slack token found.\n" +
+    "  Run one of:\n" +
+    "    slack auth token    — paste an existing xoxp-/xoxb- token\n" +
+    "    slack auth chrome   — import from Chrome browser (macOS)\n" +
+    "    slack auth app      — guided Slack app creation\n" +
+    "  Or set SLACK_TOKEN=xoxp-... in .slack-term/.env.local",
   );
 }
 
+/**
+ * Resolve a bot user token (xoxb-) for sending as the app rather than as the
+ * user. Reads SLACK_BOT_TOKEN from the environment — cli.ts loadDotenvFiles()
+ * has already sourced ~/.config/slack-cli/.env, so a bot token configured there
+ * is available here. Returns undefined when no xoxb- token is set.
+ */
+export function resolveBotToken(): string | undefined {
+  const t = process.env.SLACK_BOT_TOKEN;
+  return t && t.startsWith("xoxb-") ? t : undefined;
+}
+
 /** Resolve the xoxd session cookie for the active workspace (best-effort). */
 export function resolveCookie(workspaceFlag?: string): string | undefined {
   const store = load();
   const profiles = store.profiles;
-  const envToken = process.env.SLACK_MCP_XOXP_TOKEN;
 
-  // Env-only mode has no stored cookie
-  if (envToken) return process.env.SLACK_MCP_XOXD_COOKIE;
+  // --workspace flag: skip env-file walk, go straight to profiles.json
+  if (workspaceFlag) return profiles[workspaceFlag]?.cookie;
+
+  // process.env: SLACK_COOKIE (official extension), legacy SLACK_MCP_XOXD_COOKIE
+  if (process.env.SLACK_COOKIE) return process.env.SLACK_COOKIE;
+  if (process.env.SLACK_MCP_XOXD_COOKIE) return process.env.SLACK_MCP_XOXD_COOKIE;
+
+  // Legacy env-only mode (SLACK_MCP_XOXP_TOKEN set, no profiles)
+  const legacyToken = process.env.SLACK_MCP_XOXP_TOKEN;
+  if (legacyToken && Object.keys(profiles).length === 0) {
+    return process.env.SLACK_MCP_XOXD_COOKIE;
+  }
+
+  // Dir walk for SLACK_COOKIE
+  const walked = walkDirEnv(process.cwd(), ["SLACK_COOKIE"]);
+  if (walked) return walked;
 
-  const selected = workspaceFlag ?? process.env.SLACK_WORKSPACE;
+  // profiles.json via SLACK_WORKSPACE env var or lockfiles
+  const selected = process.env.SLACK_WORKSPACE;
   if (selected) return profiles[selected]?.cookie;
 
   const localName = readLockfile(localLockfilePath());

package/ts/rtm.ts

@@ -3,10 +3,19 @@ import { resolveDateMarkup, resolveMentions } from "./format.ts";
 
 export type RtmPollOpts = {
   thread?: string;
+  watchThread?: string;
   me?: boolean;
   myUserId?: string;
 };
 
+// A message is a thread reply (not a root/broadcast) when it carries a
+// thread_ts that differs from its own ts.
+function isThreadReply(m: Record<string, Json>): boolean {
+  const ts = typeof m.ts === "string" ? m.ts : "";
+  const tts = typeof m.thread_ts === "string" ? m.thread_ts : "";
+  return tts !== "" && tts !== ts;
+}
+
 // Minimal WebSocket interface — avoids requiring DOM lib in tsconfig
 interface WsLike {
   addEventListener(type: string, handler: (event: unknown) => void): void;
@@ -53,7 +62,8 @@ async function formatRtmLine(
   const resolved = resolveDateMarkup(await resolveMentions(token, raw, cache));
   const lines = resolved.split("\n");
   const body = lines[0] + (lines.length > 1 ? "\n" + lines.slice(1).map((l) => `  ${l}`).join("\n") : "");
-  return `${stamp}  @${handle}:  ${body}`;
+  const mark = isThreadReply(m) ? "↳ " : "";
+  return `${stamp}  ${mark}@${handle}:  ${body}`;
 }
 
 async function connectAndStream(
@@ -117,6 +127,13 @@ async function connectAndStream(
             if (parentTs !== opts.thread && ts !== opts.thread) return;
           }
 
+          // --watch-thread: keep all top-level posts plus the watched thread's
+          // replies; drop replies addressed to other threads.
+          if (opts.watchThread && isThreadReply(data)) {
+            const tts = typeof data.thread_ts === "string" ? data.thread_ts : "";
+            if (tts !== opts.watchThread) return;
+          }
+
           if (opts.me && opts.myUserId) {
             const text = typeof data.text === "string" ? data.text : "";
             if (!text.includes(`<@${opts.myUserId}>`)) return;

package/ts/slack-app.ts

@@ -2,9 +2,9 @@
 // Reads raw .ldb/.log files with regex — works even while Slack is running (no exclusive lock).
 // Also extracts the xoxd session cookie from the Slack Cookies SQLite database (macOS only).
 
-import { readdirSync, readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { readdirSync, readFileSync, existsSync, copyFileSync, unlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, dirname } from "node:path";
 import { pbkdf2Sync, createDecipheriv } from "node:crypto";
 import { execSync } from "node:child_process";
 
@@ -241,3 +241,207 @@ export async function extractSessions(): Promise<SlackAppSession[]> {
   }
   return result;
 }
+
+/**
+ * Try both AES-128-CBC variants used across Chromium versions to decrypt a v10 cookie.
+ * Returns the decrypted string if it starts with "xoxd-", otherwise undefined.
+ *
+ * Variant A (older Chrome):      IV = 16 spaces, ciphertext = enc[3:]
+ * Variant B (newer Chrome 127+): IV = enc[19:35], ciphertext = enc[35:]
+ */
+function decryptV10Cookie(enc: Buffer, aesKey: Buffer): string | undefined {
+  const tryDecrypt = (iv: Buffer, ciphertext: Buffer): string | undefined => {
+    try {
+      const decipher = createDecipheriv("aes-128-cbc", aesKey, iv);
+      decipher.setAutoPadding(true);
+      const result = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+      return result.startsWith("xoxd-") ? result : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+
+  return tryDecrypt(Buffer.alloc(16, 32), enc.slice(3))
+    ?? (enc.length >= 35 ? tryDecrypt(enc.slice(19, 35), enc.slice(35)) : undefined);
+}
+
+export type ChromeCookieCandidate = {
+  profileDir: string;  // "Default", "Profile 1", etc.
+  profileName: string; // display name from Chrome Preferences, e.g. email address
+  cookie: string;      // decrypted xoxd-...
+};
+
+/** Read the display name for a Chrome profile from its Preferences JSON. */
+function chromeProfileName(userDataDir: string, profileDir: string): string {
+  try {
+    const prefs = JSON.parse(
+      readFileSync(join(userDataDir, profileDir, "Preferences"), "utf8"),
+    ) as Record<string, unknown>;
+    const profile = prefs.profile as Record<string, unknown> | undefined;
+    const name = (profile?.name as string | undefined) ?? "";
+    const email = (profile?.user_name as string | undefined) ?? "";
+    return email ? `${name} (${email})` : name || profileDir;
+  } catch {
+    return profileDir;
+  }
+}
+
+/**
+ * Discover all Chrome browser profiles that have a Slack xoxd cookie (macOS only).
+ *
+ * Requires the Chrome Safe Storage key from the system keychain. When called from an
+ * interactive terminal, macOS will show a dialog asking for the login password.
+ * Throws on v20 (app-bound encryption). Returns [] if keychain is inaccessible.
+ */
+export type ChromeDiscoveryResult = {
+  candidates: ChromeCookieCandidate[];
+  totalProfiles: number; // how many Chrome profile dirs were scanned
+};
+
+export function discoverChromeCookies(): ChromeDiscoveryResult {
+  if (process.platform !== "darwin") return { candidates: [], totalProfiles: 0 };
+
+  const userDataDir = join(homedir(), "Library", "Application Support", "Google", "Chrome");
+  if (!existsSync(userDataDir)) return { candidates: [], totalProfiles: 0 };
+
+  let keychainPw: string;
+  try {
+    keychainPw = execSync(
+      `security find-generic-password -a Chrome -s "Chrome Safe Storage" -w`,
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    ).trimEnd();
+  } catch {
+    return { candidates: [], totalProfiles: 0 };
+  }
+  if (!keychainPw) return { candidates: [], totalProfiles: 0 };
+
+  const aesKey = pbkdf2Sync(keychainPw, "saltysalt", 1003, 16, "sha1");
+
+  const profileDirs = ["Default", ...readdirSync(userDataDir).filter((d) => d.startsWith("Profile "))];
+  const candidates: ChromeCookieCandidate[] = [];
+
+  for (const profileDir of profileDirs) {
+    const dbPath = join(userDataDir, profileDir, "Cookies");
+    if (!existsSync(dbPath)) continue;
+
+    const tmp = join(tmpdir(), `slack-chrome-cookies-${Date.now()}-${profileDir}.db`);
+    try {
+      copyFileSync(dbPath, tmp);
+      const { default: Database } = require("bun:sqlite") as typeof import("bun:sqlite");
+      const db = new Database(tmp, { readonly: true });
+      const row = db
+        .prepare("SELECT encrypted_value FROM cookies WHERE name='d' AND host_key LIKE '%slack%'")
+        .get() as { encrypted_value: Uint8Array } | null;
+      db.close();
+      if (!row) continue;
+
+      const enc = Buffer.from(row.encrypted_value);
+      const prefix = enc.slice(0, 3).toString();
+      if (prefix === "v10") {
+        // Try both AES-128-CBC variants used by different Chromium versions:
+        //   1. Standard (older Chrome):  IV = 16 spaces, ciphertext = enc[3:]
+        //   2. Embedded (newer Chrome/Electron): IV = enc[19:35], ciphertext = enc[35:]
+        const cookie = decryptV10Cookie(enc, aesKey);
+        if (!cookie) continue; // neither format produced a valid xoxd- value
+        candidates.push({ profileDir, profileName: chromeProfileName(userDataDir, profileDir), cookie });
+      } else if (prefix === "v20") {
+        throw new Error(
+          `Chrome cookie uses v20 (app-bound AES-256-GCM) which is not supported yet. ` +
+          `Prefix found: ${enc.slice(0, 4).toString("hex")}`,
+        );
+      } else {
+        throw new Error(`Unknown cookie encryption prefix: ${enc.slice(0, 4).toString("hex")}`);
+      }
+    } catch (e: unknown) {
+      if (e instanceof Error && (e.message.includes("app-bound") || e.message.includes("Unknown cookie"))) throw e;
+      // Otherwise skip this profile
+    } finally {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+    }
+  }
+  return { candidates, totalProfiles: profileDirs.length };
+}
+
+export type FirefoxCookieCandidate = {
+  profileDir: string;  // e.g. "abc123.default-release"
+  profileName: string; // display name from profiles.ini, or the dir name
+  cookie: string;      // plaintext xoxd-... (Firefox stores cookies unencrypted)
+};
+
+function firefoxProfilesDir(): string {
+  const home = homedir();
+  if (process.platform === "darwin") return join(home, "Library", "Application Support", "Firefox", "Profiles");
+  if (process.platform === "linux") return join(home, ".mozilla", "firefox");
+  if (process.platform === "win32") {
+    return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Mozilla", "Firefox", "Profiles");
+  }
+  return "";
+}
+
+/** Read Firefox profiles.ini to map profile dir names to display names. */
+function firefoxProfileNames(profilesDir: string): Record<string, string> {
+  const iniPath = join(dirname(profilesDir), "profiles.ini");
+  const map: Record<string, string> = {};
+  if (!existsSync(iniPath)) return map;
+  try {
+    const text = readFileSync(iniPath, "utf8");
+    let currentName = "";
+    let currentPath = "";
+    for (const line of text.split("\n")) {
+      const t = line.trim();
+      if (t.startsWith("[")) { currentName = ""; currentPath = ""; continue; }
+      const eq = t.indexOf("=");
+      if (eq === -1) continue;
+      const key = t.slice(0, eq).trim().toLowerCase();
+      const val = t.slice(eq + 1).trim();
+      if (key === "name") currentName = val;
+      if (key === "path") currentPath = val.split(/[\\/]/).pop() ?? val;
+      if (currentName && currentPath) { map[currentPath] = currentName; currentName = ""; currentPath = ""; }
+    }
+  } catch { /* ignore */ }
+  return map;
+}
+
+/**
+ * Discover all Firefox profiles that have a Slack xoxd cookie.
+ * Firefox stores cookies in plaintext — no keychain or decryption needed.
+ * Returns [] if Firefox is not installed or has no Slack session.
+ */
+export function discoverFirefoxCookies(): FirefoxCookieCandidate[] {
+  const profilesDir = firefoxProfilesDir();
+  if (!profilesDir || !existsSync(profilesDir)) return [];
+
+  const nameMap = firefoxProfileNames(profilesDir);
+  const candidates: FirefoxCookieCandidate[] = [];
+
+  let profileDirs: string[];
+  try {
+    profileDirs = readdirSync(profilesDir);
+  } catch {
+    return [];
+  }
+
+  for (const profileDir of profileDirs) {
+    const dbPath = join(profilesDir, profileDir, "cookies.sqlite");
+    if (!existsSync(dbPath)) continue;
+
+    const tmp = join(tmpdir(), `slack-firefox-cookies-${Date.now()}-${profileDir}.db`);
+    try {
+      copyFileSync(dbPath, tmp);
+      const { default: Database } = require("bun:sqlite") as typeof import("bun:sqlite");
+      const db = new Database(tmp, { readonly: true });
+      const row = db
+        .prepare("SELECT value FROM moz_cookies WHERE name='d' AND host LIKE '%slack%' LIMIT 1")
+        .get() as { value: string } | null;
+      db.close();
+      if (!row?.value || !row.value.startsWith("xoxd-")) continue;
+      const profileName = nameMap[profileDir] ?? profileDir;
+      candidates.push({ profileDir, profileName, cookie: row.value });
+    } catch {
+      // skip this profile
+    } finally {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+    }
+  }
+  return candidates;
+}

package/ts/slack.ts

@@ -128,6 +128,43 @@ export async function authTest(token: string): Promise<{ team: string; teamId: s
   };
 }
 
+// auth.test plus the token's granted scopes. Slack returns the granted bot/user
+// scopes in the `X-OAuth-Scopes` response header on every Web API call, which is
+// the only way to learn what a token can do without probing each endpoint.
+export async function authScopes(token: string): Promise<{
+  userId: string; botId: string; team: string; url: string; scopes: string[];
+}> {
+  const res = await fetch(`${base()}/auth.test`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (res.status === 429) {
+    const retryAfter = parseInt(res.headers.get("retry-after") ?? "60", 10);
+    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter);
+  }
+  const scopesHeader = res.headers.get("x-oauth-scopes") ?? "";
+  const body = (await res.json()) as {
+    ok?: boolean; error?: string; user_id?: string; bot_id?: string; team?: string; url?: string;
+  };
+  if (body.ok !== true) throw new Error(`Slack error on auth.test: ${body.error ?? "unknown"}`);
+  return {
+    userId: body.user_id ?? "",
+    botId: body.bot_id ?? "",
+    team: body.team ?? "",
+    url: body.url ?? "",
+    scopes: scopesHeader.split(",").map((s) => s.trim()).filter(Boolean),
+  };
+}
+
+// Resolve a bot's app_id (and bot user id) from its bot_id — needed to build the
+// app-settings deep link in messaging diagnostics.
+export async function botsInfo(token: string, botId: string): Promise<{ appId: string; userId: string }> {
+  const resp = (await get(token, "bots.info", { bot: botId })) as {
+    bot?: { app_id?: string; user_id?: string };
+  };
+  return { appId: resp.bot?.app_id ?? "", userId: resp.bot?.user_id ?? "" };
+}
+
 export async function history(token: string, channel: string, limit = 20, oldest?: string, cursor?: string): Promise<Json> {
   const params: Record<string, string> = { channel, limit: String(limit) };
   if (oldest !== undefined) params.oldest = oldest;
@@ -189,6 +226,7 @@ export async function send(
   channel: string,
   text: string,
   threadTs?: string,
+  replyBroadcast?: boolean,
 ): Promise<string> {
   const body: Record<string, Json> = {
     channel,
@@ -196,6 +234,9 @@ export async function send(
     blocks: [{ type: "markdown", text }],
   };
   if (threadTs !== undefined) body.thread_ts = threadTs;
+  // "Also send to channel": broadcast a threaded reply back to the channel.
+  // Only meaningful alongside thread_ts; Slack ignores it on top-level sends.
+  if (replyBroadcast && threadTs !== undefined) body.reply_broadcast = true;
   const resp = (await post(token, "chat.postMessage", body)) as { ts?: string };
   return resp.ts ?? "";
 }
@@ -238,6 +279,18 @@ export async function deleteScheduledMessage(
   });
 }
 
+export async function getPermalink(
+  token: string,
+  channel: string,
+  messageTs: string,
+): Promise<string> {
+  const resp = (await get(token, "chat.getPermalink", {
+    channel,
+    message_ts: messageTs,
+  })) as { permalink?: string };
+  return resp.permalink ?? "";
+}
+
 export async function editMessage(
   token: string,
   channel: string,
@@ -253,6 +306,14 @@ export async function editMessage(
   return resp.ts ?? ts;
 }
 
+export async function deleteMessage(
+  token: string,
+  channel: string,
+  ts: string,
+): Promise<void> {
+  await post(token, "chat.delete", { channel, ts });
+}
+
 export async function listConversations(token: string): Promise<Json> {
   const allChannels: Json[] = [];
   let cursor = "";
@@ -285,6 +346,42 @@ function normName(s: string): string {
   return s.toLowerCase().replace(/[-_\s]/g, "");
 }
 
+/**
+ * Resolve `@name` (or a raw U…/W… id) to a user ID. Used when DMing as a bot:
+ * the lookup runs on a *user* token (which has users:read), then the caller
+ * opens the DM with the bot token — so the bot never needs users:read.
+ */
+export async function resolveUserId(token: string, ref: string, cookie?: string): Promise<string> {
+  if (!ref.startsWith("@")) {
+    if (/^[UW][A-Za-z0-9]{6,}$/.test(ref)) return ref;
+    throw new Error(`Expected @user or a user ID, got: ${ref}`);
+  }
+  const nameNorm = normName(ref.slice(1));
+  const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
+  if (nameNorm === "you" || nameNorm === "me" || normName(selfInfo.user ?? "") === nameNorm) {
+    if (!selfInfo.user_id) throw new Error("auth.test did not return user_id");
+    return selfInfo.user_id;
+  }
+  let cursor = "";
+  while (true) {
+    const params: Record<string, string> = { limit: "200" };
+    if (cursor) params.cursor = cursor;
+    const resp = (await get(token, "users.list", params, cookie)) as {
+      members?: Array<{ id?: string; name?: string; real_name?: string; profile?: { display_name?: string } }>;
+      response_metadata?: { next_cursor?: string };
+    };
+    for (const u of resp.members ?? []) {
+      const n = normName(u.name ?? "");
+      const rn = normName(u.real_name ?? "");
+      const dn = normName(u.profile?.display_name ?? "");
+      if (n === nameNorm || rn === nameNorm || (dn && dn === nameNorm)) return u.id ?? "";
+    }
+    cursor = resp.response_metadata?.next_cursor ?? "";
+    if (!cursor) break;
+  }
+  throw new Error(`User not found: ${ref}`);
+}
+
 /** Parse a Slack permalink, returning channel ID, optional message ts, and optional thread_ts.
  *  Supports both forms:
  *    https://app.slack.com/client/T.../C...[/p1700000000000100]
@@ -326,6 +423,21 @@ export async function resolveChannel(token: string, ref: string, cookie?: string
   const nameNorm = normName(rawName);
 
   if (isIm) {
+    // Use auth.test to check if @name refers to self (avoids users:read scope requirement).
+    // auth.test is always available; users.list requires users:read which xoxc- tokens lack.
+    const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
+    const isSelf = nameNorm === "you" || nameNorm === "me" || normName(selfInfo.user ?? "") === nameNorm;
+    if (isSelf) {
+      const userId = selfInfo.user_id;
+      if (!userId) throw new Error("auth.test did not return user_id");
+      const dmResp = (await get(token, "conversations.list", { types: "im", limit: "200" }, cookie)) as {
+        channels?: Array<{ id?: string; user?: string }>;
+      };
+      const dm = (dmResp.channels ?? []).find((ch) => ch.user === userId);
+      if (dm?.id) return String(dm.id);
+      return openDm(token, userId);
+    }
+
     // Find user ID first via users.list (batch), then locate existing DM.
     let userId = "";
     let userCursor = "";