claude-slack-channel-bots 0.3.0 → 0.4.1

package/README.md

@@ -42,6 +42,7 @@ See the sections below for manual configuration details if you prefer not to use
 - `ss` from [iproute2](https://github.com/iproute2/iproute2) on your `PATH` (required for session ID discovery; pre-installed on most Linux distributions)
 - `curl` and `jq` on your `PATH` (required for the permission relay hooks)
 - Slack workspace admin access (to create and configure the Slack app)
+- **cozempic** (optional) — Python 3.10+ and `pip install cozempic` — enables session file cleaning before `--resume` for faster load times
 
 ---
 
@@ -57,6 +58,7 @@ Tokens and runtime options are read from environment variables. There is no `.en
 | `SLACK_APP_TOKEN` | Slack app-level token (`xapp-…`). Required. Generated under Basic Information → App-Level Tokens with the `connections:write` scope. |
 | `SLACK_STATE_DIR` | Override the directory where `routing.json`, `access.json`, and runtime state are stored. Defaults to `~/.claude/channels/slack`. |
 | `SLACK_ACCESS_MODE` | Set to `static` to load `access.json` once at startup and cache it for the lifetime of the process rather than re-reading it on every event. Useful in high-throughput environments where disk reads are a concern. |
+| `SLACK_DRY_RUN` | Set to `1` to start the server without Slack credentials. Token validation is skipped, Socket Mode and `web.auth.test()` are not called, and MCP tool calls (`reply`, `react`, etc.) are logged instead of sent. Useful for integration testing. |
 
 Shell profile example:
 
@@ -66,6 +68,8 @@ export SLACK_APP_TOKEN=xapp-your-app-token
 # Optional overrides:
 export SLACK_STATE_DIR=~/.config/slack-channel-bots
 export SLACK_ACCESS_MODE=static
+# Dry-run mode (no Slack credentials needed):
+export SLACK_DRY_RUN=1
 ```
 
 ---
@@ -92,7 +96,8 @@ A skeleton file is created by postinstall. Populate it before running `start`.
   "health_check_interval": 120,
   "exit_timeout": 120,
   "stop_timeout": 30,
-  "mcp_config_path": "~/.claude/slack-mcp.json"
+  "mcp_config_path": "~/.claude/slack-mcp.json",
+  "cozempic_prescription": "standard"
 }
 ```
 
@@ -111,6 +116,7 @@ A skeleton file is created by postinstall. Populate it before running `start`.
 | `stop_timeout` | number | `30` | Seconds to wait for the server process to exit after `SIGTERM` before escalating to `SIGKILL`. |
 | `mcp_config_path` | string | `~/.claude/slack-mcp.json` | Path to the MCP config file passed to Claude Code when launching managed sessions. |
 | `append_system_prompt_file` | string | — | Path to a file appended to every managed session's system prompt via `--append-system-prompt-file`. Missing file silently skipped. See `skills/EXAMPLE_CLAUDE.md` for a template. |
+| `cozempic_prescription` | string | `"standard"` | Cozempic cleaning intensity before resume. Valid values: `gentle`, `standard`, `aggressive`. Has no effect if cozempic is not installed. |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Multi-session Slack-to-Claude bridge \u2014 run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -18,6 +18,7 @@ import { defaultTmuxClient, isClaudeRunning as tmuxIsClaudeRunning, sessionName
 import { readSessions, type SessionsMap } from './sessions.ts'
 import { loadConfig as configLoadConfig, type RoutingConfig } from './config.ts'
 import { initLogging } from './logging.ts'
+import { isDryRun } from './tokens.ts'
 
 // ---------------------------------------------------------------------------
 // Injectable dependency interface
@@ -92,14 +93,16 @@ export function createCli(deps: CliDeps): CliHandlers {
       deps.exit(1)
     }
 
-    // Check required Slack tokens
-    if (!deps.env['SLACK_BOT_TOKEN']) {
-      console.error('missing prerequisite: SLACK_BOT_TOKEN environment variable')
-      deps.exit(1)
-    }
-    if (!deps.env['SLACK_APP_TOKEN']) {
-      console.error('missing prerequisite: SLACK_APP_TOKEN environment variable')
-      deps.exit(1)
+    // Check required Slack tokens (skipped in dry-run mode)
+    if (!isDryRun()) {
+      if (!deps.env['SLACK_BOT_TOKEN']) {
+        console.error('missing prerequisite: SLACK_BOT_TOKEN environment variable')
+        deps.exit(1)
+      }
+      if (!deps.env['SLACK_APP_TOKEN']) {
+        console.error('missing prerequisite: SLACK_APP_TOKEN environment variable')
+        deps.exit(1)
+      }
     }
 
     // Check routing.json exists

package/src/config.ts

@@ -17,6 +17,7 @@ import { resolve } from 'path'
 // ---------------------------------------------------------------------------
 
 export const MCP_SERVER_NAME = 'slack-channel-router'
+export const ALLOWED_PRESCRIPTIONS = ['gentle', 'standard', 'aggressive']
 
 // ---------------------------------------------------------------------------
 // Types
@@ -41,6 +42,7 @@ export interface RoutingConfigInput {
   stop_timeout?: number
   mcp_config_path?: string
   append_system_prompt_file?: string
+  cozempic_prescription?: string
 }
 
 /** Validated, fully-resolved routing configuration with all defaults applied. */
@@ -56,6 +58,7 @@ export interface RoutingConfig {
   stop_timeout: number
   mcp_config_path: string
   append_system_prompt_file?: string
+  cozempic_prescription: string
 }
 
 // ---------------------------------------------------------------------------
@@ -79,6 +82,7 @@ export function applyDefaults(input: RoutingConfigInput): RoutingConfig {
     stop_timeout: input.stop_timeout ?? 30,
     mcp_config_path: input.mcp_config_path ?? '~/.claude/slack-mcp.json',
     append_system_prompt_file: input.append_system_prompt_file,
+    cozempic_prescription: input.cozempic_prescription ?? 'standard',
   }
 }
 
@@ -152,6 +156,13 @@ export function validateConfig(config: RoutingConfig): void {
     )
   }
 
+  // cozempic_prescription must be one of the allowed values
+  if (!ALLOWED_PRESCRIPTIONS.includes(config.cozempic_prescription)) {
+    throw new Error(
+      `Routing config validation error: cozempic_prescription "${config.cozempic_prescription}" is invalid. Allowed values are: ${ALLOWED_PRESCRIPTIONS.join(', ')}.`,
+    )
+  }
+
   // default_dm_session must reference an existing route CWD
   if (config.default_dm_session !== undefined) {
     if (!seen.has(config.default_dm_session)) {

package/src/cozempic.ts

@@ -0,0 +1,150 @@
+/**
+ * cozempic.ts — Session cleaning via the cozempic CLI.
+ *
+ * Provides PATH availability checking, JSONL path resolution, file size
+ * inspection, and async session cleaning using `cozempic treat`.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+import { spawn } from 'child_process'
+import { statSync } from 'fs'
+import { homedir } from 'os'
+import { ALLOWED_PRESCRIPTIONS } from './config.ts'
+
+// ---------------------------------------------------------------------------
+// PATH availability check
+// ---------------------------------------------------------------------------
+
+let cozempicAvailable: boolean | null = null
+
+/**
+ * Checks whether `cozempic` is on PATH by spawning `which cozempic`.
+ * Sets the module-scoped flag and logs the result to stderr.
+ */
+export async function checkCozempicAvailable(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let settled = false
+    const done = (available: boolean, msg: string) => {
+      if (settled) return
+      settled = true
+      cozempicAvailable = available
+      console.error(msg)
+      resolve()
+    }
+    const proc = spawn('which', ['cozempic'])
+    proc.on('error', () => {
+      done(false, '[slack] Warning: cozempic not found on PATH — session cleaning disabled')
+    })
+    proc.on('close', (code) => {
+      if (code === 0) {
+        done(true, '[slack] cozempic available')
+      } else {
+        done(false, '[slack] Warning: cozempic not found on PATH — session cleaning disabled')
+      }
+    })
+  })
+}
+
+/** Returns true if cozempic was found on PATH during the last availability check. */
+export function getCozempicAvailable(): boolean {
+  return cozempicAvailable === true
+}
+
+/** Resets the availability flag to null (for testing). */
+export function _resetCozempicAvailable(): void {
+  cozempicAvailable = null
+}
+
+// ---------------------------------------------------------------------------
+// JSONL path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the absolute JSONL path for a given cwd and session ID.
+ * Pure function — no I/O, no validation.
+ */
+export function resolveJsonlPath(cwd: string, sessionId: string): string {
+  const slug = cwd.replace(/[^a-zA-Z0-9-]/g, '-')
+  return `${homedir()}/.claude/projects/${slug}/${sessionId}.jsonl`
+}
+
+// ---------------------------------------------------------------------------
+// File size helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the size of the file at `path` in bytes, or null if the file
+ * cannot be stat'd (missing, permission error, etc.).
+ */
+export function readFileSizeBytes(path: string): number | null {
+  try {
+    return statSync(path).size
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session cleaning
+// ---------------------------------------------------------------------------
+
+export type CleanSessionFn = (sessionId: string, cwd: string, prescription: string) => Promise<void>
+
+/**
+ * Runs `cozempic treat <sessionId> -rx <prescription> --execute` against the
+ * session's JSONL file. Always resolves — never rejects.
+ *
+ * Skips if the JSONL is missing or empty. Streams cozempic output to stderr
+ * with the `[slack] cozempic:` prefix and logs before/after file sizes.
+ */
+export async function cleanSession(sessionId: string, cwd: string, prescription: string): Promise<void> {
+  if (!ALLOWED_PRESCRIPTIONS.includes(prescription)) {
+    console.error(`[slack] cozempic: invalid prescription "${prescription}" — skipping clean session=${sessionId}`)
+    return
+  }
+  const path = resolveJsonlPath(cwd, sessionId)
+  const beforeSize = readFileSizeBytes(path)
+
+  if (beforeSize === null) {
+    console.error(`[slack] cozempic: JSONL not found — skipping clean session=${sessionId}`)
+    return
+  }
+
+  if (beforeSize === 0) {
+    console.error(`[slack] cozempic: JSONL empty — skipping clean session=${sessionId}`)
+    return
+  }
+
+  console.error(`[slack] cozempic: cleaning started session=${sessionId} size=${beforeSize}`)
+
+  return new Promise<void>((resolve) => {
+    const proc = spawn('cozempic', ['treat', sessionId, '-rx', prescription, '--execute'])
+
+    proc.stdout.on('data', (chunk: Buffer) => {
+      for (const line of chunk.toString().split('\n')) {
+        if (line.length > 0) console.error(`[slack] cozempic: ${line}`)
+      }
+    })
+
+    proc.stderr.on('data', (chunk: Buffer) => {
+      for (const line of chunk.toString().split('\n')) {
+        if (line.length > 0) console.error(`[slack] cozempic: ${line}`)
+      }
+    })
+
+    proc.on('error', (err) => {
+      console.error(`[slack] cozempic: spawn error session=${sessionId}: ${err.message}`)
+      resolve()
+    })
+
+    proc.on('close', (code) => {
+      const afterSize = readFileSizeBytes(path)
+      if (code !== 0 && code !== null) {
+        console.error(`[slack] cozempic: exit code ${code} session=${sessionId}`)
+      }
+      console.error(`[slack] cozempic: cleaning done session=${sessionId} size=${afterSize ?? 'unknown'}`)
+      resolve()
+    })
+  })
+}

package/src/registry.ts

@@ -15,6 +15,7 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
 import { MCP_SERVER_NAME, type RoutingConfig } from './config.ts'
+import { isDryRun } from './tokens.ts'
 import { getPeerPidByPort, getSessionIdForPid } from './peer-pid.ts'
 import { readSessions, writeSessions, type SessionsMap } from './sessions.ts'
 
@@ -516,6 +517,11 @@ export function createSessionServer(
         // Per-session outbound gate (t2.c1r.zk.qm)
         assertOutboundAllowed(chatId, entry.deliveredChannels)
 
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: reply to ${chatId} (${text.length} chars)`)
+          return { content: [{ type: 'text', text: `[dry-run] Would send message to ${chatId}` }] }
+        }
+
         const access = getAccess()
         const limit = access.textChunkLimit || DEFAULT_CHUNK_LIMIT
         const mode = access.chunkMode || 'newline'
@@ -575,6 +581,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'react': {
         assertOutboundAllowed(args.chat_id, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: react :${args.emoji}: on ${args.message_id}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would react :${args.emoji}: to ${args.message_id}` }] }
+        }
         await web.reactions.add({
           channel: args.chat_id,
           timestamp: args.message_id,
@@ -590,6 +600,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'edit_message': {
         assertOutboundAllowed(args.chat_id, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: edit_message ${args.message_id} in ${args.chat_id}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would edit message ${args.message_id}` }] }
+        }
         await web.chat.update({
           channel: args.chat_id,
           ts: args.message_id,
@@ -605,6 +619,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'fetch_messages': {
         assertOutboundAllowed(args.channel, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: fetch_messages from ${args.channel}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would fetch messages from ${args.channel}` }] }
+        }
         const channel: string = args.channel
         const limit = Math.min(args.limit || 20, 100)
         const threadTs: string | undefined = args.thread_ts
@@ -646,6 +664,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'download_attachment': {
         assertOutboundAllowed(args.chat_id, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: download_attachment from ${args.chat_id} msg=${args.message_id}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would download attachments from ${args.message_id}` }] }
+        }
         const channel: string = args.chat_id
         const messageTs: string = args.message_id
 

package/src/server.ts

@@ -42,6 +42,7 @@ import { loadConfig, expandTilde, type RoutingConfig, MCP_SERVER_NAME } from './
 import { readSessions, writeSessions, rotateSessions } from './sessions.ts'
 import { defaultTmuxClient, sessionName, isClaudeRunning } from './tmux.ts'
 import { startupSessionManager, launchSession } from './session-manager.ts'
+import { cleanSession, getCozempicAvailable } from './cozempic.ts'
 import {
   initRestart,
   scheduleRestart,
@@ -51,7 +52,7 @@ import {
   hasReachedMaxFailures,
 } from './restart.ts'
 import { initHealthCheck, startHealthCheck, stopHealthCheck } from './health-check.ts'
-import { loadTokens } from './tokens.ts'
+import { loadTokens, isDryRun } from './tokens.ts'
 import { checkPidConflict, writePidFile, removePidFile } from './pid.ts'
 import { trackAck, consumeAck } from './ack-tracker.ts'
 import {
@@ -946,17 +947,22 @@ export async function main(): Promise<void> {
     }
   }
 
-  // Resolve bot user ID
-  try {
-    const auth = await web.auth.test()
-    botUserId = (auth.user_id as string) || ''
-  } catch (err) {
-    console.error('[slack] Failed to resolve bot user ID:', err)
-  }
+  if (isDryRun()) {
+    console.error('[slack] Running in dry-run mode — Slack disabled')
+    botUserId = 'U000DRY'
+  } else {
+    // Resolve bot user ID
+    try {
+      const auth = await web.auth.test()
+      botUserId = (auth.user_id as string) || ''
+    } catch (err) {
+      console.error('[slack] Failed to resolve bot user ID:', err)
+    }
 
-  // Connect Socket Mode
-  await socket.start()
-  console.error('[slack] Socket Mode connected')
+    // Connect Socket Mode
+    await socket.start()
+    console.error('[slack] Socket Mode connected')
+  }
 
   // Propagate resolved port to tool deps for peer PID discovery
   sessionToolDeps.serverPort = mcpPort
@@ -1103,6 +1109,17 @@ export async function main(): Promise<void> {
         // Generate unique request ID
         const requestId = crypto.randomUUID()
 
+        // Register pending entry BEFORE posting to Slack to avoid race condition:
+        // If the user clicks Allow/Deny before postMessage returns, the interactive
+        // handler needs the entry to already exist in pendingPermissions.
+        pendingPermissions.set(requestId, {
+          requestId,
+          channelId: matchedChannelId,
+          messageTs: '',
+          toolName: tool_name,
+          waiters: [],
+        })
+
         // Post Block Kit message to channel
         let messageTs: string
         try {
@@ -1114,6 +1131,7 @@ export async function main(): Promise<void> {
           })
           messageTs = postResult.ts as string
         } catch (err) {
+          pendingPermissions.delete(requestId)
           console.error('[slack] /permission: chat.postMessage failed:', err)
           return new Response(JSON.stringify({ error: 'Failed to post message' }), {
             status: 500,
@@ -1121,14 +1139,9 @@ export async function main(): Promise<void> {
           })
         }
 
-        // Register pending entry with empty waiters array
-        pendingPermissions.set(requestId, {
-          requestId,
-          channelId: matchedChannelId,
-          messageTs,
-          toolName: tool_name,
-          waiters: [],
-        })
+        // Update with the real message timestamp (needed for chat.update on decision)
+        const pending = pendingPermissions.get(requestId)
+        if (pending) pending.messageTs = messageTs
 
         return new Response(JSON.stringify({ requestId }), {
           status: 200,
@@ -1268,6 +1281,17 @@ export async function main(): Promise<void> {
           },
         ]
 
+        // Register pending entry BEFORE posting to Slack to avoid race condition:
+        // If the user clicks a button before postMessage returns, the interactive
+        // handler needs the entry to already exist in pendingQuestions.
+        pendingQuestions.set(requestId, {
+          requestId,
+          channelId: matchedChannelId,
+          messageTs: '',
+          question: question as string,
+          waiters: [],
+        })
+
         let messageTs: string
         try {
           const postResult = await web.chat.postMessage({
@@ -1277,6 +1301,7 @@ export async function main(): Promise<void> {
           })
           messageTs = postResult.ts as string
         } catch (err) {
+          pendingQuestions.delete(requestId)
           console.error('[slack] /ask: chat.postMessage failed:', err)
           return new Response(JSON.stringify({ error: 'Failed to post message' }), {
             status: 500,
@@ -1284,13 +1309,9 @@ export async function main(): Promise<void> {
           })
         }
 
-        pendingQuestions.set(requestId, {
-          requestId,
-          channelId: matchedChannelId,
-          messageTs,
-          question: question as string,
-          waiters: [],
-        })
+        // Update with the real message timestamp
+        const pendingQ = pendingQuestions.get(requestId)
+        if (pendingQ) pendingQ.messageTs = messageTs
 
         return new Response(JSON.stringify({ requestId }), {
           status: 200,
@@ -1423,7 +1444,9 @@ export async function main(): Promise<void> {
       const resolvedSessionId = stored !== 'pending' ? stored : undefined
       const record = await launchSession(
         channelId, cwd, routingConfig, defaultTmuxClient,
-        resolvedSessionId !== undefined ? { sessionId: resolvedSessionId } : undefined,
+        resolvedSessionId !== undefined
+          ? { sessionId: resolvedSessionId, cleanSession: getCozempicAvailable() ? cleanSession : undefined }
+          : undefined,
       )
       if (record) {
         const sessions = readSessions()

package/src/session-manager.ts

@@ -10,8 +10,8 @@
  */
 
 import { accessSync, existsSync, constants } from 'fs'
-import { homedir } from 'node:os'
 import { type TmuxClient, sessionName, isClaudeRunning } from './tmux.ts'
+import { type CleanSessionFn, checkCozempicAvailable, getCozempicAvailable, cleanSession as defaultCleanSession, resolveJsonlPath } from './cozempic.ts'
 import { type SessionsMap, type SessionRecord } from './sessions.ts'
 import { type RoutingConfig, MCP_SERVER_NAME } from './config.ts'
 
@@ -26,8 +26,7 @@ import { type RoutingConfig, MCP_SERVER_NAME } from './config.ts'
  */
 export function jsonlExistsForSession(cwd: string, sessionId: string): boolean {
   if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) return false
-  const slug = cwd.replace(/[^a-zA-Z0-9-]/g, '-')
-  const path = `${homedir()}/.claude/projects/${slug}/${sessionId}.jsonl`
+  const path = resolveJsonlPath(cwd, sessionId)
   return existsSync(path)
 }
 
@@ -40,6 +39,8 @@ export interface LaunchOptions {
   pollTimeout?: number
   /** Claude session UUID to resume. When provided, --resume <id> is appended to the CLI command. */
   sessionId?: string
+  /** Optional session cleaning function to run before --resume launches. */
+  cleanSession?: CleanSessionFn
 }
 
 export interface SessionStateResult {
@@ -155,6 +156,11 @@ export async function launchSession(
   await tmuxClient.newSession(name, cwd)
   console.error(`[slack] Session created: ${name} (cwd="${cwd}")`)
 
+  // Clean JSONL before resuming (if a cleanSession fn was provided)
+  if (resumeSessionId && resumeSessionId !== 'pending' && options?.cleanSession) {
+    await options.cleanSession(resumeSessionId, cwd, routingConfig.cozempic_prescription)
+  }
+
   // Attempt launch (with --resume if sessionId provided)
   let result = await attemptLaunch(resumeSessionId, name)
 
@@ -227,6 +233,8 @@ export async function startupSessionManager(
 
   console.error(`[slack] startupSessionManager: storedSessions=${JSON.stringify(storedSessions)}`)
 
+  await checkCozempicAvailable()
+
   const routeEntries = Object.entries(routingConfig.routes)
   const concurrency = options?.concurrency ?? 3
   const startupTimeout = options?.startupTimeout ?? 60_000
@@ -294,7 +302,7 @@ export async function startupSessionManager(
       console.error(`[slack] Dead/missing process with stored session ID — resuming: channel=${channelId} session=${name} sessionId=${storedSessionId}`)
       const record = await launchSession(
         channelId, route.cwd, routingConfig, tmuxClient,
-        { ...launchOpts, sessionId: storedSessionId },
+        { ...launchOpts, sessionId: storedSessionId, cleanSession: getCozempicAvailable() ? defaultCleanSession : undefined },
       )
       const elapsed = Date.now() - routeStart
       if (record !== null) {

package/src/tokens.ts

@@ -7,11 +7,24 @@
  * SPDX-License-Identifier: MIT
  */
 
+// ---------------------------------------------------------------------------
+// Dry-run detection
+// ---------------------------------------------------------------------------
+
+export function isDryRun(): boolean {
+  const val = (process.env['SLACK_DRY_RUN'] ?? '').toLowerCase()
+  return val === '1' || val === 'true' || val === 'yes'
+}
+
 // ---------------------------------------------------------------------------
 // Token loading
 // ---------------------------------------------------------------------------
 
 export function loadTokens(): { botToken: string; appToken: string } {
+  if (isDryRun()) {
+    return { botToken: 'xoxb-dry-run', appToken: 'xapp-dry-run' }
+  }
+
   const botToken = process.env['SLACK_BOT_TOKEN'] ?? ''
   const appToken = process.env['SLACK_APP_TOKEN'] ?? ''