@herdctl/slack 1.1.1 → 1.1.3

package/README.md

@@ -0,0 +1,155 @@
+# @herdctl/slack
+
+> Slack connector for herdctl fleet management
+
+[![npm version](https://img.shields.io/npm/v/@herdctl/slack.svg)](https://www.npmjs.com/package/@herdctl/slack)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Documentation**: [herdctl.dev](https://herdctl.dev)
+
+## Overview
+
+`@herdctl/slack` enables your [herdctl](https://herdctl.dev) agents to interact via Slack. Users can chat with agents in channels or DMs, and agents stream responses in real time. The connector handles session management automatically, maintaining conversation context across messages.
+
+Herdctl is an open-source system for running fleets of autonomous AI agents powered by Claude Code. This package is part of the herdctl monorepo.
+
+## Installation
+
+```bash
+npm install @herdctl/slack
+```
+
+> **Note**: This package is typically used automatically by `@herdctl/core` when Slack is configured in your agent YAML. Direct installation is only needed for advanced use cases.
+
+## Configuration
+
+Add Slack chat configuration to your agent YAML:
+
+### Channel Bot
+
+```yaml
+name: support-bot
+model: claude-sonnet-4-20250514
+
+chat:
+  slack:
+    bot_token_env: SLACK_BOT_TOKEN
+    app_token_env: SLACK_APP_TOKEN
+    channels:
+      - id: "C0123456789"
+        name: "#support"
+        mode: mention     # Only respond when @mentioned
+      - id: "C9876543210"
+        name: "#general"
+        mode: auto        # Respond to all messages
+```
+
+### DM-Only Bot
+
+```yaml
+name: my-assistant
+model: claude-sonnet-4-20250514
+
+chat:
+  slack:
+    bot_token_env: SLACK_BOT_TOKEN
+    app_token_env: SLACK_APP_TOKEN
+    channels: []
+    dm:
+      enabled: true
+      mode: auto
+```
+
+### Full Configuration Reference
+
+```yaml
+chat:
+  slack:
+    # Required: Environment variables containing tokens
+    bot_token_env: SLACK_BOT_TOKEN
+    app_token_env: SLACK_APP_TOKEN
+
+    # Optional: Session expiry in hours (default: 24)
+    session_expiry_hours: 24
+
+    # Channel configurations
+    channels:
+      - id: "C0123456789"
+        name: "#support"        # Optional, for logging
+        mode: mention            # mention | auto
+
+    # Optional: DM configuration
+    dm:
+      enabled: true
+      mode: auto                 # mention | auto
+      allowlist: ["U001", "U002"]  # Only these users can DM
+      blocklist: ["U999"]          # These users cannot DM
+```
+
+### Chat Modes
+
+- **`auto`** - Respond to all messages in allowed channels/DMs
+- **`mention`** - Only respond when the bot is @mentioned
+
+## Features
+
+- **Conversation Continuity** - Sessions persist across messages using Claude SDK session resumption
+- **DM Support** - Users can chat privately with agents, with allowlist/blocklist controls
+- **Channel Support** - Agents can participate in multiple Slack channels
+- **Streaming Responses** - Responses are delivered incrementally as the agent generates them
+- **Typing Indicators** - Hourglass emoji reaction while the agent is processing
+- **Message Splitting** - Long responses are automatically split to fit Slack's 4,000-character limit
+- **Markdown Conversion** - Agent Markdown output is converted to Slack's mrkdwn format
+- **Socket Mode** - No public URL required; uses Slack Socket Mode for event delivery
+
+## Commands
+
+Type these in any channel where the bot is active:
+
+| Command | Description |
+|---------|-------------|
+| `!help` | Show available commands and usage |
+| `!status` | Show agent status and current session info |
+| `!reset` | Clear conversation context and start fresh |
+
+## Slack App Setup
+
+1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
+2. Enable **Socket Mode** and generate an App-Level Token (`xapp-...`)
+3. Add the following **Bot Token Scopes** under OAuth & Permissions:
+   - `chat:write`
+   - `channels:history`
+   - `groups:history`
+   - `im:history`
+   - `reactions:write`
+4. Enable **Event Subscriptions** and subscribe to:
+   - `message.channels`
+   - `message.groups`
+   - `message.im`
+5. Install the app to your workspace and copy the Bot User OAuth Token (`xoxb-...`)
+6. Set your tokens as environment variables:
+   ```bash
+   export SLACK_BOT_TOKEN="xoxb-..."
+   export SLACK_APP_TOKEN="xapp-..."
+   ```
+
+For a full walkthrough, see the [Slack Quick Start](https://herdctl.dev/guides/slack-quick-start/) guide.
+
+## Documentation
+
+For complete setup instructions, visit [herdctl.dev](https://herdctl.dev):
+
+- [Slack Quick Start](https://herdctl.dev/guides/slack-quick-start/)
+- [Chat Configuration](https://herdctl.dev/configuration/agent-config/#chat)
+
+## Related Packages
+
+- [`herdctl`](https://www.npmjs.com/package/herdctl) - CLI for running agent fleets
+- [`@herdctl/core`](https://www.npmjs.com/package/@herdctl/core) - Core library for programmatic use
+- [`@herdctl/chat`](https://www.npmjs.com/package/@herdctl/chat) - Shared chat infrastructure (used internally)
+- [`@herdctl/discord`](https://www.npmjs.com/package/@herdctl/discord) - Discord connector
+- [`@herdctl/web`](https://www.npmjs.com/package/@herdctl/web) - Web dashboard
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herdctl/slack",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Slack connector for herdctl fleet management",
   "license": "MIT",
   "type": "module",
@@ -15,8 +15,8 @@
     "slackify-markdown": "^5.0.0",
     "yaml": "^2.3.0",
     "zod": "^3.22.0",
-    "@herdctl/chat": "0.2.2",
-    "@herdctl/core": "5.2.0"
+    "@herdctl/chat": "0.2.4",
+    "@herdctl/core": "5.2.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",