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

package/dist/socket.js

@@ -1,15 +1,12 @@
 import {
   mountSlackAgentAppSocket,
   mountSlackAssistantAgentSocket
-} from "./chunk-IWUYIAY5.js";
-import "./chunk-M64Z6TYL.js";
-import "./chunk-BFUPAJON.js";
-import "./chunk-VHGV66M7.js";
-import "./chunk-FDRQOG7Q.js";
-import "./chunk-GNXWTKQ6.js";
-import "./chunk-DHPD4XH5.js";
-import "./chunk-ANIZ5NT4.js";
-import "./chunk-I2KLQ2HA.js";
+} from "./chunk-VMVQIDNR.js";
+import "./chunk-7DUO5BMW.js";
+import "./chunk-MGBNGG4D.js";
+import "./chunk-ELR6MQD7.js";
+import "./chunk-FQWFB54C.js";
+import "./chunk-TMADMHBN.js";
 export {
   mountSlackAgentAppSocket,
   mountSlackAssistantAgentSocket

package/dist/source/index.d.ts

@@ -0,0 +1,154 @@
+import { AgentEvent, Logger } from '@cuylabs/agent-core';
+import { DispatchEventStore } from '@cuylabs/agent-core/dispatch';
+import { SlackChannelType } from '@cuylabs/channel-slack/core';
+
+interface SlackAgentEventQueueState {
+    deliveredSequences: Set<number>;
+    lastQueuedStatusByKey: Map<string, string>;
+    sessionId?: string;
+    turnId?: string;
+}
+interface SlackAgentEventQueue {
+    push(event: AgentEvent, coalesce?: (previous: AgentEvent, next: AgentEvent) => AgentEvent | undefined): void;
+}
+interface RouteSlackAgentEventOptions {
+    event: AgentEvent;
+    logger?: Pick<Logger, "debug">;
+    onRecord?: (event: AgentEvent, sequence?: number) => void;
+    queue: SlackAgentEventQueue;
+    sequence?: number;
+    state: SlackAgentEventQueueState;
+}
+declare function coalesceSlackAgentEvents(previous: AgentEvent, next: AgentEvent): AgentEvent | undefined;
+declare function routeSlackAgentEvent({ event, logger, onRecord, queue, sequence, state, }: RouteSlackAgentEventOptions): boolean;
+declare function shouldQueueSlackAgentEvent({ event, logger, sequence, state, }: {
+    event: AgentEvent;
+    logger?: Pick<Logger, "debug">;
+    sequence?: number;
+    state: SlackAgentEventQueueState;
+}): boolean;
+
+declare function immediateSlackTextResponse(text: string): AsyncGenerator<AgentEvent>;
+declare function isSlackCancelMessage(message: string): boolean;
+type SlackTypedApprovalAction = "allow" | "deny" | "remember";
+declare function resolveSlackTypedApprovalAction(message: string): SlackTypedApprovalAction | undefined;
+declare function isRunningAgentTurnError(error: unknown): boolean;
+declare function isAbortLikeError(error: unknown): boolean;
+
+type SlackTurnPhase = "starting" | "reasoning" | "tool-running" | "waiting-approval" | "waiting-input" | "streaming" | "completed" | "failed" | "cancelled";
+interface SlackActiveToolCall {
+    startedAtMs: number;
+    toolCallId: string;
+    toolName: string;
+}
+interface SlackTurnActivityState {
+    currentTool?: SlackActiveToolCall;
+    lastActivityAtMs: number;
+    phase: SlackTurnPhase;
+}
+interface SlackTurnStatusVisibilityState extends SlackTurnActivityState {
+    eventCounts: Record<string, number>;
+    firstEventAtMs?: number;
+    firstEventType?: string;
+    sessionId?: string;
+    startedAtMs: number;
+    statusWarningsSent: Set<string>;
+    turnId?: string;
+}
+interface SlackTurnStatusVisibilityOptions {
+    checkIntervalMs?: number;
+    toolStaleWarningMs?: number;
+    turnStaleWarningMs?: number;
+}
+interface ResolvedSlackTurnStatusVisibilityOptions {
+    checkIntervalMs: number;
+    toolStaleWarningMs: number;
+    turnStaleWarningMs: number;
+}
+interface SlackTurnStatusVisibilityWarning {
+    elapsedMs: number;
+    firstEventLatencyMs?: number;
+    firstEventType?: string;
+    id: string;
+    idleMs: number;
+    message: string;
+    phase: SlackTurnPhase;
+    receivedEventCount: number;
+    sessionId?: string;
+    staleBeforeFirstEvent: boolean;
+    thresholdMs: number;
+    toolCallId?: string;
+    toolName?: string;
+    turnId?: string;
+    type: "tool" | "turn";
+}
+interface InspectSlackTurnStatusVisibilityOptions {
+    formatToolStaleStatus?: (toolName: string) => string;
+    formatTurnStaleStatus?: (phase: SlackTurnPhase) => string;
+    nowMs?: number;
+    options: ResolvedSlackTurnStatusVisibilityOptions;
+    state: SlackTurnStatusVisibilityState;
+}
+declare function resolveSlackTurnStatusVisibilityOptions(options: SlackTurnStatusVisibilityOptions | undefined): ResolvedSlackTurnStatusVisibilityOptions;
+declare function shouldInspectSlackTurnStatusVisibility(options: ResolvedSlackTurnStatusVisibilityOptions): boolean;
+declare function recordSlackTurnActivity(state: SlackTurnActivityState, event: AgentEvent, nowMs?: number): void;
+declare function inspectSlackTurnStatusVisibility({ formatToolStaleStatus, formatTurnStaleStatus, nowMs, options, state, }: InspectSlackTurnStatusVisibilityOptions): SlackTurnStatusVisibilityWarning | undefined;
+declare function isSlackWaitingForHumanTurnPhase(phase: SlackTurnPhase): boolean;
+declare function isSlackTerminalTurnPhase(phase: SlackTurnPhase): boolean;
+
+type SlackSubagentStartedEvent = Extract<AgentEvent, {
+    type: "subagent-start";
+}>;
+type SlackSubagentTerminalEvent = Extract<AgentEvent, {
+    type: "subagent-complete" | "subagent-error";
+}>;
+interface SlackSubagentCompletionSlackContext {
+    channelId?: string;
+    channelType?: SlackChannelType;
+    messageTs?: string;
+    teamId?: string;
+    threadTs?: string;
+}
+interface SlackSubagentCompletionTurnContext {
+    sessionId: string;
+    slack?: SlackSubagentCompletionSlackContext;
+    turnId: string;
+}
+interface SlackSubagentCompletionMessage {
+    blocks?: unknown[];
+    channel: string;
+    text: string;
+    thread_ts?: string;
+}
+type SlackSubagentCompletionPoster = (message: SlackSubagentCompletionMessage) => Promise<void>;
+interface SlackSubagentCompletionRun {
+    dispatchId: string;
+    role: string;
+    sessionId: string;
+    slack: Required<Pick<SlackSubagentCompletionSlackContext, "channelId" | "threadTs">> & Omit<SlackSubagentCompletionSlackContext, "channelId" | "threadTs">;
+    title: string;
+    turnId: string;
+}
+interface SlackSubagentCompletionMessageFormatterOptions {
+    event: SlackSubagentTerminalEvent;
+    run: SlackSubagentCompletionRun;
+}
+interface SlackSubagentCompletionNotifierOptions {
+    enabled?: boolean;
+    formatMessage?: (options: SlackSubagentCompletionMessageFormatterOptions) => SlackSubagentCompletionMessage;
+    logger?: Pick<Logger, "debug" | "info" | "warn">;
+    postMessage?: SlackSubagentCompletionPoster;
+}
+declare function createSlackSubagentCompletionNotifier({ enabled, formatMessage, logger, postMessage: initialPostMessage, }?: SlackSubagentCompletionNotifierOptions): {
+    clear(): void;
+    markResultDeliveredInline: (event: SlackSubagentTerminalEvent) => void;
+    markTurnDetached: (turnId: string) => void;
+    postDetachedCompletionsFromEventStore: (eventStore: DispatchEventStore) => Promise<void>;
+    postTerminalEvent: (event: SlackSubagentTerminalEvent) => Promise<void>;
+    setPostMessage(nextPostMessage: SlackSubagentCompletionPoster | undefined): void;
+    trackStartedRun: (turn: SlackSubagentCompletionTurnContext, event: SlackSubagentStartedEvent) => void;
+};
+declare function isSlackSubagentTerminalEvent(event: AgentEvent): event is SlackSubagentTerminalEvent;
+declare function formatDefaultSlackSubagentCompletionMessage({ event, run, }: SlackSubagentCompletionMessageFormatterOptions): SlackSubagentCompletionMessage;
+
+export { type InspectSlackTurnStatusVisibilityOptions, type ResolvedSlackTurnStatusVisibilityOptions, type RouteSlackAgentEventOptions, type SlackActiveToolCall, type SlackAgentEventQueue, type SlackAgentEventQueueState, type SlackSubagentCompletionMessage, type SlackSubagentCompletionMessageFormatterOptions, type SlackSubagentCompletionNotifierOptions, type SlackSubagentCompletionPoster, type SlackSubagentCompletionRun, type SlackSubagentCompletionSlackContext, type SlackSubagentCompletionTurnContext, type SlackTurnActivityState, type SlackTurnPhase, type SlackTurnStatusVisibilityOptions, type SlackTurnStatusVisibilityState, type SlackTurnStatusVisibilityWarning, type SlackTypedApprovalAction, coalesceSlackAgentEvents, createSlackSubagentCompletionNotifier, formatDefaultSlackSubagentCompletionMessage, immediateSlackTextResponse, inspectSlackTurnStatusVisibility, isAbortLikeError, isRunningAgentTurnError, isSlackCancelMessage, isSlackSubagentTerminalEvent, isSlackTerminalTurnPhase, isSlackWaitingForHumanTurnPhase, recordSlackTurnActivity, resolveSlackTurnStatusVisibilityOptions, resolveSlackTypedApprovalAction, routeSlackAgentEvent, shouldInspectSlackTurnStatusVisibility, shouldQueueSlackAgentEvent };

package/dist/source/index.js

@@ -0,0 +1,38 @@
+import {
+  coalesceSlackAgentEvents,
+  createSlackSubagentCompletionNotifier,
+  formatDefaultSlackSubagentCompletionMessage,
+  immediateSlackTextResponse,
+  inspectSlackTurnStatusVisibility,
+  isAbortLikeError,
+  isRunningAgentTurnError,
+  isSlackCancelMessage,
+  isSlackSubagentTerminalEvent,
+  isSlackTerminalTurnPhase,
+  isSlackWaitingForHumanTurnPhase,
+  recordSlackTurnActivity,
+  resolveSlackTurnStatusVisibilityOptions,
+  resolveSlackTypedApprovalAction,
+  routeSlackAgentEvent,
+  shouldInspectSlackTurnStatusVisibility,
+  shouldQueueSlackAgentEvent
+} from "../chunk-C7VSW4ZM.js";
+export {
+  coalesceSlackAgentEvents,
+  createSlackSubagentCompletionNotifier,
+  formatDefaultSlackSubagentCompletionMessage,
+  immediateSlackTextResponse,
+  inspectSlackTurnStatusVisibility,
+  isAbortLikeError,
+  isRunningAgentTurnError,
+  isSlackCancelMessage,
+  isSlackSubagentTerminalEvent,
+  isSlackTerminalTurnPhase,
+  isSlackWaitingForHumanTurnPhase,
+  recordSlackTurnActivity,
+  resolveSlackTurnStatusVisibilityOptions,
+  resolveSlackTypedApprovalAction,
+  routeSlackAgentEvent,
+  shouldInspectSlackTurnStatusVisibility,
+  shouldQueueSlackAgentEvent
+};

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

@@ -0,0 +1,18 @@
+# Channel Slack Agent Core Docs
+
+`@cuylabs/channel-slack-agent-core` is the `@cuylabs/agent-core` runtime binding
+for direct Slack traffic. It composes `@cuylabs/channel-slack` primitives with
+Agent Core turn sources, event streams, scopes, context fragments, approvals,
+and human-input requests.
+
+## Reference
+
+- [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.

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/boundary.md

@@ -0,0 +1,22 @@
+# Package Boundary
+
+This package owns only the `@cuylabs/agent-core` Slack binding.
+
+## In This Package
+
+- Mapping Slack turns to `AgentTurnSource.chat(...)`.
+- Creating Agent Core scopes and context fragments.
+- Converting `AgentEvent` streams to Slack messages or chat streams.
+- Mounting Agent Core sources on Express Events API and Socket Mode surfaces.
+- Binding Slack Assistant lifecycle handlers to Agent Core turns.
+- Handling Agent Core approval and human-input requests in Slack.
+- Agent Core helpers for Slack history context fragments and source events.
+
+## Outside This Package
+
+- Generic Slack activity parsing, formatting, setup, auth, policy, history,
+  targets, users, entrypoints, artifacts, and transport factories.
+- Product prompts, tools, audit policy, privacy rules, and deployment policy.
+- Slack app configuration outside the reusable setup helpers.
+
+Generic Slack mechanics live in `@cuylabs/channel-slack`.

package/docs/reference/exports.md

@@ -0,0 +1,26 @@
+# Exports
+
+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/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`.