@cuylabs/channel-slack 0.7.0 → 0.9.0

package/dist/responses/index.d.ts

@@ -0,0 +1,74 @@
+import { d as SlackArtifactClient } from '../types-C8nkPuD4.js';
+
+/**
+ * Slack response-sink contracts consumed by the event bridge.
+ *
+ * The adapter constructs a `SlackResponseSink` from the Bolt `say` function
+ * and `WebClient` instance available in each handler. Keeping the sink
+ * interface separate makes the bridge testable without a live Slack
+ * connection.
+ */
+
+type SlackStreamTaskStatus = "pending" | "in_progress" | "complete" | "error";
+type SlackStreamChunk = {
+    type: "markdown_text";
+    text: string;
+} | {
+    type: "plan_update";
+    title: string;
+} | {
+    type: "task_update";
+    id: string;
+    title: string;
+    status: SlackStreamTaskStatus;
+    details?: string;
+    output?: string;
+};
+interface SlackChatStream {
+    append(args: {
+        markdown_text?: string;
+        chunks?: SlackStreamChunk[];
+    }): Promise<unknown>;
+    stop(args?: {
+        markdown_text?: string;
+        chunks?: SlackStreamChunk[];
+    }): Promise<unknown>;
+}
+/**
+ * Minimal Slack posting interface consumed by the event bridge.
+ */
+interface SlackArtifactPublicationTarget {
+    channelId: string;
+    threadTs?: string;
+}
+interface SlackResponseSink {
+    /**
+     * Slack Web API surface used by optional artifact publishers.
+     */
+    artifactClient?: SlackArtifactClient;
+    /**
+     * Channel/thread target used by optional artifact publishers.
+     */
+    artifactTarget?: SlackArtifactPublicationTarget;
+    /**
+     * Post a new message to the channel / thread.
+     * Returns the channel ID and message timestamp needed for updates.
+     */
+    postMessage(text: string): Promise<{
+        channel: string;
+        ts: string;
+    }>;
+    /**
+     * Update an existing message by channel + ts.
+     */
+    updateMessage(channel: string, ts: string, text: string): Promise<void>;
+    /**
+     * Create a native Slack chat stream. Required when `streamingMode` is
+     * `"chat-stream"`.
+     */
+    createChatStream?(options: {
+        bufferSize: number;
+    }): SlackChatStream;
+}
+
+export type { SlackArtifactPublicationTarget, SlackChatStream, SlackResponseSink, SlackStreamChunk, SlackStreamTaskStatus };

package/dist/turn-controls/index.d.ts

@@ -0,0 +1,51 @@
+import { SectionBlock, ActionsBlock, KnownBlock } from '@slack/types';
+import { App } from '@slack/bolt';
+
+declare const SLACK_TURN_CANCEL_ACTION_ID = "agent_turn_cancel";
+interface SlackTurnCancelButtonValue {
+    action: "cancel";
+    controlId: string;
+    sessionId?: string;
+    turnId?: string;
+}
+interface SlackTurnCancelMessageOptions {
+    controlId: string;
+    actionId?: string;
+    buttonText?: string;
+    messageText?: string;
+    sessionId?: string;
+    turnId?: string;
+}
+interface SlackTurnCancelMessage {
+    text: string;
+    blocks: [SectionBlock, ActionsBlock];
+}
+declare function createSlackTurnCancelMessage(options: SlackTurnCancelMessageOptions): SlackTurnCancelMessage;
+declare function encodeSlackTurnCancelButtonValue(value: SlackTurnCancelButtonValue): string;
+declare function decodeSlackTurnCancelButtonValue(rawValue: unknown): SlackTurnCancelButtonValue | undefined;
+declare function resolveSlackTurnCancelActionId(actionId?: string): string;
+
+interface SlackTurnCancelActionContext extends SlackTurnCancelButtonValue {
+    channelId: string;
+    userId: string;
+    messageTs: string;
+    threadTs?: string;
+    teamId?: string;
+    triggerId?: string;
+    acknowledgeEphemeral: (text: string) => Promise<void>;
+    deleteMessage: () => Promise<void>;
+    updateMessage: (message: {
+        text: string;
+        blocks?: KnownBlock[];
+    }) => Promise<void>;
+}
+type SlackTurnCancelActionHandler = (context: SlackTurnCancelActionContext) => void | Promise<void>;
+interface RegisterSlackTurnCancelActionOptions {
+    actionId?: string;
+    onCancel: SlackTurnCancelActionHandler;
+}
+declare function registerSlackTurnCancelAction(app: App, options: RegisterSlackTurnCancelActionOptions): {
+    actionId: string;
+};
+
+export { type RegisterSlackTurnCancelActionOptions, SLACK_TURN_CANCEL_ACTION_ID, type SlackTurnCancelActionContext, type SlackTurnCancelActionHandler, type SlackTurnCancelButtonValue, type SlackTurnCancelMessage, type SlackTurnCancelMessageOptions, createSlackTurnCancelMessage, decodeSlackTurnCancelButtonValue, encodeSlackTurnCancelButtonValue, registerSlackTurnCancelAction, resolveSlackTurnCancelActionId };

package/dist/turn-controls/index.js

@@ -0,0 +1,16 @@
+import {
+  SLACK_TURN_CANCEL_ACTION_ID,
+  createSlackTurnCancelMessage,
+  decodeSlackTurnCancelButtonValue,
+  encodeSlackTurnCancelButtonValue,
+  registerSlackTurnCancelAction,
+  resolveSlackTurnCancelActionId
+} from "../chunk-3KP3CBCC.js";
+export {
+  SLACK_TURN_CANCEL_ACTION_ID,
+  createSlackTurnCancelMessage,
+  decodeSlackTurnCancelButtonValue,
+  encodeSlackTurnCancelButtonValue,
+  registerSlackTurnCancelAction,
+  resolveSlackTurnCancelActionId
+};

package/dist/types-C8nkPuD4.d.ts

@@ -0,0 +1,111 @@
+type SlackArtifactPublishMethod = "message" | "file" | "canvas";
+type SlackArtifactBinaryData = string | Uint8Array | ArrayBuffer;
+interface SlackArtifactBase {
+    kind: string;
+    title: string;
+    summary?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SlackTextArtifact extends SlackArtifactBase {
+    kind: "text";
+    text: string;
+    filename?: string;
+    mimeType?: string;
+    publishAs?: "message" | "file";
+}
+interface SlackFileArtifact extends SlackArtifactBase {
+    kind: "file";
+    filename: string;
+    data?: SlackArtifactBinaryData;
+    filePath?: string;
+    mimeType?: string;
+    initialComment?: string;
+}
+interface SlackImageArtifact extends SlackArtifactBase {
+    kind: "image";
+    filename: string;
+    altText: string;
+    data?: SlackArtifactBinaryData;
+    filePath?: string;
+    initialComment?: string;
+}
+interface SlackLinkArtifact extends SlackArtifactBase {
+    kind: "link";
+    url: string;
+}
+interface SlackCanvasArtifact extends SlackArtifactBase {
+    kind: "canvas";
+    markdown: string;
+    /**
+     * When set, updates an existing canvas instead of creating one.
+     */
+    canvasId?: string;
+    /**
+     * Create a channel canvas when a channel is available.
+     *
+     * @default true
+     */
+    channelCanvas?: boolean;
+}
+type SlackArtifact = SlackTextArtifact | SlackFileArtifact | SlackImageArtifact | SlackLinkArtifact | SlackCanvasArtifact;
+interface SlackArtifactPostMessageResponse {
+    ok?: boolean;
+    channel?: string;
+    ts?: string;
+    [key: string]: unknown;
+}
+interface SlackArtifactFileUploadResponse {
+    ok?: boolean;
+    file?: {
+        id?: string;
+        [key: string]: unknown;
+    };
+    files?: Array<{
+        id?: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+interface SlackArtifactCanvasResponse {
+    ok?: boolean;
+    canvas_id?: string;
+    [key: string]: unknown;
+}
+interface SlackArtifactClient {
+    chat?: {
+        postMessage(args: Record<string, unknown>): Promise<SlackArtifactPostMessageResponse>;
+    };
+    files?: {
+        uploadV2(args: Record<string, unknown>): Promise<SlackArtifactFileUploadResponse>;
+    };
+    canvases?: {
+        create(args?: Record<string, unknown>): Promise<SlackArtifactCanvasResponse>;
+        edit?(args: Record<string, unknown>): Promise<SlackArtifactCanvasResponse>;
+    };
+    conversations?: {
+        canvases?: {
+            create(args: Record<string, unknown>): Promise<SlackArtifactCanvasResponse>;
+        };
+    };
+}
+interface PublishSlackArtifactOptions {
+    client: SlackArtifactClient;
+    artifact: SlackArtifact;
+    channelId?: string;
+    threadTs?: string;
+    token?: string;
+    unfurlLinks?: boolean;
+    unfurlMedia?: boolean;
+}
+interface SlackArtifactPublication {
+    artifact: SlackArtifact;
+    method: SlackArtifactPublishMethod;
+    response: unknown;
+    channelId?: string;
+    threadTs?: string;
+    messageTs?: string;
+    fileId?: string;
+    canvasId?: string;
+}
+
+export type { PublishSlackArtifactOptions as P, SlackArtifact as S, SlackArtifactBase as a, SlackArtifactBinaryData as b, SlackArtifactCanvasResponse as c, SlackArtifactClient as d, SlackArtifactFileUploadResponse as e, SlackArtifactPostMessageResponse as f, SlackArtifactPublication as g, SlackArtifactPublishMethod as h, SlackCanvasArtifact as i, SlackFileArtifact as j, SlackImageArtifact as k, SlackLinkArtifact as l, SlackTextArtifact as m };

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

@@ -24,6 +24,9 @@ contracts.
 - User profile and mention helpers.
 - Target parsing and resolution.
 - Feedback blocks and action handler.
+- Slack response sink and chat stream contracts for runtime adapters.
+- Slack interactive request Block Kit/modal builders and in-memory/Postgres
+  stores.
 - 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.
@@ -33,8 +36,8 @@ 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.
+- Agent event stream rendering and runtime-specific response orchestration.
+- Agent-specific approval and human-input controllers.
 - Product prompts, tools, audit policy, and deployment policy.
 
 Those pieces belong in runtime-specific adapters or product applications.

package/docs/reference/exports.md

@@ -8,9 +8,11 @@ keep application code close to the package boundary it uses.
 | `@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/interactive`       | `@slack/types`; `pg` only when using connection-string Postgres storage         | Slack interactive Block Kit/modal builders and request stores            |
 | `@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/responses`         | no Slack SDK runtime imports                                                    | Slack response sink and chat stream contracts for runtime adapters       |
 | `@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           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/channel-slack",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Agent-runtime-agnostic Slack channel primitives for AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,11 +56,21 @@
       "import": "./dist/history/index.js",
       "default": "./dist/history/index.js"
     },
+    "./interactive": {
+      "types": "./dist/interactive/index.d.ts",
+      "import": "./dist/interactive/index.js",
+      "default": "./dist/interactive/index.js"
+    },
     "./policy": {
       "types": "./dist/policy/index.d.ts",
       "import": "./dist/policy/index.js",
       "default": "./dist/policy/index.js"
     },
+    "./responses": {
+      "types": "./dist/responses/index.d.ts",
+      "import": "./dist/responses/index.js",
+      "default": "./dist/responses/index.js"
+    },
     "./setup": {
       "types": "./dist/setup/index.d.ts",
       "import": "./dist/setup/index.js",
@@ -71,6 +81,11 @@
       "import": "./dist/targets/index.js",
       "default": "./dist/targets/index.js"
     },
+    "./turn-controls": {
+      "types": "./dist/turn-controls/index.d.ts",
+      "import": "./dist/turn-controls/index.js",
+      "default": "./dist/turn-controls/index.js"
+    },
     "./transports": {
       "types": "./dist/transports/index.d.ts",
       "import": "./dist/transports/index.js",
@@ -148,9 +163,9 @@
     "node": ">=20"
   },
   "scripts": {
-    "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",
+    "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/interactive/index.ts src/policy/index.ts src/responses/index.ts src/setup/index.ts src/targets/index.ts src/turn-controls/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/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",
+    "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/interactive/index.ts src/policy/index.ts src/responses/index.ts src/setup/index.ts src/targets/index.ts src/turn-controls/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",