@cuylabs/channel-slack 0.11.0 → 0.12.0

package/README.md

@@ -4,10 +4,10 @@ Agent-runtime-agnostic Slack channel primitives.
 
 This package owns reusable Slack mechanics: event parsing, message admission,
 history loading, formatting, setup inspection, auth helpers, entrypoint
-normalization, artifact publishing, interactive request rendering/storage,
-response sink contracts, Slack Assistant/classic message mounting, and HTTP or
-Socket Mode transport helpers. It does not create or run an agent, and it does
-not depend on an agent SDK.
+normalization, artifact publishing, interactive request rendering/storage and
+controller wiring, response sink contracts, Slack Assistant/classic message
+mounting, and HTTP or Socket Mode transport helpers. It does not create or run
+an agent, and it does not depend on an agent SDK.
 
 Runtime-specific adapters should compose these primitives with their own turn
 types, event streams, tools, prompts, and deployment policy.
@@ -71,9 +71,29 @@ await mountSlackAppSocket({
 });
 ```
 
+Add the Slack-native approval/human-input controller from the `interactive`
+subpath when your runtime can pause on interactive request events:
+
+```typescript
+import { createSlackInteractiveController } from "@cuylabs/channel-slack/interactive";
+import { mountSlackAppSocket } from "@cuylabs/channel-slack/socket";
+
+const interactive = createSlackInteractiveController({
+  namespace: "my_agent_slack",
+});
+
+await mountSlackAppSocket({
+  source,
+  interactive,
+  appToken: process.env.SLACK_APP_TOKEN,
+  botToken: process.env.SLACK_BOT_TOKEN,
+});
+```
+
 ## Documentation
 
 - [Package boundary](docs/reference/channel-slack-boundary.md)
+- [Interactive requests](docs/concepts/interactive-requests.md)
 - [Exports and peer expectations](docs/reference/exports.md)
 - [Source layout](docs/reference/source-layout.md)
 - [Docs index](docs/README.md)

package/dist/interactive/index.d.ts

@@ -1,7 +1,9 @@
-import { c as SlackInteractiveApprovalRequest, S as SlackInteractiveActionIds, e as SlackInteractiveHumanInputRequest, l as SlackInteractiveResolution, i as SlackInteractiveRequestRecord, k as SlackInteractiveRequestStore } from '../types-Cywfj8Mj.js';
-export { a as SlackInteractiveActor, b as SlackInteractiveApprovalAction, d as SlackInteractiveHumanInputOption, f as SlackInteractiveHumanInputResponse, g as SlackInteractiveMessageTarget, h as SlackInteractiveRequestHandler, j as SlackInteractiveRequestStatus, m as SlackInteractiveStoredRequest } from '../types-Cywfj8Mj.js';
+import { c as SlackInteractiveApprovalRequest, S as SlackInteractiveActionIds, e as SlackInteractiveHumanInputRequest, l as SlackInteractiveResolution, i as SlackInteractiveRequestRecord, k as SlackInteractiveRequestStore, f as SlackInteractiveHumanInputResponse, a as SlackInteractiveActor } from '../types-Cywfj8Mj.js';
+export { b as SlackInteractiveApprovalAction, d as SlackInteractiveHumanInputOption, g as SlackInteractiveMessageTarget, h as SlackInteractiveRequestHandler, j as SlackInteractiveRequestStatus, m as SlackInteractiveStoredRequest } from '../types-Cywfj8Mj.js';
 import { View } from '@slack/types';
-export { c as SlackInteractiveMessage, d as SlackInteractiveMessageRef, f as SlackInteractiveRequestBaseContext, g as SlackInteractiveRequestContext, i as SlackInteractiveRequestKind, j as SlackInteractiveResponder } from '../interactive-CbKYkkc_.js';
+import { App } from '@slack/bolt';
+import { g as SlackInteractiveRequestContext } from '../interactive-CbKYkkc_.js';
+export { c as SlackInteractiveMessage, d as SlackInteractiveMessageRef, f as SlackInteractiveRequestBaseContext, i as SlackInteractiveRequestKind, j as SlackInteractiveResponder } from '../interactive-CbKYkkc_.js';
 import '../activity-ByrD9Ftr.js';
 
 declare function buildApprovalRequestMessage(request: SlackInteractiveApprovalRequest, actionIds: SlackInteractiveActionIds): {
@@ -64,4 +66,66 @@ declare function prunePostgresSlackInteractiveRequestStore({ client, pruneBatchS
     tableName?: string;
 }): Promise<PostgresSlackInteractiveRequestPruneResult>;
 
-export { type PostgresSlackInteractiveRequestPruneResult, type PostgresSlackInteractiveRequestStore, type PostgresSlackInteractiveRequestStoreOptions, SlackInteractiveActionIds, SlackInteractiveApprovalRequest, SlackInteractiveHumanInputRequest, type SlackInteractivePostgresClient, SlackInteractiveRequestRecord, SlackInteractiveRequestStore, SlackInteractiveResolution, buildApprovalRequestMessage, buildHumanInputModal, buildHumanInputRequestMessage, buildResolvedMessage, cloneRecord, createInMemorySlackInteractiveRequestStore, createPostgresSlackInteractiveRequestStore, decodeActionValue, encodeActionValue, initializePostgresSlackInteractiveRequestStore, nowIso, prunePostgresSlackInteractiveRequestStore };
+type SlackApprovalResolution = Extract<SlackInteractiveResolution, {
+    kind: "approval";
+}>;
+interface SlackInteractiveRequestWaitOptions {
+    /**
+     * Abort waiting for this request. The controller removes its local waiter and
+     * deletes the pending store record when the signal fires.
+     */
+    signal?: AbortSignal;
+    /**
+     * Override the controller-level request timeout for this request. Use `0` to
+     * disable timeout cleanup for this request.
+     */
+    timeoutMs?: number;
+}
+interface SlackInteractiveControllerOptions {
+    store?: SlackInteractiveRequestStore;
+    /**
+     * Stable namespace for default Slack action IDs. Use this when installing
+     * multiple interactive controllers in the same Slack app.
+     *
+     * @default "agent_slack"
+     */
+    namespace?: string;
+    actionIds?: Partial<SlackInteractiveActionIds>;
+    /**
+     * Default timeout for local waiters and pending store records.
+     *
+     * @default 300000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Called on every successful Slack resolution after the local waiter, if
+     * present, is resolved. Use this to fan out decisions to another runtime.
+     */
+    onResolve?: (requestId: string, resolution: SlackInteractiveResolution) => void | Promise<void>;
+    /**
+     * Authorization hook for approving/responding to pending requests.
+     *
+     * Defaults to the original Slack requester only. Return `true` for delegated
+     * approvers, channel owners, or admin policy checks.
+     */
+    authorize?: (record: SlackInteractiveRequestRecord, actor: SlackInteractiveActor) => boolean | Promise<boolean>;
+}
+interface SlackInteractiveController {
+    readonly actionIds: SlackInteractiveActionIds;
+    readonly store: SlackInteractiveRequestStore;
+    approval: {
+        onRequest(request: SlackInteractiveApprovalRequest, options?: SlackInteractiveRequestWaitOptions): Promise<SlackApprovalResolution>;
+    };
+    humanInput: {
+        onRequest(request: SlackInteractiveHumanInputRequest, options?: SlackInteractiveRequestWaitOptions): Promise<SlackInteractiveHumanInputResponse>;
+    };
+    /** Reject one pending in-process waiter and delete its pending store record. */
+    cancel(requestId: string, reason?: string): Promise<boolean>;
+    /** Shutdown helper: cancel every pending request created by this controller. */
+    cancelAll(reason?: string): Promise<void>;
+    handleInteractiveRequest(context: SlackInteractiveRequestContext): Promise<boolean>;
+    install(app: App): void;
+}
+declare function createSlackInteractiveController(options?: SlackInteractiveControllerOptions): SlackInteractiveController;
+
+export { type PostgresSlackInteractiveRequestPruneResult, type PostgresSlackInteractiveRequestStore, type PostgresSlackInteractiveRequestStoreOptions, SlackInteractiveActionIds, SlackInteractiveActor, SlackInteractiveApprovalRequest, type SlackInteractiveController, type SlackInteractiveControllerOptions, SlackInteractiveHumanInputRequest, SlackInteractiveHumanInputResponse, type SlackInteractivePostgresClient, SlackInteractiveRequestContext, SlackInteractiveRequestRecord, SlackInteractiveRequestStore, type SlackInteractiveRequestWaitOptions, SlackInteractiveResolution, buildApprovalRequestMessage, buildHumanInputModal, buildHumanInputRequestMessage, buildResolvedMessage, cloneRecord, createInMemorySlackInteractiveRequestStore, createPostgresSlackInteractiveRequestStore, createSlackInteractiveController, decodeActionValue, encodeActionValue, initializePostgresSlackInteractiveRequestStore, nowIso, prunePostgresSlackInteractiveRequestStore };

package/dist/interactive/index.js

@@ -1,3 +1,7 @@
+import {
+  openSlackModal
+} from "../chunk-IRFKUPJN.js";
+
 // src/interactive/blocks.ts
 var MAX_BLOCK_TEXT = 2800;
 function buildApprovalRequestMessage(request, actionIds) {
@@ -634,6 +638,433 @@ async function importPostgresPoolConstructor() {
 function formatImportError(error) {
   return error instanceof Error ? error.message : String(error);
 }
+
+// src/interactive/controller.ts
+var DEFAULT_NAMESPACE = "agent_slack";
+var DEFAULT_REQUEST_TIMEOUT_MS = 5 * 60 * 1e3;
+var installedActionIds = /* @__PURE__ */ new WeakMap();
+function createSlackInteractiveController(options = {}) {
+  const store = options.store ?? createInMemorySlackInteractiveRequestStore();
+  const actionIds = resolveActionIds(
+    options.namespace ?? DEFAULT_NAMESPACE,
+    options.actionIds
+  );
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const waiters = /* @__PURE__ */ new Map();
+  const pendingIds = /* @__PURE__ */ new Set();
+  async function ensurePending(kind, request) {
+    const existing = await store.get(request.id);
+    if (existing) {
+      assertRecordKind(existing, kind);
+      trackPending(existing);
+      return existing;
+    }
+    const createdAt = nowIso();
+    const record = await store.upsert({
+      id: request.id,
+      kind,
+      request,
+      status: "pending",
+      createdAt,
+      updatedAt: createdAt
+    });
+    assertRecordKind(record, kind);
+    trackPending(record);
+    return record;
+  }
+  function trackPending(record) {
+    if (record.status === "pending") {
+      pendingIds.add(record.id);
+    } else {
+      pendingIds.delete(record.id);
+    }
+  }
+  async function waitForResolution(kind, request, waitOptions = {}) {
+    const existing = await ensurePending(kind, request);
+    if (existing.status === "resolved") {
+      if (!existing.resolution) {
+        throw new Error(
+          `Slack interactive request ${request.id} is resolved without a resolution.`
+        );
+      }
+      return existing.resolution;
+    }
+    if (waiters.has(request.id)) {
+      throw new Error(
+        `Slack interactive request is already waiting: ${request.id}. Resolve or cancel the in-flight request before requesting again.`
+      );
+    }
+    return await new Promise((resolve, reject) => {
+      const cleanupCallbacks = [];
+      const timeoutMs = waitOptions.timeoutMs ?? requestTimeoutMs;
+      if (timeoutMs > 0) {
+        const timeoutId = setTimeout(() => {
+          void cancel(request.id, "Slack interactive request timed out.");
+        }, timeoutMs);
+        cleanupCallbacks.push(() => clearTimeout(timeoutId));
+      }
+      let abortImmediately = false;
+      if (waitOptions.signal) {
+        const onAbort = () => {
+          void cancel(request.id, "Slack interactive request aborted.");
+        };
+        if (waitOptions.signal.aborted) {
+          abortImmediately = true;
+        } else {
+          waitOptions.signal.addEventListener("abort", onAbort, {
+            once: true
+          });
+          cleanupCallbacks.push(
+            () => waitOptions.signal?.removeEventListener("abort", onAbort)
+          );
+        }
+      }
+      waiters.set(request.id, {
+        resolve,
+        reject,
+        cleanup: () => {
+          for (const cleanup of cleanupCallbacks.splice(0)) {
+            cleanup();
+          }
+        }
+      });
+      if (abortImmediately) {
+        void cancel(request.id, "Slack interactive request aborted.");
+      }
+    });
+  }
+  async function resolveRequest(requestId, resolution) {
+    const record = await store.resolve(requestId, resolution);
+    if (!record) {
+      const waiter2 = waiters.get(requestId);
+      if (waiter2) {
+        waiters.delete(requestId);
+        waiter2.cleanup();
+        waiter2.reject(
+          new Error(`Slack interactive request no longer exists: ${requestId}`)
+        );
+      }
+      pendingIds.delete(requestId);
+      return void 0;
+    }
+    const resolvedResolution = record.resolution ?? resolution;
+    const waiter = waiters.get(requestId);
+    if (waiter) {
+      waiters.delete(requestId);
+      waiter.cleanup();
+      waiter.resolve(resolvedResolution);
+    }
+    pendingIds.delete(requestId);
+    await options.onResolve?.(requestId, resolvedResolution);
+    return { record, resolution: resolvedResolution };
+  }
+  async function cancel(requestId, reason = "Cancelled") {
+    const waiter = waiters.get(requestId);
+    if (waiter) {
+      waiters.delete(requestId);
+      waiter.cleanup();
+      waiter.reject(new Error(reason));
+    }
+    const existing = await store.get(requestId);
+    if (existing?.status === "pending") {
+      await store.delete(requestId);
+      pendingIds.delete(requestId);
+      return true;
+    }
+    pendingIds.delete(requestId);
+    return Boolean(waiter);
+  }
+  async function cancelAll(reason = "Cancelled") {
+    await Promise.all(
+      [...pendingIds].map((requestId) => cancel(requestId, reason))
+    );
+  }
+  async function handleInteractiveRequest(context) {
+    const request = context.request;
+    const record = await ensurePending(context.kind, request);
+    if (record.status === "resolved" || record.target) {
+      return true;
+    }
+    const message = context.kind === "approval" ? buildApprovalRequestMessage(
+      request,
+      actionIds
+    ) : buildHumanInputRequestMessage(
+      request,
+      actionIds
+    );
+    const ref = await context.responder.postMessage(message);
+    await store.attachTarget(request.id, {
+      channel: ref.channel,
+      ts: ref.ts,
+      userId: context.user.userId,
+      teamId: context.user.teamId,
+      ...context.slackActivity.threadTs ? { threadTs: context.slackActivity.threadTs } : {}
+    });
+    return true;
+  }
+  function install(app) {
+    assertActionIdsCanInstall(app, actionIds);
+    app.action(actionIds.approvalAllow, async (args) => {
+      await handleAction(args, {
+        kind: "approval",
+        action: "allow"
+      });
+    });
+    app.action(actionIds.approvalDeny, async (args) => {
+      await handleAction(args, {
+        kind: "approval",
+        action: "deny"
+      });
+    });
+    app.action(actionIds.approvalRemember, async (args) => {
+      const value = firstActionValue(args);
+      const rememberScope = typeof value.rememberScope === "string" ? value.rememberScope : void 0;
+      await handleAction(args, {
+        kind: "approval",
+        action: "remember",
+        ...rememberScope ? { rememberScope } : {}
+      });
+    });
+    app.action(actionIds.humanConfirm, async (args) => {
+      await handleAction(args, {
+        kind: "human-input",
+        response: { kind: "confirm", confirmed: true, text: "Confirmed" }
+      });
+    });
+    app.action(actionIds.humanDeny, async (args) => {
+      await handleAction(args, {
+        kind: "human-input",
+        response: { kind: "confirm", confirmed: false, text: "Cancelled" }
+      });
+    });
+    app.action(actionIds.humanOpen, async (args) => {
+      await openHumanInputModal(args);
+    });
+    app.view(actionIds.humanSubmit, async (args) => {
+      await submitHumanInputModal(args);
+    });
+  }
+  async function handleAction(args, resolutionInput) {
+    const actionArgs = args;
+    await actionArgs.ack();
+    const requestId = extractRequestId(firstActionValue(args));
+    if (!requestId) return;
+    const record = await store.get(requestId);
+    if (!record || record.status === "resolved") {
+      return;
+    }
+    const actor = extractActor(actionArgs.body);
+    if (!await isAuthorized(record, actor)) {
+      await postEphemeral(
+        actionArgs,
+        "Only the original requester can resolve this request."
+      );
+      return;
+    }
+    const resolved = await resolveRequest(requestId, resolutionInput);
+    if (resolved?.record.target) {
+      await updateOriginalMessage(
+        actionArgs,
+        resolved.record,
+        resolved.resolution
+      );
+    }
+  }
+  async function openHumanInputModal(args) {
+    const actionArgs = args;
+    await actionArgs.ack();
+    const requestId = extractRequestId(firstActionValue(args));
+    if (!requestId || !actionArgs.body.trigger_id) return;
+    const record = await store.get(requestId);
+    if (!record || record.kind !== "human-input") return;
+    const actor = extractActor(actionArgs.body);
+    if (!await isAuthorized(record, actor)) {
+      await postEphemeral(
+        actionArgs,
+        "Only the original requester can answer this request."
+      );
+      return;
+    }
+    await openSlackModal({
+      client: actionArgs.client,
+      triggerId: actionArgs.body.trigger_id,
+      view: buildHumanInputModal(
+        record.request,
+        actionIds
+      )
+    });
+  }
+  async function submitHumanInputModal(args) {
+    const viewArgs = args;
+    await viewArgs.ack();
+    const requestId = extractRequestIdFromView(viewArgs.view);
+    if (!requestId) return;
+    const record = await store.get(requestId);
+    if (!record || record.kind !== "human-input" || record.status === "resolved") {
+      return;
+    }
+    const actor = extractActor(viewArgs.body);
+    if (!await isAuthorized(record, actor)) {
+      return;
+    }
+    const response = responseFromView(
+      record.request,
+      viewArgs.view
+    );
+    const resolution = {
+      kind: "human-input",
+      response
+    };
+    const resolved = await resolveRequest(requestId, resolution);
+    if (resolved?.record.target) {
+      await viewArgs.client.chat.update({
+        channel: resolved.record.target.channel,
+        ts: resolved.record.target.ts,
+        ...buildResolvedMessage(
+          "Slack response received.",
+          resolved.resolution
+        )
+      });
+    }
+  }
+  async function isAuthorized(record, actor) {
+    if (options.authorize) {
+      return await options.authorize(record, actor);
+    }
+    return record.target?.userId === actor.userId;
+  }
+  async function updateOriginalMessage(args, record, resolution) {
+    const target = record.target;
+    if (!target) return;
+    const label = resolution.kind === "approval" ? `${resolution.action} selected.` : resolution.response.text;
+    await args.client.chat.update({
+      channel: target.channel,
+      ts: target.ts,
+      ...buildResolvedMessage(label, resolution)
+    });
+  }
+  return {
+    actionIds,
+    store,
+    approval: {
+      async onRequest(request, options2) {
+        const resolution = await waitForResolution(
+          "approval",
+          request,
+          options2
+        );
+        if (resolution.kind !== "approval") {
+          throw new Error(
+            `Unexpected human-input resolution for ${request.id}.`
+          );
+        }
+        return resolution;
+      }
+    },
+    humanInput: {
+      async onRequest(request, options2) {
+        const resolution = await waitForResolution(
+          "human-input",
+          request,
+          options2
+        );
+        if (resolution.kind !== "human-input") {
+          throw new Error(`Unexpected approval resolution for ${request.id}.`);
+        }
+        return resolution.response;
+      }
+    },
+    cancel,
+    cancelAll,
+    handleInteractiveRequest,
+    install
+  };
+}
+function assertRecordKind(record, kind) {
+  if (record.kind !== kind) {
+    throw new Error(
+      `Slack interactive request ${record.id} already exists as ${record.kind}; cannot reuse it as ${kind}.`
+    );
+  }
+}
+function resolveActionIds(namespace, overrides) {
+  const prefix = normalizeActionIdNamespace(namespace);
+  return {
+    approvalAllow: `${prefix}_approval_allow`,
+    approvalDeny: `${prefix}_approval_deny`,
+    approvalRemember: `${prefix}_approval_remember`,
+    humanConfirm: `${prefix}_human_confirm`,
+    humanDeny: `${prefix}_human_deny`,
+    humanOpen: `${prefix}_human_open`,
+    humanSubmit: `${prefix}_human_submit`,
+    ...overrides ?? {}
+  };
+}
+function normalizeActionIdNamespace(namespace) {
+  const trimmed = namespace.trim();
+  if (!trimmed) {
+    throw new Error("Slack interactive action namespace cannot be empty.");
+  }
+  return trimmed;
+}
+function assertActionIdsCanInstall(app, actionIds) {
+  const ids = Object.values(actionIds);
+  const duplicateWithinController = ids.find(
+    (id, index) => ids.indexOf(id) !== index
+  );
+  if (duplicateWithinController) {
+    throw new Error(
+      `Duplicate Slack interactive action id configured: ${duplicateWithinController}`
+    );
+  }
+  const appKey = app;
+  const installed = installedActionIds.get(appKey) ?? /* @__PURE__ */ new Set();
+  const duplicate = ids.find((id) => installed.has(id));
+  if (duplicate) {
+    throw new Error(
+      `Slack interactive action id '${duplicate}' is already installed on this Bolt app. Provide a unique createSlackInteractiveController({ namespace }) or actionIds config.`
+    );
+  }
+  for (const id of ids) {
+    installed.add(id);
+  }
+  installedActionIds.set(appKey, installed);
+}
+function firstActionValue(args) {
+  const body = args.body;
+  return decodeActionValue(body.actions?.[0]?.value);
+}
+function extractRequestId(value) {
+  return typeof value.requestId === "string" && value.requestId.length > 0 ? value.requestId : void 0;
+}
+function extractRequestIdFromView(view) {
+  return extractRequestId(decodeActionValue(view.private_metadata));
+}
+function extractActor(body) {
+  return {
+    userId: body.user?.id ?? "unknown",
+    ...body.user?.team_id ?? body.team?.id ? { teamId: body.user?.team_id ?? body.team?.id } : {}
+  };
+}
+async function postEphemeral(args, text) {
+  const channel = args.body.channel?.id;
+  const user = args.body.user?.id;
+  if (!channel || !user || !args.client.chat.postEphemeral) return;
+  await args.client.chat.postEphemeral({ channel, user, text });
+}
+function responseFromView(request, view) {
+  const input = view.state?.values?.input?.value;
+  if (request.kind === "choice") {
+    const selected = input?.selected_options?.map((option) => option.value ?? "").filter(Boolean) ?? (input?.selected_option?.value ? [input.selected_option.value] : []);
+    return {
+      kind: "choice",
+      selected,
+      text: selected.join(", ")
+    };
+  }
+  const text = input?.value ?? "";
+  return { kind: "text", text };
+}
 export {
   buildApprovalRequestMessage,
   buildHumanInputModal,
@@ -642,6 +1073,7 @@ export {
   cloneRecord,
   createInMemorySlackInteractiveRequestStore,
   createPostgresSlackInteractiveRequestStore,
+  createSlackInteractiveController,
   decodeActionValue,
   encodeActionValue,
   initializePostgresSlackInteractiveRequestStore,

package/docs/README.md

@@ -15,6 +15,7 @@ your adapter or application needs.
 - [Activity parsing](concepts/activity.md)
 - [Artifacts](concepts/artifacts.md)
 - [Entrypoints](concepts/entrypoints.md)
+- [Interactive requests](concepts/interactive-requests.md)
 - [Message policy](concepts/message-policy.md)
 - [Setup requirements](concepts/setup-requirements.md)
 - [Supplemental history](concepts/supplemental-history.md)

package/docs/concepts/interactive-requests.md

@@ -0,0 +1,85 @@
+# Interactive Requests
+
+Slack interactive requests render approval and human-input requests as Slack
+buttons and modals. The controller is runtime-neutral; applications adapt their
+runtime's request shapes into the generic Slack request types exported from
+`@cuylabs/channel-slack/interactive`.
+
+Use this import path for both generic Slack runtimes and runtime adapters such
+as `@cuylabs/channel-slack-agent-core`:
+
+```typescript
+import {
+  createPostgresSlackInteractiveRequestStore,
+  createSlackInteractiveController,
+} from "@cuylabs/channel-slack/interactive";
+import { mountSlackAppSocket } from "@cuylabs/channel-slack/socket";
+
+const interactiveStore = createPostgresSlackInteractiveRequestStore({
+  connectionString: process.env.DATABASE_URL,
+  schema: "agent",
+});
+
+const interactive = createSlackInteractiveController({
+  store: interactiveStore,
+  namespace: "my_agent_slack",
+  requestTimeoutMs: 5 * 60 * 1000,
+});
+
+await mountSlackAppSocket({
+  source,
+  interactive,
+  appToken: process.env.SLACK_APP_TOKEN,
+  botToken: process.env.SLACK_BOT_TOKEN,
+});
+```
+
+`mountSlackApp`, `mountSlackAppSocket`, and `installSlackAppSurface` install the
+controller on the Bolt app and route approval/human-input events to
+`handleInteractiveRequest`. If you manually compose lower-level Bolt helpers,
+call `interactive.install(boltApp)` and pass
+`interactive.handleInteractiveRequest` to the Slack runtime or adapter options.
+
+## Runtime Hooks
+
+The controller exposes request hooks for runtimes that own approval and
+human-input decisions:
+
+```typescript
+const approval = interactive.approval.onRequest;
+const humanInput = interactive.humanInput.onRequest;
+```
+
+Use those hooks at the runtime boundary where your agent pauses for an approval
+or human response. The Slack package deliberately keeps the request shapes
+generic; runtime-specific adapters should map their event/request types before
+calling the controller.
+
+Request IDs must be unique across pending approval and human-input requests.
+The controller rejects reuse of the same ID for a different request kind so one
+Slack button cannot resolve the wrong runtime wait.
+
+## Resolution Behavior
+
+The controller persists pending requests before rendering Slack buttons. Once a
+request is resolved, duplicate button clicks return the stored first-wins
+resolution and do not overwrite it. Resolved records are not rendered again if
+the same event is replayed.
+
+By default, only the Slack user who triggered the original turn can resolve the
+request. Pass `authorize(record, actor)` to allow delegated approvers, channel
+owners, or workspace-admin policy.
+
+## 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/reference/channel-slack-boundary.md

@@ -25,8 +25,8 @@ contracts.
 - 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 interactive request Block Kit/modal builders, in-memory/Postgres stores,
+  and controller.
 - 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.
@@ -37,7 +37,10 @@ contracts.
 - Agent-runtime scopes and context-fragment middleware.
 - Runtime-specific mapping from Slack entrypoints into an agent turn.
 - Agent event stream rendering and runtime-specific response orchestration.
-- Agent-specific approval and human-input controllers.
+- Runtime-specific mapping from approval and human-input requests into the
+  generic Slack interactive request shapes.
+- Runtime-specific wiring of `approval.onRequest` and `humanInput.onRequest`
+  into an agent runtime.
 - Product prompts, tools, audit policy, and deployment policy.
 
 Those pieces belong in runtime-specific adapters or product applications.

package/docs/reference/exports.md

@@ -12,7 +12,7 @@ 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/interactive`       | `@slack/bolt`, `@slack/types`; `pg` only when using connection-string storage   | Slack interactive controller, Block Kit/modal builders, and 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, Canvas, and final-response artifact publishing  |
 | `@cuylabs/channel-slack/auth`              | no Slack SDK runtime imports; `pg` is not required                              | Auth option types, auth resolution, OAuth installation stores            |

package/docs/reference/source-layout.md

@@ -21,6 +21,7 @@ src/
     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
+  interactive/            approval/human-input controller, blocks, stores
   policy/
     message/              message admission and state-store component
   setup/                  scopes, events, manifests, setup inspection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/channel-slack",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Agent-runtime-agnostic Slack channel primitives for AI agents",
   "type": "module",
   "main": "./dist/index.js",