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

package/dist/interactive/index.d.ts

@@ -1,5 +1,6 @@
 import { i as SlackInteractiveRequestRecord, k as SlackInteractiveRequestStore, b as SlackInteractiveApprovalRequest, S as SlackInteractiveActionIds, e as SlackInteractiveHumanInputRequest, m as SlackInteractiveResolution, d as SlackInteractiveControllerOptions, c as SlackInteractiveController } from '../types-Crpil4kb.js';
 export { a as SlackInteractiveActor, f as SlackInteractiveMessageTarget, g as SlackInteractivePendingWaiter, h as SlackInteractivePostedMessage, j as SlackInteractiveRequestStatus, l as SlackInteractiveRequestWaitOptions, n as SlackInteractiveStoredRequest } from '../types-Crpil4kb.js';
+import { View } from '@slack/types';
 import '@cuylabs/agent-core';
 import '@slack/bolt';
 import '../interactive-o_NZb-Xg.js';
@@ -9,6 +10,46 @@ declare function createInMemorySlackInteractiveRequestStore(): SlackInteractiveR
 declare function nowIso(): string;
 declare function cloneRecord(record: SlackInteractiveRequestRecord): SlackInteractiveRequestRecord;
 
+interface SlackInteractivePostgresClient {
+    end?: () => Promise<void>;
+    query<T = unknown>(sql: string, values?: readonly unknown[]): Promise<{
+        rows: T[];
+        rowCount?: number | null;
+    }>;
+}
+interface PostgresSlackInteractiveRequestStoreOptions {
+    client?: SlackInteractivePostgresClient;
+    connectionString?: string;
+    ensureSchema?: boolean;
+    onPruneError?: (error: unknown) => void;
+    pruneBatchSize?: number;
+    pruneIntervalMs?: number;
+    retentionMs?: number;
+    schema?: string;
+    tableName?: string;
+}
+interface PostgresSlackInteractiveRequestStore extends SlackInteractiveRequestStore {
+    close(): Promise<void>;
+    prune(): Promise<PostgresSlackInteractiveRequestPruneResult>;
+}
+interface PostgresSlackInteractiveRequestPruneResult {
+    deleted: number;
+}
+declare function createPostgresSlackInteractiveRequestStore({ client, connectionString, ensureSchema, onPruneError, pruneBatchSize, pruneIntervalMs, retentionMs, schema, tableName, }: PostgresSlackInteractiveRequestStoreOptions): PostgresSlackInteractiveRequestStore;
+declare function initializePostgresSlackInteractiveRequestStore({ client, ensureSchema, schema, tableName, }: {
+    client: SlackInteractivePostgresClient;
+    ensureSchema?: boolean;
+    schema?: string;
+    tableName?: string;
+}): Promise<void>;
+declare function prunePostgresSlackInteractiveRequestStore({ client, pruneBatchSize, retentionMs, schema, tableName, }: {
+    client: SlackInteractivePostgresClient;
+    pruneBatchSize?: number;
+    retentionMs?: number;
+    schema?: string;
+    tableName?: string;
+}): Promise<PostgresSlackInteractiveRequestPruneResult>;
+
 declare function buildApprovalRequestMessage(request: SlackInteractiveApprovalRequest, actionIds: SlackInteractiveActionIds): {
     text: string;
     blocks: unknown[];
@@ -21,10 +62,10 @@ declare function buildResolvedMessage(label: string, resolution: SlackInteractiv
     text: string;
     blocks: unknown[];
 };
-declare function buildHumanInputModal(request: SlackInteractiveHumanInputRequest, actionIds: SlackInteractiveActionIds): Record<string, unknown>;
+declare function buildHumanInputModal(request: SlackInteractiveHumanInputRequest, actionIds: SlackInteractiveActionIds): View;
 declare function encodeActionValue(payload: Record<string, unknown>): string;
 declare function decodeActionValue(value: unknown): Record<string, unknown>;
 
 declare function createSlackInteractiveController(options?: SlackInteractiveControllerOptions): SlackInteractiveController;
 
-export { SlackInteractiveActionIds, SlackInteractiveApprovalRequest, SlackInteractiveController, SlackInteractiveControllerOptions, SlackInteractiveHumanInputRequest, SlackInteractiveRequestRecord, SlackInteractiveRequestStore, SlackInteractiveResolution, buildApprovalRequestMessage, buildHumanInputModal, buildHumanInputRequestMessage, buildResolvedMessage, cloneRecord, createInMemorySlackInteractiveRequestStore, createSlackInteractiveController, decodeActionValue, encodeActionValue, nowIso };
+export { type PostgresSlackInteractiveRequestPruneResult, type PostgresSlackInteractiveRequestStore, type PostgresSlackInteractiveRequestStoreOptions, SlackInteractiveActionIds, SlackInteractiveApprovalRequest, SlackInteractiveController, SlackInteractiveControllerOptions, SlackInteractiveHumanInputRequest, type SlackInteractivePostgresClient, SlackInteractiveRequestRecord, SlackInteractiveRequestStore, SlackInteractiveResolution, buildApprovalRequestMessage, buildHumanInputModal, buildHumanInputRequestMessage, buildResolvedMessage, cloneRecord, createInMemorySlackInteractiveRequestStore, createPostgresSlackInteractiveRequestStore, createSlackInteractiveController, decodeActionValue, encodeActionValue, initializePostgresSlackInteractiveRequestStore, nowIso, prunePostgresSlackInteractiveRequestStore };

package/dist/interactive/index.js

@@ -5,11 +5,14 @@ import {
   buildResolvedMessage,
   cloneRecord,
   createInMemorySlackInteractiveRequestStore,
+  createPostgresSlackInteractiveRequestStore,
   createSlackInteractiveController,
   decodeActionValue,
   encodeActionValue,
-  nowIso
-} from "../chunk-J6CW2RGO.js";
+  initializePostgresSlackInteractiveRequestStore,
+  nowIso,
+  prunePostgresSlackInteractiveRequestStore
+} from "../chunk-X7ILLZZP.js";
 export {
   buildApprovalRequestMessage,
   buildHumanInputModal,
@@ -17,8 +20,11 @@ export {
   buildResolvedMessage,
   cloneRecord,
   createInMemorySlackInteractiveRequestStore,
+  createPostgresSlackInteractiveRequestStore,
   createSlackInteractiveController,
   decodeActionValue,
   encodeActionValue,
-  nowIso
+  initializePostgresSlackInteractiveRequestStore,
+  nowIso,
+  prunePostgresSlackInteractiveRequestStore
 };

package/dist/{options-C7OYeNR-.d.ts → options-BcDReOJv.d.ts}

@@ -1,4 +1,5 @@
 import { AgentEvent, ApprovalEvent } from '@cuylabs/agent-core';
+import { SlackFinalResponseArtifactPublisher, SlackFinalResponseArtifactDeliveryMode, SlackFinalResponseArtifactContext, SlackFinalResponseArtifactResult } from './artifacts/index.js';
 import { a as SlackEventInteractiveRequestHandler } from './interactive-o_NZb-Xg.js';
 
 /**
@@ -13,6 +14,9 @@ type HumanInputEvent = Extract<AgentEvent, {
 type ToolStartEvent = Extract<AgentEvent, {
     type: "tool-start";
 }>;
+type ToolResultEvent = Extract<AgentEvent, {
+    type: "tool-result";
+}>;
 interface SlackEventBridgeOptions {
     showReasoning: boolean;
     /** Render root-agent tool rows/status updates. */
@@ -24,6 +28,13 @@ interface SlackEventBridgeOptions {
     formatToolTitle?: (toolName: string) => string;
     formatToolUpdate: (toolName: string) => string;
     formatToolDetails?: (event: ToolStartEvent) => string | undefined;
+    /**
+     * Format the completed tool output shown in Slack task rows.
+     *
+     * Return `undefined` to use the default generic formatter. Return `null` to
+     * intentionally omit task-row output for this tool result.
+     */
+    formatToolResultOutput?: (event: ToolResultEvent) => string | null | undefined;
     formatToolError: (toolName: string, error: string) => string;
     formatReasoningUpdate: () => string;
     formatMessageText: (text: string) => string;
@@ -65,6 +76,43 @@ interface SlackEventBridgeOptions {
     chatStreamFinalArgs?: {
         blocks?: unknown[];
     } & Record<string, unknown>;
+    /**
+     * Optional post-processing hook for publishing a rich artifact from the final
+     * accumulated response, such as a Slack Canvas for long answers.
+     */
+    publishFinalResponseArtifact?: SlackFinalResponseArtifactPublisher;
+    /**
+     * Controls whether artifact publication is additive or becomes the primary
+     * final-answer surface.
+     *
+     * - `supplemental`: finalize the Slack text normally, then publish artifact.
+     * - `replace`: publish artifact first and use a compact Slack final message.
+     *
+     * @default "supplemental"
+     */
+    finalResponseArtifactMode?: SlackFinalResponseArtifactDeliveryMode;
+    /**
+     * When replacement mode is active, continue streaming text up to this many
+     * raw characters, then suppress further text deltas and publish the full
+     * answer as an artifact at completion. This preserves normal short-answer
+     * streaming without flooding Slack for long answers.
+     *
+     * @default 4000
+     */
+    finalResponseArtifactStreamThreshold?: number;
+    /**
+     * Notice appended when replacement mode suppresses the remaining text stream.
+     */
+    formatFinalResponseArtifactContinuationNotice?: (context: Pick<SlackFinalResponseArtifactContext, "text" | "formattedText">) => string;
+    /**
+     * Final compact message used when an artifact replaces the full Slack text.
+     */
+    formatFinalResponseArtifactMessage?: (result: SlackFinalResponseArtifactResult, context: SlackFinalResponseArtifactContext) => string;
+    /**
+     * Called when `publishFinalResponseArtifact` throws. Errors from this hook
+     * are swallowed so artifact publication cannot break a completed turn.
+     */
+    onFinalResponseArtifactError?: (error: unknown, context: SlackFinalResponseArtifactContext) => void | Promise<void>;
 }
 declare function resolveSlackEventBridgeOptions(partial: Partial<SlackEventBridgeOptions>): SlackEventBridgeOptions;
 

package/dist/{options-Uf-qmQKN.d.ts → options-CdqBABcM.d.ts}

@@ -3,7 +3,7 @@ import { AssistantUserMessageMiddleware, AssistantThreadStartedMiddleware, Assis
 import { WebClient } from '@slack/web-api';
 import { SlackAuthContext, SlackAssistantThreadContext, SlackAssistantUtilities, SlackTurnPreparation, SlackAssistantTaskDisplayMode, SlackAssistantStatusUpdate, SlackAssistantSuggestedPrompts, SlackChatStreamStartArgs, SlackMessageFormattingOptions } from '@cuylabs/channel-slack/core';
 import { h as SlackInteractiveRequestHandler } from './interactive-o_NZb-Xg.js';
-import { S as SlackEventBridgeOptions } from './options-C7OYeNR-.js';
+import { S as SlackEventBridgeOptions } from './options-BcDReOJv.js';
 import { SlackFeedbackBlockOptions, SlackFeedbackHandler } from '@cuylabs/channel-slack/feedback';
 import { ParsedAssistantUserMessage } from '@cuylabs/channel-slack/assistant';
 
@@ -201,6 +201,7 @@ interface CreateSlackAssistantBridgeOptions {
     formatToolTitle?: (toolName: string) => string;
     formatToolUpdate?: (toolName: string) => string;
     formatToolDetails?: SlackEventBridgeOptions["formatToolDetails"];
+    formatToolResultOutput?: SlackEventBridgeOptions["formatToolResultOutput"];
     formatToolError?: (toolName: string, error: string) => string;
     formatReasoningUpdate?: () => string;
     chatStreamBufferSize?: number;
@@ -223,6 +224,30 @@ interface CreateSlackAssistantBridgeOptions {
      * blocks.
      */
     chatStreamFinalArgs?: SlackEventBridgeOptions["chatStreamFinalArgs"];
+    /**
+     * Optional publisher for rich artifacts derived from the final accumulated
+     * answer, such as creating a Slack Canvas for long responses.
+     */
+    publishFinalResponseArtifact?: SlackEventBridgeOptions["publishFinalResponseArtifact"];
+    /**
+     * Controls whether final-response artifacts are supplemental or replace long
+     * Slack text with a compact artifact pointer.
+     *
+     * @default "supplemental"
+     */
+    finalResponseArtifactMode?: SlackEventBridgeOptions["finalResponseArtifactMode"];
+    /**
+     * Raw-character threshold for replacement-mode streaming suppression.
+     *
+     * @default 4000
+     */
+    finalResponseArtifactStreamThreshold?: SlackEventBridgeOptions["finalResponseArtifactStreamThreshold"];
+    /** Notice emitted when replacement mode moves the remaining response to an artifact. */
+    formatFinalResponseArtifactContinuationNotice?: SlackEventBridgeOptions["formatFinalResponseArtifactContinuationNotice"];
+    /** Compact final Slack message emitted after artifact publication succeeds. */
+    formatFinalResponseArtifactMessage?: SlackEventBridgeOptions["formatFinalResponseArtifactMessage"];
+    /** Diagnostics hook for final-response artifact publishing failures. */
+    onFinalResponseArtifactError?: SlackEventBridgeOptions["onFinalResponseArtifactError"];
     formatChatMarkdown?: SlackMessageFormattingOptions;
     formatStreamError?: (error: Error) => string;
     /**

package/dist/shared/index.d.ts

@@ -1,9 +1,11 @@
 export { D as DEFAULT_SLACK_CONTEXT_FRAGMENT_KEY, S as SlackContextFragmentMiddlewareOptions, a as SlackContextFragmentPayload, b as SlackContextFragmentResolver, c as SlackContextFragmentResolverContext, d as createSlackContextFragmentMiddleware } from '../context-fragments-CQEDcjYR.js';
 import { AgentEvent } from '@cuylabs/agent-core';
-import { S as SlackEventBridgeOptions } from '../options-C7OYeNR-.js';
-export { r as resolveSlackEventBridgeOptions } from '../options-C7OYeNR-.js';
+import { S as SlackEventBridgeOptions } from '../options-BcDReOJv.js';
+export { r as resolveSlackEventBridgeOptions } from '../options-BcDReOJv.js';
+import { SlackArtifactClient } from '@cuylabs/channel-slack/artifacts';
 export { S as SlackApprovalRequest, a as SlackEventInteractiveRequestHandler, b as SlackHumanInputRequest, c as SlackInteractiveMessage, d as SlackInteractiveMessageRef, e as SlackInteractiveRequest, f as SlackInteractiveRequestBaseContext, g as SlackInteractiveRequestContext, h as SlackInteractiveRequestHandler, i as SlackInteractiveRequestKind, j as SlackInteractiveResponder } from '../interactive-o_NZb-Xg.js';
 import '@cuylabs/channel-slack/core';
+import '../artifacts/index.js';
 
 /**
  * Slack response-sink contracts consumed by the event bridge.
@@ -13,6 +15,7 @@ import '@cuylabs/channel-slack/core';
  * interface separate makes the bridge testable without a live Slack
  * connection.
  */
+
 type SlackStreamTaskStatus = "pending" | "in_progress" | "complete" | "error";
 type SlackStreamChunk = {
     type: "markdown_text";
@@ -41,7 +44,19 @@ interface SlackChatStream {
 /**
  * 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.
@@ -90,9 +105,8 @@ declare function bridgeAgentEventsToSlack(events: AsyncGenerator<AgentEvent>, si
  * `human-input-request` event reaches the Slack transport in a mode that
  * does not support in-channel resolution.
  *
- * Hosts can catch this error to fall back to message-and-error mode or to
- * route the request through a custom block / view flow. Future work will
- * add a first-class Slack rendering path here.
+ * Hosts can catch this error to fall back to message-and-error mode, or install
+ * `createSlackInteractiveController` to render and resolve requests in Slack.
  */
 declare class UnsupportedSlackInteractiveRequestError extends Error {
     readonly kind: "approval" | "human-input";
@@ -100,4 +114,4 @@ declare class UnsupportedSlackInteractiveRequestError extends Error {
     constructor(kind: "approval" | "human-input", requestId: string, message: string);
 }
 
-export { type SlackChatStream, SlackEventBridgeOptions, type SlackResponseSink, type SlackStreamChunk, type SlackStreamTaskStatus, UnsupportedSlackInteractiveRequestError, bridgeAgentEventsToSlack };
+export { type SlackArtifactPublicationTarget, type SlackChatStream, SlackEventBridgeOptions, type SlackResponseSink, type SlackStreamChunk, type SlackStreamTaskStatus, UnsupportedSlackInteractiveRequestError, bridgeAgentEventsToSlack };

package/dist/shared/index.js

@@ -6,7 +6,7 @@ import {
   UnsupportedSlackInteractiveRequestError,
   bridgeAgentEventsToSlack,
   resolveSlackEventBridgeOptions
-} from "../chunk-NOVWLAVP.js";
+} from "../chunk-TMADMHBN.js";
 export {
   DEFAULT_SLACK_CONTEXT_FRAGMENT_KEY,
   UnsupportedSlackInteractiveRequestError,

package/dist/socket.d.ts

@@ -1,17 +1,21 @@
 import { App } from '@slack/bolt';
 import { CreateSlackSocketBoltAppOptions } from '@cuylabs/channel-slack/transports/socket';
 import { SlackDirectAuthOptions, SlackDirectAuthMode } from '@cuylabs/channel-slack/auth';
-import { S as SlackAssistantBridge, C as CreateSlackAssistantBridgeOptions, b as SlackAssistantFeedbackConfig } from './options-Uf-qmQKN.js';
+import { S as SlackAssistantBridge, C as CreateSlackAssistantBridgeOptions, b as SlackAssistantFeedbackConfig } from './options-CdqBABcM.js';
 import { SlackAgentAppSurfaceOptions } from './app-surface.js';
 import { SlackFeedbackHandler } from '@cuylabs/channel-slack/feedback';
 import '@cuylabs/agent-core';
 import '@slack/web-api';
 import '@cuylabs/channel-slack/core';
 import './interactive-o_NZb-Xg.js';
-import './options-C7OYeNR-.js';
+import './options-BcDReOJv.js';
+import './artifacts/index.js';
+import '@cuylabs/channel-slack/artifacts';
 import '@cuylabs/channel-slack/assistant';
-import './types-BqRzb_Cd.js';
+import './types-CRWzJB5G.js';
 import './types-Crpil4kb.js';
+import './types-CiwGU6zC.js';
+import '@cuylabs/channel-slack/views';
 
 /**
  * Socket Mode helpers for direct Slack.

package/dist/socket.js

@@ -1,12 +1,12 @@
 import {
   mountSlackAgentAppSocket,
   mountSlackAssistantAgentSocket
-} from "./chunk-QEJ7TAZJ.js";
-import "./chunk-P7KK5GQG.js";
-import "./chunk-ZDVD46RT.js";
+} from "./chunk-VMVQIDNR.js";
+import "./chunk-7DUO5BMW.js";
+import "./chunk-MGBNGG4D.js";
 import "./chunk-ELR6MQD7.js";
-import "./chunk-TIQGJ52F.js";
-import "./chunk-NOVWLAVP.js";
+import "./chunk-FQWFB54C.js";
+import "./chunk-TMADMHBN.js";
 export {
   mountSlackAgentAppSocket,
   mountSlackAssistantAgentSocket

package/dist/{types-BqRzb_Cd.d.ts → types-CRWzJB5G.d.ts}

@@ -1,5 +1,6 @@
 import { Agent, AgentTurnSource, AgentEvent, ApprovalEvent, Logger } from '@cuylabs/agent-core';
 import { SlackActivityInfo, SlackTurnRequestContext, SlackAssistantStatusUpdate, SlackChatStreamStartArgs, SlackUserIdentity, SlackTurnPreparation } from '@cuylabs/channel-slack/core';
+import { S as SlackEventBridgeOptions } from './options-BcDReOJv.js';
 import { h as SlackInteractiveRequestHandler } from './interactive-o_NZb-Xg.js';
 
 /**
@@ -13,6 +14,9 @@ type HumanInputEvent = Extract<AgentEvent, {
 type SlackToolStartEvent = Extract<AgentEvent, {
     type: "tool-start";
 }>;
+type SlackToolResultEvent = Extract<AgentEvent, {
+    type: "tool-result";
+}>;
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Session mapping strategy.
@@ -125,6 +129,13 @@ interface SlackChannelOptions {
      * @default details use the tool-start status text
      */
     formatToolDetails?: (event: SlackToolStartEvent) => string | undefined;
+    /**
+     * Format completed tool output shown in Slack task cards.
+     *
+     * Return `undefined` to use the default generic formatter. Return `null` to
+     * intentionally omit output for this result.
+     */
+    formatToolResultOutput?: (event: SlackToolResultEvent) => string | null | undefined;
     /**
      * Format the tool-error status text.
      * @default (toolName) => `⚠️ Tool ${toolName} encountered an error`
@@ -235,6 +246,30 @@ interface SlackChannelOptions {
     chatStreamFinalArgs?: {
         blocks?: unknown[];
     } & Record<string, unknown>;
+    /**
+     * Optional publisher for rich artifacts derived from the final accumulated
+     * answer, such as creating a Slack Canvas for long responses.
+     */
+    publishFinalResponseArtifact?: SlackEventBridgeOptions["publishFinalResponseArtifact"];
+    /**
+     * Controls whether final-response artifacts are supplemental or replace long
+     * Slack text with a compact artifact pointer.
+     *
+     * @default "supplemental"
+     */
+    finalResponseArtifactMode?: SlackEventBridgeOptions["finalResponseArtifactMode"];
+    /**
+     * Raw-character threshold for replacement-mode streaming suppression.
+     *
+     * @default 4000
+     */
+    finalResponseArtifactStreamThreshold?: SlackEventBridgeOptions["finalResponseArtifactStreamThreshold"];
+    /** Notice emitted when replacement mode moves the remaining response to an artifact. */
+    formatFinalResponseArtifactContinuationNotice?: SlackEventBridgeOptions["formatFinalResponseArtifactContinuationNotice"];
+    /** Compact final Slack message emitted after artifact publication succeeds. */
+    formatFinalResponseArtifactMessage?: SlackEventBridgeOptions["formatFinalResponseArtifactMessage"];
+    /** Diagnostics hook for final-response artifact publishing failures. */
+    onFinalResponseArtifactError?: SlackEventBridgeOptions["onFinalResponseArtifactError"];
     /**
      * Convert common markdown constructs emitted by models into Slack mrkdwn.
      *

package/dist/types-CiwGU6zC.d.ts

@@ -0,0 +1,56 @@
+import { App } from '@slack/bolt';
+import { SlackViewPayload, RegisterSlackViewWorkflowOptions, SlackViewWorkflowContext, SlackViewSubmissionAckResponse } from '@cuylabs/channel-slack/views';
+
+type SlackAgentViewStateValue = string | string[] | boolean | number | Record<string, unknown> | undefined;
+type SlackAgentViewStateValues = Record<string, Record<string, SlackAgentViewStateValue>>;
+declare function extractSlackAgentViewStateValues(viewOrState: SlackViewPayload | unknown): SlackAgentViewStateValues;
+declare function readSlackAgentViewStateValue(valuesOrView: SlackAgentViewStateValues | SlackViewPayload | unknown, blockId: string, actionId: string): SlackAgentViewStateValue;
+
+interface SlackAgentViewWorkflow {
+    id: string;
+    callbackId: string;
+}
+interface SlackAgentViewWorkflowContext<TMetadata = unknown> extends SlackViewWorkflowContext<TMetadata> {
+    workflow: SlackAgentViewWorkflow;
+    stateValues: SlackAgentViewStateValues;
+    getStateValue(blockId: string, actionId: string): SlackAgentViewStateValue;
+}
+interface SlackAgentViewWorkflowDefinition<TMetadata = unknown> {
+    /**
+     * Stable product/agent workflow id. Used to derive the default Slack
+     * callback id as `${namespace}_${id}`.
+     */
+    id: string;
+    /**
+     * Explicit Slack view callback id. Prefer this only when integrating with an
+     * existing Slack app surface.
+     */
+    callbackId?: string;
+    decodePrivateMetadata?: RegisterSlackViewWorkflowOptions<TMetadata>["decodePrivateMetadata"];
+    onSubmission?: (context: SlackAgentViewWorkflowContext<TMetadata>) => SlackViewSubmissionAckResponse | void | Promise<SlackViewSubmissionAckResponse | void>;
+    onClose?: (context: SlackAgentViewWorkflowContext<TMetadata>) => void | Promise<void>;
+    onError?: (error: unknown, context: Omit<SlackAgentViewWorkflowContext<TMetadata>, "metadata"> & {
+        metadata?: TMetadata | undefined;
+    }) => void | Promise<void>;
+}
+interface CreateSlackAgentViewWorkflowControllerOptions {
+    /**
+     * Namespace for derived Slack callback ids.
+     *
+     * @default "agent_slack_view"
+     */
+    namespace?: string;
+    workflows?: readonly SlackAgentViewWorkflowDefinition[];
+    onError?: (error: unknown, context: Omit<SlackAgentViewWorkflowContext, "metadata"> & {
+        metadata?: unknown;
+    }) => void | Promise<void>;
+}
+interface SlackAgentViewWorkflowController {
+    readonly namespace: string;
+    register<TMetadata = unknown>(workflow: SlackAgentViewWorkflowDefinition<TMetadata>): string;
+    callbackIdFor(workflowId: string): string;
+    list(): SlackAgentViewWorkflow[];
+    install(app: App): void;
+}
+
+export { type CreateSlackAgentViewWorkflowControllerOptions as C, type SlackAgentViewStateValue as S, type SlackAgentViewStateValues as a, type SlackAgentViewWorkflow as b, type SlackAgentViewWorkflowContext as c, type SlackAgentViewWorkflowController as d, type SlackAgentViewWorkflowDefinition as e, extractSlackAgentViewStateValues as f, readSlackAgentViewStateValue as r };

package/dist/views/index.d.ts

@@ -0,0 +1,8 @@
+import { C as CreateSlackAgentViewWorkflowControllerOptions, d as SlackAgentViewWorkflowController } from '../types-CiwGU6zC.js';
+export { S as SlackAgentViewStateValue, a as SlackAgentViewStateValues, b as SlackAgentViewWorkflow, c as SlackAgentViewWorkflowContext, e as SlackAgentViewWorkflowDefinition, f as extractSlackAgentViewStateValues, r as readSlackAgentViewStateValue } from '../types-CiwGU6zC.js';
+import '@slack/bolt';
+import '@cuylabs/channel-slack/views';
+
+declare function createSlackAgentViewWorkflowController({ namespace, workflows, onError, }?: CreateSlackAgentViewWorkflowControllerOptions): SlackAgentViewWorkflowController;
+
+export { CreateSlackAgentViewWorkflowControllerOptions, SlackAgentViewWorkflowController, createSlackAgentViewWorkflowController };

package/dist/views/index.js

@@ -0,0 +1,10 @@
+import {
+  createSlackAgentViewWorkflowController,
+  extractSlackAgentViewStateValues,
+  readSlackAgentViewStateValue
+} from "../chunk-C7CHMYV6.js";
+export {
+  createSlackAgentViewWorkflowController,
+  extractSlackAgentViewStateValues,
+  readSlackAgentViewStateValue
+};

package/docs/README.md

@@ -9,3 +9,10 @@ and human-input requests.
 
 - [Package boundary](reference/boundary.md)
 - [Exports and peer expectations](reference/exports.md)
+
+## Concepts
+
+- [Final response artifacts](concepts/final-response-artifacts.md)
+- [Interactive requests](concepts/interactive-requests.md)
+- [Tool task rendering](concepts/tool-task-rendering.md)
+- [View workflows](concepts/view-workflows.md)

package/docs/concepts/final-response-artifacts.md

@@ -0,0 +1,39 @@
+# Final Response Artifacts
+
+Final response artifacts let a Slack host publish a rich surface from the
+completed Agent Core response. The first built-in publisher creates a Slack
+Canvas for long answers and can fall back to a text file when Canvas
+publication is unavailable.
+
+```typescript
+import { createSlackFinalResponseArtifactPublisher } from "@cuylabs/channel-slack-agent-core/artifacts";
+
+const publishFinalResponseArtifact = createSlackFinalResponseArtifactPublisher({
+  minCharacters: 4000,
+  title: "Agent response",
+  fallback: "file",
+});
+
+await mountSlackAgentApp({
+  source,
+  publishFinalResponseArtifact,
+  finalResponseArtifactMode: "replace",
+  finalResponseArtifactStreamThreshold: 4000,
+});
+```
+
+By default, `finalResponseArtifactMode` is `"supplemental"`: the Slack response
+is finalized normally, then the artifact is published as an extra surface.
+
+Use `"replace"` when long answers should move to the artifact instead of being
+duplicated in chat. In chat-stream mode, the bridge streams text until
+`finalResponseArtifactStreamThreshold`, appends a continuation notice, and then
+publishes the full final text as a Canvas/file at completion. If publication
+does not produce an artifact, the bridge falls back to the full Slack text.
+
+The publisher receives the raw final text, formatted Slack text, the Slack Web
+API client, and the target channel/thread. Short responses are skipped.
+
+Canvas and file publication use `@cuylabs/channel-slack/artifacts`, so the
+required Slack scopes are the same: `canvases:write` for Canvas and
+`files:write` for file fallback.

package/docs/concepts/interactive-requests.md

@@ -0,0 +1,43 @@
+# Interactive Requests
+
+Slack interactive requests render Agent Core approval and human-input requests
+as Slack buttons and modals.
+
+```typescript
+import {
+  createPostgresSlackInteractiveRequestStore,
+  createSlackInteractiveController,
+} from "@cuylabs/channel-slack-agent-core/interactive";
+
+const interactiveStore = createPostgresSlackInteractiveRequestStore({
+  connectionString: process.env.DATABASE_URL,
+  schema: "agent",
+});
+
+const interactive = createSlackInteractiveController({
+  store: interactiveStore,
+  namespace: "my_agent_slack",
+  requestTimeoutMs: 5 * 60 * 1000,
+});
+
+// Wire these into the Agent Core runtime:
+// approval: { onRequest: interactive.approval.onRequest }
+// humanInput: { onRequest: interactive.humanInput.onRequest }
+
+// Wire the controller into the Slack app surface:
+// installSlackAgentAppSurface(boltApp, { source, interactive, ... })
+```
+
+## Store Choices
+
+- `createInMemorySlackInteractiveRequestStore` is useful for tests and local
+  single-process apps.
+- `createPostgresSlackInteractiveRequestStore` persists pending requests across
+  restarts and lets multiple Slack workers resolve the same request safely.
+
+The Postgres store uses one table keyed by request ID. `resolve(...)` is
+idempotent: the first resolution wins, and later duplicate button clicks return
+the original resolution without overwriting it.
+
+Call `close()` during shutdown when the store owns its `pg` pool. Call
+`prune()` manually when you disable the background prune timer.

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.