@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 +69 -9
- package/bin/pipa.mjs +4 -1
- package/package.json +1 -1
- package/src/app.mjs +2 -0
- package/src/state.mjs +3 -0
package/README.md
CHANGED
|
@@ -1,17 +1,65 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
4
|
-
|
|
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
|
-
|
|
54
|
+
## Security model
|
|
7
55
|
|
|
8
|
-
|
|
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
|
-
|
|
58
|
+
Read [SECURITY.md](SECURITY.md) for the full model and reporting path.
|
|
11
59
|
|
|
12
60
|
## Pipa Managed
|
|
13
61
|
|
|
14
|
-
Want
|
|
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
|
|
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
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
|
}
|