paperclip-plugin-slack-socket 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xCVH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# paperclip-plugin-slack-socket
+
+A Paperclip plugin that connects Slack to Paperclip over [Socket Mode](https://api.slack.com/apis/socket-mode) — Paperclip opens an outbound WebSocket connection to Slack, so no public URL, reverse proxy, or inbound webhook endpoint is required. Install it, paste in two Slack tokens and a handful of IDs, and your Paperclip agents are reachable from Slack.
+
+## What it is
+
+This plugin lets people talk to Paperclip agents from Slack and lets Paperclip push updates back into Slack, all over a single Socket Mode connection. Concretely it provides:
+
+- **Agent chat** — DM the bot, or `@mention` it in a channel it has been invited to, to start a conversation with your configured default agent. Replies stream into the thread as the agent produces them. Replying inside that thread continues the same agent session without needing to mention the bot again.
+- **Notifications** — Paperclip posts to Slack when an issue is created, when an issue is marked done, and when an agent run fails, each independently toggleable, with an optional per-category channel override (falling back to a default channel).
+- **Approvals with buttons** — when Paperclip requests an approval, the plugin posts a message with Approve/Reject buttons; clicking one calls the Paperclip REST API to decide the approval and updates the Slack message in place to show the outcome.
+- **The `ask_human` tool** — agents can pause and ask a human a question in Slack, either via an emoji reaction or a threaded text reply. The response is recorded as a comment on a Paperclip issue and wakes the issue's agent back up.
+- **`/paperclip issue <title>`** — a slash command that creates a Paperclip issue from Slack and replies with a link, visible only to the person who ran it.
+
+## Install the plugin
+
+Paperclip installs plugins instance-wide from an npm package name or a local path, via any of three equivalent routes:
+
+- **Paperclip UI** — **Settings → Plugins → Install**, then enter the npm package name.
+- **CLI** — `paperclipai plugin install <npm-package-or-absolute-path>`.
+- **REST API** — `POST /api/plugins/install` with a JSON body of `{"packageName": "...", "isLocalPath": true|false}`.
+
+This package is not yet published to npm, so today you install it from a local clone instead of by package name:
+
+```sh
+git clone https://github.com/0xCVH/paperclip-plugin-slack-socket
+cd paperclip-plugin-slack-socket
+npm install
+npm run build
+```
+
+Then install the **absolute path** to that clone via whichever route you prefer — UI (paste the absolute path where it asks for a package name), CLI (`paperclipai plugin install /absolute/path/to/paperclip-plugin-slack-socket`), or REST (`{"packageName": "/absolute/path/to/paperclip-plugin-slack-socket", "isLocalPath": true}`). Once this package is published to npm, `paperclip-plugin-slack-socket` will install by name through any of the three routes instead.
+
+Per Paperclip's plugin spec, the host running Paperclip needs a writable filesystem, `npm` available on its `PATH`, and (for npm-name installs) network access to the npm registry.
+
+## Slack setup
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**.
+2. Choose **From an app manifest**, pick the workspace you want to install into, and paste the contents of [`slack-app-manifest.json`](./slack-app-manifest.json) from this repo when prompted. Review and create the app.
+3. On the app's **Install App** page, click **Install to Workspace**, approve the requested scopes, and then copy the **Bot User OAuth Token** (starts with `xoxb-`) — you'll need it in Paperclip.
+4. Go to **Basic Information** → **App-Level Tokens** and click **Generate Token and Scopes**. Give it a name, add the `connections:write` scope, and generate it. Copy the resulting **App-Level Token** (starts with `xapp-`) — this is what lets Socket Mode open its connection.
+
+That's it on the Slack side — the manifest already enables Socket Mode, declares the bot events (`app_mention`, `message.channels`, `message.groups`, `message.im`, `reaction_added`), interactivity (for the approval buttons), and the `/paperclip` slash command, and requests the minimum bot scopes the plugin needs (`app_mentions:read`, `chat:write`, `channels:history`, `groups:history`, `im:history`, `im:read`, `im:write`, `reactions:read`, `users:read`, `commands`).
+
+## Paperclip setup
+
+1. In Paperclip, go to **Settings → Secrets** and create two secrets: one holding the Bot User OAuth Token (`xoxb-…`) and one holding the App-Level Token (`xapp-…`). Note the secret reference Paperclip shows for each (the settings form's secret-ref fields store whatever the Secrets page provides — the plugin passes it through opaquely and never sees the raw value).
+2. Install the plugin into your Paperclip instance (plugin id `cvh.slack-socket`) — see [Install the plugin](#install-the-plugin) above.
+3. Open the plugin's instance settings and fill in:
+   - **Slack Bot Token (secret reference)** — the secret reference for the bot token secret from step 1.
+   - **Slack App-Level Token (secret reference)** — the secret reference for the app token secret from step 1.
+   - **Company ID** — the Paperclip company UUID used for sessions, issues, and approvals.
+   - **Default Agent ID** — the agent that handles DM and @mention conversations.
+   - **Default Slack Channel ID** — the fallback channel for notifications (e.g. `C01ABC2DEF3`).
+   
+   These five fields are required. Optionally set per-category notification toggles (`notifyOnIssueCreated`, `notifyOnIssueDone`, `notifyOnAgentRunFailed`, `notifyOnApprovalCreated`, all on by default), per-category channel overrides (`issuesChannelId`, `errorsChannelId`, `approvalsChannelId` — each falls back to the default channel when unset), a `paperclipBaseUrl` (see below), and `sessionIdleHours` (default 24) controlling how long an idle chat session stays open before the cleanup job closes it.
+   - **Paperclip Base URL** (`paperclipBaseUrl`) — the base URL of your Paperclip instance. This is load-bearing, not just cosmetic: it's used both to build dashboard links in Slack messages *and* as the target of the approval decision REST calls (`POST {paperclipBaseUrl}/api/approvals/:id/approve|reject`).
+   - **Paperclip Board API Key** (`paperclipApiKeyRef`, optional) — a secret reference to a Paperclip API key for a board-role user. Leave empty if your Paperclip instance runs in `local_trusted` deployment mode (every request is implicitly a board actor there). Set it if your instance runs in `authenticated` mode — approval decisions (the Approve/Reject buttons) need to authenticate as a board user, and the plugin sends this key as an `Authorization: Bearer` header on those requests.
+4. Press **Test Connection**. This calls Slack's `auth.test` with the bot token (verifies it's valid) and `apps.connections.open` with the app token (verifies it has `connections:write` and Socket Mode can be established). Fix any reported error before saving — a missing or malformed token, or a token missing the `connections:write` scope, are the most common failures here.
+5. Save. The plugin resolves both secrets, opens the Socket Mode connection, and registers the `ask_human` tool and the `*/15 * * * *` cleanup job (which closes agent sessions idle beyond `sessionIdleHours` and expires unanswered `ask_human` questions past their `timeoutMinutes`, default 1440).
+
+## Usage
+
+- **DM the bot** from the Apps section of Slack's sidebar to start a private conversation with the default agent.
+- **In a channel**, first `/invite @paperclip` (the bot only sees channel messages after being invited), then `@mention` it to start a thread-scoped conversation.
+- **Reply in the thread** to continue the same agent session — no need to `@mention` the bot again once a thread has an active session.
+- Run **`/paperclip issue <title>`** anywhere to create a Paperclip issue; the confirmation with a link is ephemeral (only you see it), which requires the bot to be a member of the channel the command was run in — `/invite @paperclip` first, or run the command in a DM with the bot. (The issue is still created even if the bot isn't in the channel; only the confirmation message would fail to post.) `/paperclip help` shows usage.
+- Agents can call the **`ask_human`** tool mid-run to ask a person a question in Slack (by channel or by DMing a user), either waiting for an emoji reaction (`mode: "reaction"`) or a threaded text reply (`mode: "answer"`); the response is attached to the issue as a comment and the issue is woken up.
+
+**Note:** multi-person group DMs (mpim) are treated the same as channels — the bot only responds in an mpim thread that already has an active session; it does not start new sessions there the way it does in a 1:1 DM. Starting a conversation in an mpim isn't currently supported.
+
+## Manual smoke test checklist
+
+After installing and configuring the plugin, walk through this checklist end-to-end in a real Slack workspace:
+
+1. Plugin health shows **OK** after configuring the required fields and pressing Test Connection.
+2. DM the bot "hello" → a streamed agent reply appears in the thread.
+3. `@mention` the bot in a channel it has been invited to → it replies in a thread.
+4. Reply again in that same thread without mentioning the bot → the conversation continues in the same agent session.
+5. Create an issue in Paperclip → a Slack notification appears in the configured (or default) channel.
+6. Create an approval in Paperclip → Approve/Reject buttons appear in Slack; clicking **Approve** updates the message in place to show it was approved.
+7. Have an agent call `ask_human` with `mode: "reaction"` → react to the posted question with an emoji → a comment recording the response lands on the referenced Paperclip issue.
+8. Run `/paperclip issue Test` → an ephemeral message with a link to the new issue appears.
+
+## Security notes
+
+- **Zero inbound HTTP surface.** Socket Mode means Paperclip connects out to Slack; there is no webhook endpoint, no public URL, and nothing for an attacker to send unsolicited requests to.
+- **Tokens live only in Paperclip Secrets.** The plugin config stores secret UUIDs, never raw token values; the bot and app tokens are resolved from Paperclip's secret store at runtime and are never logged.
+- **No allowlisting yet.** Any workspace member who can DM the bot can converse with the configured default agent, and anyone who can `@mention` it in a channel it's been invited to can do the same. There is currently no per-user or per-channel allowlist — restricting who can talk to the bot is a matter of who is in the workspace and which channels it's invited to. Tighter access control (e.g. an allowlist of Slack user or channel IDs) is future work.

package/dist/approvals.d.ts

@@ -0,0 +1,11 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+import type { InboundAction, SlackGateway, SlackSocketConfig } from "./types.js";
+export interface ApprovalDeps {
+    ctx: PluginContext;
+    gateway: SlackGateway;
+    getConfig: () => Promise<SlackSocketConfig>;
+}
+export interface Approvals {
+    handleAction(action: InboundAction): Promise<void>;
+}
+export declare function createApprovals({ ctx, gateway, getConfig }: ApprovalDeps): Approvals;

package/dist/approvals.js

@@ -0,0 +1,104 @@
+import { ACTION_IDS } from "./constants.js";
+import { formatApprovalCreated, formatApprovalDecided } from "./formatters.js";
+import { errString } from "./redact.js";
+export function createApprovals({ ctx, gateway, getConfig }) {
+    ctx.events.on("approval.created", async (event) => {
+        const e = event;
+        const cfg = await getConfig();
+        if (!cfg.notifyOnApprovalCreated || !e.entityId)
+            return;
+        const channel = cfg.approvalsChannelId || cfg.defaultChannelId;
+        if (!channel)
+            return;
+        try {
+            await gateway.postMessage({
+                channel,
+                ...formatApprovalCreated(e.entityId, e.payload, cfg.paperclipBaseUrl),
+            });
+            await ctx.metrics.write("slack.notifications.sent", 1, { type: "approval_created" }).catch(() => { });
+        }
+        catch (err) {
+            ctx.logger.warn("Slack approval notification failed", { err: errString(err) });
+            await ctx.metrics.write("slack.notifications.failed", 1, { type: "approval_created" }).catch(() => { });
+        }
+    });
+    async function postFailureEphemeral(action, approvalId, decision, hint) {
+        await gateway
+            .postEphemeral({
+            channel: action.channel,
+            user: action.user,
+            text: `:x: Failed to ${decision} approval \`${approvalId}\`. ${hint}`,
+        })
+            .catch(() => { });
+    }
+    return {
+        async handleAction(action) {
+            const cfg = await getConfig();
+            const decision = action.actionId === ACTION_IDS.approvalApprove ? "approve" : "reject";
+            const approvalId = action.value;
+            if (!approvalId) {
+                ctx.logger.warn("Approval action received with an empty value; ignoring", {
+                    actionId: action.actionId,
+                    user: action.user,
+                });
+                await gateway
+                    .postEphemeral({
+                    channel: action.channel,
+                    user: action.user,
+                    text: ":x: Could not process this action — no approval id was attached to the button.",
+                })
+                    .catch(() => { });
+                return;
+            }
+            // In `local_trusted` deployment mode every request is implicitly a
+            // board actor, so no Authorization header is needed. In `authenticated`
+            // mode the server requires a board API key to authenticate the
+            // decision — resolve it only when the operator configured one.
+            let authHeaders = {};
+            if (cfg.paperclipApiKeyRef) {
+                try {
+                    const apiKey = await ctx.secrets.resolve(cfg.paperclipApiKeyRef);
+                    authHeaders = { Authorization: `Bearer ${apiKey}` };
+                }
+                catch (err) {
+                    ctx.logger.warn("Approval decision via Slack failed: could not resolve the Paperclip board API key", {
+                        err: errString(err),
+                        approvalId,
+                    });
+                    await postFailureEphemeral(action, approvalId, decision, "The configured Paperclip board API key could not be resolved — check the plugin settings.");
+                    return;
+                }
+            }
+            try {
+                const response = await ctx.http.fetch(`${cfg.paperclipBaseUrl}/api/approvals/${encodeURIComponent(approvalId)}/${decision}`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", ...authHeaders },
+                    // The server ignores decidedByUserId in the body (it uses the
+                    // authenticated actor) but does record decisionNote.
+                    body: JSON.stringify({
+                        decisionNote: `Decided via Slack by ${action.userName} (slack:${action.user})`,
+                    }),
+                });
+                if (response.status < 200 || response.status >= 300) {
+                    throw new Error(`Approval ${decision} returned HTTP ${response.status}`);
+                }
+                await gateway.updateMessage({
+                    channel: action.channel,
+                    ts: action.messageTs,
+                    ...formatApprovalDecided(approvalId, decision, action.userName),
+                });
+                await ctx.activity.log({
+                    companyId: cfg.companyId,
+                    message: `Approval ${approvalId} ${decision === "approve" ? "approved" : "rejected"} via Slack by ${action.userName} (slack:${action.user})`,
+                    entityType: "approval",
+                    entityId: approvalId,
+                });
+                await ctx.metrics.write("slack.approvals.decided", 1, { decision });
+            }
+            catch (err) {
+                ctx.logger.warn("Approval decision via Slack failed", { err: errString(err), approvalId });
+                await postFailureEphemeral(action, approvalId, decision, "It may already be decided.");
+            }
+        },
+    };
+}

package/dist/ask-human.d.ts

@@ -0,0 +1,13 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+import type { InboundMessage, InboundReaction, SlackGateway } from "./types.js";
+export interface AskHumanDeps {
+    ctx: PluginContext;
+    gateway: SlackGateway;
+}
+export interface AskHuman {
+    registerTool(): void;
+    /** Returns true when the message was an answer to a pending question (callers must stop routing it). */
+    tryHandleAnswer(msg: InboundMessage): Promise<boolean>;
+    handleReaction(reaction: InboundReaction): Promise<void>;
+}
+export declare function createAskHuman({ ctx, gateway }: AskHumanDeps): AskHuman;

package/dist/ask-human.js

@@ -0,0 +1,156 @@
+import { ASK_HUMAN_TOOL_DECLARATION, STATE_KEYS, TOOL_NAMES, stateScope } from "./constants.js";
+import { formatQuestion, formatQuestionResolved } from "./formatters.js";
+import { errString } from "./redact.js";
+import { updateIndex } from "./state-index.js";
+export function createAskHuman({ ctx, gateway }) {
+    // Same-process claim guard against the double-resolution race: two
+    // near-simultaneous events for the same pending question (e.g. a reaction
+    // and a thread reply, or two overlapping reactions) can both pass the
+    // "pending exists" read before either has written its resolution. Callers
+    // must check-and-add this set synchronously (no await in between) right
+    // after confirming the event matches a pending question, so only the
+    // first in-flight resolution for a given key proceeds.
+    const claimed = new Set();
+    async function resolvePending(key, pending, response, responderName) {
+        const body = `Slack response from ${responderName} to: "${pending.question}"\n\n${response}`;
+        await ctx.issues.createComment(pending.issueId, body, pending.companyId);
+        try {
+            await ctx.issues.requestWakeup(pending.issueId, pending.companyId, {
+                reason: "slack_ask_human_response",
+                contextSource: "slack-socket.ask-human",
+            });
+        }
+        catch (err) {
+            ctx.logger.warn("Wakeup after Slack answer failed", { err: errString(err), issueId: pending.issueId });
+        }
+        await gateway.updateMessage({
+            channel: pending.channel,
+            ts: pending.ts,
+            ...formatQuestionResolved(pending.question, response, responderName),
+        });
+        await ctx.state.delete(stateScope(key));
+        await updateIndex(ctx, STATE_KEYS.questionIndex, (current) => current.filter((k) => k !== key));
+        await ctx.metrics.write("slack.questions.answered", 1, { mode: pending.mode });
+    }
+    return {
+        registerTool() {
+            ctx.tools.register(TOOL_NAMES.askHuman, {
+                displayName: ASK_HUMAN_TOOL_DECLARATION.displayName,
+                description: ASK_HUMAN_TOOL_DECLARATION.description,
+                parametersSchema: ASK_HUMAN_TOOL_DECLARATION.parametersSchema,
+            }, async (params, runCtx) => {
+                const p = (params ?? {});
+                const question = typeof p.question === "string" ? p.question.trim() : "";
+                const target = typeof p.target === "string" ? p.target.trim() : "";
+                const mode = p.mode === "reaction" || p.mode === "answer" ? p.mode : null;
+                const issueId = typeof p.issueId === "string" ? p.issueId : "";
+                const timeoutMinutes = typeof p.timeoutMinutes === "number" && p.timeoutMinutes > 0 ? p.timeoutMinutes : 1440;
+                if (!question || !target || !mode || !issueId) {
+                    return { error: "question, target, mode and issueId are required" };
+                }
+                let posted;
+                try {
+                    // "U" is a regular user id; Enterprise Grid's cross-workspace
+                    // "connected" users get a "W" id instead. Both DM.
+                    const channel = target.startsWith("U") || target.startsWith("W") ? await gateway.openDm(target) : target;
+                    posted = await gateway.postMessage({ channel, ...formatQuestion(question, mode) });
+                }
+                catch (err) {
+                    return { error: `Failed to post question to Slack: ${errString(err)}` };
+                }
+                const key = STATE_KEYS.question(posted.channel, posted.ts);
+                try {
+                    const pending = {
+                        channel: posted.channel,
+                        ts: posted.ts,
+                        issueId,
+                        companyId: runCtx.companyId,
+                        mode,
+                        question,
+                        askedAt: new Date().toISOString(),
+                        timeoutMinutes,
+                    };
+                    await ctx.state.set(stateScope(key), pending);
+                    await updateIndex(ctx, STATE_KEYS.questionIndex, (current) => [...current, key]);
+                }
+                catch (err) {
+                    // The question is now a live, unanswerable message in Slack: it
+                    // posted successfully but we failed to record enough state to
+                    // resolve it later. Log loudly, warn in the thread best-effort,
+                    // and tell the caller the truth instead of the misleading
+                    // "failed to post" message.
+                    ctx.logger.error("Failed to track ask_human question after posting to Slack", {
+                        err: errString(err),
+                        channel: posted.channel,
+                        ts: posted.ts,
+                        issueId,
+                    });
+                    await gateway
+                        .updateMessage({
+                        channel: posted.channel,
+                        ts: posted.ts,
+                        text: ":warning: This question could not be tracked — please ask again.",
+                    })
+                        .catch((updateErr) => {
+                        ctx.logger.error("Failed to mark untracked ask_human question in Slack", {
+                            err: String(updateErr),
+                            channel: posted.channel,
+                            ts: posted.ts,
+                        });
+                    });
+                    return { error: "Question was posted to Slack but could not be tracked; ask again." };
+                }
+                try {
+                    await ctx.metrics.write("slack.questions.asked", 1, { mode });
+                }
+                catch (err) {
+                    ctx.logger.warn("Failed to write ask_human metrics", { err: errString(err) });
+                }
+                return {
+                    content: `Question posted to Slack channel ${posted.channel}. The response will be recorded as a comment on issue ${issueId}.`,
+                    data: { channel: posted.channel, ts: posted.ts },
+                };
+            });
+        },
+        async tryHandleAnswer(msg) {
+            if (!msg.threadTs || msg.threadTs === msg.ts)
+                return false;
+            const key = STATE_KEYS.question(msg.channel, msg.threadTs);
+            const pending = (await ctx.state.get(stateScope(key)));
+            if (!pending || pending.mode !== "answer")
+                return false;
+            // This message IS an answer to a pending question — claim it before
+            // any further await so a concurrent resolution for the same key
+            // can't also record it. If another in-flight call already holds the
+            // claim, this is still an answer (caller must not fall through to
+            // chat routing), so return true without re-resolving.
+            if (claimed.has(key))
+                return true;
+            claimed.add(key);
+            try {
+                const name = await gateway.getUserDisplayName(msg.user);
+                await resolvePending(key, pending, msg.text, name);
+            }
+            finally {
+                claimed.delete(key);
+            }
+            return true;
+        },
+        async handleReaction(reaction) {
+            const key = STATE_KEYS.question(reaction.channel, reaction.messageTs);
+            const pending = (await ctx.state.get(stateScope(key)));
+            if (!pending || pending.mode !== "reaction")
+                return;
+            if (claimed.has(key))
+                return;
+            claimed.add(key);
+            try {
+                const name = await gateway.getUserDisplayName(reaction.user);
+                await resolvePending(key, pending, `:${reaction.reaction}:`, name);
+            }
+            finally {
+                claimed.delete(key);
+            }
+        },
+    };
+}

package/dist/bolt-gateway.d.ts

@@ -0,0 +1,46 @@
+import type { InboundAction, InboundCommand, InboundMessage, InboundReaction, OutboundMessage, SlackGateway } from "./types.js";
+interface GatewayLogger {
+    warn(message: string, data?: Record<string, unknown>): void;
+}
+export declare class BoltGateway implements SlackGateway {
+    private readonly app;
+    private readonly logger;
+    private connected;
+    private botId;
+    private messageHandlers;
+    private mentionHandlers;
+    private reactionHandlers;
+    constructor(opts: {
+        botToken: string;
+        appToken: string;
+        logger: GatewayLogger;
+    });
+    private dispatch;
+    onMessage(handler: (msg: InboundMessage) => Promise<void>): void;
+    onMention(handler: (msg: InboundMessage) => Promise<void>): void;
+    onReaction(handler: (r: InboundReaction) => Promise<void>): void;
+    onAction(pattern: RegExp, handler: (action: InboundAction) => Promise<void>): void;
+    onCommand(command: string, handler: (cmd: InboundCommand) => Promise<void>): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isConnected(): boolean;
+    botUserId(): string | undefined;
+    postMessage(msg: OutboundMessage): Promise<{
+        channel: string;
+        ts: string;
+    }>;
+    updateMessage(msg: {
+        channel: string;
+        ts: string;
+        text: string;
+        blocks?: unknown[];
+    }): Promise<void>;
+    postEphemeral(msg: {
+        channel: string;
+        user: string;
+        text: string;
+    }): Promise<void>;
+    openDm(userId: string): Promise<string>;
+    getUserDisplayName(userId: string): Promise<string>;
+}
+export {};

package/dist/bolt-gateway.js

@@ -0,0 +1,153 @@
+import boltPkg from "@slack/bolt";
+import { errString } from "./redact.js";
+const { App } = boltPkg;
+export class BoltGateway {
+    app;
+    logger;
+    connected = false;
+    botId;
+    messageHandlers = [];
+    mentionHandlers = [];
+    reactionHandlers = [];
+    constructor(opts) {
+        this.logger = opts.logger;
+        this.app = new App({ token: opts.botToken, appToken: opts.appToken, socketMode: true });
+        this.app.event("app_mention", async ({ event }) => {
+            const e = event;
+            await this.dispatch(this.mentionHandlers, {
+                channel: e.channel,
+                channelType: "channel",
+                user: e.user ?? "",
+                text: e.text ?? "",
+                ts: e.ts,
+                threadTs: e.thread_ts,
+            });
+        });
+        this.app.message(async ({ message }) => {
+            const m = message;
+            // thread_broadcast messages ("also send to channel" replies) are
+            // genuine human thread replies and must reach chat routing like any
+            // other reply; every other subtype (message_changed, message_deleted,
+            // bot_message, etc.) is not a live human message and stays filtered.
+            if ((m.subtype && m.subtype !== "thread_broadcast") || m.bot_id || !m.user)
+                return;
+            const channelType = m.channel_type === "im" ? "im" : m.channel_type === "group" ? "group" : "channel";
+            await this.dispatch(this.messageHandlers, {
+                channel: m.channel,
+                channelType,
+                user: m.user,
+                text: m.text ?? "",
+                ts: m.ts,
+                threadTs: m.thread_ts,
+            });
+        });
+        this.app.event("reaction_added", async ({ event }) => {
+            const e = event;
+            if (e.item.type !== "message" || !e.item.channel || !e.item.ts)
+                return;
+            await this.dispatch(this.reactionHandlers, {
+                channel: e.item.channel,
+                messageTs: e.item.ts,
+                user: e.user,
+                reaction: e.reaction,
+            });
+        });
+    }
+    async dispatch(handlers, payload) {
+        for (const handler of handlers) {
+            try {
+                await handler(payload);
+            }
+            catch (err) {
+                this.logger.warn("Slack handler failed", { err: errString(err) });
+            }
+        }
+    }
+    onMessage(handler) { this.messageHandlers.push(handler); }
+    onMention(handler) { this.mentionHandlers.push(handler); }
+    onReaction(handler) { this.reactionHandlers.push(handler); }
+    onAction(pattern, handler) {
+        this.app.action(pattern, async ({ ack, body, action }) => {
+            await ack();
+            const b = body;
+            const a = action;
+            try {
+                await handler({
+                    actionId: a.action_id ?? "",
+                    value: a.value ?? "",
+                    user: b.user?.id ?? "",
+                    userName: b.user?.name ?? b.user?.username ?? b.user?.id ?? "unknown",
+                    channel: b.channel?.id ?? "",
+                    messageTs: b.message?.ts ?? "",
+                });
+            }
+            catch (err) {
+                this.logger.warn("Slack action handler failed", { err: errString(err) });
+            }
+        });
+    }
+    onCommand(command, handler) {
+        this.app.command(command, async ({ ack, command: cmd }) => {
+            await ack();
+            try {
+                await handler({ command: cmd.command, text: cmd.text ?? "", user: cmd.user_id, channel: cmd.channel_id });
+            }
+            catch (err) {
+                this.logger.warn("Slack command handler failed", { err: errString(err) });
+            }
+        });
+    }
+    async start() {
+        // Verify the bot token (and capture the bot's user id) before opening
+        // the socket at all. auth.test is a plain HTTP call against
+        // `this.app.client`, which doesn't require the socket to be started.
+        // Doing this first means a bad token fails fast with no socket to unwind.
+        const auth = await this.app.client.auth.test();
+        this.botId = auth.user_id;
+        const receiver = this.app.receiver;
+        receiver?.client?.on?.("connected", () => { this.connected = true; });
+        receiver?.client?.on?.("disconnected", () => { this.connected = false; });
+        await this.app.start();
+        this.connected = true;
+    }
+    async stop() {
+        await this.app.stop();
+        this.connected = false;
+    }
+    isConnected() { return this.connected; }
+    botUserId() { return this.botId; }
+    async postMessage(msg) {
+        const res = await this.app.client.chat.postMessage({
+            channel: msg.channel,
+            text: msg.text,
+            blocks: msg.blocks,
+            thread_ts: msg.threadTs,
+        });
+        return { channel: res.channel ?? msg.channel, ts: res.ts ?? "" };
+    }
+    async updateMessage(msg) {
+        await this.app.client.chat.update({
+            channel: msg.channel,
+            ts: msg.ts,
+            text: msg.text,
+            blocks: (msg.blocks ?? []),
+        });
+    }
+    async postEphemeral(msg) {
+        await this.app.client.chat.postEphemeral({ channel: msg.channel, user: msg.user, text: msg.text });
+    }
+    async openDm(userId) {
+        const res = await this.app.client.conversations.open({ users: userId });
+        return res.channel?.id ?? userId;
+    }
+    async getUserDisplayName(userId) {
+        try {
+            const res = await this.app.client.users.info({ user: userId });
+            const user = res.user;
+            return user?.profile?.display_name || user?.profile?.real_name || user?.real_name || userId;
+        }
+        catch {
+            return userId;
+        }
+    }
+}

package/dist/chat.d.ts

@@ -0,0 +1,14 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+import type { InboundMessage, SlackGateway, SlackSocketConfig } from "./types.js";
+export interface ChatDeps {
+    ctx: PluginContext;
+    gateway: SlackGateway;
+    getConfig: () => Promise<SlackSocketConfig>;
+    /** Minimum ms between streaming chat.update calls. Tests pass 0. */
+    updateIntervalMs?: number;
+}
+export interface Chat {
+    handleMention(msg: InboundMessage): Promise<void>;
+    handleMessage(msg: InboundMessage): Promise<void>;
+}
+export declare function createChat(deps: ChatDeps): Chat;