@crewhaus/channel-adapter-slack 0.3.1 → 0.4.0

package/dist/approvals.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Loop contract 0.4 (Batch C, G11) — Slack's interactive approval surface.
+ *
+ * When a channel run parks a pending tool approval, the Slack adapter renders
+ * an interactive Block Kit message with Approve / Deny buttons in the run's
+ * thread. Clicking a button POSTs Slack's interactivity webhook (a
+ * `block_actions` payload) back to the daemon's `/<adapter>/actions` route;
+ * that request is signed with the SAME `v0:${ts}:${body}` HMAC machinery as
+ * an events webhook, so the existing `verify()` authenticates it unchanged.
+ * The gateway then resolves the approval in the store and ACKs in-thread.
+ *
+ * This module is pure parse/build (no network, no `RunContext`): the adapter's
+ * `postApproval` / `ackApproval` do the I/O, and the channel-generic store +
+ * orchestration live in `@crewhaus/channel-adapter-base`.
+ */
+/** Block Kit `action_id`s for the two buttons — the interaction parser keys on
+ *  these, so they are part of the wire contract. */
+export declare const APPROVE_ACTION_ID = "crewhaus_approve";
+export declare const DENY_ACTION_ID = "crewhaus_deny";
+/** `block_id` prefix carrying the approval id (a redundant channel to the
+ *  buttons' `value`, so the id survives even if Slack ever elides `value`). */
+export declare const APPROVAL_BLOCK_ID_PREFIX = "crewhaus_approval:";
+/** The content a parked approval renders — mirrors channel-adapter-base's
+ *  `postApproval` argument (kept local so this package needs no cross-dep). */
+export type ApprovalPromptContent = {
+    readonly approvalId: string;
+    readonly toolName: string;
+    readonly inputPreview: string;
+    readonly surface: string;
+};
+/** A built Slack message: `text` is the notification/accessibility fallback,
+ *  `blocks` the interactive Block Kit payload. */
+export type SlackApprovalMessage = {
+    readonly text: string;
+    readonly blocks: readonly unknown[];
+};
+/**
+ * Build the Approve/Deny Block Kit message for a parked approval. Each button
+ * carries the `approvalId` in its `value`, and the actions block's `block_id`
+ * carries it too (`crewhaus_approval:<id>`), so the interaction parser can
+ * recover the id from either.
+ */
+export declare function buildApprovalMessage(content: ApprovalPromptContent): SlackApprovalMessage;
+/**
+ * The one-line "decision recorded" message the ACK replaces the buttons with,
+ * so a resolved approval can't be clicked twice and the thread shows who
+ * decided. Returned as text + a single context block (buttons removed).
+ */
+export declare function buildApprovalAckMessage(args: {
+    readonly decision: "grant" | "deny";
+    readonly by: string;
+    readonly toolName?: string;
+}): SlackApprovalMessage;
+/** A parsed Slack interactivity webhook. Only Approve/Deny `block_actions` are
+ *  surfaced; every other interaction type is `skip`. */
+export type ParsedInteraction = {
+    readonly kind: "approval_action";
+    readonly approvalId: string;
+    readonly decision: "grant" | "deny";
+    /** The Slack user who clicked (deciding identity). */
+    readonly userId: string;
+    readonly channelId?: string;
+    /** ts of the message the buttons live on (for `chat.update` ACK). */
+    readonly messageTs?: string;
+    readonly threadTs?: string;
+    /** Slack's per-interaction `response_url` (30-min ACK channel). */
+    readonly responseUrl?: string;
+} | {
+    readonly kind: "skip";
+};
+/**
+ * Parse a Slack interactivity webhook body. Slack POSTs
+ * `application/x-www-form-urlencoded` with a single `payload` field holding the
+ * URL-encoded `block_actions` JSON. Returns the normalised Approve/Deny action,
+ * or `{ kind: "skip" }` for any non-approval interaction / malformed body.
+ */
+export declare function parseSlackInteraction(body: string): ParsedInteraction;

package/dist/approvals.js

@@ -0,0 +1,187 @@
+/**
+ * Loop contract 0.4 (Batch C, G11) — Slack's interactive approval surface.
+ *
+ * When a channel run parks a pending tool approval, the Slack adapter renders
+ * an interactive Block Kit message with Approve / Deny buttons in the run's
+ * thread. Clicking a button POSTs Slack's interactivity webhook (a
+ * `block_actions` payload) back to the daemon's `/<adapter>/actions` route;
+ * that request is signed with the SAME `v0:${ts}:${body}` HMAC machinery as
+ * an events webhook, so the existing `verify()` authenticates it unchanged.
+ * The gateway then resolves the approval in the store and ACKs in-thread.
+ *
+ * This module is pure parse/build (no network, no `RunContext`): the adapter's
+ * `postApproval` / `ackApproval` do the I/O, and the channel-generic store +
+ * orchestration live in `@crewhaus/channel-adapter-base`.
+ */
+/** Block Kit `action_id`s for the two buttons — the interaction parser keys on
+ *  these, so they are part of the wire contract. */
+export const APPROVE_ACTION_ID = "crewhaus_approve";
+export const DENY_ACTION_ID = "crewhaus_deny";
+/** `block_id` prefix carrying the approval id (a redundant channel to the
+ *  buttons' `value`, so the id survives even if Slack ever elides `value`). */
+export const APPROVAL_BLOCK_ID_PREFIX = "crewhaus_approval:";
+/**
+ * Build the Approve/Deny Block Kit message for a parked approval. Each button
+ * carries the `approvalId` in its `value`, and the actions block's `block_id`
+ * carries it too (`crewhaus_approval:<id>`), so the interaction parser can
+ * recover the id from either.
+ */
+export function buildApprovalMessage(content) {
+    const text = `Approval needed: \`${content.toolName}\` wants to run (surface: ${content.surface})`;
+    const blocks = [
+        {
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: `*Approval needed* · surface \`${content.surface}\`\n\`${content.toolName}\` requested with:\n\`\`\`${truncateForBlock(content.inputPreview)}\`\`\``,
+            },
+        },
+        {
+            type: "actions",
+            block_id: `${APPROVAL_BLOCK_ID_PREFIX}${content.approvalId}`,
+            elements: [
+                {
+                    type: "button",
+                    action_id: APPROVE_ACTION_ID,
+                    text: { type: "plain_text", text: "Approve" },
+                    style: "primary",
+                    value: content.approvalId,
+                },
+                {
+                    type: "button",
+                    action_id: DENY_ACTION_ID,
+                    text: { type: "plain_text", text: "Deny" },
+                    style: "danger",
+                    value: content.approvalId,
+                },
+            ],
+        },
+        {
+            type: "context",
+            elements: [
+                {
+                    type: "mrkdwn",
+                    text: `id \`${content.approvalId}\` · or run \`crewhaus approvals grant ${content.approvalId}\``,
+                },
+            ],
+        },
+    ];
+    return { text, blocks };
+}
+/**
+ * The one-line "decision recorded" message the ACK replaces the buttons with,
+ * so a resolved approval can't be clicked twice and the thread shows who
+ * decided. Returned as text + a single context block (buttons removed).
+ */
+export function buildApprovalAckMessage(args) {
+    const verb = args.decision === "grant" ? "Approved" : "Denied";
+    const icon = args.decision === "grant" ? "✅" : "🚫";
+    const tool = args.toolName !== undefined ? ` \`${args.toolName}\`` : "";
+    const text = `${icon} ${verb}${tool} by ${args.by}`;
+    return {
+        text,
+        blocks: [{ type: "context", elements: [{ type: "mrkdwn", text }] }],
+    };
+}
+/**
+ * Parse a Slack interactivity webhook body. Slack POSTs
+ * `application/x-www-form-urlencoded` with a single `payload` field holding the
+ * URL-encoded `block_actions` JSON. Returns the normalised Approve/Deny action,
+ * or `{ kind: "skip" }` for any non-approval interaction / malformed body.
+ */
+export function parseSlackInteraction(body) {
+    let raw;
+    try {
+        raw = new URLSearchParams(body).get("payload");
+    }
+    catch {
+        return { kind: "skip" };
+    }
+    if (raw === null)
+        return { kind: "skip" };
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "skip" };
+    }
+    if (typeof payload !== "object" || payload === null)
+        return { kind: "skip" };
+    const p = payload;
+    if (p["type"] !== "block_actions")
+        return { kind: "skip" };
+    const actions = p["actions"];
+    if (!Array.isArray(actions) || actions.length === 0)
+        return { kind: "skip" };
+    const action = actions[0];
+    if (action === undefined)
+        return { kind: "skip" };
+    const decision = action["action_id"] === APPROVE_ACTION_ID
+        ? "grant"
+        : action["action_id"] === DENY_ACTION_ID
+            ? "deny"
+            : undefined;
+    if (decision === undefined)
+        return { kind: "skip" };
+    // Prefer the button's `value`; fall back to the actions block_id suffix.
+    const approvalId = (typeof action["value"] === "string" && action["value"].length > 0
+        ? action["value"]
+        : undefined) ?? approvalIdFromBlockId(action["block_id"]);
+    if (approvalId === undefined)
+        return { kind: "skip" };
+    const user = p["user"];
+    const userId = typeof user === "object" &&
+        user !== null &&
+        typeof user["id"] === "string"
+        ? user["id"]
+        : undefined;
+    if (userId === undefined)
+        return { kind: "skip" };
+    const channel = p["channel"];
+    const channelId = typeof channel === "object" &&
+        channel !== null &&
+        typeof channel["id"] === "string"
+        ? channel["id"]
+        : undefined;
+    const message = p["message"];
+    const messageRec = typeof message === "object" && message !== null
+        ? message
+        : undefined;
+    const messageTs = typeof messageRec?.["ts"] === "string" ? messageRec["ts"] : undefined;
+    const container = p["container"];
+    const containerRec = typeof container === "object" && container !== null
+        ? container
+        : undefined;
+    const threadTs = (typeof messageRec?.["thread_ts"] === "string"
+        ? messageRec["thread_ts"]
+        : undefined) ??
+        (typeof containerRec?.["thread_ts"] === "string"
+            ? containerRec["thread_ts"]
+            : undefined);
+    const responseUrl = typeof p["response_url"] === "string" ? p["response_url"] : undefined;
+    return {
+        kind: "approval_action",
+        approvalId,
+        decision,
+        userId,
+        ...(channelId !== undefined ? { channelId } : {}),
+        ...(messageTs !== undefined ? { messageTs } : {}),
+        ...(threadTs !== undefined ? { threadTs } : {}),
+        ...(responseUrl !== undefined ? { responseUrl } : {}),
+    };
+}
+function approvalIdFromBlockId(blockId) {
+    if (typeof blockId !== "string")
+        return undefined;
+    if (!blockId.startsWith(APPROVAL_BLOCK_ID_PREFIX))
+        return undefined;
+    const id = blockId.slice(APPROVAL_BLOCK_ID_PREFIX.length);
+    return id.length > 0 ? id : undefined;
+}
+/** Slack's ```code``` fences break if the preview itself contains a triple
+ *  backtick; strip them and cap the length so the block stays well-formed. */
+function truncateForBlock(preview, max = 500) {
+    const safe = preview.replace(/```/g, "'''");
+    return safe.length > max ? `${safe.slice(0, max)}…` : safe;
+}

package/dist/index.d.ts

@@ -23,7 +23,9 @@
  * surface minimal.
  */
 import { CrewhausError } from "@crewhaus/errors";
+import { type ApprovalPromptContent, type ParsedInteraction } from "./approvals.js";
 export { signSlackBody, verifySlackSignature } from "./verify.js";
+export { APPROVE_ACTION_ID, DENY_ACTION_ID, APPROVAL_BLOCK_ID_PREFIX, type ApprovalPromptContent, type SlackApprovalMessage, type ParsedInteraction, buildApprovalMessage, buildApprovalAckMessage, parseSlackInteraction, } from "./approvals.js";
 export declare class SlackAdapterError extends CrewhausError {
     readonly name = "SlackAdapterError";
     constructor(message: string, cause?: unknown);
@@ -111,6 +113,38 @@ export interface ChannelAdapter {
         event: InboundEvent;
         emoji: string;
     }): Promise<void>;
+    /**
+     * Loop contract 0.4 (Batch C, G11) — post an interactive Approve/Deny
+     * approval message into the run's thread and return the posted message ts
+     * (for a later `chat.update` ACK). Only adapters with interactive buttons
+     * (Slack) implement this; the channel-generic `postApprovalPrompt` falls
+     * back to a text message via `sendReply` when it is undefined.
+     */
+    postApproval?(args: {
+        event: InboundEvent;
+        approval: ApprovalPromptContent;
+    }): Promise<{
+        messageTs?: string;
+    }>;
+    /**
+     * G11 — parse this channel's interactivity webhook (a button click) into a
+     * normalised approval action. Undefined for adapters without interactive
+     * buttons; the gateway's `/<adapter>/actions` route no-ops for them.
+     */
+    parseInteraction?(req: RawRequest): ParsedInteraction;
+    /**
+     * G11 — ACK a resolved approval in-thread: replace the buttons with a
+     * "decision recorded" line so it can't be clicked twice and the thread shows
+     * who decided. Best-effort — a failure here must not fail the resolution.
+     */
+    ackApproval?(args: {
+        interaction: Extract<ParsedInteraction, {
+            kind: "approval_action";
+        }>;
+        decision: "grant" | "deny";
+        by: string;
+        toolName?: string;
+    }): Promise<void>;
 }
 export type SlackAdapterConfig = {
     readonly botToken: string;

package/dist/index.js

@@ -23,8 +23,11 @@
  * surface minimal.
  */
 import { CrewhausError } from "@crewhaus/errors";
+import { buildApprovalAckMessage, buildApprovalMessage, parseSlackInteraction, } from "./approvals.js";
 import { signSlackBody, verifySlackSignature } from "./verify.js";
 export { signSlackBody, verifySlackSignature } from "./verify.js";
+// Loop contract 0.4 (Batch C, G11) — Slack interactive approval surface.
+export { APPROVE_ACTION_ID, DENY_ACTION_ID, APPROVAL_BLOCK_ID_PREFIX, buildApprovalMessage, buildApprovalAckMessage, parseSlackInteraction, } from "./approvals.js";
 export class SlackAdapterError extends CrewhausError {
     name = "SlackAdapterError";
     constructor(message, cause) {
@@ -207,5 +210,92 @@ export function createSlackAdapter(config, opts = {}) {
                 }
             }
         },
+        // G11 — post the interactive Approve/Deny approval message into the run's
+        // thread. Returns the posted message ts so the gateway can `chat.update`
+        // the buttons away when the approval resolves.
+        async postApproval(args) {
+            const message = buildApprovalMessage(args.approval);
+            const url = `${apiBaseUrl}/chat.postMessage`;
+            const threadKey = args.event.threadTs ?? args.event.ts;
+            const res = await doFetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json; charset=utf-8",
+                    Authorization: `Bearer ${config.botToken}`,
+                },
+                body: JSON.stringify({
+                    channel: args.event.channelId,
+                    thread_ts: threadKey,
+                    text: message.text,
+                    blocks: message.blocks,
+                }),
+            });
+            if (!res.ok) {
+                throw new SlackAdapterError(`chat.postMessage (approval) failed: ${res.status} ${res.statusText}`);
+            }
+            const ct = res.headers.get("content-type") ?? "";
+            if (ct.includes("application/json")) {
+                const body = (await res.json());
+                if (body.ok === false) {
+                    throw new SlackAdapterError(`chat.postMessage (approval) error: ${body.error ?? "unknown"}`);
+                }
+                return typeof body.ts === "string" ? { messageTs: body.ts } : {};
+            }
+            return {};
+        },
+        // G11 — parse Slack's interactivity webhook (a block_actions button click).
+        parseInteraction(req) {
+            return parseSlackInteraction(req.body);
+        },
+        // G11 — ACK a resolved approval in-thread. Prefers the interaction's
+        // `response_url` (no extra scope, replaces the original message); falls
+        // back to `chat.update` with the bot token when the message ts is known.
+        async ackApproval(args) {
+            const ack = buildApprovalAckMessage({
+                decision: args.decision,
+                by: args.by,
+                ...(args.toolName !== undefined ? { toolName: args.toolName } : {}),
+            });
+            if (args.interaction.responseUrl !== undefined) {
+                const res = await doFetch(args.interaction.responseUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json; charset=utf-8" },
+                    body: JSON.stringify({
+                        replace_original: true,
+                        text: ack.text,
+                        blocks: ack.blocks,
+                    }),
+                });
+                if (!res.ok) {
+                    throw new SlackAdapterError(`approval ack (response_url) failed: ${res.status} ${res.statusText}`);
+                }
+                return;
+            }
+            if (args.interaction.channelId !== undefined && args.interaction.messageTs !== undefined) {
+                const res = await doFetch(`${apiBaseUrl}/chat.update`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json; charset=utf-8",
+                        Authorization: `Bearer ${config.botToken}`,
+                    },
+                    body: JSON.stringify({
+                        channel: args.interaction.channelId,
+                        ts: args.interaction.messageTs,
+                        text: ack.text,
+                        blocks: ack.blocks,
+                    }),
+                });
+                if (!res.ok) {
+                    throw new SlackAdapterError(`approval ack (chat.update) failed: ${res.status} ${res.statusText}`);
+                }
+                const ct = res.headers.get("content-type") ?? "";
+                if (ct.includes("application/json")) {
+                    const body = (await res.json());
+                    if (body.ok === false) {
+                        throw new SlackAdapterError(`approval ack (chat.update) error: ${body.error ?? "unknown"}`);
+                    }
+                }
+            }
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/channel-adapter-slack",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Slack channel adapter: webhook signature verification, event parsing, reply-to-thread (Section 12)",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.3.1"
+    "@crewhaus/errors": "0.4.0"
   },
   "license": "Apache-2.0",
   "author": {