@cuylabs/agent-channel-slack

@cuylabs/agent-channel-slack

Direct Slack channel integration for @cuylabs/agent-core.

This package is the native Slack transport. It uses Slack Bolt and the Slack Web API directly, so Slack Events API requests, Socket Mode events, Assistant events, Block Kit actions, history reads, and streaming responses stay in the Slack app model.

M365/Azure Bot Service Slack is no longer exported from this package. Its transport will release separately.

Install

pnpm add @cuylabs/agent-channel-slack @slack/bolt @slack/web-api express

Quick Start

import { mountSlackAgent } from "@cuylabs/agent-channel-slack";

await mountSlackAgent(agent, {
  path: "/slack/events",
});

Required environment variables:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
PORT=3000

For local development with Socket Mode:

import { mountSlackAgentAppSocket } from "@cuylabs/agent-channel-slack";

await mountSlackAgentAppSocket(agent, {
  appToken: process.env.SLACK_APP_TOKEN,
});

What This Package Provides

• direct Slack transport via Bolt
• unified Slack app mounting for Assistant pane, DMs, app_mention, and optional channel messages
• Slack Assistant lifecycle support for status, suggested prompts, title, native chatStream, and feedback blocks
• Slack-native HITL helpers using Block Kit actions and modals
• Slack setup diagnostics and manifest requirement helpers
• Slack thread/channel history helpers with optional author attribution
• richer model-facing Slack text extraction from plain text, Block Kit, rich_text, media alt text, and legacy attachments
• target parsing and resolution helpers for channel/user references
• cached Slack user profile resolution and optional mention enrichment
• markdown-to-mrkdwn response formatting
• shared ambient Slack turn context via currentSlackTurnContext()

Core APIs

• createSlackBoltApp(...)
• createSlackChannelAdapter(...)
• mountSlackAgent(...)
• createSlackAssistantBridge(...)
• mountSlackAssistantAgent(...)
• mountSlackAssistantAgentSocket(...)
• mountSlackAgentApp(...)
• mountSlackAgentAppSocket(...)
• createSlackInteractiveController(...)
• createSlackFeedbackBlock(...)
• registerSlackFeedbackAction(...)
• readSlackThreadHistory(...)
• readSlackChannelHistory(...)
• formatSlackHistoryForPrompt(...)
• loadSlackTurnHistoryContext(...)
• createSlackMessagePolicyResolver(...)
• inspectSlackConnection(...)
• inspectSlackTokenScopes(...)
• getSlackSetupRequirements(...)
• createSlackAppManifest(...)
• compareSlackAppManifest(...)
• inspectSlackAppSetup(...)
• parseSlackTarget(...)
• parseSlackTargets(...)
• resolveSlackChannelTargets(...)
• resolveSlackUserTargets(...)
• resolveSlackAllowedChannelIds(...)
• createSlackUserProfileResolver(...)
• enrichSlackUserMentions(...)
• createSlackMcpServerConfig(...)
• createSlackContextFragmentMiddleware(...)
• currentSlackTurnContext()
• parseSlackMessageActivity(...)
• parseSlackMentionActivity(...)
• parseSlackMessageActivityFromMessageEvent(...)
• extractSlackMessageText(...)

Setup Helpers

The setup helpers describe what your Slack app needs for the package features you enabled:

import {
  compareSlackAppManifest,
  createSlackAppManifest,
  getSlackSetupRequirements,
  inspectSlackAppSetup,
} from "@cuylabs/agent-channel-slack";

const requirements = getSlackSetupRequirements({
  preset: "agent-app",
  features: ["history", "user-profiles"],
  transport: "socket",
});

const manifest = createSlackAppManifest({
  name: "Ops Agent",
  description: "Internal operations assistant",
  assistantDescription: "Internal operations assistant",
  preset: "agent-app",
  features: ["history", "user-profiles"],
  transport: "socket",
});

const comparison = compareSlackAppManifest(manifest, requirements);
const installed = await inspectSlackAppSetup({
  token: process.env.SLACK_BOT_TOKEN,
  preset: "agent-app",
  features: ["history", "user-profiles"],
  transport: "socket",
});

History Attribution

Use loadSlackTurnHistoryContext({ resolveAuthor }) when history messages need stable author labels:

const history = await loadSlackTurnHistoryContext({
  client,
  activity: slackActivity,
  teamId,
  limit: 15,
  maxCharacters: 10_000,
  resolveAuthor: async (message) => {
    if (message.role === "assistant") return "Assistant";
    if (message.role === "bot") return "Bot";
    return message.userId ? `Slack user ${message.userId}` : undefined;
  },
});

Mention Enrichment

Use enrichSlackUserMentions(...) when model-facing text should keep stable Slack mention tokens while adding display labels:

const profileResolver = createSlackUserProfileResolver({ botToken });

const enriched = await enrichSlackUserMentions(
  {
    text: "Can <@U123> review this alert?",
    teamId,
    botToken,
  },
  {
    profileResolver,
    maxLookups: 20,
    concurrency: 4,
  },
);

Docs

• docs/direct-slack.md
• docs/architecture.md
• examples/README.md