@cuylabs/channel-slack 0.4.0 → 0.5.1

package/dist/policy.js

@@ -1,16 +1,22 @@
 import {
   createAsyncSlackMessagePolicyResolver,
   createInMemorySlackMessagePolicyStateStore,
+  createPostgresSlackMessagePolicyStateStore,
   createSlackMessagePolicyMessageKey,
   createSlackMessagePolicyResolver,
   createSlackMessagePolicyThreadKey,
+  initializePostgresSlackMessagePolicyState,
+  prunePostgresSlackMessagePolicyState,
   shouldRegisterSlackPassiveChannelMessages
-} from "./chunk-BODPT4I6.js";
+} from "./chunk-CMR6B76C.js";
 export {
   createAsyncSlackMessagePolicyResolver,
   createInMemorySlackMessagePolicyStateStore,
+  createPostgresSlackMessagePolicyStateStore,
   createSlackMessagePolicyMessageKey,
   createSlackMessagePolicyResolver,
   createSlackMessagePolicyThreadKey,
+  initializePostgresSlackMessagePolicyState,
+  prunePostgresSlackMessagePolicyState,
   shouldRegisterSlackPassiveChannelMessages
 };

package/dist/setup.d.ts

@@ -1,4 +1,4 @@
-import { InspectSlackConnectionOptions, SlackDiagnosticsClient, SlackConnectionInspection } from './diagnostics.js';
+import { I as InspectSlackConnectionOptions, f as SlackDiagnosticsClient, c as SlackConnectionInspection } from './inspect-BpY5JA0K.js';
 
 type SlackSetupFeature = "assistant" | "app-mentions" | "direct-messages" | "channel-messages" | "history" | "interactivity" | "feedback" | "user-profiles" | "user-emails";
 type SlackSetupFeaturePreset = "assistant" | "channel-adapter" | "agent-app";

package/dist/setup.js

@@ -1,6 +1,6 @@
 import {
   inspectSlackConnection
-} from "./chunk-FX2JOVX5.js";
+} from "./chunk-IDVDMJ5U.js";
 
 // src/setup/requirements.ts
 var DEFAULT_EVENTS_PATH = "/slack/events";

package/docs/concepts/bolt-runtime.md

@@ -28,3 +28,34 @@ that can:
 - optionally trip a restart guard after repeated websocket health warnings.
 
 Use `runtime.close()` during shutdown so a process lock is released.
+
+The runtime log reports the SDK-local process lock separately as
+`processLockConfigured` and `processLockAcquired`. These fields describe only
+the SDK file/process lock created by `createSlackSocketModeRuntime`; they do not
+describe a distributed Postgres lock acquired separately.
+
+For distributed deployments, `acquireSlackSocketModePostgresLock` can acquire a
+Postgres advisory lock before starting the Socket Mode app:
+
+```typescript
+import {
+  acquireSlackSocketModePostgresLock,
+  createSlackSocketModeRuntime,
+} from "@cuylabs/channel-slack/bolt";
+
+const postgresLock = await acquireSlackSocketModePostgresLock({
+  appSlug: "my-agent",
+  appToken: process.env.SLACK_APP_TOKEN,
+  connectionString: process.env.DATABASE_URL,
+});
+
+const runtime = createSlackSocketModeRuntime({
+  appSlug: "my-agent",
+  appToken: process.env.SLACK_APP_TOKEN,
+  lockEnabled: false,
+});
+```
+
+Use `postgresLock.release()` or `postgresLock.close()` during shutdown. Pass
+`namespace` if an existing deployment already coordinates with a specific
+advisory-lock key namespace.

package/docs/concepts/message-policy.md

@@ -16,6 +16,10 @@ const decision = policy.resolve(activity);
 if (!decision.accepted) return;
 ```
 
+`decision.reason` is intended for host-owned logs, metrics, and audit records.
+For example, a host can distinguish `bot-mentioned` from
+`mentioned-thread-reply` without the SDK choosing log levels or log shape.
+
 ## Channel Message Policy
 
 `messagePolicy` controls passive channel messages:
@@ -27,6 +31,15 @@ if (!decision.accepted) return;
 
 DMs and direct mentions are always accepted unless they are duplicates.
 
+Accepted decisions include one of these reasons:
+
+- `direct-message`: the message came from a DM.
+- `bot-mentioned`: the bot was directly mentioned.
+- `mentioned-thread-reply`: a non-mentioned reply continued a remembered
+  mentioned thread.
+- `allowed-channel`: a passive message matched `allowed-channels`.
+- `any-added-channel`: a passive message matched `any-added-channel`.
+
 ## Thread Reply Policy
 
 `threadReplyPolicy` controls non-mentioned replies inside remembered mentioned
@@ -47,3 +60,35 @@ 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.
+
+## Postgres State
+
+`createPostgresSlackMessagePolicyStateStore` provides a durable state store for
+Postgres deployments:
+
+```typescript
+import {
+  createAsyncSlackMessagePolicyResolver,
+  createPostgresSlackMessagePolicyStateStore,
+} from "@cuylabs/channel-slack/policy";
+
+const stateStore = createPostgresSlackMessagePolicyStateStore({
+  connectionString: process.env.DATABASE_URL,
+  schema: "agent_state",
+});
+
+const policy = createAsyncSlackMessagePolicyResolver({
+  messagePolicy: "mentioned-threads",
+  threadReplyPolicy: "original-user",
+  stateStore,
+});
+```
+
+The helper creates two tables by default:
+
+- `channel_slack_message_policy_threads`
+- `channel_slack_message_policy_messages`
+
+Pass `mentionedThreadsTableName` and `acceptedMessagesTableName` when migrating
+from an existing application-owned schema. Call `stateStore.close()` during
+shutdown if the store owns its `pg` pool.

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

@@ -19,6 +19,11 @@ app.event("app_mention", async ({ event, client }) => {
   const activity = parseSlackMentionActivity(event);
   const decision = policy.resolve(activity);
   if (!decision.accepted) return;
+  logger.info("Slack message accepted", {
+    channelId: activity.channelId,
+    reason: decision.reason,
+    threadTs: activity.threadTs,
+  });
 
   const answer = await runAgent({
     input: decision.text,

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

@@ -15,13 +15,13 @@ approval or human-input contracts.
 - Markdown-to-Slack formatting.
 - Thread-aware session helpers.
 - Slack auth and installation store helpers.
-- Socket Mode runtime guard and process lock.
+- Socket Mode runtime guard, process lock, and optional Postgres advisory 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.
+- Slack message policy resolver and in-memory/Postgres state stores.
 - Supplemental history reader, context loader, and visibility policy.
 - Assistant message parser and thread-context store.
 

package/docs/reference/exports.md

@@ -3,18 +3,18 @@
 Use feature subpaths for new code. They make dependency expectations clearer and
 keep application code close to the package boundary it uses.
 
-| Export | Depends on | Notes |
-| --- | --- | --- |
-| `@cuylabs/channel-slack/core` | no Slack SDK runtime imports | Transport-neutral parsing, formatting, types, sessions, turn context |
-| `@cuylabs/channel-slack/shared` | no Slack SDK runtime imports | Compatibility alias for `core` |
-| `@cuylabs/channel-slack/policy` | no Slack SDK runtime imports | Message admission and policy state |
-| `@cuylabs/channel-slack/history` | `@slack/web-api` types | History reader accepts a Slack WebClient or minimal conversations client |
-| `@cuylabs/channel-slack/bolt` | `@slack/bolt`, `express` | Bolt app factories and Socket Mode runtime helpers |
-| `@cuylabs/channel-slack/setup` | diagnostics only when inspecting live tokens | Setup requirements and app manifest helpers |
-| `@cuylabs/channel-slack/diagnostics` | `@slack/web-api` | Token, auth, and scope inspection |
-| `@cuylabs/channel-slack/users` | `@slack/web-api` when using default client | User profile lookup and mention enrichment |
-| `@cuylabs/channel-slack/targets` | no Slack SDK runtime imports unless resolving names through a client | Parse and resolve channel/user targets |
-| `@cuylabs/channel-slack/feedback` | `@slack/types` types | Feedback block and action helpers |
+| Export                               | Depends on                                                                      | Notes                                                                    |
+| ------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `@cuylabs/channel-slack/core`        | no Slack SDK runtime imports                                                    | Transport-neutral parsing, formatting, types, sessions, turn context     |
+| `@cuylabs/channel-slack/shared`      | no Slack SDK runtime imports                                                    | Compatibility alias for `core`                                           |
+| `@cuylabs/channel-slack/policy`      | `pg` only when using connection-string Postgres state                           | Message admission and in-memory/Postgres policy state                    |
+| `@cuylabs/channel-slack/history`     | `@slack/web-api` types                                                          | History reader accepts a Slack WebClient or minimal conversations client |
+| `@cuylabs/channel-slack/bolt`        | `@slack/bolt`, `express`; `pg` only when using connection-string Postgres locks | Bolt app factories and Socket Mode runtime helpers                       |
+| `@cuylabs/channel-slack/setup`       | diagnostics only when inspecting live tokens                                    | Setup requirements and app manifest helpers                              |
+| `@cuylabs/channel-slack/diagnostics` | `@slack/web-api`                                                                | Token, auth, and scope inspection                                        |
+| `@cuylabs/channel-slack/users`       | `@slack/web-api` when using default client                                      | User profile lookup and mention enrichment                               |
+| `@cuylabs/channel-slack/targets`     | no Slack SDK runtime imports unless resolving names through a client            | Parse and resolve channel/user targets                                   |
+| `@cuylabs/channel-slack/feedback`    | `@slack/types` types                                                            | Feedback block and action helpers                                        |
 
 The root export remains available for lightweight core and policy helpers:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/channel-slack",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "SDK-neutral Slack channel primitives for AI agents",
   "type": "module",
   "main": "./dist/index.js",

package/dist/chunk-BODPT4I6.js

@@ -1,322 +0,0 @@
-// src/policy/message/keys.ts
-function createSlackMessagePolicyMessageKey(activity) {
-  if (!activity.messageTs) {
-    return void 0;
-  }
-  return `${activity.teamId ?? "unknown"}:${activity.channelId}:${activity.messageTs}`;
-}
-function createSlackMessagePolicyThreadKey(activity) {
-  return `${activity.teamId ?? "unknown"}:${activity.channelId}:${activity.threadTs ?? activity.messageTs ?? "unthreaded"}`;
-}
-
-// src/policy/message/state-store.ts
-var DEFAULT_MAX_MENTIONED_THREADS = 1e4;
-var DEFAULT_MAX_ACCEPTED_MESSAGES = 1e4;
-function createInMemorySlackMessagePolicyStateStore({
-  maxAcceptedMessages = DEFAULT_MAX_ACCEPTED_MESSAGES,
-  maxMentionedThreads = DEFAULT_MAX_MENTIONED_THREADS
-} = {}) {
-  const mentionedThreads = /* @__PURE__ */ new Map();
-  const mentionedThreadOrder = [];
-  const acceptedMessageKeys = /* @__PURE__ */ new Set();
-  const acceptedMessageOrder = [];
-  function claimAcceptedMessageKey(key) {
-    if (acceptedMessageKeys.has(key)) {
-      return false;
-    }
-    acceptedMessageKeys.add(key);
-    acceptedMessageOrder.push(key);
-    trimSetByOrder(
-      acceptedMessageKeys,
-      acceptedMessageOrder,
-      maxAcceptedMessages
-    );
-    return true;
-  }
-  return {
-    getMentionedThread(key) {
-      return mentionedThreads.get(key);
-    },
-    hasAcceptedMessage(key) {
-      return acceptedMessageKeys.has(key);
-    },
-    claimAcceptedMessage(key) {
-      return claimAcceptedMessageKey(key);
-    },
-    rememberMentionedThread(key, state) {
-      if (!mentionedThreads.has(key)) {
-        mentionedThreadOrder.push(key);
-      }
-      mentionedThreads.set(key, state);
-      trimMapByOrder(
-        mentionedThreads,
-        mentionedThreadOrder,
-        maxMentionedThreads
-      );
-    },
-    rememberAcceptedMessage(key) {
-      claimAcceptedMessageKey(key);
-    }
-  };
-}
-function trimMapByOrder(map, order, maxEntries) {
-  if (!Number.isFinite(maxEntries) || maxEntries <= 0) {
-    map.clear();
-    order.length = 0;
-    return;
-  }
-  while (order.length > maxEntries) {
-    const oldest = order.shift();
-    if (oldest !== void 0) {
-      map.delete(oldest);
-    }
-  }
-}
-function trimSetByOrder(set, order, maxEntries) {
-  if (!Number.isFinite(maxEntries) || maxEntries <= 0) {
-    set.clear();
-    order.length = 0;
-    return;
-  }
-  while (order.length > maxEntries) {
-    const oldest = order.shift();
-    if (oldest !== void 0) {
-      set.delete(oldest);
-    }
-  }
-}
-
-// src/policy/message/async-resolver.ts
-function createAsyncSlackMessagePolicyResolver(config = {}) {
-  const allowedChannelIds = new Set(config.allowedChannelIds ?? []);
-  const messagePolicy = config.messagePolicy ?? "disabled";
-  const threadReplyPolicy = config.threadReplyPolicy ?? "mention-required";
-  const stateStore = config.stateStore ?? createInMemorySlackMessagePolicyStateStore({
-    maxAcceptedMessages: config.maxAcceptedMessages,
-    maxMentionedThreads: config.maxMentionedThreads
-  });
-  async function rememberMentionedThread(activity) {
-    const key = createSlackMessagePolicyThreadKey(activity);
-    const originalUserId = activity.parentUserId ?? activity.userId;
-    await stateStore.rememberMentionedThread(
-      key,
-      { originalUserId },
-      {
-        activity,
-        key
-      }
-    );
-  }
-  async function claimAcceptedMessage(activity) {
-    const key = createSlackMessagePolicyMessageKey(activity);
-    if (!key) {
-      return true;
-    }
-    const context = { activity, key };
-    if (stateStore.claimAcceptedMessage) {
-      return await stateStore.claimAcceptedMessage(key, context);
-    }
-    if (await stateStore.hasAcceptedMessage(key, context)) {
-      return false;
-    }
-    await stateStore.rememberAcceptedMessage(key, context);
-    return true;
-  }
-  async function isDuplicate(activity) {
-    const key = createSlackMessagePolicyMessageKey(activity);
-    return Boolean(
-      key && await stateStore.hasAcceptedMessage(key, { activity, key })
-    );
-  }
-  async function accept(activity, reason) {
-    if (!await claimAcceptedMessage(activity)) {
-      return reject(activity, "duplicate-message-event");
-    }
-    return {
-      accepted: true,
-      activity,
-      reason,
-      text: activity.text
-    };
-  }
-  function reject(activity, reason) {
-    return {
-      accepted: false,
-      activity,
-      reason
-    };
-  }
-  async function resolve(activity) {
-    if (activity.isMention) {
-      await rememberMentionedThread(activity);
-      return accept(activity, "bot-mentioned");
-    }
-    if (await isDuplicate(activity)) {
-      return reject(activity, "duplicate-message-event");
-    }
-    if (activity.channelType === "dm") {
-      return accept(activity, "direct-message");
-    }
-    if (messagePolicy === "disabled") {
-      return reject(activity, "passive-channel-messages-disabled");
-    }
-    if (messagePolicy === "any-added-channel") {
-      return accept(activity, "any-added-channel");
-    }
-    if (messagePolicy === "allowed-channels") {
-      return allowedChannelIds.has(activity.channelId) ? accept(activity, "allowed-channel") : reject(activity, "channel-not-allowed");
-    }
-    const threadKey = createSlackMessagePolicyThreadKey(activity);
-    const threadState = await stateStore.getMentionedThread(threadKey, {
-      activity,
-      key: threadKey
-    });
-    if (!threadState) {
-      return reject(activity, "thread-not-mentioned");
-    }
-    if (threadReplyPolicy === "mention-required") {
-      return reject(activity, "thread-reply-mention-required");
-    }
-    if (threadReplyPolicy === "original-user" && threadState.originalUserId && activity.userId !== threadState.originalUserId) {
-      return reject(activity, "thread-reply-not-original-user");
-    }
-    return accept(activity, "mentioned-thread-reply");
-  }
-  return {
-    resolve,
-    async resolveMessage(activity) {
-      const decision = await resolve(activity);
-      return decision.accepted ? decision.text : void 0;
-    }
-  };
-}
-
-// src/policy/message/passive.ts
-function shouldRegisterSlackPassiveChannelMessages(config = {}) {
-  const messagePolicy = config.messagePolicy ?? "disabled";
-  const threadReplyPolicy = config.threadReplyPolicy ?? "mention-required";
-  if (messagePolicy === "disabled") {
-    return false;
-  }
-  if (messagePolicy === "mentioned-threads" && threadReplyPolicy === "mention-required") {
-    return false;
-  }
-  if (messagePolicy === "allowed-channels") {
-    return Boolean(config.allowedChannelIds?.length);
-  }
-  return true;
-}
-
-// src/policy/message/resolver.ts
-function createSlackMessagePolicyResolver(config = {}) {
-  const allowedChannelIds = new Set(config.allowedChannelIds ?? []);
-  const messagePolicy = config.messagePolicy ?? "disabled";
-  const threadReplyPolicy = config.threadReplyPolicy ?? "mention-required";
-  const stateStore = config.stateStore ?? createInMemorySlackMessagePolicyStateStore({
-    maxAcceptedMessages: config.maxAcceptedMessages,
-    maxMentionedThreads: config.maxMentionedThreads
-  });
-  function rememberMentionedThread(activity) {
-    const key = createSlackMessagePolicyThreadKey(activity);
-    const originalUserId = activity.parentUserId ?? activity.userId;
-    stateStore.rememberMentionedThread(
-      key,
-      { originalUserId },
-      {
-        activity,
-        key
-      }
-    );
-  }
-  function claimAcceptedMessage(activity) {
-    const key = createSlackMessagePolicyMessageKey(activity);
-    if (!key) {
-      return true;
-    }
-    const context = { activity, key };
-    if (stateStore.claimAcceptedMessage) {
-      return stateStore.claimAcceptedMessage(key, context);
-    }
-    if (stateStore.hasAcceptedMessage(key, context)) {
-      return false;
-    }
-    stateStore.rememberAcceptedMessage(key, context);
-    return true;
-  }
-  function isDuplicate(activity) {
-    const key = createSlackMessagePolicyMessageKey(activity);
-    return Boolean(
-      key && stateStore.hasAcceptedMessage(key, { activity, key })
-    );
-  }
-  function accept(activity, reason) {
-    if (!claimAcceptedMessage(activity)) {
-      return reject(activity, "duplicate-message-event");
-    }
-    return {
-      accepted: true,
-      activity,
-      reason,
-      text: activity.text
-    };
-  }
-  function reject(activity, reason) {
-    return {
-      accepted: false,
-      activity,
-      reason
-    };
-  }
-  function resolve(activity) {
-    if (activity.isMention) {
-      rememberMentionedThread(activity);
-      return accept(activity, "bot-mentioned");
-    }
-    if (isDuplicate(activity)) {
-      return reject(activity, "duplicate-message-event");
-    }
-    if (activity.channelType === "dm") {
-      return accept(activity, "direct-message");
-    }
-    if (messagePolicy === "disabled") {
-      return reject(activity, "passive-channel-messages-disabled");
-    }
-    if (messagePolicy === "any-added-channel") {
-      return accept(activity, "any-added-channel");
-    }
-    if (messagePolicy === "allowed-channels") {
-      return allowedChannelIds.has(activity.channelId) ? accept(activity, "allowed-channel") : reject(activity, "channel-not-allowed");
-    }
-    const threadKey = createSlackMessagePolicyThreadKey(activity);
-    const threadState = stateStore.getMentionedThread(threadKey, {
-      activity,
-      key: threadKey
-    });
-    if (!threadState) {
-      return reject(activity, "thread-not-mentioned");
-    }
-    if (threadReplyPolicy === "mention-required") {
-      return reject(activity, "thread-reply-mention-required");
-    }
-    if (threadReplyPolicy === "original-user" && threadState.originalUserId && activity.userId !== threadState.originalUserId) {
-      return reject(activity, "thread-reply-not-original-user");
-    }
-    return accept(activity, "mentioned-thread-reply");
-  }
-  return {
-    resolve,
-    resolveMessage(activity) {
-      const decision = resolve(activity);
-      return decision.accepted ? decision.text : void 0;
-    }
-  };
-}
-
-export {
-  createSlackMessagePolicyMessageKey,
-  createSlackMessagePolicyThreadKey,
-  createInMemorySlackMessagePolicyStateStore,
-  createAsyncSlackMessagePolicyResolver,
-  shouldRegisterSlackPassiveChannelMessages,
-  createSlackMessagePolicyResolver
-};