@cuylabs/channel-slack 0.1.0

package/dist/users.js

@@ -0,0 +1,240 @@
+// src/users/profile.ts
+var DEFAULT_MAX_ENTRIES = 5e3;
+var DEFAULT_TTL_MS = 30 * 60 * 1e3;
+var DEFAULT_ERROR_TTL_MS = 5 * 60 * 1e3;
+function createSlackUserProfileResolver(options = {}) {
+  const cache = /* @__PURE__ */ new Map();
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const errorTtlMs = options.errorTtlMs ?? Math.min(ttlMs, DEFAULT_ERROR_TTL_MS);
+  function cacheProfile(key, profile, entryTtlMs) {
+    if (!key || entryTtlMs <= 0 || !Number.isFinite(entryTtlMs)) {
+      return;
+    }
+    cache.set(key, {
+      expiresAt: Date.now() + entryTtlMs,
+      profile
+    });
+    trimCache(cache, maxEntries);
+  }
+  return {
+    async resolve(input) {
+      const fallback = { userId: input.userId };
+      const key = input.teamId ? `${input.teamId}:${input.userId}` : void 0;
+      const cached = key ? cache.get(key) : void 0;
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.profile;
+      }
+      if (cached && key) {
+        cache.delete(key);
+      }
+      const botToken = input.botToken ?? options.botToken;
+      if (!botToken && !options.client) {
+        return fallback;
+      }
+      try {
+        const client = await resolveClient(options, botToken);
+        const response = await client.users.info({
+          user: input.userId,
+          ...botToken ? { token: botToken } : {}
+        });
+        const profile = normalizeSlackUserProfile(input.userId, response);
+        cacheProfile(key, profile, ttlMs);
+        return profile;
+      } catch (error) {
+        options.onLookupError?.({ ...input, error });
+        cacheProfile(key, fallback, errorTtlMs);
+        return fallback;
+      }
+    },
+    clear() {
+      cache.clear();
+    }
+  };
+}
+async function resolveClient(options, botToken) {
+  if (options.client) {
+    return options.client;
+  }
+  if (options.clientFactory && botToken) {
+    return options.clientFactory(botToken);
+  }
+  const { WebClient } = await import("@slack/web-api");
+  return new WebClient(botToken);
+}
+function normalizeSlackUserProfile(userId, response) {
+  const user = readRecord(readRecord(response)?.user);
+  const profile = readRecord(user?.profile);
+  const displayName = readString(profile?.display_name_normalized) ?? readString(profile?.display_name) ?? readString(profile?.real_name_normalized) ?? readString(profile?.real_name) ?? readString(user?.real_name) ?? readString(user?.name);
+  const realName = readString(profile?.real_name_normalized) ?? readString(profile?.real_name) ?? readString(user?.real_name);
+  const email = readString(profile?.email) ?? readString(user?.email);
+  return {
+    userId,
+    ...displayName ? { displayName } : {},
+    ...realName ? { realName } : {},
+    ...email ? { email } : {}
+  };
+}
+function trimCache(cache, maxEntries) {
+  if (!Number.isFinite(maxEntries) || maxEntries <= 0) {
+    cache.clear();
+    return;
+  }
+  while (cache.size > maxEntries) {
+    const firstKey = cache.keys().next().value;
+    if (firstKey === void 0) {
+      return;
+    }
+    cache.delete(firstKey);
+  }
+}
+function readRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function readString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+
+// src/users/mentions.ts
+var SLACK_USER_MENTION_PATTERN = /<@([A-Z0-9]+)(?:\|[^>]+)?>/gi;
+var DEFAULT_MAX_LOOKUPS = 20;
+var DEFAULT_CONCURRENCY = 4;
+async function enrichSlackUserMentions(input, options = {}) {
+  const request = typeof input === "string" ? { text: input } : input;
+  const text = request.text;
+  const teamId = request.teamId;
+  const botToken = request.botToken ?? options.botToken;
+  const mentions = collectUniqueUserMentions(text);
+  if (mentions.length === 0) {
+    return emptyResult(text);
+  }
+  const maxLookups = resolveNonNegativeInteger(
+    options.maxLookups,
+    DEFAULT_MAX_LOOKUPS
+  );
+  const concurrency = resolvePositiveInteger(
+    options.concurrency,
+    DEFAULT_CONCURRENCY
+  );
+  const lookups = mentions.slice(0, maxLookups);
+  const skippedUserIds = mentions.slice(maxLookups).map((entry) => entry.userId);
+  const profileResolver = options.profileResolver ?? createSlackUserProfileResolver(options);
+  const labelByUserId = /* @__PURE__ */ new Map();
+  const unresolvedUserIds = /* @__PURE__ */ new Set();
+  await mapWithConcurrency(lookups, concurrency, async (lookup) => {
+    try {
+      const profile = await profileResolver.resolve({
+        userId: lookup.userId,
+        ...teamId ? { teamId } : {},
+        ...botToken ? { botToken } : {}
+      });
+      const label = normalizeLabel(
+        (options.formatLabel ?? defaultMentionLabel)({
+          userId: lookup.userId,
+          mention: lookup.mention,
+          profile
+        })
+      );
+      if (label) {
+        labelByUserId.set(lookup.userId, label);
+      } else {
+        unresolvedUserIds.add(lookup.userId);
+      }
+    } catch (error) {
+      options.onResolveError?.({
+        userId: lookup.userId,
+        ...teamId ? { teamId } : {},
+        error
+      });
+      unresolvedUserIds.add(lookup.userId);
+    }
+  });
+  const lookedUpUserIds = lookups.map((entry) => entry.userId);
+  return {
+    text: replaceUserMentions(text, labelByUserId),
+    lookedUpUserIds,
+    enrichedUserIds: lookedUpUserIds.filter(
+      (userId) => labelByUserId.has(userId)
+    ),
+    unresolvedUserIds: lookedUpUserIds.filter(
+      (userId) => unresolvedUserIds.has(userId)
+    ),
+    skippedUserIds
+  };
+}
+function collectUniqueUserMentions(text) {
+  const seen = /* @__PURE__ */ new Set();
+  const mentions = [];
+  SLACK_USER_MENTION_PATTERN.lastIndex = 0;
+  for (const match of text.matchAll(SLACK_USER_MENTION_PATTERN)) {
+    const rawUserId = match[1];
+    if (!rawUserId) {
+      continue;
+    }
+    const userId = rawUserId.toUpperCase();
+    if (seen.has(userId)) {
+      continue;
+    }
+    seen.add(userId);
+    mentions.push({
+      userId,
+      mention: `<@${userId}>`
+    });
+  }
+  return mentions;
+}
+function replaceUserMentions(text, labelByUserId) {
+  if (labelByUserId.size === 0) {
+    return text;
+  }
+  SLACK_USER_MENTION_PATTERN.lastIndex = 0;
+  return text.replace(
+    SLACK_USER_MENTION_PATTERN,
+    (mention, rawUserId) => labelByUserId.get(rawUserId.toUpperCase()) ?? mention
+  );
+}
+function defaultMentionLabel(context) {
+  const displayName = normalizeLabel(
+    context.profile.displayName ?? context.profile.realName
+  );
+  return displayName ? `${context.mention} (${displayName})` : void 0;
+}
+function normalizeLabel(value) {
+  const trimmed = value?.trim();
+  return trimmed || void 0;
+}
+function emptyResult(text) {
+  return {
+    text,
+    lookedUpUserIds: [],
+    enrichedUserIds: [],
+    unresolvedUserIds: [],
+    skippedUserIds: []
+  };
+}
+function resolveNonNegativeInteger(value, fallback) {
+  return value !== void 0 && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+function resolvePositiveInteger(value, fallback) {
+  return value !== void 0 && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+async function mapWithConcurrency(values, concurrency, run) {
+  if (values.length === 0) {
+    return;
+  }
+  let nextIndex = 0;
+  const workerCount = Math.min(concurrency, values.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextIndex < values.length) {
+        const index = nextIndex;
+        nextIndex += 1;
+        await run(values[index]);
+      }
+    })
+  );
+}
+export {
+  createSlackUserProfileResolver,
+  enrichSlackUserMentions
+};

package/docs/concepts/activity.md

@@ -0,0 +1,33 @@
+# Activity
+
+An activity is the normalized message shape an agent adapter receives from
+Slack. It is intentionally smaller than a raw Slack event and does not depend on
+Bolt.
+
+```typescript
+import { parseSlackMentionActivity } from "@cuylabs/channel-slack/core";
+
+const activity = parseSlackMentionActivity(event);
+```
+
+`SlackActivityInfo` contains:
+
+- `channelId`: Slack channel, DM, group, or thread surface ID.
+- `channelType`: normalized surface type such as `dm`, `channel`, `group`, or
+  `thread`.
+- `userId`: author of the message.
+- `teamId`: workspace ID when Slack provided one.
+- `threadTs`: parent thread timestamp for threaded replies.
+- `messageTs`: timestamp of the inbound message.
+- `parentUserId`: Slack's parent-thread user marker when present.
+- `actionToken`: request-bound Slack Assistant action token when present.
+- `text`: model-facing text with leading mentions stripped where appropriate.
+- `isMention`: whether this was an app mention event.
+
+The parser extracts text from plain text, rich text blocks, section/header/
+context blocks, image or video alt/title text, and legacy attachments. This lets
+agent adapters process the visible Slack message instead of only `event.text`.
+
+Use `isProcessableMessage` before parsing passive `message` events. It filters
+bot messages, message edits, deletions, reply fan-out events, and events without
+an identifiable user.

package/docs/concepts/bolt-runtime.md

@@ -0,0 +1,30 @@
+# Bolt Runtime
+
+The Bolt helpers create Slack transports and auth wiring. They deliberately do
+not register handlers, own prompts, run agents, or choose deployment policy.
+
+## HTTP
+
+`createSlackBoltApp` creates a Bolt `App`, `ExpressReceiver`, and Express app
+for Events API and interactivity requests.
+
+Supported auth modes:
+
+- single-workspace bot token.
+- Bolt-managed OAuth with an installation store.
+- custom `authorize` function for externally managed installs.
+
+## Socket Mode
+
+`createSlackSocketBoltApp` creates a Socket Mode Bolt app from the same auth
+shape plus `SLACK_APP_TOKEN`.
+
+`createSlackSocketModeRuntime` returns receiver options and a Slack SDK logger
+that can:
+
+- acquire a process lock for single-instance Socket Mode deployments.
+- tune ping/pong receiver settings.
+- redact sensitive log fields.
+- optionally trip a restart guard after repeated websocket health warnings.
+
+Use `runtime.close()` during shutdown so a process lock is released.

package/docs/concepts/message-policy.md

@@ -0,0 +1,49 @@
+# Message Policy
+
+Message policy decides whether a parsed Slack activity should become an agent
+turn. It is separate from parsing so products can choose their own behavior
+without duplicating Slack event mechanics.
+
+```typescript
+import { createSlackMessagePolicyResolver } from "@cuylabs/channel-slack/policy";
+
+const policy = createSlackMessagePolicyResolver({
+  messagePolicy: "mentioned-threads",
+  threadReplyPolicy: "original-user",
+});
+
+const decision = policy.resolve(activity);
+if (!decision.accepted) return;
+```
+
+## Channel Message Policy
+
+`messagePolicy` controls passive channel messages:
+
+- `disabled`: accept DMs and direct mentions only.
+- `mentioned-threads`: accept replies in threads where the bot was mentioned.
+- `allowed-channels`: accept passive messages only from configured channel IDs.
+- `any-added-channel`: accept passive messages anywhere the app is present.
+
+DMs and direct mentions are always accepted unless they are duplicates.
+
+## Thread Reply Policy
+
+`threadReplyPolicy` controls non-mentioned replies inside remembered mentioned
+threads:
+
+- `mention-required`: require another direct mention.
+- `original-user`: allow only the original thread user.
+- `anyone`: allow any user in the thread.
+
+## State
+
+The resolver tracks two state sets:
+
+- mentioned thread keys for continuation policy.
+- accepted message keys for duplicate suppression.
+
+The in-memory store is enough for single-process development. Production
+multi-worker deployments should pass an async durable store to
+`createAsyncSlackMessagePolicyResolver` and implement `claimAcceptedMessage` as
+an insert-if-absent operation.

package/docs/concepts/setup-requirements.md

@@ -0,0 +1,44 @@
+# Setup Requirements
+
+Setup helpers translate package features into the Slack app configuration they
+require.
+
+```typescript
+import { getSlackSetupRequirements } from "@cuylabs/channel-slack/setup";
+
+const requirements = getSlackSetupRequirements({
+  preset: "agent-app",
+  transport: "socket",
+});
+```
+
+## Presets
+
+- `assistant`: Slack Assistant surface and feedback controls.
+- `channel-adapter`: app mentions and direct messages.
+- `agent-app`: Assistant, app mentions, direct messages, and feedback.
+
+Pass `preset: false` and provide `features` when an app needs exact control.
+
+## Features
+
+Feature selections produce:
+
+- required bot scopes.
+- optional bot scopes.
+- app-level token scopes for Socket Mode.
+- bot events.
+- Slack settings such as Assistant view, event subscriptions, interactivity, and
+  Socket Mode.
+- environment variables needed by the chosen transport.
+
+## Manifests
+
+`createSlackAppManifest` produces a Slack app manifest from the same
+requirements. `compareSlackAppManifest` checks an existing manifest-like object
+against requirements and returns path-level findings.
+
+## Inspection
+
+`inspectSlackAppSetup` combines requirements with a live token inspection. It
+does not mutate Slack configuration.

package/docs/concepts/supplemental-history.md

@@ -0,0 +1,55 @@
+# Supplemental History
+
+Supplemental history loads Slack conversation context for a single agent turn.
+The package does not decide whether your model should use this context. It
+returns a prompt string and a context-fragment payload that host runtimes can
+place into their own turn model.
+
+```typescript
+import {
+  createSlackSupplementalHistoryVisibilityPolicy,
+  loadSlackTurnHistoryContext,
+} from "@cuylabs/channel-slack/history";
+
+const history = await loadSlackTurnHistoryContext({
+  client,
+  activity,
+  botUserId,
+  visibilityPolicy: createSlackSupplementalHistoryVisibilityPolicy({
+    mode: "current-user-plus-assistant",
+  }),
+});
+```
+
+## Sources
+
+The loader can include three sources:
+
+- `thread`: messages from the current Slack thread.
+- `channel`: recent messages from the current channel when thread history is not
+  usable.
+- `origin-channel`: recent messages from a different source channel, useful for
+  routed workflows such as incident channels.
+
+Thread history is preferred. Top-level channel history is a fallback when no
+usable thread history exists unless `includeTopLevelChannelFallback` is false.
+
+## Visibility
+
+Visibility policy filters fetched messages before they become model-visible.
+Built-in modes are:
+
+- `all`
+- `current-user-plus-assistant`
+- `original-user-plus-assistant`
+- `allowed-users-plus-assistant`
+
+Custom policies can implement the same `filter(messages, context)` interface.
+If a visibility policy throws, that source is omitted and reported as an error
+decision.
+
+## Unavailable History
+
+Slack often rejects history reads because the app is missing a scope, not in a
+channel, or blocked from the conversation. These expected failures are returned
+in `unavailable` with hints instead of throwing from the top-level loader.

package/docs/recipes/app-mention-handler.md

@@ -0,0 +1,34 @@
+# App Mention Handler
+
+This recipe shows the package boundary. The agent call is intentionally left to
+the host application.
+
+```typescript
+import {
+  markdownToSlackMrkdwn,
+  parseSlackMentionActivity,
+} from "@cuylabs/channel-slack/core";
+import { createSlackMessagePolicyResolver } from "@cuylabs/channel-slack/policy";
+
+const policy = createSlackMessagePolicyResolver({
+  messagePolicy: "mentioned-threads",
+  threadReplyPolicy: "original-user",
+});
+
+app.event("app_mention", async ({ event, client }) => {
+  const activity = parseSlackMentionActivity(event);
+  const decision = policy.resolve(activity);
+  if (!decision.accepted) return;
+
+  const answer = await runAgent({
+    input: decision.text,
+    slack: activity,
+  });
+
+  await client.chat.postMessage({
+    channel: activity.channelId,
+    thread_ts: activity.threadTs ?? activity.messageTs,
+    text: markdownToSlackMrkdwn(answer),
+  });
+});
+```

package/docs/recipes/assistant-thread-handler.md

@@ -0,0 +1,28 @@
+# Assistant Thread Handler
+
+Bolt assistant handlers deliver a broad message shape. Use the Assistant parser
+to normalize only parseable user messages.
+
+```typescript
+import { parseSlackMessageActivityFromMessageEvent } from "@cuylabs/channel-slack/assistant";
+import { markdownToSlackMrkdwn } from "@cuylabs/channel-slack/core";
+
+assistant.userMessage(async ({ client, message, say }) => {
+  const activity = parseSlackMessageActivityFromMessageEvent(message);
+  if (!activity) return;
+
+  const answer = await runAgent({
+    input: activity.text,
+    slack: activity,
+  });
+
+  await say({
+    text: markdownToSlackMrkdwn(answer),
+    thread_ts: activity.threadTs,
+  });
+});
+```
+
+When using Bolt Assistant thread context, pass
+`createSlackAssistantThreadContextStore()` to avoid a process-local context
+cache that is not keyed by thread.

package/docs/recipes/generate-slack-manifest.md

@@ -0,0 +1,28 @@
+# Generate A Slack Manifest
+
+```typescript
+import { createSlackAppManifest } from "@cuylabs/channel-slack/setup";
+
+const manifest = createSlackAppManifest({
+  name: "My Agent",
+  description: "Agent-backed Slack assistant",
+  preset: "agent-app",
+  transport: "socket",
+  assistantDescription: "Ask the agent for help with workspace tasks.",
+});
+
+console.log(JSON.stringify(manifest, null, 2));
+```
+
+For HTTP transport, pass `baseUrl` so event and interactivity request URLs are
+included:
+
+```typescript
+const manifest = createSlackAppManifest({
+  name: "My Agent",
+  preset: "agent-app",
+  transport: "http",
+  baseUrl: "https://agent.example.com",
+  eventsPath: "/slack/events",
+});
+```

package/docs/recipes/history-visibility.md

@@ -0,0 +1,36 @@
+# History Visibility Filter
+
+Use visibility filters when Slack history is useful but should not expose every
+participant's prior messages to the model.
+
+```typescript
+import {
+  createSlackSupplementalHistoryVisibilityPolicy,
+  loadSlackTurnHistoryContext,
+} from "@cuylabs/channel-slack/history";
+
+const visibilityPolicy = createSlackSupplementalHistoryVisibilityPolicy({
+  mode: "current-user-plus-assistant",
+});
+
+const history = await loadSlackTurnHistoryContext({
+  client,
+  activity,
+  botUserId,
+  visibilityPolicy,
+});
+
+const fragments = history.fragment ? [history.fragment] : [];
+```
+
+For allow-list behavior:
+
+```typescript
+const visibilityPolicy = createSlackSupplementalHistoryVisibilityPolicy({
+  mode: "allowed-users-plus-assistant",
+  allowedUserIds: ["U123", "U456"],
+});
+```
+
+The result reports omitted counts per source and overall so callers can audit
+what happened without logging message text.

package/docs/recipes/socket-mode-app.md

@@ -0,0 +1,29 @@
+# Socket Mode App
+
+```typescript
+import {
+  createSlackSocketBoltApp,
+  createSlackSocketModeRuntime,
+} from "@cuylabs/channel-slack/bolt";
+
+const runtime = createSlackSocketModeRuntime({
+  appSlug: "my-agent",
+  appToken: process.env.SLACK_APP_TOKEN,
+  restartGuardEnabled: true,
+});
+
+const { boltApp } = await createSlackSocketBoltApp({
+  appToken: process.env.SLACK_APP_TOKEN,
+  botToken: process.env.SLACK_BOT_TOKEN,
+  boltAppOptions: runtime.boltAppOptions,
+  socketModeReceiverOptions: runtime.socketModeReceiverOptions,
+});
+
+process.on("SIGTERM", () => {
+  runtime.close();
+});
+
+await boltApp.start();
+```
+
+Socket Mode requires an app-level token with `connections:write`.

package/docs/reference/channel-slack-boundary.md

@@ -0,0 +1,50 @@
+# Channel Slack Boundary
+
+`@cuylabs/channel-slack` is the SDK-neutral Slack mechanics package. It parses
+Slack events, formats Slack output, applies reusable admission and history
+policies, and provides Slack setup/runtime helpers. It does not create or run an
+agent.
+
+`@cuylabs/channel-slack-agent-core` is the `@cuylabs/agent-core` binding. It
+composes this package with agent-core scopes, event streams, context fragments,
+and approval or human-input contracts.
+
+## In This Package
+
+- Slack activity parsing and text extraction.
+- Markdown-to-Slack formatting.
+- Thread-aware session helpers.
+- Slack auth and installation store helpers.
+- Socket Mode runtime guard and process lock.
+- Setup requirements and manifest helpers.
+- Diagnostics.
+- User profile and mention helpers.
+- Target parsing and resolution.
+- Feedback blocks and action handler.
+- Slack message policy resolver and state store.
+- Supplemental history reader, context loader, and visibility policy.
+- Assistant message parser and thread-context store.
+
+## Outside This Package
+
+- Agent runtime execution.
+- Agent-runtime scopes and context-fragment middleware.
+- Agent event stream rendering.
+- Agent-specific approval and human-input request contracts.
+- Product prompts, tools, audit policy, and deployment policy.
+
+Those pieces belong in runtime-specific adapters or product applications.
+
+## Behavior Notes
+
+- The root export is lightweight: `core`, `policy`, and `Logger`.
+- Peer-backed helpers live behind feature subpaths such as `bolt`, `history`,
+  `setup`, `diagnostics`, and `users`.
+- Interactive request types are generic rather than derived from any
+  agent-runtime event type.
+- Socket Mode logging uses this package's logger bridge rather than an agent
+  runtime logger.
+
+One migration caveat: the default Socket Mode process-lock directory is
+`${tmpdir}/channel-slack`. Runtime-specific adapters that need continuity with
+an older local lock path should pass an explicit `lockDir`.