@cuylabs/channel-slack 0.1.0

package/dist/feedback.d.ts

@@ -0,0 +1,137 @@
+import { ContextActionsBlock, View } from '@slack/types';
+import { App } from '@slack/bolt';
+
+/**
+ * Slack feedback block builder.
+ *
+ * Slack's "thumbs up / thumbs down" UI is a `context_actions` block with a
+ * single `feedback_buttons` element. The block shape follows the official
+ * `@slack/types` Block Kit definitions.
+ */
+
+type SlackFeedbackButtons = Extract<ContextActionsBlock["elements"][number], {
+    type: "feedback_buttons";
+}> & {
+    action_id: string;
+};
+/**
+ * Slack feedback block shape. Returned to callers as a typed object so it can
+ * be appended directly to `chatStream.stop({ blocks })` without further
+ * casting.
+ */
+interface SlackFeedbackContextBlock extends Omit<ContextActionsBlock, "type" | "elements"> {
+    type: "context_actions";
+    elements: [SlackFeedbackButtons];
+}
+declare const SLACK_FEEDBACK_ACTION_ID = "agent_feedback";
+type SlackFeedbackVerdict = "positive" | "negative";
+interface SlackFeedbackButtonConfig {
+    /**
+     * Slack block-action `value` for the positive button.
+     *
+     * @default "good-feedback"
+     */
+    positiveValue?: string;
+    /**
+     * Slack block-action `value` for the negative button.
+     *
+     * @default "bad-feedback"
+     */
+    negativeValue?: string;
+    /**
+     * Visible button text and accessibility labels.
+     */
+    positiveButton?: {
+        text: string;
+        accessibilityLabel?: string;
+    };
+    negativeButton?: {
+        text: string;
+        accessibilityLabel?: string;
+    };
+}
+interface SlackFeedbackBlockOptions extends SlackFeedbackButtonConfig {
+    /**
+     * Block-action id used to dispatch the click. Override only if you need
+     * multiple feedback widgets in the same workspace.
+     *
+     * @default SLACK_FEEDBACK_ACTION_ID
+     */
+    actionId?: string;
+}
+/**
+ * Build the canonical feedback block to attach to assistant replies.
+ *
+ * The shape mirrors the official Bolt assistant template's `feedback_block`
+ * (a `context_actions` block with a single `feedback_buttons` element).
+ */
+declare function createSlackFeedbackBlock(options?: SlackFeedbackBlockOptions): SlackFeedbackContextBlock;
+
+/**
+ * Slack feedback block-action handler.
+ *
+ * Wires the click on the canonical feedback block onto a Bolt `App`. Bolt
+ * routes the click as a `block_actions` payload whose
+ * `actions[0].type === "feedback_buttons"`. This module parses the verdict,
+ * acknowledges the click, calls the host's `onFeedback` handler, and posts an
+ * ephemeral acknowledgement.
+ */
+
+interface SlackFeedbackContext {
+    verdict: SlackFeedbackVerdict;
+    /** Raw value submitted by the button. */
+    value: string;
+    channelId: string;
+    userId: string;
+    /** Timestamp of the message the feedback applies to. */
+    messageTs: string;
+    /** Thread the message lives in, if any. */
+    threadTs?: string;
+    /** Slack interactivity trigger id for opening a modal from the click. */
+    triggerId?: string;
+    /** Optional agent session id resolved by the host bridge. */
+    sessionId?: string;
+    /** Convenience helper that opens a Slack modal from the feedback click. */
+    openModal: (view: View) => Promise<void>;
+    /** Convenience helper that posts a private acknowledgement to the user. */
+    acknowledgeEphemeral: (text: string) => Promise<void>;
+}
+type SlackFeedbackHandler = (context: SlackFeedbackContext) => void | Promise<void>;
+interface RegisterSlackFeedbackOptions extends SlackFeedbackBlockOptions {
+    /**
+     * Handler invoked after the block-action ack resolves.
+     */
+    onFeedback: SlackFeedbackHandler;
+    /**
+     * Ephemeral text shown to the user for a positive click.
+     *
+     * Set to `false` to skip the auto-ack message; the handler is still called.
+     *
+     * @default "Thanks for the feedback!"
+     */
+    positiveAck?: string | false;
+    /**
+     * Ephemeral text shown for a negative click.
+     *
+     * @default "Thanks — we'll use this to improve the assistant."
+     */
+    negativeAck?: string | false;
+    /**
+     * Optional resolver used by higher-level bridges to attach the agent session
+     * id that produced the message.
+     */
+    resolveSessionId?: (context: Omit<SlackFeedbackContext, "acknowledgeEphemeral" | "openModal" | "sessionId">) => string | undefined;
+}
+/**
+ * Register the feedback block-action handler on a Bolt `App`.
+ *
+ * Returns the resolved actionId and verdict mapping so the same values can be
+ * passed to `createSlackFeedbackBlock` when generating the block.
+ */
+declare function registerSlackFeedbackAction(app: App, options: RegisterSlackFeedbackOptions): {
+    actionId: string;
+    positiveValue: string;
+    negativeValue: string;
+};
+
+export { type RegisterSlackFeedbackOptions, SLACK_FEEDBACK_ACTION_ID, type SlackFeedbackBlockOptions, type SlackFeedbackButtonConfig, type SlackFeedbackContext, type SlackFeedbackContextBlock, type SlackFeedbackHandler, type SlackFeedbackVerdict, createSlackFeedbackBlock, registerSlackFeedbackAction };

package/dist/feedback.js

@@ -0,0 +1,128 @@
+// src/feedback/block.ts
+var SLACK_FEEDBACK_ACTION_ID = "agent_feedback";
+function createSlackFeedbackBlock(options = {}) {
+  const actionId = (options.actionId ?? SLACK_FEEDBACK_ACTION_ID).trim();
+  if (!actionId) {
+    throw new Error(
+      "createSlackFeedbackBlock: actionId must be a non-empty string"
+    );
+  }
+  const positiveValue = options.positiveValue ?? "good-feedback";
+  const negativeValue = options.negativeValue ?? "bad-feedback";
+  const positiveLabel = options.positiveButton?.text ?? "Good Response";
+  const negativeLabel = options.negativeButton?.text ?? "Bad Response";
+  const positiveA11y = options.positiveButton?.accessibilityLabel ?? "Submit positive feedback on this response";
+  const negativeA11y = options.negativeButton?.accessibilityLabel ?? "Submit negative feedback on this response";
+  return {
+    type: "context_actions",
+    elements: [
+      {
+        type: "feedback_buttons",
+        action_id: actionId,
+        positive_button: {
+          text: { type: "plain_text", text: positiveLabel },
+          accessibility_label: positiveA11y,
+          value: positiveValue
+        },
+        negative_button: {
+          text: { type: "plain_text", text: negativeLabel },
+          accessibility_label: negativeA11y,
+          value: negativeValue
+        }
+      }
+    ]
+  };
+}
+
+// src/feedback/action.ts
+function registerSlackFeedbackAction(app, options) {
+  const actionId = (options.actionId ?? SLACK_FEEDBACK_ACTION_ID).trim();
+  const positiveValue = options.positiveValue ?? "good-feedback";
+  const negativeValue = options.negativeValue ?? "bad-feedback";
+  const positiveAck = options.positiveAck === void 0 ? "Thanks for the feedback!" : options.positiveAck;
+  const negativeAck = options.negativeAck === void 0 ? "Thanks \u2014 we'll use this to improve the assistant." : options.negativeAck;
+  app.action(
+    actionId,
+    // Bolt's action args don't have a single shared exported type; the
+    // structural shape we read here (ack/body/client/logger) is stable.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async ({ ack, body, client, logger }) => {
+      const ackFn = ack;
+      await ackFn();
+      try {
+        if (body?.type !== "block_actions" || !Array.isArray(body.actions) || body.actions.length === 0) {
+          return;
+        }
+        const action = body.actions[0];
+        if (action?.type !== "feedback_buttons") {
+          return;
+        }
+        const value = String(action.value ?? "");
+        const verdict = value === positiveValue ? "positive" : value === negativeValue ? "negative" : void 0;
+        if (!verdict) {
+          return;
+        }
+        const channelId = body.channel?.id ?? body.container?.channel_id;
+        const userId = body.user?.id;
+        const messageTs = body.message?.ts ?? body.container?.message_ts;
+        const threadTs = body.message?.thread_ts ?? body.container?.thread_ts;
+        const triggerId = typeof body.trigger_id === "string" ? body.trigger_id : void 0;
+        if (!channelId || !userId || !messageTs) {
+          return;
+        }
+        const openModal = async (view) => {
+          if (!triggerId) {
+            throw new Error(
+              "Slack feedback payload did not include trigger_id."
+            );
+          }
+          if (typeof client.views?.open !== "function") {
+            throw new Error("Slack client does not expose views.open.");
+          }
+          await client.views.open({
+            trigger_id: triggerId,
+            view
+          });
+        };
+        const acknowledgeEphemeral = async (text) => {
+          await client.chat.postEphemeral({
+            channel: channelId,
+            user: userId,
+            ...threadTs ? { thread_ts: threadTs } : { thread_ts: messageTs },
+            text
+          });
+        };
+        const feedbackContext = {
+          verdict,
+          value,
+          channelId,
+          userId,
+          messageTs,
+          ...threadTs ? { threadTs } : {},
+          ...triggerId ? { triggerId } : {}
+        };
+        const sessionId = options.resolveSessionId?.(feedbackContext);
+        await options.onFeedback({
+          ...feedbackContext,
+          ...sessionId ? { sessionId } : {},
+          openModal,
+          acknowledgeEphemeral
+        });
+        const ackText = verdict === "positive" ? positiveAck : negativeAck;
+        if (ackText) {
+          await acknowledgeEphemeral(ackText);
+        }
+      } catch (error) {
+        logger?.error?.(
+          `[channel-slack] feedback handler failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  );
+  return { actionId, positiveValue, negativeValue };
+}
+export {
+  SLACK_FEEDBACK_ACTION_ID,
+  createSlackFeedbackBlock,
+  registerSlackFeedbackAction
+};

package/dist/history.d.ts

@@ -0,0 +1,266 @@
+import { S as SlackActivityInfo } from './activity-ByrD9Ftr.js';
+import { ConversationsHistoryResponse, ConversationsRepliesResponse, WebClient } from '@slack/web-api';
+import { L as Logger } from './logging-Bl3HfcC8.js';
+
+interface SlackContextFragmentPayload {
+    content: string;
+    budgetBehavior?: string;
+    dedupeKey?: string;
+    kind?: string;
+    lifetime?: string;
+    maxChars?: number;
+    metadata?: Record<string, unknown>;
+    placement?: string;
+    role?: string;
+    source?: string;
+    title?: string;
+}
+
+type HistoryMessageElement = NonNullable<ConversationsHistoryResponse["messages"]>[number];
+type RepliesMessageElement = NonNullable<ConversationsRepliesResponse["messages"]>[number];
+type SlackApiMessageElement = HistoryMessageElement | RepliesMessageElement;
+type SlackConversationsClient = Pick<WebClient["conversations"], "history" | "replies">;
+type SlackHistoryReaderClient = WebClient | SlackConversationsClient;
+type SlackHistoryMessageRole = "user" | "assistant" | "bot" | "system" | "unknown";
+interface SlackHistoryMessage {
+    channelId: string;
+    ts: string;
+    threadTs?: string;
+    userId?: string;
+    botId?: string;
+    appId?: string;
+    subtype?: string;
+    text: string;
+    role: SlackHistoryMessageRole;
+    isBot: boolean;
+    raw: SlackApiMessageElement;
+}
+interface SlackHistoryPage {
+    messages: SlackHistoryMessage[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+type SlackHistoryAuthorFormatter = (message: SlackHistoryMessage) => string | undefined;
+type SlackHistoryContextSource = "thread" | "channel" | "origin-channel";
+interface SlackHistoryAuthorResolverContext {
+    source: SlackHistoryContextSource;
+    channelId: string;
+    teamId?: string;
+}
+type SlackHistoryAuthorResolver = (message: SlackHistoryMessage, context: SlackHistoryAuthorResolverContext) => string | undefined | Promise<string | undefined>;
+interface BaseReadSlackHistoryOptions {
+    client: SlackHistoryReaderClient;
+    channelId: string;
+    /**
+     * Optional token override. Useful when the caller must choose between bot
+     * and user tokens for a specific Slack API call.
+     */
+    token?: string;
+    /**
+     * Current app's bot user id. When provided, messages from this user are
+     * classified as `assistant` instead of generic `bot`.
+     */
+    botUserId?: string;
+    /** Number of messages to request. Defaults to Slack's stricter modern page size. */
+    limit?: number;
+    cursor?: string;
+    includeAllMetadata?: boolean;
+}
+interface ReadSlackThreadHistoryOptions extends BaseReadSlackHistoryOptions {
+    threadTs: string;
+    oldest?: string;
+    latest?: string;
+    inclusive?: boolean;
+}
+interface ReadSlackChannelHistoryOptions extends BaseReadSlackHistoryOptions {
+    oldest?: string;
+    latest?: string;
+    inclusive?: boolean;
+    /** Reverse Slack's newest-first channel history response into chronological order. @default true */
+    oldestFirst?: boolean;
+}
+interface FormatSlackHistoryForPromptOptions {
+    header?: string | false;
+    maxMessages?: number;
+    maxCharacters?: number;
+    includeTimestamps?: boolean;
+    roleLabels?: Partial<Record<SlackHistoryMessageRole, string>>;
+    /**
+     * Override the author label for a message. Return `undefined` to use the
+     * role label fallback (`User`, `Assistant`, etc.).
+     */
+    formatAuthor?: SlackHistoryAuthorFormatter;
+}
+declare function readSlackThreadHistory(options: ReadSlackThreadHistoryOptions): Promise<SlackHistoryPage>;
+declare function readSlackChannelHistory(options: ReadSlackChannelHistoryOptions): Promise<SlackHistoryPage>;
+declare function formatSlackHistoryForPrompt(messages: readonly SlackHistoryMessage[], options?: FormatSlackHistoryForPromptOptions): string;
+
+type SlackSupplementalHistoryVisibilityMode = "all" | "current-user-plus-assistant" | "original-user-plus-assistant" | "allowed-users-plus-assistant";
+interface SlackSupplementalHistoryVisibilityContext {
+    activity: SlackActivityInfo;
+    botUserId?: string;
+    channelId: string;
+    source: SlackHistoryContextSource;
+    teamId?: string;
+}
+interface SlackSupplementalHistoryVisibilityDecision {
+    messages: SlackHistoryMessage[];
+    mode?: SlackSupplementalHistoryVisibilityMode | "custom" | "error";
+    omittedCount: number;
+    source: SlackHistoryContextSource;
+}
+interface SlackSupplementalHistoryVisibilityPolicy {
+    filter(messages: readonly SlackHistoryMessage[], context: SlackSupplementalHistoryVisibilityContext): Promise<SlackSupplementalHistoryVisibilityDecision>;
+}
+interface CreateSlackSupplementalHistoryVisibilityPolicyOptions {
+    /**
+     * Controls which Slack history messages can become model-visible prompt
+     * context. `all` preserves existing behavior.
+     *
+     * @default "all"
+     */
+    mode?: SlackSupplementalHistoryVisibilityMode;
+    /**
+     * User IDs allowed when `mode` is `allowed-users-plus-assistant`.
+     */
+    allowedUserIds?: Iterable<string>;
+}
+declare function createSlackSupplementalHistoryVisibilityPolicy({ allowedUserIds, mode, }?: CreateSlackSupplementalHistoryVisibilityPolicyOptions): SlackSupplementalHistoryVisibilityPolicy;
+
+interface SlackHistoryUnavailable {
+    source: "thread" | "channel" | "origin-channel";
+    method: "conversations.replies" | "conversations.history";
+    channelId: string;
+    errorCode?: string;
+    expected: boolean;
+    hint?: string;
+    message: string;
+}
+interface LoadSlackTurnHistoryContextOptions {
+    client: SlackHistoryReaderClient;
+    activity: SlackActivityInfo;
+    /**
+     * Current app's bot user id. Messages from this user are labeled Assistant.
+     */
+    botUserId?: string;
+    /**
+     * Optional token override for Slack Web API calls.
+     */
+    token?: string;
+    /**
+     * Number of Slack messages to request per history API call.
+     *
+     * @default 15
+     */
+    limit?: number;
+    /**
+     * Maximum formatted prompt characters.
+     *
+     * @default 12000
+     */
+    maxCharacters?: number;
+    /**
+     * Optional source channel to include when the active thread is in a different
+     * channel, such as a routed incident channel.
+     */
+    originChannelId?: string;
+    /**
+     * Request-level Slack team/workspace ID used for author resolution. Defaults
+     * to `activity.teamId`.
+     */
+    teamId?: string;
+    /**
+     * Read channel history as a fallback when there is no usable thread history.
+     *
+     * @default true
+     */
+    includeTopLevelChannelFallback?: boolean;
+    headers?: {
+        thread?: string | false;
+        channel?: string | false;
+        originChannel?: string | false;
+    };
+    /**
+     * Optional author-label resolver for history messages. Use this to turn
+     * Slack user IDs into model-visible labels such as `Rosa Rodriguez (U123)`.
+     * Failed or empty resolutions fall back to the default role labels.
+     */
+    resolveAuthor?: SlackHistoryAuthorResolver;
+    /** Called when `resolveAuthor` throws. Does not include message text/raw payload. */
+    onResolveAuthorError?: (context: SlackHistoryAuthorResolutionErrorContext) => void;
+    /**
+     * Slack assistant surfaces can return the root user message as if it were
+     * authored by the assistant. When set, the first assistant-authored thread
+     * history item is corrected to this request user unless it looks like an
+     * assistant greeting. Rendered author labels still come from `resolveAuthor`.
+     */
+    assistantSurfaceThreadRootUser?: SlackAssistantSurfaceThreadRootNormalization;
+    /** Called when assistant-surface thread root history is corrected. */
+    onAssistantSurfaceThreadRootNormalized?: (context: SlackAssistantSurfaceThreadRootNormalizationContext) => void;
+    /**
+     * Optional policy that filters fetched Slack history before it becomes
+     * model-visible supplemental context.
+     */
+    visibilityPolicy?: SlackSupplementalHistoryVisibilityPolicy;
+    /** Called when the visibility policy throws. The affected source is omitted. */
+    onVisibilityPolicyError?: (context: SlackSupplementalHistoryVisibilityErrorContext) => void;
+}
+interface SlackHistoryAuthorResolutionErrorContext extends SlackHistoryAuthorResolverContext {
+    userId?: string;
+    error: unknown;
+}
+interface SlackAssistantSurfaceThreadRootNormalization {
+    userId: string;
+}
+interface SlackAssistantSurfaceThreadRootNormalizationContext {
+    action: "corrected-author" | "removed-duplicate";
+    channelId: string;
+    teamId?: string;
+    threadTs: string;
+    userId: string;
+}
+interface SlackSupplementalHistoryVisibilityErrorContext {
+    channelId: string;
+    error: unknown;
+    source: SlackHistoryContextSource;
+    teamId?: string;
+}
+interface SlackTurnHistoryContextResult {
+    prompt?: string;
+    fragment?: SlackContextFragmentPayload;
+    threadMessageCount: number;
+    topLevelChannelMessageCount: number;
+    originChannelMessageCount: number;
+    threadVisibilityOmittedMessageCount: number;
+    topLevelChannelVisibilityOmittedMessageCount: number;
+    originChannelVisibilityOmittedMessageCount: number;
+    visibilityOmittedMessageCount: number;
+    visibility: SlackSupplementalHistoryVisibilityDecision[];
+    unavailable: SlackHistoryUnavailable[];
+}
+
+declare function loadSlackTurnHistoryContext(options: LoadSlackTurnHistoryContextOptions): Promise<SlackTurnHistoryContextResult>;
+
+interface SlackSessionTranscriptInspector {
+    hasConversationMessages(sessionId: string): Promise<boolean>;
+}
+interface SlackSupplementalHistoryPolicyRequest {
+    slackActivity: Pick<SlackActivityInfo, "channelId" | "channelType" | "teamId" | "threadTs">;
+    sessionId?: string;
+}
+type SlackSupplementalHistoryInclusionReason = "shared-slack-surface" | "first-direct-session-turn" | "session-transcript-covers-direct-turn";
+type SlackSupplementalHistoryInclusionSource = "shared-surface" | "session-transcript" | "process-memory";
+interface SlackSupplementalHistoryInclusionDecision {
+    include: boolean;
+    reason: SlackSupplementalHistoryInclusionReason;
+    source: SlackSupplementalHistoryInclusionSource;
+}
+interface SlackSupplementalHistoryPolicy {
+    decide(request: SlackSupplementalHistoryPolicyRequest): Promise<SlackSupplementalHistoryInclusionDecision>;
+}
+declare function createSlackSupplementalHistoryPolicy({ logger, sessionTranscript, }?: {
+    logger?: Logger;
+    sessionTranscript?: SlackSessionTranscriptInspector;
+}): SlackSupplementalHistoryPolicy;
+
+export { type CreateSlackSupplementalHistoryVisibilityPolicyOptions, type FormatSlackHistoryForPromptOptions, type LoadSlackTurnHistoryContextOptions, type ReadSlackChannelHistoryOptions, type ReadSlackThreadHistoryOptions, type SlackAssistantSurfaceThreadRootNormalization, type SlackAssistantSurfaceThreadRootNormalizationContext, type SlackHistoryAuthorFormatter, type SlackHistoryAuthorResolutionErrorContext, type SlackHistoryAuthorResolver, type SlackHistoryAuthorResolverContext, type SlackHistoryContextSource, type SlackHistoryMessage, type SlackHistoryMessageRole, type SlackHistoryPage, type SlackHistoryReaderClient, type SlackHistoryUnavailable, type SlackSessionTranscriptInspector, type SlackSupplementalHistoryInclusionDecision, type SlackSupplementalHistoryInclusionReason, type SlackSupplementalHistoryInclusionSource, type SlackSupplementalHistoryPolicy, type SlackSupplementalHistoryPolicyRequest, type SlackSupplementalHistoryVisibilityContext, type SlackSupplementalHistoryVisibilityDecision, type SlackSupplementalHistoryVisibilityErrorContext, type SlackSupplementalHistoryVisibilityMode, type SlackSupplementalHistoryVisibilityPolicy, type SlackTurnHistoryContextResult, createSlackSupplementalHistoryPolicy, createSlackSupplementalHistoryVisibilityPolicy, formatSlackHistoryForPrompt, loadSlackTurnHistoryContext, readSlackChannelHistory, readSlackThreadHistory };