@gugu910/pi-slack-bridge 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+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,299 @@
+# slack-bridge (Pinet)
+
+Slack assistant integration for [pi](https://github.com/badlogic/pi-mono) — multi-agent broker, thread routing, and inbox tools powered by Socket Mode.
+
+## Install
+
+```bash
+pi install @gugu910/pi-slack-bridge
+```
+
+Or with npm:
+
+```bash
+npm install @gugu910/pi-slack-bridge
+```
+
+## Prerequisites
+
+- A Slack workspace where you have permission to install apps
+- Node.js 22+ (uses native `fetch` and `WebSocket`)
+- [pi](https://github.com/badlogic/pi-mono) installed
+
+## Slack App Setup
+
+### 1. Create the app
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App**
+2. Choose **From a manifest**
+3. Select your workspace
+4. Paste the contents of [`manifest.yaml`](./manifest.yaml) from this directory
+5. Click **Create**
+
+The manifest configures Socket Mode, the assistant view, all required bot scopes, and event subscriptions automatically.
+
+### 2. Generate tokens
+
+You need two tokens:
+
+| Token               | Where to find it                                                                 | Looks like   |
+| ------------------- | -------------------------------------------------------------------------------- | ------------ |
+| **App-Level Token** | Basic Information → App-Level Tokens → Generate (with `connections:write` scope) | `xapp-1-...` |
+| **Bot Token**       | OAuth & Permissions → Install to Workspace → Bot User OAuth Token                | `xoxb-...`   |
+
+### 3. Required bot scopes
+
+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:write          groups:history       groups:read
+im:history           im:read              im:write
+pins:read            pins:write           reactions:read
+reactions:write      users:read
+```
+
+## Configuration
+
+Add your tokens to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "slack-bridge": {
+    "botToken": "xoxb-your-bot-token",
+    "appToken": "xapp-your-app-token"
+  }
+}
+```
+
+That's it for a minimal setup. Start pi and Pinet appears in Slack's sidebar.
+
+### Environment variables (alternative)
+
+```bash
+export SLACK_BOT_TOKEN="xoxb-..."
+export SLACK_APP_TOKEN="xapp-..."
+```
+
+Settings in `settings.json` take priority over env vars.
+
+### Optional Pinet mesh auth
+
+Shared-secret mesh auth is **optional**. You can configure it with either settings keys or environment variables:
+
+```json
+{
+  "slack-bridge": {
+    "meshSecret": "shared-secret"
+  }
+}
+```
+
+```json
+{
+  "slack-bridge": {
+    "meshSecretPath": "/Users/alice/.config/pi/pinet.secret"
+  }
+}
+```
+
+```bash
+export PINET_MESH_SECRET="shared-secret"
+# or
+export PINET_MESH_SECRET_PATH="$HOME/.config/pi/pinet.secret"
+```
+
+Behavior and precedence:
+
+- `slack-bridge.meshSecret` and `slack-bridge.meshSecretPath` override the environment fallbacks.
+- Inline secrets win over secret paths. If `meshSecret` or `PINET_MESH_SECRET` is set, the corresponding `*Path` value is ignored.
+- If all four values are unset, broker/follower mesh auth is disabled.
+- A broker started with `meshSecretPath` creates the secret file if it does not exist yet.
+- A follower started with `meshSecretPath` does **not** create the file. If the configured file is missing, follow fails with a clear error telling you to point at an existing file, provide `meshSecret` directly, or leave both unset to disable shared-secret auth.
+- A follower configured for mesh auth will fail closed against an older/no-auth broker with a clear compatibility error. It will **not** silently retry as an unauthenticated follower.
+
+### Full settings reference
+
+```json
+{
+  "slack-bridge": {
+    "botToken": "xoxb-...",
+    "appToken": "xapp-...",
+    "allowedUsers": ["U_EXAMPLE_MEMBER_ID"],
+    "defaultChannel": "C_EXAMPLE_CHANNEL_ID",
+    "logChannel": "#pinet-logs",
+    "logLevel": "actions",
+    "autoFollow": true,
+    "meshSecretPath": "/Users/alice/.config/pi/pinet.secret",
+    "suggestedPrompts": [{ "title": "Status", "message": "What are you working on?" }],
+    "security": {
+      "readOnly": false,
+      "requireConfirmation": ["slack_create_channel"],
+      "blockedTools": []
+    }
+  }
+}
+```
+
+| Key                            | Required | Description                                                                                             |
+| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------- |
+| `botToken`                     | **yes**  | Bot User OAuth Token (`xoxb-...`)                                                                       |
+| `appToken`                     | **yes**  | App-Level Token for Socket Mode (`xapp-...`)                                                            |
+| `allowedUsers`                 | no       | Slack user IDs that can interact (all users if unset)                                                   |
+| `defaultChannel`               | no       | Default channel for `slack_post_channel`                                                                |
+| `logChannel`                   | no       | Channel for broker activity logs                                                                        |
+| `logLevel`                     | no       | `"errors"`, `"actions"` (default), or `"verbose"`                                                       |
+| `autoFollow`                   | no       | Auto-connect as follower when broker is running                                                         |
+| `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                                                      |
+| `security.readOnly`            | no       | Block all write tools                                                                                   |
+| `security.requireConfirmation` | no       | Tools that need user approval before executing                                                          |
+| `security.blockedTools`        | no       | Tools that are completely disabled                                                                      |
+
+## Usage
+
+Once configured, Pinet appears in Slack's sidebar. Users open it, type a message, and the pi agent responds.
+
+```
+User opens Pinet in Slack sidebar
+  └─► types a message
+        └─► 👀 reaction appears (thinking)
+              └─► message queued for pi agent
+                    └─► agent responds via slack_send
+                          └─► 👀 removed, reply appears in thread
+```
+
+Messages queue while the agent is busy. When the agent finishes, it automatically drains the inbox and responds.
+
+### Available tools
+
+| Tool                   | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `slack_send`           | Reply in a Slack assistant thread                              |
+| `slack_react`          | Add an emoji reaction to a message                             |
+| `slack_read`           | Read messages from a thread                                    |
+| `slack_inbox`          | Check pending incoming messages                                |
+| `slack_upload`         | Upload files, snippets, or diffs into Slack                    |
+| `slack_schedule`       | Schedule a message for later delivery                          |
+| `slack_post_channel`   | Post to a channel (by name or ID)                              |
+| `slack_read_channel`   | Read channel history or a thread in a channel                  |
+| `slack_create_channel` | Create a new Slack channel                                     |
+| `slack_project_create` | Create a project channel + RFC canvas + bot invite in one call |
+| `slack_pin`            | Pin or unpin a message                                         |
+| `slack_bookmark`       | Add, list, or remove channel bookmarks                         |
+| `slack_export`         | Export a thread as markdown, plain text, or JSON               |
+| `slack_presence`       | Check if users are active, away, or in DND                     |
+| `slack_canvas_create`  | Create a standalone or channel canvas                          |
+| `slack_canvas_update`  | Append, prepend, or replace canvas content                     |
+| `slack_blocks_build`   | Build Block Kit message templates                              |
+| `slack_modal_build`    | Build Slack modal templates                                    |
+| `slack_modal_open`     | Open a modal from a trigger interaction                        |
+| `slack_modal_push`     | Push a new step onto a modal stack                             |
+| `slack_modal_update`   | Update an existing open modal                                  |
+| `slack_confirm_action` | Request user confirmation before a dangerous action            |
+
+### Slash commands
+
+| Command         | Description                                         |
+| --------------- | --------------------------------------------------- |
+| `/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             |
+| `/slack-logs`   | Show recent Slack bridge log entries                |
+
+## Pinet (Multi-Agent Mode)
+
+Pinet supports a broker/follower architecture for coordinating multiple pi agents over Slack.
+
+### Quick start
+
+**Broker** (one per mesh — coordinates routing and health):
+
+```
+/pinet-start
+```
+
+**Follower** (workers that connect to the broker):
+
+```
+/pinet-follow
+```
+
+Or set `"autoFollow": true` in settings to auto-connect when a broker is running.
+
+### Multi-agent tools
+
+| Tool             | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `pinet_message`  | Send a message to another connected agent             |
+| `pinet_agents`   | List connected agents with status and capabilities    |
+| `pinet_free`     | Signal that this agent is idle and available for work |
+| `pinet_schedule` | Schedule a future wake-up message for this agent      |
+
+### Broker commands
+
+| 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-skin <theme>`   | Change the mesh naming theme (broker only) |
+
+### How it works
+
+- The **broker** runs Slack Socket Mode, routes messages to agents, monitors health via the RALPH loop, and maintains a control plane canvas
+- **Followers** connect to the broker over a local Unix socket, poll for work, and report results
+- Agents can optionally authenticate using a shared local secret (`meshSecret` or `meshSecretPath`); when both are unset, mesh auth is disabled
+- Thread ownership is first-responder-wins — the first agent to reply claims the thread
+
+## Security
+
+- **User allowlist**: Set `allowedUsers` to restrict who can interact with Pinet
+- **Tool guardrails**: Use `security.requireConfirmation` and `security.blockedTools` to control tool access
+- **Mesh authentication**: Optional. Configure `meshSecret` or `meshSecretPath` (or `PINET_MESH_SECRET` / `PINET_MESH_SECRET_PATH`) to require a shared secret; leave them unset to disable shared-secret auth. Configured followers fail closed on missing secret files or older/no-auth brokers rather than silently downgrading.
+
+Find Slack user IDs: click a user's profile → **More** → **Copy member ID**.
+
+---
+
+## Development
+
+### Build
+
+```bash
+pnpm run build
+```
+
+### Lint / Typecheck / Test
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+```
+
+### Deploy manifest to Slack
+
+```bash
+pnpm deploy:slack
+```
+
+Requires `appId` and `appConfigToken` in settings (or `SLACK_APP_ID` / `SLACK_APP_CONFIG_TOKEN` env vars).
+
+### Architecture
+
+- **Socket Mode** — outbound WebSocket, no public URL needed
+- **Zero runtime npm deps** — native `fetch`, `WebSocket`, `node:sqlite` (Node 22+)
+- **Hybrid inbox** — queue when busy, auto-drain when idle
+- **Reactions** — 👀 as a lightweight "thinking" indicator
+- **Thread persistence** — thread state survives `/reload`
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/dist/activity-log.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlackActivityLogger = void 0;
+exports.normalizeActivityLogLevel = normalizeActivityLogLevel;
+exports.shouldLogActivity = shouldLogActivity;
+exports.redactSensitiveText = redactSensitiveText;
+exports.buildActivityLogText = buildActivityLogText;
+exports.buildActivityLogBlocks = buildActivityLogBlocks;
+exports.buildActivityLogThreadHeader = buildActivityLogThreadHeader;
+exports.formatRecentActivityLogEntries = formatRecentActivityLogEntries;
+const LEVEL_RANK = {
+    errors: 0,
+    actions: 1,
+    verbose: 2,
+};
+const DEFAULT_MAX_RECENT_ENTRIES = 100;
+const MAX_TEXT_LENGTH = 2800;
+const REDACTED = "[REDACTED]";
+function normalizeWhitespace(value) {
+    return value.replace(/\r\n/g, "\n").replaceAll("\u0000", "").trim();
+}
+function truncate(value, maxLength = MAX_TEXT_LENGTH) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+function normalizeActivityLogLevel(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "errors" || normalized === "actions" || normalized === "verbose") {
+        return normalized;
+    }
+    return "actions";
+}
+function shouldLogActivity(configuredLevel, eventLevel) {
+    return LEVEL_RANK[eventLevel] <= LEVEL_RANK[configuredLevel];
+}
+function redactSensitiveText(value) {
+    let redacted = normalizeWhitespace(value);
+    const replacements = [
+        [/xox[baprs]-[A-Za-z0-9-]+/g, REDACTED],
+        [/xoxe\.[A-Za-z0-9.-]+/g, REDACTED],
+        [/(Bearer\s+)[^\s]+/gi, `$1${REDACTED}`],
+        [
+            /\b(token|password|secret|api[_-]?key|authorization)\b\s*([:=])\s*([^\s,;]+)/gi,
+            `$1$2 ${REDACTED}`,
+        ],
+        [
+            /("(?:token|password|secret|api[_-]?key|authorization)"\s*:\s*")([^"]+)(")/gi,
+            `$1${REDACTED}$3`,
+        ],
+        [/(SLACK_[A-Z_]+)=([^\s]+)/g, `$1=${REDACTED}`],
+    ];
+    for (const [pattern, replacement] of replacements) {
+        redacted = redacted.replace(pattern, replacement);
+    }
+    return truncate(redacted);
+}
+function sanitizeFieldValue(value) {
+    if (value == null) {
+        return "—";
+    }
+    if (typeof value === "boolean") {
+        return value ? "yes" : "no";
+    }
+    return redactSensitiveText(String(value));
+}
+function sanitizeEntry(entry, now) {
+    return {
+        ...entry,
+        title: redactSensitiveText(entry.title),
+        summary: redactSensitiveText(entry.summary),
+        details: entry.details?.map((detail) => redactSensitiveText(detail)).filter(Boolean),
+        fields: entry.fields
+            ?.map((field) => ({
+            label: redactSensitiveText(field.label),
+            value: sanitizeFieldValue(field.value),
+        }))
+            .filter((field) => field.label.length > 0),
+        timestamp: entry.timestamp ?? now.toISOString(),
+    };
+}
+function getToneEmoji(tone) {
+    switch (tone) {
+        case "success":
+            return "✅";
+        case "warning":
+            return "⚠️";
+        case "error":
+            return "🚨";
+        case "info":
+        default:
+            return "📡";
+    }
+}
+function formatSlackTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    if (Number.isNaN(date.getTime())) {
+        return timestamp;
+    }
+    return date.toISOString().replace(".000Z", "Z");
+}
+function buildActivityLogText(agentName, agentEmoji, entry) {
+    return `${getToneEmoji(entry.tone)} ${entry.title} — ${entry.summary} (${agentEmoji} ${agentName} · ${formatSlackTimestamp(entry.timestamp)})`;
+}
+function buildActivityLogBlocks(agentName, agentEmoji, entry) {
+    const blocks = [
+        {
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: `*${getToneEmoji(entry.tone)} ${entry.title}*\n${entry.summary}`,
+            },
+        },
+    ];
+    const fields = (entry.fields ?? [])
+        .filter((field) => field.value !== "—")
+        .slice(0, 10)
+        .map((field) => ({
+        type: "mrkdwn",
+        text: `*${field.label}*\n${field.value}`,
+    }));
+    if (fields.length > 0) {
+        blocks.push({ type: "section", fields });
+    }
+    if (entry.details && entry.details.length > 0) {
+        blocks.push({
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: entry.details.map((detail) => `• ${detail}`).join("\n"),
+            },
+        });
+    }
+    blocks.push({
+        type: "context",
+        elements: [
+            {
+                type: "mrkdwn",
+                text: `${agentEmoji} ${agentName} · ${entry.kind} · ${formatSlackTimestamp(entry.timestamp)}`,
+            },
+        ],
+    });
+    return blocks;
+}
+function buildActivityLogThreadHeader(agentName, agentEmoji, dateKey) {
+    return {
+        text: `Pinet activity log — ${dateKey}`,
+        blocks: [
+            {
+                type: "section",
+                text: {
+                    type: "mrkdwn",
+                    text: `*📚 Pinet activity log — ${dateKey}*\nBroker-side coordination updates: assignments, completions, merges, stalls, and RALPH maintenance events.`,
+                },
+            },
+            {
+                type: "context",
+                elements: [
+                    {
+                        type: "mrkdwn",
+                        text: `${agentEmoji} ${agentName} · daily thread`,
+                    },
+                ],
+            },
+        ],
+    };
+}
+function formatRecentActivityLogEntries(entries) {
+    if (entries.length === 0) {
+        return "No activity log entries recorded in this session.";
+    }
+    return entries
+        .map((entry) => `[${formatSlackTimestamp(entry.timestamp)}] ${entry.title} — ${entry.summary}`)
+        .join("\n");
+}
+class SlackActivityLogger {
+    deps;
+    queue = [];
+    recent = [];
+    maxRecentEntries;
+    flushTimer = null;
+    flushRunning = false;
+    resolvedChannelCache = null;
+    dailyThreadCache = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.maxRecentEntries = deps.maxRecentEntries ?? DEFAULT_MAX_RECENT_ENTRIES;
+    }
+    log(entry) {
+        const rawChannel = this.deps.getLogChannel()?.trim();
+        if (!rawChannel) {
+            return;
+        }
+        const configuredLevel = normalizeActivityLogLevel(this.deps.getLogLevel());
+        if (!shouldLogActivity(configuredLevel, entry.level)) {
+            return;
+        }
+        const sanitized = sanitizeEntry(entry, this.getNow());
+        this.recent.unshift(sanitized);
+        this.recent.splice(this.maxRecentEntries);
+        this.queue.push({ entry: sanitized, attempts: 0 });
+        this.scheduleFlush(0);
+    }
+    getRecentEntries(limit = 20) {
+        return this.recent.slice(0, Math.max(0, limit));
+    }
+    clearPending() {
+        this.queue.splice(0, this.queue.length);
+        this.resolvedChannelCache = null;
+        this.dailyThreadCache = null;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    getNow() {
+        return this.deps.now ? this.deps.now() : new Date();
+    }
+    scheduleFlush(delayMs) {
+        if (this.flushTimer || this.flushRunning || this.queue.length === 0) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flushNext();
+        }, delayMs);
+        this.flushTimer.unref?.();
+    }
+    async flushNext() {
+        if (this.flushRunning) {
+            return;
+        }
+        const next = this.queue.shift();
+        if (!next) {
+            return;
+        }
+        this.flushRunning = true;
+        try {
+            await this.postEntry(next.entry);
+        }
+        catch (error) {
+            if (next.attempts < 2) {
+                this.queue.unshift({ entry: next.entry, attempts: next.attempts + 1 });
+            }
+            else {
+                this.deps.onError?.(error);
+            }
+        }
+        finally {
+            this.flushRunning = false;
+            if (this.queue.length > 0) {
+                this.scheduleFlush(1000);
+            }
+        }
+    }
+    async resolveLogChannel(rawChannel) {
+        if (this.resolvedChannelCache?.raw === rawChannel) {
+            return this.resolvedChannelCache.id;
+        }
+        const channelId = await this.deps.resolveChannel(rawChannel);
+        this.resolvedChannelCache = { raw: rawChannel, id: channelId };
+        return channelId;
+    }
+    async ensureDailyThread(rawChannel, channelId) {
+        const dateKey = this.getNow().toISOString().slice(0, 10);
+        if (this.dailyThreadCache?.rawChannel === rawChannel &&
+            this.dailyThreadCache.dateKey === dateKey) {
+            return this.dailyThreadCache.threadTs;
+        }
+        const token = this.deps.getBotToken();
+        if (!token) {
+            throw new Error("Slack bot token unavailable for activity logging.");
+        }
+        const heading = buildActivityLogThreadHeader(this.deps.getAgentName(), this.deps.getAgentEmoji(), dateKey);
+        const response = await this.deps.slack("chat.postMessage", token, {
+            channel: channelId,
+            text: heading.text,
+            blocks: heading.blocks,
+        });
+        const threadTs = typeof response.ts === "string" ? response.ts : null;
+        if (!threadTs) {
+            throw new Error("Slack activity log thread creation did not return a ts.");
+        }
+        this.dailyThreadCache = { rawChannel, dateKey, threadTs };
+        return threadTs;
+    }
+    async postEntry(entry) {
+        const rawChannel = this.deps.getLogChannel()?.trim();
+        const token = this.deps.getBotToken();
+        if (!rawChannel || !token) {
+            return;
+        }
+        const channelId = await this.resolveLogChannel(rawChannel);
+        const threadTs = await this.ensureDailyThread(rawChannel, channelId);
+        await this.deps.slack("chat.postMessage", token, {
+            channel: channelId,
+            thread_ts: threadTs,
+            text: buildActivityLogText(this.deps.getAgentName(), this.deps.getAgentEmoji(), entry),
+            blocks: buildActivityLogBlocks(this.deps.getAgentName(), this.deps.getAgentEmoji(), entry),
+        });
+    }
+}
+exports.SlackActivityLogger = SlackActivityLogger;