@cuylabs/channel-slack 0.5.0 → 0.6.0

package/docs/README.md

@@ -0,0 +1,31 @@
+# Channel Slack Docs
+
+`@cuylabs/channel-slack` is the reusable Slack mechanics package. Start with
+the package boundary, then use the reference and recipes for the feature surface
+your adapter or application needs.
+
+## Reference
+
+- [Package boundary](reference/channel-slack-boundary.md)
+- [Exports and peer expectations](reference/exports.md)
+- [Source layout](reference/source-layout.md)
+
+## Concepts
+
+- [Activity parsing](concepts/activity.md)
+- [Artifacts](concepts/artifacts.md)
+- [Entrypoints](concepts/entrypoints.md)
+- [Message policy](concepts/message-policy.md)
+- [Setup requirements](concepts/setup-requirements.md)
+- [Supplemental history](concepts/supplemental-history.md)
+- [Transport runtime](concepts/transport-runtime.md)
+
+## Recipes
+
+- [App mention handler](recipes/app-mention-handler.md)
+- [Assistant thread handler](recipes/assistant-thread-handler.md)
+- [Socket Mode app](recipes/socket-mode-app.md)
+- [Slash command and shortcut handler](recipes/slash-command-and-shortcut.md)
+- [Publish an artifact](recipes/publish-artifact.md)
+- [Generate a Slack manifest](recipes/generate-slack-manifest.md)
+- [History visibility filter](recipes/history-visibility.md)

package/docs/concepts/activity.md

@@ -1,8 +1,8 @@
 # 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.
+An activity is the normalized Slack message shape an adapter or application can
+map into its own runtime. It is intentionally smaller than a raw Slack event and
+does not depend on Bolt.
 
 ```typescript
 import { parseSlackMentionActivity } from "@cuylabs/channel-slack/core";

package/docs/concepts/artifacts.md

@@ -0,0 +1,56 @@
+# Artifacts
+
+Artifacts publish generated outputs to Slack without depending on any agent
+runtime. The package accepts a structural Slack Web API client, so callers can
+pass a real `WebClient`, a scoped client from a request handler, or a test
+double with the methods they use.
+
+```typescript
+import { publishSlackArtifact } from "@cuylabs/channel-slack/artifacts";
+
+const publication = await publishSlackArtifact({
+  client,
+  channelId: activity.channelId,
+  threadTs: activity.threadTs ?? activity.messageTs,
+  artifact: {
+    kind: "text",
+    title: "Investigation summary",
+    summary: "Key findings from the thread.",
+    text: reportMarkdown,
+  },
+});
+```
+
+## Artifact Kinds
+
+- `text`: uploads text as a Slack file by default. Set `publishAs: "message"`
+  to post it as a Block Kit message instead.
+- `file`: uploads binary or text data from `data` or `filePath`.
+- `image`: uploads an image file and requires `altText`.
+- `link`: posts a Block Kit message with a Slack-formatted link.
+- `canvas`: creates or updates a Slack Canvas from Markdown.
+
+## Results
+
+`publishSlackArtifact` returns a `SlackArtifactPublication` with:
+
+- `method`: `message`, `file`, or `canvas`.
+- the original `artifact`.
+- the raw Slack API `response`.
+- target metadata such as `channelId`, `threadTs`, `messageTs`, `fileId`, or
+  `canvasId` when Slack returns it.
+
+## Slack Client Surface
+
+Only the method required by the selected artifact kind must exist:
+
+- message/link artifacts use `client.chat.postMessage`.
+- text/file/image file uploads use `client.files.uploadV2`.
+- Canvas creation uses `client.conversations.canvases.create` for channel
+  canvases when available, or `client.canvases.create` otherwise.
+- Canvas updates use `client.canvases.edit`.
+
+## Setup
+
+The `artifacts` setup feature adds `chat:write` and `files:write`.
+The `canvas-artifacts` setup feature adds `canvases:write`.

package/docs/concepts/entrypoints.md

@@ -0,0 +1,73 @@
+# Entrypoints
+
+Entrypoints normalize Slack slash command and shortcut payloads into small
+package contracts. They do not start a turn or choose a runtime request shape.
+
+```typescript
+import { parseSlackSlashCommandEntrypoint } from "@cuylabs/channel-slack/entrypoints";
+
+const entrypoint = parseSlackSlashCommandEntrypoint(payload);
+```
+
+## Slash Commands
+
+`parseSlackSlashCommandEntrypoint` returns:
+
+- `kind: "slash-command"`.
+- `command`: the invoked slash command, such as `/ask`.
+- `activity`: a `SlackActivityInfo` shape with channel, user, team, and text.
+- optional Slack request metadata such as `triggerId`, `responseUrl`,
+  `channelName`, `teamDomain`, `appId`, and enterprise fields.
+
+The parser treats the command text as the model-facing text. A host adapter can
+map `entrypoint.activity.text` into its own runtime input while preserving the
+Slack metadata for routing, logging, or response targets.
+
+## Shortcuts
+
+Use `parseSlackShortcutEntrypoint` when one handler receives both global and
+message shortcuts:
+
+```typescript
+import { parseSlackShortcutEntrypoint } from "@cuylabs/channel-slack/entrypoints";
+
+const entrypoint = parseSlackShortcutEntrypoint(payload);
+```
+
+Global shortcuts return `kind: "global-shortcut"` and include trigger/user/team
+metadata, but no selected message.
+
+Message shortcuts return `kind: "message-shortcut"`, include the selected
+message text, and also expose `activity` so a runtime adapter can treat the
+selection as a Slack turn candidate.
+
+## Setup
+
+Passing `slashCommands` or `shortcuts` to setup helpers automatically enables
+the matching feature, the `commands` scope, and Slack interactivity settings.
+
+```typescript
+import { createSlackAppManifest } from "@cuylabs/channel-slack/setup";
+
+const manifest = createSlackAppManifest({
+  name: "My Agent",
+  preset: false,
+  transport: "http",
+  baseUrl: "https://agent.example.com",
+  slashCommands: [
+    {
+      command: "/ask",
+      description: "Ask the agent",
+      usage_hint: "summarize this thread",
+    },
+  ],
+  shortcuts: [
+    {
+      type: "message",
+      name: "Summarize message",
+      callback_id: "summarize_message",
+      description: "Summarize the selected Slack message",
+    },
+  ],
+});
+```

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

package/docs/concepts/setup-requirements.md

@@ -19,6 +19,10 @@ const requirements = getSlackSetupRequirements({
 - `agent-app`: Assistant, app mentions, direct messages, and feedback.
 
 Pass `preset: false` and provide `features` when an app needs exact control.
+Supplying `slashCommands` or `shortcuts` automatically enables the matching
+feature and adds the Slack `commands` scope plus interactivity settings.
+The `artifacts` feature adds `chat:write` and `files:write`; the
+`canvas-artifacts` feature adds `canvases:write`.
 
 ## Features
 
@@ -32,12 +36,31 @@ Feature selections produce:
   Socket Mode.
 - environment variables needed by the chosen transport.
 
+Common feature selections:
+
+- `assistant`: Assistant view events, `assistant:write`, and `chat:write`.
+- `app-mentions`: app mention event subscription and reply permission.
+- `direct-messages`: DM message events and DM history/read scopes.
+- `channel-messages`: passive channel/group message events and history scopes.
+- `slash-commands`: `commands` scope and interactivity.
+- `shortcuts`: `commands` scope and interactivity.
+- `artifacts`: `chat:write` and `files:write`.
+- `canvas-artifacts`: `canvases:write`.
+- `history`: channel, group, DM, and MPIM history scopes.
+- `feedback` and `interactivity`: `chat:write` plus interactivity.
+- `user-profiles` and `user-emails`: Slack user profile scopes.
+- `workspace-search`: Slack search scopes.
+
 ## 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.
 
+Pass `slashCommands` and `shortcuts` to include those manifest sections. For
+HTTP transport, command and interactivity URLs are filled from `baseUrl` and
+`eventsPath` unless a command defines its own `url`.
+
 ## Inspection
 
 `inspectSlackAppSetup` combines requirements with a live token inspection. It

package/docs/concepts/{bolt-runtime.md → transport-runtime.md}

@@ -1,7 +1,12 @@
-# Bolt Runtime
+# Transport Runtime
 
-The Bolt helpers create Slack transports and auth wiring. They deliberately do
-not register handlers, own prompts, run agents, or choose deployment policy.
+The transport helpers create Slack apps with Bolt auth wiring. They deliberately
+do not register handlers, own prompts, run agents, or choose deployment policy.
+
+Use transport-specific imports:
+
+- `@cuylabs/channel-slack/transports/http`
+- `@cuylabs/channel-slack/transports/socket`
 
 ## HTTP
 
@@ -29,6 +34,11 @@ that can:
 
 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:
 
@@ -36,7 +46,7 @@ Postgres advisory lock before starting the Socket Mode app:
 import {
   acquireSlackSocketModePostgresLock,
   createSlackSocketModeRuntime,
-} from "@cuylabs/channel-slack/bolt";
+} from "@cuylabs/channel-slack/transports/socket";
 
 const postgresLock = await acquireSlackSocketModePostgresLock({
   appSlug: "my-agent",

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/recipes/generate-slack-manifest.md

@@ -9,6 +9,22 @@ const manifest = createSlackAppManifest({
   preset: "agent-app",
   transport: "socket",
   assistantDescription: "Ask the agent for help with workspace tasks.",
+  slashCommands: [
+    {
+      command: "/ask",
+      description: "Ask the agent",
+      usage_hint: "summarize this thread",
+    },
+  ],
+  shortcuts: [
+    {
+      type: "message",
+      name: "Summarize message",
+      callback_id: "summarize_message",
+      description: "Summarize the selected Slack message",
+    },
+  ],
+  features: ["artifacts", "canvas-artifacts"],
 });
 
 console.log(JSON.stringify(manifest, null, 2));

package/docs/recipes/publish-artifact.md

@@ -0,0 +1,45 @@
+# Publish An Artifact
+
+Use artifact helpers when a runtime produces a report, file, image, link, or
+Canvas and the Slack adapter only needs to publish it.
+
+```typescript
+import { publishSlackArtifact } from "@cuylabs/channel-slack/artifacts";
+
+const result = await publishSlackArtifact({
+  client,
+  channelId: activity.channelId,
+  threadTs: activity.threadTs ?? activity.messageTs,
+  artifact: {
+    kind: "text",
+    title: "Launch summary",
+    summary: "Generated from the selected Slack thread.",
+    text: reportMarkdown,
+  },
+});
+
+logger.info("Slack artifact published", {
+  method: result.method,
+  fileId: result.fileId,
+  messageTs: result.messageTs,
+  canvasId: result.canvasId,
+});
+```
+
+To create a Canvas instead:
+
+```typescript
+await publishSlackArtifact({
+  client,
+  channelId: activity.channelId,
+  artifact: {
+    kind: "canvas",
+    title: "Launch plan",
+    summary: "Generated plan",
+    markdown: canvasMarkdown,
+  },
+});
+```
+
+Enable the `artifacts` setup feature for files and messages. Enable
+`canvas-artifacts` when publishing canvases.

package/docs/recipes/slash-command-and-shortcut.md

@@ -0,0 +1,51 @@
+# Slash Command And Shortcut Handler
+
+Use entrypoint parsers to normalize Slack request payloads before handing them
+to an application-owned runtime.
+
+```typescript
+import {
+  parseSlackShortcutEntrypoint,
+  parseSlackSlashCommandEntrypoint,
+} from "@cuylabs/channel-slack/entrypoints";
+
+app.command("/ask", async ({ ack, body, client }) => {
+  await ack();
+
+  const entrypoint = parseSlackSlashCommandEntrypoint(body);
+  const answer = await runAgent({
+    input: entrypoint.activity.text,
+    slack: entrypoint.activity,
+    entrypoint,
+  });
+
+  await client.chat.postMessage({
+    channel: entrypoint.activity.channelId,
+    text: answer,
+  });
+});
+
+app.shortcut("summarize_message", async ({ ack, body, client }) => {
+  await ack();
+
+  const entrypoint = parseSlackShortcutEntrypoint(body);
+  if (entrypoint.kind !== "message-shortcut") return;
+
+  const answer = await runAgent({
+    input: entrypoint.selectedMessage.text,
+    slack: entrypoint.activity,
+    entrypoint,
+  });
+
+  await client.chat.postMessage({
+    channel: entrypoint.selectedMessage.channelId,
+    thread_ts:
+      entrypoint.selectedMessage.threadTs ??
+      entrypoint.selectedMessage.messageTs,
+    text: answer,
+  });
+});
+```
+
+For manifest setup, pass `slashCommands` and `shortcuts` to
+`createSlackAppManifest`.

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

@@ -4,7 +4,7 @@
 import {
   createSlackSocketBoltApp,
   createSlackSocketModeRuntime,
-} from "@cuylabs/channel-slack/bolt";
+} from "@cuylabs/channel-slack/transports/socket";
 
 const runtime = createSlackSocketModeRuntime({
   appSlug: "my-agent",

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

@@ -5,16 +5,19 @@ 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 agent-core runtime binding. It
-composes this package with runtime scopes, event streams, context fragments, and
-approval or human-input contracts.
+Runtime-specific adapter packages compose these primitives with their own
+runtime scopes, event streams, context fragments, and approval or human-input
+contracts.
 
 ## In This Package
 
 - Slack activity parsing and text extraction.
+- Slack slash command and shortcut entrypoint normalization.
+- Slack artifact publishing contracts and helpers.
 - Markdown-to-Slack formatting.
 - Thread-aware session helpers.
-- Slack auth and installation store helpers.
+- Slack auth and installation-store helpers.
+- HTTP and Socket Mode Bolt transport helpers.
 - Socket Mode runtime guard, process lock, and optional Postgres advisory lock.
 - Setup requirements and manifest helpers.
 - Diagnostics.
@@ -29,6 +32,7 @@ approval or human-input contracts.
 
 - Agent runtime execution.
 - Agent-runtime scopes and context-fragment middleware.
+- Runtime-specific mapping from Slack entrypoints into an agent turn.
 - Agent event stream rendering.
 - Agent-specific approval and human-input request contracts.
 - Product prompts, tools, audit policy, and deployment policy.
@@ -38,8 +42,8 @@ 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`.
+- Peer-backed helpers live behind feature subpaths such as `transports`,
+  `app-home`, `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

package/docs/reference/exports.md

@@ -6,12 +6,17 @@ 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`      | `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/app-home`    | `@slack/bolt`, `@slack/types`                                                   | Slack App Home registration helper                                       |
+| `@cuylabs/channel-slack/artifacts`   | no Slack SDK runtime imports; requires a Web API-like client at call time       | Text, file, image, link, and Canvas artifact publishing                  |
+| `@cuylabs/channel-slack/auth`        | no Slack SDK runtime imports; `pg` is not required                              | Auth option types, auth resolution, OAuth installation stores            |
+| `@cuylabs/channel-slack/transports`  | `@slack/bolt`, `express`; `pg` only when using connection-string Postgres locks | HTTP and Socket Mode transport helpers                                   |
+| `@cuylabs/channel-slack/transports/http` | `@slack/bolt`, `express`                                                    | HTTP Events API Bolt app factory                                         |
+| `@cuylabs/channel-slack/transports/socket` | `@slack/bolt`; `pg` only when using connection-string Postgres locks      | Socket Mode app factory, runtime guard, process/Postgres locks           |
 | `@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/entrypoints` | no Slack SDK runtime imports                                                    | Slash command and shortcut payload normalization                         |
 | `@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                                        |

package/docs/reference/source-layout.md

@@ -0,0 +1,35 @@
+# Source Layout
+
+The package is organized by Slack capability. Public imports should use package
+exports such as `@cuylabs/channel-slack/core` or
+`@cuylabs/channel-slack/transports/socket`; application code should not import
+from `src`.
+
+```text
+src/
+  core.ts                 public core entrypoint
+  shared/                 types, parsing, formatting, turn helpers
+  assistant/              Slack Assistant API helpers
+  app-home.ts             Slack App Home registration helper
+  artifacts/              text, file, image, link, and Canvas publishing
+  auth/                   auth options, auth resolution, installation stores
+  diagnostics/            token and scope inspection
+  entrypoints/            slash command and shortcut normalization
+  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
+  transports/
+    http/                 HTTP Events API Bolt app factory
+    socket/               Socket Mode Bolt app factory, runtime, locks
+  targets/                channel/user target parsing and resolution
+  users/                  profile lookup and mention enrichment
+```
+
+For public export details and peer dependency expectations, see
+[Exports](exports.md).