@cuylabs/channel-slack 0.5.1 → 0.7.0

package/docs/concepts/views.md

@@ -0,0 +1,46 @@
+# Slack Views
+
+`@cuylabs/channel-slack/views` provides Slack-runtime primitives for modal and
+Home view workflows. It keeps Slack Web API and Bolt details in
+`channel-slack` while product packages decide what a workflow means.
+
+```typescript
+import {
+  encodeSlackViewPrivateMetadata,
+  openSlackModal,
+  registerSlackViewWorkflow,
+} from "@cuylabs/channel-slack/views";
+
+await openSlackModal({
+  client,
+  triggerId,
+  view: {
+    type: "modal",
+    callback_id: "incident_triage",
+    private_metadata: encodeSlackViewPrivateMetadata({
+      workflowId: "triage-123",
+    }),
+    title: { type: "plain_text", text: "Triage incident" },
+    submit: { type: "plain_text", text: "Continue" },
+    close: { type: "plain_text", text: "Cancel" },
+    blocks: [],
+  },
+});
+
+registerSlackViewWorkflow({
+  boltApp,
+  callbackId: "incident_triage",
+  onSubmission: async ({ metadata, view, actor }) => {
+    // Load product-owned workflow state by metadata.workflowId, validate
+    // view.state, then continue the workflow or return field errors.
+    return { response_action: "clear" };
+  },
+});
+```
+
+Use `private_metadata` for compact routing data such as a workflow id, request
+id, or session id. Store durable workflow state outside the view, for example in
+the application database or the existing interactive-request store.
+
+The `views` setup feature does not require a special bot scope, but it does
+require Slack interactivity to be enabled for the app.

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

@@ -3,18 +3,24 @@
 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`      | `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                                        |
+| Export                                     | Depends on                                                                      | Notes                                                                    |
+| ------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `@cuylabs/channel-slack/core`              | no Slack SDK runtime imports                                                    | Transport-neutral parsing, formatting, types, sessions, turn context     |
+| `@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/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                                        |
+| `@cuylabs/channel-slack/views`             | `@slack/bolt`, `@slack/types`                                                   | Modal/Home view operations and workflow registration                     |
 
 The root export remains available for lightweight core and policy helpers:
 

package/docs/reference/source-layout.md

@@ -0,0 +1,36 @@
+# 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
+  views/                  modal/Home view operations and workflow registration
+```
+
+For public export details and peer dependency expectations, see
+[Exports](exports.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cuylabs/channel-slack",
-  "version": "0.5.1",
-  "description": "SDK-neutral Slack channel primitives for AI agents",
+  "version": "0.7.0",
+  "description": "Agent-runtime-agnostic Slack channel primitives for AI agents",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,14 +12,24 @@
       "default": "./dist/index.js"
     },
     "./assistant": {
-      "types": "./dist/assistant.d.ts",
-      "import": "./dist/assistant.js",
-      "default": "./dist/assistant.js"
+      "types": "./dist/assistant/index.d.ts",
+      "import": "./dist/assistant/index.js",
+      "default": "./dist/assistant/index.js"
     },
-    "./bolt": {
-      "types": "./dist/bolt.d.ts",
-      "import": "./dist/bolt.js",
-      "default": "./dist/bolt.js"
+    "./app-home": {
+      "types": "./dist/app-home.d.ts",
+      "import": "./dist/app-home.js",
+      "default": "./dist/app-home.js"
+    },
+    "./artifacts": {
+      "types": "./dist/artifacts/index.d.ts",
+      "import": "./dist/artifacts/index.js",
+      "default": "./dist/artifacts/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js",
+      "default": "./dist/auth/index.js"
     },
     "./core": {
       "types": "./dist/core.d.ts",
@@ -27,44 +37,64 @@
       "default": "./dist/core.js"
     },
     "./diagnostics": {
-      "types": "./dist/diagnostics.d.ts",
-      "import": "./dist/diagnostics.js",
-      "default": "./dist/diagnostics.js"
+      "types": "./dist/diagnostics/index.d.ts",
+      "import": "./dist/diagnostics/index.js",
+      "default": "./dist/diagnostics/index.js"
+    },
+    "./entrypoints": {
+      "types": "./dist/entrypoints/index.d.ts",
+      "import": "./dist/entrypoints/index.js",
+      "default": "./dist/entrypoints/index.js"
     },
     "./feedback": {
-      "types": "./dist/feedback.d.ts",
-      "import": "./dist/feedback.js",
-      "default": "./dist/feedback.js"
+      "types": "./dist/feedback/index.d.ts",
+      "import": "./dist/feedback/index.js",
+      "default": "./dist/feedback/index.js"
     },
     "./history": {
-      "types": "./dist/history.d.ts",
-      "import": "./dist/history.js",
-      "default": "./dist/history.js"
+      "types": "./dist/history/index.d.ts",
+      "import": "./dist/history/index.js",
+      "default": "./dist/history/index.js"
     },
     "./policy": {
-      "types": "./dist/policy.d.ts",
-      "import": "./dist/policy.js",
-      "default": "./dist/policy.js"
+      "types": "./dist/policy/index.d.ts",
+      "import": "./dist/policy/index.js",
+      "default": "./dist/policy/index.js"
     },
     "./setup": {
-      "types": "./dist/setup.d.ts",
-      "import": "./dist/setup.js",
-      "default": "./dist/setup.js"
-    },
-    "./shared": {
-      "types": "./dist/shared.d.ts",
-      "import": "./dist/shared.js",
-      "default": "./dist/shared.js"
+      "types": "./dist/setup/index.d.ts",
+      "import": "./dist/setup/index.js",
+      "default": "./dist/setup/index.js"
     },
     "./targets": {
-      "types": "./dist/targets.d.ts",
-      "import": "./dist/targets.js",
-      "default": "./dist/targets.js"
+      "types": "./dist/targets/index.d.ts",
+      "import": "./dist/targets/index.js",
+      "default": "./dist/targets/index.js"
+    },
+    "./transports": {
+      "types": "./dist/transports/index.d.ts",
+      "import": "./dist/transports/index.js",
+      "default": "./dist/transports/index.js"
+    },
+    "./transports/http": {
+      "types": "./dist/transports/http/index.d.ts",
+      "import": "./dist/transports/http/index.js",
+      "default": "./dist/transports/http/index.js"
+    },
+    "./transports/socket": {
+      "types": "./dist/transports/socket/index.d.ts",
+      "import": "./dist/transports/socket/index.js",
+      "default": "./dist/transports/socket/index.js"
     },
     "./users": {
-      "types": "./dist/users.d.ts",
-      "import": "./dist/users.js",
-      "default": "./dist/users.js"
+      "types": "./dist/users/index.d.ts",
+      "import": "./dist/users/index.js",
+      "default": "./dist/users/index.js"
+    },
+    "./views": {
+      "types": "./dist/views/index.d.ts",
+      "import": "./dist/views/index.js",
+      "default": "./dist/views/index.js"
     }
   },
   "files": [
@@ -108,8 +138,7 @@
     "agent",
     "slack",
     "channel",
-    "adapter",
-    "bolt"
+    "adapter"
   ],
   "license": "Apache-2.0",
   "publishConfig": {
@@ -119,9 +148,9 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/core.ts src/shared.ts src/assistant.ts src/bolt.ts src/diagnostics.ts src/feedback.ts src/history.ts src/policy.ts src/setup.ts src/targets.ts src/users.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/app-home.ts src/artifacts/index.ts src/core.ts src/assistant/index.ts src/auth/index.ts src/diagnostics/index.ts src/entrypoints/index.ts src/feedback/index.ts src/history/index.ts src/policy/index.ts src/setup/index.ts src/targets/index.ts src/transports/index.ts src/transports/http/index.ts src/transports/socket/index.ts src/users/index.ts src/views/index.ts --format esm --dts --clean",
     "clean": "rm -rf dist",
-    "dev": "tsup src/index.ts src/core.ts src/shared.ts src/assistant.ts src/bolt.ts src/diagnostics.ts src/feedback.ts src/history.ts src/policy.ts src/setup.ts src/targets.ts src/users.ts --format esm --dts --watch",
+    "dev": "tsup src/index.ts src/app-home.ts src/artifacts/index.ts src/core.ts src/assistant/index.ts src/auth/index.ts src/diagnostics/index.ts src/entrypoints/index.ts src/feedback/index.ts src/history/index.ts src/policy/index.ts src/setup/index.ts src/targets/index.ts src/transports/index.ts src/transports/http/index.ts src/transports/socket/index.ts src/users/index.ts src/views/index.ts --format esm --dts --watch",
     "lint": "eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\" --max-warnings=0",
     "test": "vitest run",
     "test:watch": "vitest",