@cuylabs/channel-slack-agent-core 0.6.0 → 0.8.0

package/docs/concepts/tool-task-rendering.md

@@ -0,0 +1,46 @@
+# Tool Task Rendering
+
+`chat-stream` mode can render Agent Core tool activity as Slack task updates.
+The bridge owns the generic event-to-Slack mapping, while applications can
+format titles, in-progress details, and completed output.
+
+Use these hooks when a tool result has structured metadata that should be shown
+more cleanly than the generic stringified result:
+
+- `formatToolTitle(toolName)` controls the Slack task title.
+- `formatToolDetails(event)` controls the in-progress task details for a
+  `tool-start` event.
+- `formatToolResultOutput(event)` controls the completed task output for a
+  `tool-result` event.
+
+`formatToolResultOutput` receives the full `tool-result` event, including
+`toolName`, `toolCallId`, `result`, and any tool metadata preserved by Agent
+Core. Return `undefined` to use the default formatter. Return `null` to omit the
+completed task output intentionally.
+
+```ts
+createSlackChannelAdapter({
+  source,
+  streamingMode: "chat-stream",
+  formatToolTitle: (toolName) => (toolName === "plan" ? "Plan" : toolName),
+  formatToolResultOutput: (event) => {
+    if (event.toolName !== "plan") {
+      return undefined;
+    }
+
+    const entries = readPlanEntries(event.metadata);
+    if (!entries) {
+      return undefined;
+    }
+
+    return entries
+      .map(
+        (entry) => `${entry.status === "done" ? "[x]" : "[ ]"} ${entry.title}`,
+      )
+      .join("\n");
+  },
+});
+```
+
+Keep task rows compact. Slack task updates are a visible progress projection for
+the current turn, not a durable audit log or replacement for the final answer.

package/docs/concepts/view-workflows.md

@@ -0,0 +1,52 @@
+# View Workflows
+
+Agent view workflows connect Slack modal submissions to agent or product logic.
+They sit above `@cuylabs/channel-slack/views`: the lower package owns Slack Web
+API/Bolt mechanics, while this package adds namespaced callback ids, decoded
+metadata, submitted state values, and app-surface mounting.
+
+```typescript
+import {
+  encodeSlackViewPrivateMetadata,
+  openSlackModal,
+} from "@cuylabs/channel-slack/views";
+import { createSlackAgentViewWorkflowController } from "@cuylabs/channel-slack-agent-core/views";
+
+const viewWorkflows = createSlackAgentViewWorkflowController({
+  namespace: "cdo",
+  workflows: [
+    {
+      id: "incident_triage",
+      onSubmission: async ({ metadata, stateValues, getStateValue, actor }) => {
+        const severity = getStateValue("severity", "value");
+        // Load product-owned workflow state by metadata.workflowId, validate the
+        // submitted values, then continue an agent turn or product workflow.
+        return { response_action: "clear" };
+      },
+    },
+  ],
+});
+
+await openSlackModal({
+  client,
+  triggerId,
+  view: {
+    type: "modal",
+    callback_id: viewWorkflows.callbackIdFor("incident_triage"),
+    private_metadata: encodeSlackViewPrivateMetadata({
+      workflowId: "triage-123",
+    }),
+    title: { type: "plain_text", text: "Triage incident" },
+    submit: { type: "plain_text", text: "Continue" },
+    blocks: [],
+  },
+});
+```
+
+Pass the controller to `mountSlackAgentApp` / `installSlackAgentAppSurface` as
+`viewWorkflows`. The controller installs `view_submission` and `view_closed`
+handlers on the underlying Bolt app.
+
+Keep `private_metadata` compact. Store durable workflow state in an application
+database or existing request store and put only routing keys, such as
+`workflowId`, `requestId`, or `sessionId`, into the modal.

package/docs/reference/exports.md

@@ -3,22 +3,24 @@
 Use feature subpaths when you only need one adapter surface. Generic Slack
 primitives should be imported from `@cuylabs/channel-slack` directly.
 
-| Export | Depends on | Notes |
-| --- | --- | --- |
-| `@cuylabs/channel-slack-agent-core` | `@cuylabs/agent-core`, selected Slack peers | Full adapter surface re-export |
-| `@cuylabs/channel-slack-agent-core/adapter` | `@slack/bolt`, `@slack/web-api` types | Classic app mention, DM, and passive channel-message adapter |
-| `@cuylabs/channel-slack-agent-core/app` | `@slack/bolt`, `@slack/web-api` | Direct app factory for mounted Slack surfaces |
-| `@cuylabs/channel-slack-agent-core/app-surface` | `@slack/bolt`, `@slack/web-api` types | Shared surface installer for Assistant, mentions, DMs, feedback, and interactions |
-| `@cuylabs/channel-slack-agent-core/assistant` | `@slack/bolt`, `@slack/web-api` types | Slack Assistant bridge and lifecycle handlers |
-| `@cuylabs/channel-slack-agent-core/express` | `@slack/bolt`, `express` | Express Events API mounting for classic Slack surfaces |
-| `@cuylabs/channel-slack-agent-core/express-assistant` | `@slack/bolt`, `express` | Express Events API mounting for Slack Assistant |
-| `@cuylabs/channel-slack-agent-core/feedback` | `@slack/bolt`, `@slack/types` | Agent Core feedback binding helpers |
-| `@cuylabs/channel-slack-agent-core/history` | `@slack/web-api`, `@cuylabs/agent-core` types | Agent Core turn history context fragment assembly |
-| `@cuylabs/channel-slack-agent-core/interactive` | `@slack/bolt`, `@slack/types` | Agent Core approval and human-input binding for Slack |
-| `@cuylabs/channel-slack-agent-core/mcp` | `@cuylabs/agent-core/mcp` types | Slack OAuth token bridge for Agent Core MCP setup |
-| `@cuylabs/channel-slack-agent-core/shared` | `@cuylabs/agent-core` types | Context fragments, event bridge, and interactive request contracts |
-| `@cuylabs/channel-slack-agent-core/socket` | `@slack/bolt` | Socket Mode mounting helpers |
-| `@cuylabs/channel-slack-agent-core/source` | `@cuylabs/agent-core` types | Source event queue, response helpers, and status visibility helpers |
+| Export                                                | Depends on                                                                             | Notes                                                                             |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `@cuylabs/channel-slack-agent-core`                   | `@cuylabs/agent-core`, selected Slack peers                                            | Full adapter surface re-export                                                    |
+| `@cuylabs/channel-slack-agent-core/adapter`           | `@slack/bolt`, `@slack/web-api` types                                                  | Classic app mention, DM, and passive channel-message adapter                      |
+| `@cuylabs/channel-slack-agent-core/app`               | `@slack/bolt`, `@slack/web-api`                                                        | Direct app factory for mounted Slack surfaces                                     |
+| `@cuylabs/channel-slack-agent-core/app-surface`       | `@slack/bolt`, `@slack/web-api` types                                                  | Shared surface installer for Assistant, mentions, DMs, feedback, and interactions |
+| `@cuylabs/channel-slack-agent-core/artifacts`         | `@cuylabs/channel-slack/artifacts`                                                     | Agent Core final-response artifact publishers for Slack surfaces                  |
+| `@cuylabs/channel-slack-agent-core/assistant`         | `@slack/bolt`, `@slack/web-api` types                                                  | Slack Assistant bridge and lifecycle handlers                                     |
+| `@cuylabs/channel-slack-agent-core/express`           | `@slack/bolt`, `express`                                                               | Express Events API mounting for classic Slack surfaces                            |
+| `@cuylabs/channel-slack-agent-core/express-assistant` | `@slack/bolt`, `express`                                                               | Express Events API mounting for Slack Assistant                                   |
+| `@cuylabs/channel-slack-agent-core/feedback`          | `@slack/bolt`, `@slack/types`                                                          | Agent Core feedback binding helpers                                               |
+| `@cuylabs/channel-slack-agent-core/history`           | `@slack/web-api`, `@cuylabs/agent-core` types                                          | Agent Core turn history context fragment assembly                                 |
+| `@cuylabs/channel-slack-agent-core/interactive`       | `@slack/bolt`, `@slack/types`; `pg` only when using connection-string Postgres storage | Agent Core approval and human-input binding for Slack                             |
+| `@cuylabs/channel-slack-agent-core/mcp`               | `@cuylabs/agent-core/mcp` types                                                        | Slack OAuth token bridge for Agent Core MCP setup                                 |
+| `@cuylabs/channel-slack-agent-core/shared`            | `@cuylabs/agent-core` types                                                            | Context fragments, event bridge, and interactive request contracts                |
+| `@cuylabs/channel-slack-agent-core/socket`            | `@slack/bolt`                                                                          | Socket Mode mounting helpers                                                      |
+| `@cuylabs/channel-slack-agent-core/source`            | `@cuylabs/agent-core` types                                                            | Source event queue, response helpers, and status visibility helpers               |
+| `@cuylabs/channel-slack-agent-core/views`             | `@cuylabs/channel-slack/views`, `@slack/bolt`                                          | Agent/product Slack modal workflow controller and submitted state helpers         |
 
 For generic Slack package exports, see
 `@cuylabs/channel-slack/docs/reference/exports.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/channel-slack-agent-core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Slack adapter for @cuylabs/agent-core built on @cuylabs/channel-slack",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,11 @@
       "import": "./dist/app-surface.js",
       "default": "./dist/app-surface.js"
     },
+    "./artifacts": {
+      "types": "./dist/artifacts/index.d.ts",
+      "import": "./dist/artifacts/index.js",
+      "default": "./dist/artifacts/index.js"
+    },
     "./assistant": {
       "types": "./dist/assistant/index.d.ts",
       "import": "./dist/assistant/index.js",
@@ -75,6 +80,11 @@
       "types": "./dist/source/index.d.ts",
       "import": "./dist/source/index.js",
       "default": "./dist/source/index.js"
+    },
+    "./views": {
+      "types": "./dist/views/index.d.ts",
+      "import": "./dist/views/index.js",
+      "default": "./dist/views/index.js"
     }
   },
   "files": [
@@ -84,7 +94,7 @@
   ],
   "dependencies": {
     "@cuylabs/agent-core": "^7.2.0",
-    "@cuylabs/channel-slack": "^0.6.0"
+    "@cuylabs/channel-slack": "^0.8.0"
   },
   "peerDependencies": {
     "@slack/bolt": ">=4.7.3",
@@ -134,9 +144,9 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/shared/index.ts src/adapter/index.ts src/app.ts src/app-surface.ts src/assistant/index.ts src/express.ts src/express-assistant.ts src/feedback/index.ts src/history/index.ts src/interactive/index.ts src/mcp.ts src/socket.ts src/source/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/shared/index.ts src/adapter/index.ts src/app.ts src/app-surface.ts src/artifacts/index.ts src/assistant/index.ts src/express.ts src/express-assistant.ts src/feedback/index.ts src/history/index.ts src/interactive/index.ts src/mcp.ts src/socket.ts src/source/index.ts src/views/index.ts --format esm --dts --clean",
     "clean": "rm -rf dist",
-    "dev": "tsup src/index.ts src/shared/index.ts src/adapter/index.ts src/app.ts src/app-surface.ts src/assistant/index.ts src/express.ts src/express-assistant.ts src/feedback/index.ts src/history/index.ts src/interactive/index.ts src/mcp.ts src/socket.ts src/source/index.ts --format esm --dts --watch",
+    "dev": "tsup src/index.ts src/shared/index.ts src/adapter/index.ts src/app.ts src/app-surface.ts src/artifacts/index.ts src/assistant/index.ts src/express.ts src/express-assistant.ts src/feedback/index.ts src/history/index.ts src/interactive/index.ts src/mcp.ts src/socket.ts src/source/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",