@cuylabs/channel-slack

Slack channel primitives for AI agents.

This package contains reusable Slack mechanics: activity parsing, message formatting, message admission policy, supplemental history, visibility filters, Socket Mode runtime guards, OAuth installation storage, setup inspection, and Slack API helpers. It intentionally does not create or run an agent.

It is not an agent runtime adapter. Use @cuylabs/channel-slack-agent-core for the runtime-specific adapter. See Channel Slack Boundary for the package boundary.

Install

npm install @cuylabs/channel-slack

Slack SDK packages are optional peers. Install the peers for the components you use:

npm install @slack/bolt @slack/web-api @slack/types express

Postgres-backed helpers lazy-load pg when you pass a connection string. Install pg in applications that use those helpers without injecting their own client or pool.

Import Map

Prefer feature-specific imports so applications only couple to the Slack surface they need.

| Import | Use for | | ------------------------------------ | ---------------------------------------------------------------------------------- | | @cuylabs/channel-slack/core | Activity parsing, formatting, sessions, turn context, shared types | | @cuylabs/channel-slack/policy | Message admission, duplicate suppression, mentioned-thread state | | @cuylabs/channel-slack/history | Slack history reading, prompt shaping, supplemental-history visibility | | @cuylabs/channel-slack/bolt | Bolt app factories, auth options, Socket Mode runtime helpers, installation stores | | @cuylabs/channel-slack/setup | Required scopes/events/settings, generated manifests, setup inspection | | @cuylabs/channel-slack/diagnostics | Slack token and scope checks | | @cuylabs/channel-slack/users | User profile lookup and mention enrichment | | @cuylabs/channel-slack/targets | Human-friendly Slack channel/user target parsing and resolution | | @cuylabs/channel-slack/feedback | Feedback Block Kit and action helpers |

The package root re-exports core and policy as a lightweight convenience. Use feature-specific imports for peer-backed helpers such as bolt, diagnostics, setup, and users. @cuylabs/channel-slack/shared remains as an alias of core.

Core Flow

Most Slack agent adapters follow this flow:

1. Parse a Slack event into SlackActivityInfo.
2. Resolve whether the message should start or continue an agent turn.
3. Optionally load model-visible Slack history for the turn.
4. Run the product-owned agent.
5. Format the response back to Slack.

import {
  markdownToSlackMrkdwn,
  parseSlackMentionActivity,
} from "@cuylabs/channel-slack/core";
import { createSlackMessagePolicyResolver } from "@cuylabs/channel-slack/policy";

const activity = parseSlackMentionActivity(slackAppMentionEvent);
const policy = createSlackMessagePolicyResolver({
  messagePolicy: "mentioned-threads",
  threadReplyPolicy: "original-user",
});

const decision = policy.resolve(activity);
if (!decision.accepted) return;

const responseText = markdownToSlackMrkdwn("**Ready**");

Components

Core

core is transport-neutral. It parses raw Slack message and app mention payloads, extracts model-facing text from Slack text, Block Kit, rich text, and attachments, formats Markdown to Slack mrkdwn, derives thread-aware session IDs, and carries request context.

See Activity.

Policy

policy decides which Slack messages an adapter should process. It accepts DMs and direct mentions by default, can allow passive channel messages by channel or install scope, tracks mentioned threads, and suppresses duplicate Slack events. Use createPostgresSlackMessagePolicyStateStore when duplicate suppression and mentioned-thread state must survive restarts or coordinate across workers.

See Message Policy.

History

history reads Slack thread/channel history, normalizes messages, formats prompt sections, reports expected Slack history access failures, and filters supplemental context before it reaches a model.

See Supplemental History.

Bolt

bolt contains app factories for HTTP and Socket Mode, direct auth resolution, OAuth installation-store types, development installation stores, and Socket Mode process/runtime guards. It also exposes a Postgres advisory-lock helper for distributed Socket Mode single-instance coordination. It does not register agent handlers.

See Bolt Runtime.

Setup

setup turns feature selections into Slack scopes, bot events, settings, environment variables, and app manifests. It can also inspect a token against the requirements.

See Setup Requirements.

Recipes

• App mention handler
• Assistant thread handler
• Socket Mode app
• Generate a Slack manifest
• History visibility filter

Source Layout

src/
  core.ts                 public core entrypoint
  shared/                 types, parsing, formatting, turn helpers
  assistant/              Slack Assistant API helpers
  bolt/                   Bolt app/auth/runtime helpers
  diagnostics/            token and scope inspection
  feedback/               feedback blocks and action parsing
  history/
    context/              turn-history loading component
    reader.ts             Slack history API reader and prompt formatter
    visibility-policy.ts  model-visible history filters
    inclusion-policy.ts   direct-message supplemental-history inclusion policy
  policy/
    message/              message admission and state-store component
  setup/                  scopes, events, manifests, setup inspection
  targets/                channel/user target parsing and resolution
  users/                  profile lookup and mention enrichment

Development

pnpm --filter @cuylabs/channel-slack typecheck
pnpm --filter @cuylabs/channel-slack test
pnpm --filter @cuylabs/channel-slack build

Run workspace checks before publishing changes:

pnpm lint
pnpm typecheck
pnpm build
pnpm test
pnpm format:check