@usepipa/pipa 0.5.5 → 0.5.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,17 +1,65 @@
1
- # Pipa
1
+ <p align="center">
2
+ <a href="https://www.usepipa.com/opencode-slack?utm_source=github&utm_medium=repo_readme&utm_campaign=signup&utm_content=readme_banner">
3
+ <img src="docs/assets/banner.png" alt="Pipa: run OpenCode from Slack" width="100%">
4
+ </a>
5
+ </p>
6
+
7
+ <p align="center">
8
+ <a href="https://github.com/lunchpaillola/pipa/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/lunchpaillola/pipa/ci.yml?branch=main&style=flat-square&label=CI"></a>
9
+ <a href="https://www.npmjs.com/package/@usepipa/pipa"><img alt="npm" src="https://img.shields.io/npm/v/@usepipa/pipa?style=flat-square&color=2437F5&label=npm"></a>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <strong>Pipa turns a Slack thread into a durable OpenCode session on one private server, local by default.</strong><br>
14
+ No relay, no database, no public endpoint.
15
+ </p>
16
+
17
+ <p align="center">
18
+ <a href="https://www.youtube.com/watch?v=rlTMdkPWPcA"><strong>Watch the 3-minute setup</strong></a>
19
+ ·
20
+ <a href="https://www.usepipa.com/opencode-slack?utm_source=github&utm_medium=repo_readme&utm_campaign=signup&utm_content=readme_how_it_works">How it works</a>
21
+ ·
22
+ <a href="CONTRIBUTING.md">Contributing</a>
23
+ ·
24
+ <a href="https://github.com/lunchpaillola/pipa/issues">Issues</a>
25
+ </p>
26
+
27
+ > **Early preview.** Features may break unintentionally, and CLI commands, configuration, and Slack behavior may continue to change.
28
+
29
+ ## Why Pipa
30
+
31
+ | What it does | What that means |
32
+ | --- | --- |
33
+ | **One server** | In local mode, Pipa starts one private OpenCode server on `127.0.0.1` and reuses it for every Slack turn. Attached servers follow their own network controls. |
34
+ | **Thread sessions** | A mention starts a session; replies in that thread continue it. Different threads run independently, and a newer message interrupts only its own thread. |
35
+ | **Routines** | Schedule timezone-aware work that runs through the same agent and delivers to an exact channel or thread. |
36
+ | **Generated files** | In local mode, long work returns as a concise summary with generated files from a private per-turn directory. Attached non-loopback servers return inline text. |
37
+ | **Access control** | Restrict by Slack channel, human user, and bot. Allowlists are rechecked on every turn, interaction, and delivery. |
38
+ | **Restart** | `pipa restart` hands off to a detached worker and reports a durable status. |
39
+
40
+ If Pipa is useful, [star the repo](https://github.com/lunchpaillola/pipa).
41
+
42
+ ## Quickstart
43
+
44
+ **Runs on** macOS, Linux, and Windows. **Requires** Node.js 22 or newer, [OpenCode](https://opencode.ai) installed and authenticated, and a Slack workspace where you can create an app.
2
45
 
3
- [![CI](https://github.com/lunchpaillola/pipa/actions/workflows/ci.yml/badge.svg)](https://github.com/lunchpaillola/pipa/actions/workflows/ci.yml)
4
- [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
46
+ ```sh
47
+ npm install --global @usepipa/pipa
48
+ pipa init
49
+ pipa start
50
+ ```
51
+
52
+ `pipa init` creates the Slack app manifest, opens the install flow, and saves the profile under `~/.pipa`. Invite Pipa to a channel and mention it. The [3-minute setup video](https://www.youtube.com/watch?v=rlTMdkPWPcA) shows the flow, and the [OpenCode Slack integration guide](https://www.usepipa.com/opencode-slack?utm_source=github&utm_medium=repo_readme&utm_campaign=signup&utm_content=readme_install_guide) is the current written path.
5
53
 
6
- Pipa runs Slack through one persistent private OpenCode server with no hosted relay, database, public endpoint, or sandbox.
54
+ ## Security model
7
55
 
8
- [View Pipa on GitHub](https://github.com/lunchpaillola/pipa). If it is useful, star the repo so more people can find it.
56
+ In local mode, Pipa runs on your machine, not behind a relay. The local OpenCode server binds to `127.0.0.1` on an operating-system-assigned port; attached servers follow their own network controls. Slack access is limited by channel, user, and bot allowlists, rechecked on every turn. Tokens stay in the local profile with private file permissions, and OpenCode manages provider credentials.
9
57
 
10
- **Pipa is in early preview. Features may break unintentionally, and CLI commands, configuration, and Slack behavior may continue to change.**
58
+ Read [SECURITY.md](SECURITY.md) for the full model and reporting path.
11
59
 
12
60
  ## Pipa Managed
13
61
 
14
- Want someone to configure, run, and manage agent workflows for your company? Check out [Pipa Managed](https://usepipa.com/managed). We set up a Slack-native operations agent around how your team works, then keep its workflows running and improving over time.
62
+ Want Lunch Pail Labs to configure, run, and manage agent workflows for your company? Check out [Pipa Managed](https://usepipa.com/managed?utm_source=github&utm_medium=repo_readme&utm_campaign=signup&utm_content=readme_footer). We set up a Slack-native operations agent for your team, then keep the workflows running.
15
63
 
16
64
  ## Local Socket Mode
17
65
 
@@ -47,9 +95,9 @@ pipa init
47
95
  pipa start
48
96
  ```
49
97
 
50
- Keep `pipa start` running, invite Pipa to a trusted public or private Slack channel, and mention it there. Pipa starts one OpenCode server bound to `127.0.0.1` on an operating-system-assigned port and reuses it for every Slack turn. Port `0` asks the operating system for an available port; no port configuration is required. Pipa replies in a thread, and follow-up messages in that thread reuse the same OpenCode session without another mention. A newer follow-up interrupts an active turn in the same thread, while other threads continue independently. While a turn is active, Pipa shows a typing status in its Slack thread.
98
+ Keep `pipa start` running, invite Pipa to a trusted public or private Slack channel, and mention it there. In owned local mode, Pipa starts one OpenCode server bound to `127.0.0.1` on an operating-system-assigned port and reuses it for every Slack turn. Port `0` asks the operating system for an available port; no port configuration is required. Pipa replies in a thread, and follow-up messages in that thread reuse the same OpenCode session without another mention. A newer follow-up interrupts an active turn in the same thread, while other threads continue independently. While a turn is active, Pipa shows a typing status in its Slack thread.
51
99
 
52
- Pipa keeps naturally short answers inline. For deeper work, OpenCode can return a concise summary with suitable generated files, such as documents, spreadsheets, PDFs, or images. Files are read only from a private session directory under `.pipa/artifacts` in the configured working directory. The directory is cleared before each turn, files are validated and limited to 10 files and 100 MB per file or response, and the directory is deleted locally after delivery. If file delivery fails, Pipa retries the declaration-free summary without the files. Attached OpenCode servers on non-loopback hosts use inline text fallback instead of local artifact delivery.
100
+ Pipa keeps naturally short answers inline. For deeper work, OpenCode can return a concise summary with suitable generated files, such as documents, spreadsheets, PDFs, or images. Files are read only from a private session directory under `.pipa/artifacts` in the configured working directory. The directory is cleared before each turn, files are validated and limited to 10 files and 100 MB total, and the directory is deleted locally after delivery. If file delivery fails, Pipa retries the declaration-free summary without the files. Attached OpenCode servers on non-loopback hosts use inline text fallback instead of local artifact delivery.
53
101
 
54
102
  Incoming messages can include up to Slack's 10-file limit, with a maximum size of 100 MB per file. Attachments require a text prompt and are copied to a temporary directory only for the duration of the turn.
55
103
 
@@ -73,6 +121,18 @@ A human user's mention is only handled when the channel and user pass their resp
73
121
 
74
122
  By default Pipa ignores messages sent by other Slack apps. Unlike the human user and channel lists, an absent or empty `allowedSlackBotIds` disables all other bots. List their bot IDs to let those messages through; an allowed bot only needs its bot ID (e.g. `B0C6Q27E82X`), not an entry in `allowedSlackUserIds`. Bots still must pass the channel allowlist. Bots not on the list stay ignored even when `allowedSlackUserIds` is empty. Set it non-interactively during setup with `PIPA_ALLOWED_BOT_IDS` (comma-separated).
75
123
 
124
+ #### Mention-only mode
125
+
126
+ By default, once Pipa is mentioned in a thread it subscribes to that thread and answers every later message in it without another mention. Set `mentionOnly` to `true` to require a direct @-mention for every turn, including in threads Pipa is already in:
127
+
128
+ ```json
129
+ {
130
+ "mentionOnly": true
131
+ }
132
+ ```
133
+
134
+ `pipa init` asks for this, and you can set it non-interactively with `PIPA_MENTION_ONLY` (`1`, `true`, or `yes`). An absent or `false` value keeps the default thread-following behavior. Routines are unaffected.
135
+
76
136
  #### Find the sender's bot ID
77
137
 
78
138
  Use the message event's `bot_id` (`B…`), not the app ID (`A…`) or bot user ID (`U…`). To look up the sender app's OAuth bot ID:
package/bin/pipa.mjs CHANGED
@@ -359,8 +359,11 @@ async function init(io) {
359
359
  ?? (await prompt.question("Allowed Slack user IDs (comma-separated, e.g. UFWBSCZ54; leave empty to allow any user): ")).trim();
360
360
  const allowedSlackBotIds = process.env.PIPA_ALLOWED_BOT_IDS
361
361
  ?? (await prompt.question("Allowed Slack bot IDs (comma-separated, e.g. B0C6Q27E82X; leave empty to ignore bot messages): ")).trim();
362
+ const mentionOnly = process.env.PIPA_MENTION_ONLY !== undefined
363
+ ? /^(1|true|yes)$/iu.test(process.env.PIPA_MENTION_ONLY.trim())
364
+ : /^y(es)?$/iu.test((await prompt.question("Only respond when @-mentioned, even in threads Pipa is already in? [y/N]: ")).trim());
362
365
  io.output.write("\nChecking OpenCode and Slack credentials...\n");
363
- const result = await initializePipa({ botName, workingDirectory, slackAppToken, slackBotToken, allowedSlackChannelIds, allowedSlackUserIds, allowedSlackBotIds });
366
+ const result = await initializePipa({ botName, workingDirectory, slackAppToken, slackBotToken, allowedSlackChannelIds, allowedSlackUserIds, allowedSlackBotIds, mentionOnly });
364
367
  io.output.write(`✓ Credentials validated.\n\nSaved config to ${result.paths.config}. Run \`pipa start\`.\n`);
365
368
  } finally {
366
369
  prompt.close();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usepipa/pipa",
3
- "version": "0.5.5",
3
+ "version": "0.5.6",
4
4
  "description": "Run Pipa through Slack Socket Mode with OpenCode",
5
5
  "keywords": [
6
6
  "slack",
package/src/app.mjs CHANGED
@@ -21,6 +21,7 @@ export async function initializePipa(input, options = {}) {
21
21
  allowedSlackChannelIds: normalizeIdList(input.allowedSlackChannelIds),
22
22
  allowedSlackUserIds: normalizeIdList(input.allowedSlackUserIds),
23
23
  allowedSlackBotIds: normalizeIdList(input.allowedSlackBotIds),
24
+ mentionOnly: input.mentionOnly === true,
24
25
  };
25
26
  const openCodeVersion = await (options.checkOpenCode ?? runOpenCodeVersion)();
26
27
  if (!/^v?1(?:\.|$)/u.test(openCodeVersion)) throw new Error(`Pipa requires OpenCode v1; found ${openCodeVersion || "an unknown version"}.`);
@@ -181,6 +182,7 @@ export async function startPipa(options = {}) {
181
182
 
182
183
  const handle = async (thread, message, subscribe) => {
183
184
  if (!accepting || !isAuthorized(thread, message, config) || shouldIgnore(thread, message, config)) return;
185
+ if (config.mentionOnly && !subscribe && !message.isMention) return;
184
186
  const messageText = subscribe || message.isMention ? stripMention(message.text) : message.text.trim();
185
187
  const missingLinks = (message.links ?? []).map((link) => link.url)
186
188
  .filter((url) => typeof url === "string" && !messageText.split(/\s+/u).includes(url));
package/src/state.mjs CHANGED
@@ -183,6 +183,9 @@ export async function loadConfig(file = pipaPaths().config) {
183
183
  throw new Error(`Invalid Pipa config: ${key} must be a list of non-empty Slack IDs.`);
184
184
  }
185
185
  }
186
+ if (config.mentionOnly !== undefined && typeof config.mentionOnly !== "boolean") {
187
+ throw new Error("Invalid Pipa config: mentionOnly must be a boolean.");
188
+ }
186
189
  normalizeModel(config.defaultModel);
187
190
  return { ...config, slackMode };
188
191
  }