@pinet/slack-bridge 0.1.0 → 0.2.0

package/README.md

@@ -4,17 +4,42 @@ Slack assistant integration for [pi](https://github.com/badlogic/pi-mono) — mu
 
 ## Install
 
+Install the latest Pinet Slack bridge pi package:
+
 ```bash
 pi install npm:@pinet/slack-bridge
 ```
 
-Or with npm:
+Or pin an exact published version for reproducible installs:
+
+```bash
+pi install npm:@pinet/slack-bridge@0.1.0
+```
+
+For package managers or local inspection, the npm package is also installable directly:
 
 ```bash
 npm install @pinet/slack-bridge
 ```
 
-## Publishing
+## Package metadata and publishing
+
+This package declares pi package/gallery metadata in [`package.json`](./package.json):
+
+- `keywords` includes `pi-package` for gallery discovery.
+- `pi.extensions` points at the built extension entrypoint, `./dist/index.js`.
+- `pi.skills` points at the bundled skill directory, `./skills`.
+- No `pi.image` or `pi.video` preview is declared yet because this package does
+  not currently include a reviewed gallery image/video asset.
+
+The published tarball is expected to include the package metadata, README,
+Slack app manifest, built `dist/` files, bundled `skills/`, and LICENSE. Verify
+that locally with:
+
+```bash
+cd slack-bridge
+npm pack --dry-run
+```
 
 This package is included in the full npm publish set tracked in
 [`../plans/npm-publish.md`](../plans/npm-publish.md). Use the GitHub Actions
@@ -35,9 +60,10 @@ bump versions without explicit maintainer release approval.
 2. Choose **From a manifest**
 3. Select your workspace
 4. Paste the contents of [`manifest.yaml`](./manifest.yaml) from this directory
-5. Click **Create**
+5. If the Slack app is not named Pinet, change `features.slash_commands[0].command` before creating the app (for example, Oathgate uses `/oathgate` instead of the packaged `/pinet` default)
+6. Click **Create**
 
-The manifest configures Socket Mode, the assistant view, all required bot scopes, and event subscriptions automatically.
+The manifest configures Socket Mode, the assistant view, all required bot scopes, event subscriptions, and the packaged Pinet slash-command default automatically.
 
 ### 2. Generate tokens
 
@@ -56,13 +82,13 @@ These are included in the manifest, but for reference:
 app_mentions:read    assistant:write      bookmarks:read
 bookmarks:write      canvases:read        canvases:write
 channels:history     channels:read        chat:write
-files:read           files:write          groups:history
+commands             files:read           files:write          groups:history
 groups:read          im:history           im:read
 im:write             pins:read            pins:write
 reactions:read       reactions:write      users:read
 ```
 
-`files:read` is required because Slack exposes canvas comment pagination through `files.info`, even when the target is first validated via canvas-specific APIs.
+`commands` is required for the Slack slash-command surface (`/<app> agents list [all]`). `files:read` is required because Slack exposes canvas comment pagination through `files.info`, even when the target is first validated via canvas-specific APIs.
 
 Slack thread shimmer/status updates use `assistant.threads.setStatus`; Slack's 2026 scope update allows this method with the existing `chat:write` bot scope, so no new `assistant:write` scope is needed for status-only support.
 
@@ -173,6 +199,8 @@ Slack access is now **default-deny** unless you configure one of these explicitl
 | `ralphSnoozeAfterEmptyCycles`  | no       | Broker RALPH auto-snooze trigger after N empty cycles; defaults to `0` (disabled), valid range `0`-`100`              |
 | `ralphSnoozeDurationMs`        | no       | Broker RALPH auto-snooze duration in milliseconds; defaults to `1800000` (30 minutes), valid range `60000`-`86400000` |
 | `skinTheme`                    | no       | Pinet presentation skin selected at broker startup/reload (`default`, `foundation`, `cosmere`, or free-form)          |
+| `slackCommandName`             | no       | Slack web app slash command name for `agents list`; defaults to `/pinet`, or `/oathgate` for Oathgate/Cosmere skins   |
+| `slackCommandNames`            | no       | Optional list of accepted/deployed Slack slash command aliases when one app needs multiple command names              |
 | `meshSecret`                   | no       | Optional inline Pinet shared secret; overrides `meshSecretPath` and env fallbacks                                     |
 | `meshSecretPath`               | no       | Optional path to a shared-secret file; broker creates it if missing, followers require an existing file               |
 | `suggestedPrompts`             | no       | Prompts shown when a user opens a new conversation                                                                    |
@@ -209,7 +237,7 @@ Messages queue while the agent is busy. When the agent finishes, it automaticall
 
 ### Reaction triggers
 
-Configured emoji reactions create structured Pinet requests from the reacted-to Slack message. The default set includes `:arrow_up:` / ⬆️ as `steer`, which marks and redelivers the referenced message as steering so the current thread owner sees an unread operator instruction when relevant and safe. The default `:octagonal_sign:` / 🛑 mapping sends an explicit `interrupt` control to the current thread owner; it aborts the active turn when the owner is busy, but does not reload or exit the process. Pinet adds ✅ when it accepts the reaction-triggered request. If it cannot process the reaction at all, it adds ❌; check broker logs for the underlying Slack/API error. When Slack cannot return the reacted message text, Pinet still routes the reaction with channel/thread/message IDs so steering reactions do not fail solely because message lookup was unavailable.
+Slack emoji reactions are ignored by default: they do not enqueue Pinet work, trigger reviews, steer agents, interrupt owners, or cause broker/worker replies. To opt in deliberately, configure `reactionCommands` for the exact emoji aliases that should become structured Pinet requests from the reacted-to Slack message. Even configured reactions are accepted only inside an already authorized Pinet thread (for example a thread with a current Pinet owner, or persisted Slack assistant-thread context). Reaction authorization is deny-by-default: it requires an explicit broker-backed authorization gate, and a thread the adapter has merely seen or cached never qualifies on its own. Reactions in ordinary, uninvoked Slack channel threads remain no-op — even from authorized users — and they do not enqueue work, persist thread state, claim ownership, or receive a Slack ACK. Messages and interactive events from users outside the allowlist also never mint known-thread state that could later admit reactions or replies. Pinet adds ✅ only when it accepts an opt-in reaction-triggered request. If it cannot process an accepted opted-in reaction, it adds ❌; check broker logs for the underlying Slack/API error. When Slack cannot return the reacted message text, Pinet can still route configured reactions when the message timestamp itself identifies an already authorized thread; otherwise it ignores the reaction safely.
 
 ### Available tools
 
@@ -229,6 +257,7 @@ Cold Slack actions live behind the `slack` dispatcher:
 | `react`                | Add an emoji reaction to a message                                                |
 | `read`                 | Read messages from a thread                                                       |
 | `upload`               | Upload files, snippets, or diffs into Slack                                       |
+| `file`                 | Download Slack-hosted files to a controlled local temp cache by file ID           |
 | `schedule`             | Schedule a message for later delivery                                             |
 | `post_channel`         | Post to a channel (by name or ID)                                                 |
 | `delete`               | Delete a bot-posted message or an entire thread                                   |
@@ -282,7 +311,21 @@ migration.
 - **Uploads are for bulky artifacts.** Use `upload` for logs, screenshots,
   long diffs, and generated files instead of large inline messages. Inline
   uploads require `filename`; path uploads are guarded and must stay within the
-  current working directory or system temp directory.
+  current working directory or system temp directory. `slack_send` also accepts
+  `files: [{ path, filename?, title?, filetype? }]` so one assistant-thread
+  reply can contain both text and local binary attachments in the same Slack
+  file upload message. Slack external file uploads cannot include Block Kit in
+  that same message, so omit `blocks` when sending files or send a separate
+  block-only reply.
+- **Inbound Slack files are fetched explicitly.** Incoming file-share messages
+  preserve safe `slackFiles` metadata such as file ID, name, type, size, and
+  permalink, but private Slack download URLs are not exposed in normal tool
+  output. To inspect raw content, call dispatcher action `file` with
+  `op: "download"`, `file_id`, and optionally `thread_ts`, `message_ts`, and
+  `channel`. The bot fetches the file with Slack bot auth, stores it under the
+  system temp `pi-slack-files` cache with best-effort TTL cleanup, and returns a
+  descriptor containing the local path, filename, type, size, SHA-256, expiry,
+  and residual privacy risks.
 - **Upload host egress note.** The second upload leg goes to Slack file upload
   hosts (`files.slack.com`/`uploads.slack.com`) for the raw payload. In
   environments with restricted egress this can fail with `403` (proxy
@@ -317,10 +360,13 @@ migration.
 ...` string from the error, request confirmation, wait for the user's approval
   via `slack_inbox`, then retry the guarded call unchanged. Batched
   multi-thread Slack turns cannot satisfy a single-thread confirmation.
-- **Reaction and interaction triggers are explicit tasks.** Reaction-triggered
-  requests and Block Kit/modal interaction payloads arrive through
-  `slack_inbox` with metadata; treat them as user instructions tied to the
-  referenced Slack thread or message.
+- **Plain emoji reactions are not tasks.** Slack emoji reactions are ignored
+  unless `reactionCommands` explicitly opts that emoji into structured
+  reaction-trigger handling and the reacted message belongs to an already
+  authorized Pinet thread. If an opt-in reaction-triggered request or a Block
+  Kit/modal interaction payload arrives through `slack_inbox` with metadata,
+  treat it as a user instruction tied to the referenced Slack thread or
+  message.
 
 #### Common dispatcher examples
 
@@ -393,12 +439,13 @@ The `canvas_comments_read` dispatcher action is intentionally narrow:
 
 ### Slash commands
 
-| Command           | Description                                                |
-| ----------------- | ---------------------------------------------------------- |
-| `/pinet <action>` | Unified Pinet command surface; run `/pinet help` for usage |
-| `/pinet status`   | Show connection status, threads, and agent identity        |
-| `/pinet rename`   | Change the agent's display name                            |
-| `/pinet logs`     | Show recent broker activity log entries                    |
+| Command                    | Description                                                |
+| -------------------------- | ---------------------------------------------------------- |
+| `/pinet <action>`          | Unified Pinet command surface; run `/pinet help` for usage |
+| `/pinet status`            | Show connection status, threads, and agent identity        |
+| `/pinet rename`            | Change the agent's display name                            |
+| `/pinet logs`              | Show recent broker activity log entries                    |
+| `/<app> agents list [all]` | Slack-native broker roster, workload, task, and lane view  |
 
 ## Runtime modes
 
@@ -469,13 +516,17 @@ Only broker prompt content is replaceable. Broker runtime/tool restrictions rema
 
 ### Multi-agent tools
 
-| Tool    | Description                                                                                                                                                       |
-| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pinet` | Pinet dispatcher with token-efficient `action`-based routing (`help`, `send`, `read`, `free`, `snooze`, `schedule`, `agents`, `lanes`, `ports`, `reload`, `exit`) |
+| Tool    | Description                                                                                                                                                                |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pinet` | Pinet dispatcher with token-efficient `action`-based routing (`help`, `send`, `read`, `free`, `snooze`, `schedule`, `agents`, `lanes`, `ports`, `spawn`, `reload`, `exit`) |
+
+Use the dispatcher for Pinet tool actions: `pinet action=send`, `pinet action=read`, `pinet action=free`, `pinet action=snooze`, `pinet action=schedule`, `pinet action=agents`, `pinet action=lanes`, `pinet action=ports`, `pinet action=spawn`, `pinet action=reload`, and `pinet action=exit`. Use slash commands for UI lifecycle transitions: `/pinet start`, `/pinet follow`, `/pinet unfollow`, and `/pinet subtree start`. Dedicated direct Pinet tools (`pinet_message`, `pinet_read`, `pinet_agents`, `pinet_free`, `pinet_schedule`) are no longer registered. Legacy `pinet_*` guardrail patterns still match dispatcher action names, and legacy send policies such as `pinet_send` or `pinet_message` also cover `pinet action=send`, so existing security configs fail closed during migration.
+
+Worker-owned subtree brokers let a follower worker supervise its own child mesh without registering those children in the central broker. Run `/pinet subtree start` (alias: `/pinet subbroker start`) from a follower worker. The worker remains connected to the central broker as a normal worker, and it also starts a separate broker socket/database under `~/.pi/pinet-subtrees/<worker>/`. Child workers launched by this worker receive `PINET_SOCKET_PATH`, `PINET_PARENT_AGENT_ID`, `PINET_ROOT_AGENT_ID`, `PINET_LAUNCH_ID`, `PINET_SUBTREE_ROLE`, and related metadata, so they follow the worker's subtree broker instead of the central Pinet broker.
 
-Use the dispatcher for Pinet tool actions: `pinet action=send`, `pinet action=read`, `pinet action=free`, `pinet action=snooze`, `pinet action=schedule`, `pinet action=agents`, `pinet action=lanes`, `pinet action=ports`, `pinet action=reload`, and `pinet action=exit`. Use slash commands for UI lifecycle transitions: `/pinet start`, `/pinet follow`, and `/pinet unfollow`. Dedicated direct Pinet tools (`pinet_message`, `pinet_read`, `pinet_agents`, `pinet_free`, `pinet_schedule`) are no longer registered. Legacy `pinet_*` guardrail patterns still match dispatcher action names, and legacy send policies such as `pinet_send` or `pinet_message` also cover `pinet action=send`, so existing security configs fail closed during migration.
+Use `pinet action=spawn args.repo=<repo> args.task=<task> [args.role=<role>] [args.lane_id=<lane>]` or `/pinet subtree spawn repo=<repo> [role=<role>] [lane=<lane>] <task>` to launch a tmux-backed child worker, wait for it to register in the subtree broker, and deliver the task over private Pinet A2A. Use `pinet action=agents args.scope=subtree args.full=true` from the supervising worker to list subtree children, `pinet action=send args.to=<child> args.message=<message>` to reply/control them, `pinet action=read` to read child reports, and `pinet action=exit args.target=<child>` or `/pinet subtree stop` to clean them up. The central broker sees only the supervising worker; the subtree DB contains the child roster and messages.
 
-Dispatcher content defaults to terse CLI-style confirmations/summaries for noisy reads, sends, and agent lists. In default CLI mode, bulky read/agent payloads are also compacted in `data.details` so tool renderers do not surface full message bodies or agent metadata by accident. Pass `args.format="json"` (or `args.f` / `args["-f"]`) for the dispatcher envelope in content with full structured `data.details`, or `args.full=true` / `args["--full"]=true` for verbose text with full structured `data.details`.
+Dispatcher content defaults to terse CLI-style confirmations/summaries for noisy reads, sends, and agent lists. Bulky read/agent payloads are compacted in `data.details` by default, including when `args.format="json"` (or `args.f` / `args["-f"]`) renders the dispatcher envelope in content. Use `args.full=true` / `args["--full"]=true` only when you need verbose text and full structured debug details such as exact message bodies or agent metadata.
 
 Durable Pinet inbox notifications are classified as `steering`, `fwup`, or `maintenance/context` from explicit metadata or message cues. Follower prompts receive compact pointers such as `pinet action=read args.thread_id=...` instead of the full durable message body; agents use `pinet action=read` to retrieve the actual context. Delivery, read/ack state, and mail classification remain separate.
 
@@ -491,17 +542,18 @@ RALPH snooze quiets non-urgent empty maintenance cycles without disabling human-
 
 ### Pinet command surface
 
-Use `/pinet <action> [args]` for mesh lifecycle and broker operations.
+Use `/pinet <action> [args]` for mesh lifecycle and broker operations. In the Slack web app, use `/<app> agents list [all]` for the Slack-native broker roster/current-work view: `/pinet agents list` for the Pinet app, or `/oathgate agents list` for an Oathgate-named app. Set `slackCommandName` (or `slackCommandNames`) in `slack-bridge` settings before deploying the manifest when the Slack command should match a non-default app name.
 
-| Command                               | Description                                                                   |
-| ------------------------------------- | ----------------------------------------------------------------------------- |
-| `/pinet start`                        | Start as the mesh broker                                                      |
-| `/pinet follow`                       | Connect as a follower worker                                                  |
-| `/pinet unfollow`                     | Disconnect from the broker                                                    |
-| `/pinet reload <agent>`               | Ask another agent to reload                                                   |
-| `/pinet exit <agent>`                 | Ask another agent to exit                                                     |
-| `/pinet free`                         | Mark this agent as idle                                                       |
-| `/pinet snooze [duration/off/status]` | Quiet empty RALPH cycles while preserving human-triggered wake/route behavior |
+| Command                                    | Description                                                                   |
+| ------------------------------------------ | ----------------------------------------------------------------------------- |
+| `/pinet start`                             | Start as the mesh broker                                                      |
+| `/pinet follow`                            | Connect as a follower worker                                                  |
+| `/pinet unfollow`                          | Disconnect from the broker                                                    |
+| `/pinet reload <agent>`                    | Ask another agent to reload                                                   |
+| `/pinet exit <agent>`                      | Ask another agent to exit                                                     |
+| `/pinet free`                              | Mark this agent as idle                                                       |
+| `/pinet snooze [duration/off/status]`      | Quiet empty RALPH cycles while preserving human-triggered wake/route behavior |
+| `/pinet subtree [start/status/spawn/stop]` | Run this worker as a local subtree broker for child followers                 |
 
 ### Pinet skins
 
@@ -555,7 +607,7 @@ pnpm test
 pnpm deploy:slack
 ```
 
-Requires `appId` and `appConfigToken` in settings (or `SLACK_APP_ID` / `SLACK_APP_CONFIG_TOKEN` env vars).
+Requires `appId` and `appConfigToken` in settings (or `SLACK_APP_ID` / `SLACK_APP_CONFIG_TOKEN` env vars). The deploy path rewrites `features.slash_commands` from `slackCommandName` / `slackCommandNames` (or the configured `skinTheme`) before validating and uploading, so set `slackCommandName: "/oathgate"` for an Oathgate app and leave it unset for the packaged Pinet `/pinet` default.
 
 ### Architecture
 

package/dist/broker/adapters/slack.d.ts

@@ -1,4 +1,4 @@
-import { type ParsedAppHomeOpened, type ParsedThreadStarted } from "../../slack-access.js";
+import { type ParsedAppHomeOpened, type ParsedSlashCommand, type ParsedThreadStarted } from "../../slack-access.js";
 import { type ReactionCommandSettings } from "../../reaction-triggers.js";
 import type { AdapterCapabilityRequest, AdapterCapabilityResult, InboundMessage, OutboundMessage, MessageAdapter } from "./types.js";
 export { classifyMessage, extractAppHomeOpened, extractThreadStarted, parseMemberJoinedChannel, parseSocketFrame, RECONNECT_DELAY_MS, } from "../../slack-access.js";
@@ -21,8 +21,22 @@ export interface SlackAdapterConfig {
     } | null;
     /** Persist thread metadata in the broker DB without claiming ownership. */
     rememberKnownThread?: (threadTs: string, channelId: string, context?: ParsedThreadStarted["context"] | null) => void;
+    /**
+     * Gate reaction-trigger handling after the reacted message thread is known.
+     * Use this to require an already authorized/Pinet-owned thread before an
+     * opt-in reaction command can enqueue work or mutate durable thread state.
+     *
+     * Reaction triggers are denied by default: when this callback is not
+     * configured, opt-in reaction commands never route, even for threads the
+     * adapter has merely seen/cached. Authorization must be explicit so that
+     * reactions pass the same invoked/owned-thread admission bar as normal
+     * Slack messages (#812).
+     */
+    isReactionThreadAuthorized?: (threadTs: string, channelId: string) => boolean;
     /** Best-effort callback for Home tab opens. */
     onAppHomeOpened?: (event: ParsedAppHomeOpened) => Promise<void> | void;
+    /** Best-effort callback for Slack slash commands handled by the broker process. */
+    onSlashCommand?: (event: ParsedSlashCommand) => Promise<string | null> | string | null;
 }
 export declare const SLACK_THREAD_CACHE_MAX_SIZE = 5000;
 export declare const SLACK_THREAD_CACHE_TTL_MS: number;
@@ -58,9 +72,13 @@ export declare class SlackAdapter implements MessageAdapter {
     private resolveScopeForThread;
     private onThreadStarted;
     private onContextChanged;
+    private sendSlashCommandResponse;
+    private onSlashCommand;
     private onAppHomeOpened;
     private fetchMessageByTs;
     private onReactionAdded;
+    private getCachedThread;
+    private isReactionThreadAuthorized;
     private onMessage;
     private emitInteractiveInbound;
     private onMemberJoined;

package/dist/broker/adapters/slack.js

@@ -1,9 +1,11 @@
+import os from "node:os";
 import { addSlackReaction, buildSlackThreadRuntimeScope, classifyMessage, extractAppHomeOpened, extractThreadContextChanged, extractThreadStarted, fetchSlackMessageByTs, isSlackUserAllowed, removeSlackReaction, resolveSlackUserName, setSlackSuggestedPrompts, SlackSocketModeClient, } from "../../slack-access.js";
 import { createAbortableOperationTracker, callSlackAPI, isAbortError, buildAllowlist, buildPinetControlMessage, buildPinetControlMetadata, } from "../../helpers.js";
 import { buildReactionTriggerMessage, normalizeReactionName, resolveReactionCommands, } from "../../reaction-triggers.js";
 import { TtlCache, TtlSet } from "../../ttl-cache.js";
 import { SLACK_SOCKET_DELIVERY_DEDUP_MAX_SIZE, SLACK_SOCKET_DELIVERY_DEDUP_TTL_MS, } from "../../slack-access.js";
 import { DEFAULT_SLACK_THREAD_STATUS, SlackThreadStatusManager, } from "../../slack-thread-status.js";
+import { performSlackUploads, prepareSlackUpload } from "../../slack-upload.js";
 export { classifyMessage, extractAppHomeOpened, extractThreadStarted, parseMemberJoinedChannel, parseSocketFrame, RECONNECT_DELAY_MS, } from "../../slack-access.js";
 export const SLACK_THREAD_CACHE_MAX_SIZE = 5000;
 export const SLACK_THREAD_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
@@ -72,6 +74,7 @@ export class SlackAdapter {
             onMemberJoinedChannel: (event) => this.onMemberJoined(event),
             onAppHomeOpened: (event) => this.onAppHomeOpened(event),
             onInteractive: (event) => this.emitInteractiveInbound(event),
+            onSlashCommand: (event) => this.onSlashCommand(event),
             onError: (error) => {
                 if (!isAbortError(error)) {
                     console.error(`[slack-adapter] Socket Mode: ${errorMsg(error)}`);
@@ -140,7 +143,28 @@ export class SlackAdapter {
                 },
             };
         }
-        await this.callSlack("chat.postMessage", this.config.botToken, body);
+        if (msg.files && msg.files.length > 0) {
+            if (slackBlocks && slackBlocks.length > 0) {
+                throw new Error("Slack text+file replies use Slack's external upload flow, which does not support Block Kit blocks in the same upload message. Omit blocks or send a separate block-only message.");
+            }
+            const uploads = await Promise.all(msg.files.map((file) => prepareSlackUpload({
+                path: file.path,
+                ...(file.filename ? { filename: file.filename } : {}),
+                ...(file.title ? { title: file.title } : {}),
+                ...(file.filetype ? { filetype: file.filetype } : {}),
+            }, process.cwd(), os.tmpdir())));
+            await performSlackUploads({
+                uploads,
+                channelId: msg.channel,
+                threadTs: msg.threadId,
+                initialComment: msg.content?.text ?? msg.text,
+                slack: this.callSlack.bind(this),
+                token: this.config.botToken,
+            });
+        }
+        else {
+            await this.callSlack("chat.postMessage", this.config.botToken, body);
+        }
         if (this.shuttingDown)
             return;
         const pending = this.pendingEyes.get(msg.threadId);
@@ -233,6 +257,50 @@ export class SlackAdapter {
             /* best effort — DB cache sync must not break Slack event handling */
         }
     }
+    async sendSlashCommandResponse(event, text, options = {}) {
+        if (options.useResponseUrl !== false && event.responseUrl) {
+            try {
+                const response = await this.slackRequests.run((signal) => fetch(event.responseUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json; charset=utf-8" },
+                    body: JSON.stringify({ response_type: "ephemeral", text }),
+                    signal,
+                }));
+                if (response.ok) {
+                    return;
+                }
+                console.error(`[slack-adapter] Slash command response_url failed: HTTP ${response.status}`);
+            }
+            catch (error) {
+                console.error(`[slack-adapter] Slash command response_url failed: ${errorMsg(error)}`);
+            }
+        }
+        await this.callSlack("chat.postEphemeral", this.config.botToken, {
+            channel: event.channelId,
+            user: event.userId,
+            text,
+        });
+    }
+    async onSlashCommand(event) {
+        if (this.shuttingDown || !this.config.onSlashCommand)
+            return;
+        if (!isSlackUserAllowed(this.allowlist, event.userId)) {
+            await this.sendSlashCommandResponse(event, "Sorry, I can only respond to authorized users. Please contact an admin if you need access.");
+            return;
+        }
+        try {
+            const responseText = await this.config.onSlashCommand(event);
+            if (responseText && !this.shuttingDown) {
+                await this.sendSlashCommandResponse(event, responseText);
+            }
+        }
+        catch (error) {
+            console.error(`[slack-adapter] Slash command failed: ${errorMsg(error)}`);
+            await this.sendSlashCommandResponse(event, `Slack command failed: ${errorMsg(error)}`, {
+                useResponseUrl: false,
+            });
+        }
+    }
     async onAppHomeOpened(event) {
         if (this.shuttingDown)
             return;
@@ -280,25 +348,17 @@ export class SlackAdapter {
         try {
             const isInterruptReaction = command.action === "interrupt";
             const reactedMessage = await this.fetchMessageByTs(item.channel, item.ts);
-            if (!reactedMessage && isInterruptReaction) {
-                throw new Error(`Unable to identify Slack thread for interrupt reaction ${item.ts} in channel ${item.channel}`);
-            }
             const reactedMessageFetchStatus = reactedMessage ? "found" : "unavailable";
             const threadTs = reactedMessage?.thread_ts ??
                 reactedMessage?.ts ??
                 item.ts;
-            if (!this.getThread(threadTs)) {
-                this.threads.set(threadTs, {
-                    channelId: item.channel,
-                    threadTs,
-                    userId: reactedMessage?.user ?? userId,
-                });
-                try {
-                    this.config.rememberKnownThread?.(threadTs, item.channel, null);
-                }
-                catch {
-                    /* best effort — DB cache sync must not break reaction handling */
-                }
+            const cachedThread = this.getCachedThread(threadTs);
+            if (!this.isReactionThreadAuthorized(threadTs, item.channel, cachedThread)) {
+                return;
+            }
+            const existingThread = cachedThread ?? this.getThread(threadTs);
+            if (!existingThread || existingThread.channelId !== item.channel) {
+                return;
             }
             const reactorName = isInterruptReaction
                 ? await this.resolveUser(userId).catch(() => userId)
@@ -323,7 +383,6 @@ export class SlackAdapter {
                     : reactedMessage
                         ? "(no text)"
                         : "(message text unavailable; Slack did not return the reacted message, so use the channel/thread/message ids for context)";
-            const threadInfo = this.getThread(threadTs);
             const reactionEventTs = evt.event_ts ?? item.ts;
             this.inboundHandler?.({
                 source: "slack",
@@ -370,7 +429,7 @@ export class SlackAdapter {
                 },
                 scope: buildSlackThreadRuntimeScope({
                     channelId: item.channel,
-                    context: threadInfo?.context,
+                    context: existingThread.context,
                 }),
             });
             await this.addReaction(item.channel, item.ts, "white_check_mark");
@@ -380,6 +439,31 @@ export class SlackAdapter {
             await this.addReaction(item.channel, item.ts, "x");
         }
     }
+    getCachedThread(threadTs) {
+        const cached = this.threads.get(threadTs);
+        if (cached) {
+            this.threads.set(threadTs, cached);
+        }
+        return cached;
+    }
+    isReactionThreadAuthorized(threadTs, channelId, cachedThread) {
+        if (cachedThread && cachedThread.channelId !== channelId)
+            return false;
+        // Deny by default (#812): without an explicit authorization gate, a
+        // merely cached/known thread must never authorize reaction routing.
+        const authorize = this.config.isReactionThreadAuthorized;
+        if (!authorize)
+            return false;
+        try {
+            return authorize(threadTs, channelId);
+        }
+        catch (error) {
+            // Authorization failures must fail closed without posting visible
+            // error reactions into threads Pinet does not own.
+            console.error(`[slack-adapter] reaction thread authorization failed: ${errorMsg(error)}`);
+            return false;
+        }
+    }
     async onMessage(evt) {
         if (this.shuttingDown)
             return;
@@ -392,6 +476,10 @@ export class SlackAdapter {
             this.shouldSuppressLegacyThreadedDm(threadTs)) {
             return;
         }
+        // Check the allowlist before recording any thread state so unauthorized
+        // traffic can never mint known-thread/affinity side effects (#812).
+        if (!isSlackUserAllowed(this.allowlist, userId))
+            return;
         if (!this.getThread(threadTs)) {
             this.threads.set(threadTs, {
                 channelId: channel,
@@ -399,8 +487,6 @@ export class SlackAdapter {
                 userId,
             });
         }
-        if (!isSlackUserAllowed(this.allowlist, userId))
-            return;
         void this.threadStatuses.begin(channel, threadTs, DEFAULT_SLACK_THREAD_STATUS);
         void this.addReaction(channel, messageTs, "eyes");
         const pending = this.pendingEyes.get(threadTs) ?? [];
@@ -430,6 +516,11 @@ export class SlackAdapter {
         });
     }
     async emitInteractiveInbound(normalized) {
+        // Check the allowlist before recording in-memory or durable thread state
+        // so unauthorized interactive events cannot mint known-thread/affinity
+        // side effects (#812).
+        if (!isSlackUserAllowed(this.allowlist, normalized.userId))
+            return;
         if (!this.getThread(normalized.threadTs)) {
             this.threads.set(normalized.threadTs, {
                 channelId: normalized.channel,
@@ -443,8 +534,6 @@ export class SlackAdapter {
         catch {
             /* best effort — DB cache sync must not break Slack event handling */
         }
-        if (!isSlackUserAllowed(this.allowlist, normalized.userId))
-            return;
         const userName = await this.resolveUser(normalized.userId);
         if (this.shuttingDown)
             return;

package/dist/broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { PinetReadOptions, PinetReadResult } from "@pinet/pinet-core/pinet-read-formatting";
-import type { ClientAgentInfo, NormalizedMessageContent, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
+import type { ClientAgentInfo, NormalizedMessageContent, OutboundAttachmentFile, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
 export interface InboxItem {
     inboxId: number;
     message: {
@@ -105,6 +105,7 @@ export declare class BrokerClient {
         channel?: string;
         content?: NormalizedMessageContent;
         blocks?: ReadonlyArray<Record<string, unknown>>;
+        files?: ReadonlyArray<OutboundAttachmentFile>;
         agentName?: string;
         agentEmoji?: string;
         agentOwnerToken?: string;

package/dist/broker/client.js

@@ -269,6 +269,7 @@ export class BrokerClient {
             ...(input.channel ? { channel: input.channel } : {}),
             ...(input.content ? { content: input.content } : {}),
             ...(input.blocks && input.blocks.length > 0 ? { blocks: input.blocks } : {}),
+            ...(input.files && input.files.length > 0 ? { files: input.files } : {}),
             ...(input.agentName ? { agentName: input.agentName } : {}),
             ...(input.agentEmoji ? { agentEmoji: input.agentEmoji } : {}),
             ...(input.agentOwnerToken ? { agentOwnerToken: input.agentOwnerToken } : {}),

package/dist/broker/socket-server.js

@@ -601,6 +601,23 @@ export class BrokerSocketServer {
         const blocks = Array.isArray(params.blocks)
             ? params.blocks.filter((entry) => !!entry && typeof entry === "object")
             : undefined;
+        const files = Array.isArray(params.files)
+            ? params.files.flatMap((entry) => {
+                if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                    return [];
+                const file = entry;
+                if (typeof file.path !== "string" || file.path.trim().length === 0)
+                    return [];
+                return [
+                    {
+                        path: file.path,
+                        ...(typeof file.filename === "string" ? { filename: file.filename } : {}),
+                        ...(typeof file.title === "string" ? { title: file.title } : {}),
+                        ...(typeof file.filetype === "string" ? { filetype: file.filetype } : {}),
+                    },
+                ];
+            })
+            : undefined;
         let content;
         if (params.content !== undefined) {
             if (!params.content || typeof params.content !== "object" || Array.isArray(params.content)) {
@@ -638,6 +655,7 @@ export class BrokerSocketServer {
             ...(channel ? { channel } : {}),
             ...(content ? { content } : {}),
             ...(blocks && blocks.length > 0 ? { blocks } : {}),
+            ...(files && files.length > 0 ? { files } : {}),
             ...(agentName ? { agentName } : {}),
             ...(agentEmoji ? { agentEmoji } : {}),
             ...(agentOwnerToken ? { agentOwnerToken } : {}),

package/dist/deploy-manifest.d.ts

@@ -2,6 +2,9 @@ export interface SlackBridgeSettings {
     appId?: string;
     appToken?: string;
     appConfigToken?: string;
+    skinTheme?: string;
+    slackCommandName?: string;
+    slackCommandNames?: string[];
 }
 export interface ManifestScopeChanges {
     addedBotScopes: string[];
@@ -14,6 +17,7 @@ export interface ResolvedDeployConfig {
     appId?: string;
     appConfigToken?: string;
     appToken?: string;
+    settings: SlackBridgeSettings;
 }
 export interface DeployResult {
     appId: string;
@@ -23,5 +27,6 @@ export declare function diffManifestScopes(beforeManifest: Record<string, unknow
 export declare function formatScopeChangeSummary(changes: ManifestScopeChanges): string[];
 export declare function resolveDeployConfig(settings: SlackBridgeSettings, env: NodeJS.ProcessEnv, cwd?: string): ResolvedDeployConfig;
 export declare function getDeployConfigError(config: ResolvedDeployConfig): string | null;
+export declare function applyConfiguredSlashCommands(manifest: Record<string, unknown>, settings: SlackBridgeSettings): Record<string, unknown>;
 export declare function deploySlackManifest(config: ResolvedDeployConfig): Promise<DeployResult>;
 export declare function run(): Promise<void>;

package/dist/deploy-manifest.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { pathToFileURL } from "node:url";
+import { resolveSlackAgentCommandNames } from "./slack-agents-command.js";
 const execFile = promisify(execFileCallback);
 class SlackMethodError extends Error {
     method;
@@ -104,6 +105,7 @@ export function resolveDeployConfig(settings, env, cwd = process.cwd()) {
         appId: settings.appId ?? env.SLACK_APP_ID,
         appConfigToken: settings.appConfigToken ?? env.SLACK_APP_CONFIG_TOKEN ?? env.SLACK_CONFIG_TOKEN,
         appToken: settings.appToken ?? env.SLACK_APP_TOKEN,
+        settings,
     };
 }
 export function getDeployConfigError(config) {
@@ -123,6 +125,33 @@ export function getDeployConfigError(config) {
     }
     return messages.length > 0 ? messages.join(" ") : null;
 }
+export function applyConfiguredSlashCommands(manifest, settings) {
+    const commandNames = resolveSlackAgentCommandNames(settings);
+    const features = asRecord(manifest.features) ?? {};
+    const oauthConfig = asRecord(manifest.oauth_config) ?? {};
+    const scopes = asRecord(oauthConfig.scopes) ?? {};
+    const botScopes = readScopeList(manifest, "bot");
+    const nextBotScopes = botScopes.includes("commands") ? botScopes : [...botScopes, "commands"];
+    return {
+        ...manifest,
+        features: {
+            ...features,
+            slash_commands: commandNames.map((command) => ({
+                command,
+                description: "Show the Pinet broker roster and current work",
+                usage_hint: "agents list [all]",
+                should_escape: false,
+            })),
+        },
+        oauth_config: {
+            ...oauthConfig,
+            scopes: {
+                ...scopes,
+                bot: nextBotScopes,
+            },
+        },
+    };
+}
 async function parseManifestYaml(manifestPath) {
     try {
         const program = [
@@ -169,7 +198,7 @@ export async function deploySlackManifest(config) {
     }
     const appId = config.appId;
     const appConfigToken = config.appConfigToken;
-    const manifest = await parseManifestYaml(config.manifestPath);
+    const manifest = applyConfiguredSlashCommands(await parseManifestYaml(config.manifestPath), config.settings);
     const previousManifest = await exportRemoteManifest(appId, appConfigToken);
     await validateManifest(manifest, appConfigToken);
     await updateManifest(appId, manifest, appConfigToken);