@cuylabs/channel-slack 0.1.0

package/dist/core.d.ts

@@ -0,0 +1,425 @@
+import { S as SlackActivityInfo, b as SlackUserIdentity, a as SlackChannelType } from './activity-ByrD9Ftr.js';
+
+/**
+ * Slack auth context — credentials and identifiers resolved from the inbound
+ * request. **Sensitive**: see security note on `SlackAuthContext`.
+ */
+/**
+ * Slack credentials and identifiers resolved from the inbound request.
+ *
+ * Surfaced to `prepareTurn`, the ambient `currentSlackTurnContext()`, and the
+ * assistant message context so tools and middleware can call the Slack Web
+ * API or attach per-user OAuth tokens to MCP servers (see
+ * `createSlackMcpServerConfig`).
+ *
+ * Security: `botToken` and `userToken` are secrets. Do not include this auth
+ * bag in logs, telemetry attributes, baggage, tool results, message history,
+ * or model-visible prompts. Pass only the exact token needed to a trusted
+ * Slack API/MCP client.
+ *
+ * Most fields come from Bolt's enriched `args.context`. They are all optional
+ * because availability depends on the auth mode (single-workspace vs OAuth)
+ * and on whether the installer granted user scopes.
+ */
+interface SlackAuthContext {
+    /** Workspace bot token (`xoxb-...`). */
+    botToken?: string;
+    /** End-user OAuth token (`xoxp-...`) when user scopes were granted. */
+    userToken?: string;
+    /** Workspace ID (`T...`). */
+    teamId?: string;
+    /** Enterprise grid ID (`E...`) when applicable. */
+    enterpriseId?: string;
+    /** Bot user ID (`U...`) — useful for distinguishing bot self-mentions. */
+    botUserId?: string;
+    /** Internal Slack bot ID (`B...`). */
+    botId?: string;
+    /** Slack user ID (`U...`) of the human author of the inbound event. */
+    userId?: string;
+}
+
+/**
+ * Slack assistant lifecycle types — status updates, suggested prompts, thread
+ * context, and the channel-neutral `SlackAssistantUtilities` interface that
+ * the assistant bridge surfaces ambiently for tools and middleware.
+ */
+/**
+ * Slack assistant thread context — the channel of origin metadata Slack tracks
+ * while a user navigates the workspace. Surfaces the same fields Bolt's
+ * `AssistantThreadContextStore` returns.
+ *
+ * @see https://docs.slack.dev/reference/events/assistant_thread_context_changed
+ */
+interface SlackAssistantThreadContext {
+    channel_id?: string;
+    team_id?: string;
+    enterprise_id?: string | null;
+}
+/** Display mode passed to `client.chatStream`. */
+type SlackAssistantTaskDisplayMode = "plan" | "timeline";
+/**
+ * Slack message authorship fields supported by AI assistant status updates
+ * and native chat stream start calls.
+ */
+interface SlackMessageAuthorshipOptions {
+    /** Emoji shown as the message/status icon, e.g. `":robot_face:"`. */
+    icon_emoji?: string;
+    /** Image URL shown as the message/status icon. */
+    icon_url?: string;
+    /** Display name shown for the message/status. */
+    username?: string;
+}
+/** Optional passthrough fields for Slack's native `chat.startStream`. */
+type SlackChatStreamStartArgs = SlackMessageAuthorshipOptions & {
+    /**
+     * Slack task display mode for streamed tool/task chunks. `timeline` shows
+     * individual task cards; `plan` groups task cards together.
+     */
+    task_display_mode?: SlackAssistantTaskDisplayMode;
+};
+/** A single suggested prompt chip shown in the assistant pane. */
+interface SlackAssistantSuggestedPrompt {
+    title: string;
+    message: string;
+}
+/** Suggested prompts payload for `assistant.threads.setSuggestedPrompts`. */
+interface SlackAssistantSuggestedPrompts {
+    /** Title shown above the chips. Defaults to Slack's "Try these prompts:". */
+    title?: string;
+    prompts: SlackAssistantSuggestedPrompt[];
+}
+/** Status payload accepted by Bolt's assistant `setStatus`. */
+interface SlackAssistantStatusUpdate extends SlackMessageAuthorshipOptions {
+    status: string;
+    loading_messages?: string[];
+}
+/**
+ * Assistant pane utilities surfaced ambiently so tools/middleware can call
+ * them mid-turn without wiring the raw Bolt args through.
+ *
+ * Only present when the turn is running through the assistant bridge.
+ */
+interface SlackAssistantUtilities {
+    setStatus: (update: SlackAssistantStatusUpdate) => Promise<void>;
+    setSuggestedPrompts: (prompts: SlackAssistantSuggestedPrompts) => Promise<void>;
+    setTitle: (title: string) => Promise<void>;
+    getThreadContext: () => Promise<SlackAssistantThreadContext>;
+    saveThreadContext: () => Promise<void>;
+}
+/**
+ * Status utility exposed by Bolt for any message/app_mention event with a
+ * channel + thread timestamp. It calls Slack's assistant thread status API,
+ * but unlike the full Assistant surface it does not imply suggested prompts,
+ * thread titles, or origin-channel context.
+ */
+type SlackThreadStatusSetter = (update: SlackAssistantStatusUpdate) => Promise<void>;
+
+/**
+ * Slack turn-request and turn-preparation contracts shared by Slack transport
+ * packages. Direct Slack fills these from Bolt events; M365-backed Slack fills
+ * the same shape from Bot Framework activities.
+ */
+
+/**
+ * Context available while preparing a Slack turn.
+ */
+interface SlackTurnRequestContext {
+    /** Parsed Slack activity metadata */
+    slackActivity: SlackActivityInfo;
+    /** Extracted Slack user identity */
+    user: SlackUserIdentity;
+    /** Resolved agent session ID for this conversation */
+    sessionId: string;
+    /** Plain-text message forwarded to the host application */
+    message: string;
+    /**
+     * Slack auth + identity resolved from the inbound request.
+     *
+     * Includes the bot token, optional end-user OAuth token, team/enterprise
+     * IDs, and bot user ID. Tools and `prepareTurn` callers can use these to
+     * call the Slack Web API or attach the user token to MCP servers.
+     */
+    auth?: SlackAuthContext;
+    /**
+     * Assistant thread context resolved by Bolt for assistant-pane turns.
+     *
+     * Tells the agent which channel/workspace the user is currently viewing
+     * while talking to the assistant — useful for context-aware system prompts
+     * and for resolving relative references like "this channel".
+     *
+     * `undefined` when the turn was not routed through the assistant bridge.
+     */
+    threadContext?: SlackAssistantThreadContext;
+    /**
+     * Slack thread status setter available when Bolt provides `setStatus` for
+     * the inbound event. This can be present on classic `app_mention` /
+     * `message` turns as well as full Assistant-pane turns.
+     */
+    setStatus?: SlackThreadStatusSetter;
+}
+/**
+ * Optional turn preparation result for a Slack turn.
+ */
+interface SlackTurnPreparation {
+    /** Optional system override for the host application */
+    system?: string;
+    /** Optional message override for the host application. */
+    message?: string;
+    /** Optional session override for this turn. */
+    sessionId?: string;
+    /** Optional custom scope name for the activity */
+    scopeName?: string;
+    /** Additional scalar attributes merged into the activity scope */
+    scopeAttributes?: Record<string, string | number | boolean | null | undefined>;
+    /** Arbitrary app-specific per-turn context exposed via AsyncLocalStorage */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Transport-neutral interactive request contracts.
+ *
+ * These types let callers delegate approval and human-input requests to a
+ * Slack-specific renderer without importing Bolt or Web API types into
+ * `shared/`.
+ */
+
+type SlackInteractiveRequestKind = "approval" | "human-input";
+type SlackApprovalRequest = Record<string, unknown>;
+type SlackHumanInputRequest = Record<string, unknown>;
+type SlackInteractiveRequest = SlackApprovalRequest | SlackHumanInputRequest;
+interface SlackInteractiveMessageRef {
+    channel: string;
+    ts: string;
+}
+interface SlackInteractiveMessage {
+    text: string;
+    blocks?: unknown[];
+}
+interface SlackInteractiveResponder {
+    postMessage(message: SlackInteractiveMessage): Promise<SlackInteractiveMessageRef>;
+    updateMessage(ref: SlackInteractiveMessageRef, message: SlackInteractiveMessage): Promise<void>;
+}
+interface SlackInteractiveRequestBaseContext {
+    kind: SlackInteractiveRequestKind;
+    request: SlackInteractiveRequest;
+    fallbackText: string;
+}
+interface SlackInteractiveRequestContext extends SlackInteractiveRequestBaseContext {
+    slackActivity: SlackActivityInfo;
+    user: SlackUserIdentity;
+    sessionId: string;
+    message: string;
+    responder: SlackInteractiveResponder;
+}
+type SlackInteractiveRequestHandler = (context: SlackInteractiveRequestContext) => boolean | void | Promise<boolean | void>;
+type SlackEventInteractiveRequestHandler = (context: SlackInteractiveRequestBaseContext) => boolean | void | Promise<boolean | void>;
+
+/**
+ * Raw Slack event payload parsers — produce `SlackActivityInfo` from the
+ * shapes Bolt delivers for `message` and `app_mention` events.
+ */
+
+interface RawSlackAssistantThreadPayload {
+    action_token?: string;
+    [key: string]: unknown;
+}
+interface RawSlackActionTokenPayload {
+    action_token?: unknown;
+    assistant_thread?: unknown;
+}
+interface RawSlackMessagePayload {
+    type: string;
+    subtype?: string;
+    text?: string;
+    user?: string;
+    bot_id?: string;
+    channel?: string;
+    channel_type?: string;
+    ts?: string;
+    thread_ts?: string;
+    parent_user_id?: string;
+    team?: string;
+    action_token?: string;
+    assistant_thread?: RawSlackAssistantThreadPayload;
+    blocks?: unknown[];
+    attachments?: unknown[];
+}
+interface RawSlackAppMentionPayload {
+    type: string;
+    text?: string;
+    user?: string;
+    channel?: string;
+    ts?: string;
+    thread_ts?: string;
+    parent_user_id?: string;
+    team?: string;
+    action_token?: string;
+    assistant_thread?: RawSlackAssistantThreadPayload;
+    blocks?: unknown[];
+    attachments?: unknown[];
+}
+declare function extractSlackActionToken(payload: RawSlackActionTokenPayload | undefined): string | undefined;
+/**
+ * Parse a raw Slack message event payload into a `SlackActivityInfo`.
+ */
+declare function parseSlackMessageActivity(payload: RawSlackMessagePayload): SlackActivityInfo;
+/**
+ * Parse a raw Slack `app_mention` event payload into a `SlackActivityInfo`.
+ */
+declare function parseSlackMentionActivity(payload: RawSlackAppMentionPayload): SlackActivityInfo;
+
+/**
+ * Slack channel-type classification + message-text normalisation helpers.
+ */
+
+/**
+ * Classify a Slack channel ID into a high-level surface type.
+ *
+ * Slack channel IDs have stable prefixes:
+ * - `D` — Direct message (IM)
+ * - `C` — Public or private channel
+ * - `G` — Multi-party DM / group DM (legacy)
+ */
+declare function resolveSlackChannelType(channelId: string, threadTs: string | undefined, inReplyToMessage: boolean): SlackChannelType;
+/**
+ * Strip leading `<@USERID>` mention(s) from a Slack message text.
+ * Slack wraps mentions in `<@U...>` format in the raw message text.
+ */
+declare function stripLeadingMentions(text: string): string;
+/**
+ * Return `true` if a raw Slack message payload represents a plain user
+ * message that the adapter should process. Filters out bot messages,
+ * edits, deletions, and other system subtypes.
+ */
+declare function isProcessableMessage(payload: RawSlackMessagePayload): boolean;
+
+interface ExtractSlackMessageTextOptions {
+    /**
+     * Strip leading Slack mention tokens from the final extracted text.
+     *
+     * Useful for `app_mention` and non-DM message handling where the leading bot
+     * mention should not become model input.
+     */
+    stripLeadingMentions?: boolean;
+}
+interface SlackMessageTextPayload {
+    text?: string;
+    blocks?: unknown[];
+    attachments?: unknown[];
+}
+/**
+ * Extract model-facing text from a Slack message payload.
+ *
+ * Slack often includes useful user-visible text in Block Kit payloads even
+ * when `payload.text` is missing or too generic. This helper keeps the common
+ * fast path (`text`) but falls back to rich text, section/header/context text,
+ * image/video alt/title text, and legacy Slack attachment fields when needed.
+ */
+declare function extractSlackMessageText(payload: SlackMessageTextPayload | undefined, options?: ExtractSlackMessageTextOptions): string;
+declare function extractSlackBlocksText(blocks: unknown): string;
+declare function extractSlackAttachmentsText(attachments: unknown): string;
+
+/**
+ * Identity + auth extractors that sit alongside the Slack activity parsers.
+ *
+ * `extractSlackAuthContext` reads Bolt's enriched `args.context` bag and
+ * returns the credentials needed for outgoing Slack API calls. The result is
+ * sensitive — see the security note on `SlackAuthContext`.
+ */
+
+/**
+ * Extract a `SlackUserIdentity` from a parsed `SlackActivityInfo`.
+ */
+declare function extractSlackUserIdentity(info: SlackActivityInfo): SlackUserIdentity;
+/**
+ * Extract Slack auth and identity values from Bolt's enriched `context` bag.
+ *
+ * The returned object can contain bot/user OAuth tokens. Treat it as
+ * sensitive: keep it in ambient turn context only and never copy it into
+ * logs, telemetry attributes, or model-visible content.
+ */
+declare function extractSlackAuthContext(context: unknown, eventUserId?: string): SlackAuthContext;
+
+/**
+ * Slack text formatting helpers.
+ *
+ * Agent models generally emit CommonMark-style markdown. Slack accepts its
+ * own mrkdwn dialect, so direct Slack and Slack-via-ABS transports should
+ * normalize common constructs before posting.
+ */
+type SlackMessageFormatter = (text: string) => string;
+interface SlackMessageFormattingOptions {
+    /**
+     * Convert common markdown constructs to Slack mrkdwn.
+     *
+     * @default true
+     */
+    formatChatMarkdown?: boolean;
+    /**
+     * Custom text formatter. When provided, this takes precedence over the
+     * built-in markdown-to-mrkdwn conversion.
+     */
+    formatMessageText?: SlackMessageFormatter;
+}
+declare function resolveSlackMessageFormatter(options: SlackMessageFormattingOptions): SlackMessageFormatter;
+declare function markdownToSlackMrkdwn(markdown: string): string;
+
+declare function formatSlackAttributedFollowUp(message: string): string;
+
+/**
+ * Resolve Slack sessions using natural Slack conversation boundaries.
+ *
+ * - DMs use the channel ID.
+ * - Thread replies use `channelId:threadTs`.
+ * - Top-level channel messages use `channelId:messageTs`, so follow-up
+ *   replies in the created thread can share context.
+ */
+declare function resolveThreadAwareSlackSessionId(info: SlackActivityInfo): string;
+
+/**
+ * Ambient turn context exposed via `currentSlackTurnContext()`.
+ *
+ * Tools and middleware running inside a Slack turn can read this to call the
+ * Slack Web API, attach the per-user OAuth token to MCP servers, or update
+ * the assistant pane (status, suggested prompts, title) mid-turn.
+ *
+ * Security: `auth.botToken` and `auth.userToken` are secrets. Do not write
+ * them to logs, traces, telemetry baggage, tool results, message history, or
+ * model-visible prompts. Pass only the exact token needed to trusted Slack
+ * clients or MCP transports.
+ *
+ * Fields beyond `SlackTurnRequestContext`:
+ * - `context`     — arbitrary host-supplied bag from `prepareTurn`
+ * - `assistant`   — assistant pane utilities (only present on assistant turns)
+ *
+ * The auth bag, `threadContext`, and generic `setStatus` status setter are
+ * inherited from `SlackTurnRequestContext`.
+ */
+interface SlackAmbientTurnContext extends SlackTurnRequestContext {
+    /**
+     * Arbitrary app-specific turn context resolved by `prepareTurn(...)`.
+     *
+     * Use this for things like user preferences, workspace-scoped config, or
+     * request-bound helper objects needed by tools and middleware.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Assistant pane utilities (`setStatus`, `setSuggestedPrompts`, `setTitle`,
+     * `getThreadContext`, `saveThreadContext`).
+     *
+     * Only present when the turn is routed through the assistant bridge. Use the
+     * top-level `setStatus` when code only needs status updates and should also
+     * work for classic `app_mention` / `message` turns.
+     */
+    assistant?: SlackAssistantUtilities;
+}
+/**
+ * Return the Slack turn currently bound to this async execution context.
+ *
+ * The returned context can contain Slack OAuth tokens in `auth`; treat it as
+ * sensitive application state and never serialize it wholesale.
+ */
+declare function currentSlackTurnContext(): Readonly<SlackAmbientTurnContext> | undefined;
+declare function runWithSlackTurnContext<T>(value: SlackAmbientTurnContext, fn: () => T | Promise<T>): Promise<T>;
+
+export { type ExtractSlackMessageTextOptions, type RawSlackActionTokenPayload, type RawSlackAppMentionPayload, type RawSlackAssistantThreadPayload, type RawSlackMessagePayload, SlackActivityInfo, type SlackAmbientTurnContext, type SlackApprovalRequest, type SlackAssistantStatusUpdate, type SlackAssistantSuggestedPrompt, type SlackAssistantSuggestedPrompts, type SlackAssistantTaskDisplayMode, type SlackAssistantThreadContext, type SlackAssistantUtilities, type SlackAuthContext, SlackChannelType, type SlackChatStreamStartArgs, type SlackEventInteractiveRequestHandler, type SlackHumanInputRequest, type SlackInteractiveMessage, type SlackInteractiveMessageRef, type SlackInteractiveRequest, type SlackInteractiveRequestBaseContext, type SlackInteractiveRequestContext, type SlackInteractiveRequestHandler, type SlackInteractiveRequestKind, type SlackInteractiveResponder, type SlackMessageAuthorshipOptions, type SlackMessageFormatter, type SlackMessageFormattingOptions, type SlackMessageTextPayload, type SlackThreadStatusSetter, type SlackTurnPreparation, type SlackTurnRequestContext, SlackUserIdentity, currentSlackTurnContext, extractSlackActionToken, extractSlackAttachmentsText, extractSlackAuthContext, extractSlackBlocksText, extractSlackMessageText, extractSlackUserIdentity, formatSlackAttributedFollowUp, isProcessableMessage, markdownToSlackMrkdwn, parseSlackMentionActivity, parseSlackMessageActivity, resolveSlackChannelType, resolveSlackMessageFormatter, resolveThreadAwareSlackSessionId, runWithSlackTurnContext, stripLeadingMentions };

package/dist/core.js

@@ -0,0 +1,42 @@
+import {
+  currentSlackTurnContext,
+  formatSlackAttributedFollowUp,
+  markdownToSlackMrkdwn,
+  resolveSlackMessageFormatter,
+  resolveThreadAwareSlackSessionId,
+  runWithSlackTurnContext
+} from "./chunk-JZG4IETE.js";
+import {
+  extractSlackActionToken,
+  extractSlackAuthContext,
+  extractSlackUserIdentity,
+  parseSlackMentionActivity,
+  parseSlackMessageActivity
+} from "./chunk-TWJGVDA2.js";
+import {
+  extractSlackAttachmentsText,
+  extractSlackBlocksText,
+  extractSlackMessageText,
+  isProcessableMessage,
+  resolveSlackChannelType,
+  stripLeadingMentions
+} from "./chunk-FPCE5V5Y.js";
+export {
+  currentSlackTurnContext,
+  extractSlackActionToken,
+  extractSlackAttachmentsText,
+  extractSlackAuthContext,
+  extractSlackBlocksText,
+  extractSlackMessageText,
+  extractSlackUserIdentity,
+  formatSlackAttributedFollowUp,
+  isProcessableMessage,
+  markdownToSlackMrkdwn,
+  parseSlackMentionActivity,
+  parseSlackMessageActivity,
+  resolveSlackChannelType,
+  resolveSlackMessageFormatter,
+  resolveThreadAwareSlackSessionId,
+  runWithSlackTurnContext,
+  stripLeadingMentions
+};

package/dist/diagnostics.d.ts

@@ -0,0 +1,105 @@
+type SlackScopeInspectionMethod = "auth.test" | "auth.scopes" | "apps.permissions.info";
+type SlackConnectionInspectionFindingSeverity = "info" | "warning" | "error";
+type SlackTokenSource = "provided" | "environment" | "client" | "none";
+interface SlackDiagnosticsClient {
+    auth: {
+        test(args?: {
+            token?: string;
+        }): Promise<unknown>;
+    };
+    apiCall(method: string, args?: Record<string, unknown>): Promise<unknown>;
+}
+interface SlackApiInspectionError {
+    message: string;
+    code?: string;
+    method?: string;
+    needed?: string;
+    providedScopes?: string[];
+    acceptedScopes?: string[];
+    statusCode?: number;
+}
+interface SlackScopeInspectionMethodError {
+    method: SlackScopeInspectionMethod;
+    error: SlackApiInspectionError;
+}
+interface SlackScopeInspection {
+    ok: boolean;
+    scopes: string[];
+    source?: SlackScopeInspectionMethod;
+    errors: SlackScopeInspectionMethodError[];
+}
+interface SlackConnectionInspectionFinding {
+    severity: SlackConnectionInspectionFindingSeverity;
+    code: string;
+    message: string;
+}
+interface SlackConnectionAuthInfo {
+    ok: boolean;
+    url?: string;
+    team?: string;
+    teamId?: string;
+    user?: string;
+    userId?: string;
+    botId?: string;
+    enterpriseId?: string;
+    isEnterpriseInstall?: boolean;
+}
+interface SlackConnectionInspection {
+    ok: boolean;
+    tokenSource: SlackTokenSource;
+    elapsedMs: number;
+    auth?: SlackConnectionAuthInfo;
+    scopes?: SlackScopeInspection;
+    requiredScopes: string[];
+    optionalScopes: string[];
+    missingRequiredScopes: string[];
+    missingOptionalScopes: string[];
+    findings: SlackConnectionInspectionFinding[];
+    error?: SlackApiInspectionError;
+}
+interface InspectSlackTokenScopesOptions {
+    /**
+     * Slack bot or user OAuth token. When omitted, the injected client is used
+     * as-is and no token override is passed to Slack API calls.
+     */
+    token?: string;
+    /** Inject a preconfigured Slack Web API client, useful for OAuth stores/tests. */
+    client?: SlackDiagnosticsClient;
+    /**
+     * Maximum time for each Slack API request in milliseconds. Set `0` to
+     * disable the local timeout wrapper.
+     *
+     * @default 2500
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Scope-bearing methods to try in order.
+     *
+     * @default ["auth.test", "auth.scopes", "apps.permissions.info"]
+     */
+    methods?: readonly SlackScopeInspectionMethod[];
+}
+interface InspectSlackConnectionOptions extends Omit<InspectSlackTokenScopesOptions, "methods"> {
+    /**
+     * Slack OAuth scopes that must be present for this installation to be
+     * considered usable by the caller.
+     */
+    requiredScopes?: readonly string[];
+    /**
+     * Slack OAuth scopes that are useful but not mandatory. Missing optional
+     * scopes are returned as warnings.
+     */
+    optionalScopes?: readonly string[];
+    /**
+     * Whether to inspect token scopes after `auth.test` succeeds.
+     *
+     * @default true
+     */
+    inspectScopes?: boolean;
+    /** Override the scope-inspection method order. */
+    scopeMethods?: readonly SlackScopeInspectionMethod[];
+}
+declare function inspectSlackConnection(options?: InspectSlackConnectionOptions): Promise<SlackConnectionInspection>;
+declare function inspectSlackTokenScopes(options?: InspectSlackTokenScopesOptions): Promise<SlackScopeInspection>;
+
+export { type InspectSlackConnectionOptions, type InspectSlackTokenScopesOptions, type SlackApiInspectionError, type SlackConnectionInspection, type SlackConnectionInspectionFinding, type SlackConnectionInspectionFindingSeverity, type SlackDiagnosticsClient, type SlackScopeInspection, type SlackScopeInspectionMethod, type SlackScopeInspectionMethodError, type SlackTokenSource, inspectSlackConnection, inspectSlackTokenScopes };

package/dist/diagnostics.js

@@ -0,0 +1,8 @@
+import {
+  inspectSlackConnection,
+  inspectSlackTokenScopes
+} from "./chunk-FX2JOVX5.js";
+export {
+  inspectSlackConnection,
+  inspectSlackTokenScopes
+};