@usepipa/pipa 0.6.0-beta.1 → 0.6.0-beta.3

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
@@ -10,12 +10,11 @@
10
10
  </p>
11
11
 
12
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.
13
+ <strong>Pipa turns OpenCode into a Slack agent. Start sessions and talk to OpenCode from Slack.</strong>
15
14
  </p>
16
15
 
17
16
  <p align="center">
18
- <a href="https://www.youtube.com/watch?v=rlTMdkPWPcA"><strong>Watch the 3-minute setup</strong></a>
17
+ <a href="https://www.youtube.com/watch?v=rlTMdkPWPcA"><strong>Watch the four-minute setup video</strong></a>
19
18
  ·
20
19
  <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
20
  ·
@@ -24,20 +23,21 @@
24
23
  <a href="https://github.com/lunchpaillola/pipa/issues">Issues</a>
25
24
  </p>
26
25
 
27
- > **Early preview.** Features may break unintentionally, and CLI commands, configuration, and Slack behavior may continue to change.
26
+ > **Early preview.** Features may break. Commands, configuration, and Slack behavior may change.
27
+
28
+ If Pipa is useful, [star the repo](https://github.com/lunchpaillola/pipa).
28
29
 
29
30
  ## Why Pipa
30
31
 
31
32
  | What it does | What that means |
32
33
  | --- | --- |
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. |
34
+ | **Thread sessions** | Mention Pipa to start a session. Reply in the thread to keep working. |
35
+ | **Routines** | Schedule work in your timezone. Send results to a channel or thread. |
36
+ | **Access control** | Choose which Slack channels, people, and bots can use Pipa. |
39
37
 
40
- If Pipa is useful, [star the repo](https://github.com/lunchpaillola/pipa).
38
+ ## Pipa Managed
39
+
40
+ Want Lunch Pail Labs to set up and run agent workflows for your team? See [Pipa Managed](https://usepipa.com/managed?utm_source=github&utm_medium=repo_readme&utm_campaign=signup&utm_content=readme_footer).
41
41
 
42
42
  ## Quickstart
43
43
 
@@ -49,47 +49,31 @@ pipa init
49
49
  pipa start
50
50
  ```
51
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.
52
+ `pipa init` walks you through Slack setup and saves your profile under `~/.pipa`. Invite Pipa to an allowed channel and mention it. Follow the [four-minute setup video](https://www.youtube.com/watch?v=rlTMdkPWPcA) or the [written tutorial](https://www.usepipa.com/opencode-slack?utm_source=github&utm_medium=repo_readme&utm_campaign=signup&utm_content=readme_install_guide).
53
53
 
54
54
  ### Opt-in 0.6 beta
55
55
 
56
- `0.6.0-beta.1` is being prepared for controlled testing, not stable release.
57
- Once published, opt in with:
56
+ `0.6.0-beta.3` is being prepared for controlled testing, not stable release. Once published, opt in with:
58
57
 
59
58
  ```sh
60
- npm install --global @usepipa/pipa@0.6.0-beta.1
59
+ npm install --global @usepipa/pipa@0.6.0-beta.3
61
60
  ```
62
61
 
63
- Normal installs keep using npm's `latest` tag; subsequent betas use `@beta`.
64
- This updates Pipa only, not OpenCode. For an existing installation, arrange a
65
- maintenance window, stop Pipa and back up its profile before installing. Keep
66
- your current OpenCode version initially; do not rerun `pipa init` or create a
67
- second listener. See the [beta release notes](https://github.com/lunchpaillola/pipa/blob/main/docs/beta-release.md)
68
- for changes, limitations, and trial/rollback guidance.
62
+ Normal installs use npm's `latest` tag; later betas use `@beta`. This updates Pipa, not OpenCode. Before upgrading, stop Pipa and back up its profile. Keep your current OpenCode version initially. Do not rerun `pipa init` or start a second listener. Read the [beta release notes](https://github.com/lunchpaillola/pipa/blob/main/docs/beta-release.md) for limits and rollback steps.
69
63
 
70
64
  ## Security model
71
65
 
72
- 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.
66
+ Pipa runs locally by default. Its OpenCode server listens on `127.0.0.1`; attached servers use their own network controls. Slack allowlists control who can send requests. Empty channel and human-user lists allow everyone otherwise eligible. Other bots are blocked unless listed.
73
67
 
74
- Read [SECURITY.md](SECURITY.md) for the full model and reporting path.
68
+ **The working directory is a starting location, not a sandbox.** Allowed users can ask the agent to use the OpenCode profile's tools and permissions beyond that directory. Set channel and user allowlists before sharing Pipa.
75
69
 
76
- ## Pipa Managed
70
+ Slack tokens stay in the local profile with private file permissions. OpenCode manages provider credentials. Keep tokens, passwords, and local state out of shared output and commits.
77
71
 
78
- 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.
72
+ Read [SECURITY.md](SECURITY.md) for security boundaries and reporting.
79
73
 
80
74
  ## Local Socket Mode
81
75
 
82
- Profiles created by `pipa init` use Socket Mode. Profiles written before mode support continue to load as Socket Mode.
83
-
84
- ### Requirements
85
-
86
- - Node.js 22 or newer
87
- - [OpenCode](https://opencode.ai) installed and authenticated; the dual-adapter candidate selects native v1/v2 automatically (current native v2 qualification target: 2.2.5; historical v2 pin: 2.0.29; v1 pins: 1.18.35, 1.19.0; release-qualified minimums pending)
88
- - A Slack workspace where you can create an app
89
-
90
- Invite the Slack app only to channels whose members may use OpenCode in the configured working directory.
91
-
92
- See [OpenCode compatibility](docs/opencode-compatibility.md) for remaining-on-v1 and deliberate-v2 upgrade paths, matched-snapshot rollback, capability differences and remaining release gates. Upgrading Pipa preserves the existing Slack profile; it does not require recreating the Slack app or upgrading OpenCode.
76
+ Socket Mode connects Pipa to Slack through an outbound connection. You do not need a public web endpoint.
93
77
 
94
78
  ### Install
95
79
 
@@ -105,7 +89,7 @@ npm install --global @usepipa/pipa
105
89
  pipa init
106
90
  ```
107
91
 
108
- `pipa init` guides you through creating and installing the Slack app and saving its local configuration. The generated manifest includes `channels:read`, `assistant:write`, and `commands`, plus a slash command derived from your configured bot name (`Chopper` gets `/chopper`) and a `/pipa` compatibility alias. For `Pipa`, these are the same command and appear only once. Review the alias collision guidance below before installing multiple apps in one workspace. Known missing scopes produce upgrade guidance without blocking startup.
92
+ Follow the prompts to create and install the Slack app. Choose your working directory and set channel and user allowlists.
109
93
 
110
94
  3. Start Pipa:
111
95
 
@@ -113,27 +97,23 @@ pipa init
113
97
  pipa start
114
98
  ```
115
99
 
116
- 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.
117
-
118
- Ordinary startup detects OpenCode v1/v2 and waits for listening, workspace readiness and Slack initialization without a default overall timeout or migration-status gate. OpenCode owns schema/data upgrades; Pipa never converts that data. Ctrl+C cancels startup and stops owned children, never attached servers. See the [startup contract](docs/opencode-compatibility.md#startup-contract) for retry, failure and explicit-deadline behavior.
100
+ Keep `pipa start` running. Invite Pipa to an allowed channel and mention it. Replies in that thread continue the same session without another mention. Different threads work independently.
119
101
 
120
- **Managed external-client upgrade notice:** Before upgrading a Managed profile used by external OpenCode clients, set a shared explicit `OPENCODE_SERVER_PASSWORD` in the Pipa server/restart launch environment and configure that password in every external client. For v2, `OPENCODE_PASSWORD` takes precedence; match it to the shared password or remove conflicting values from the server/restart and client environments. If no explicit password is set, Pipa generates a private per-launch password unavailable to external clients, and unauthenticated clients no longer connect. Keep generated passwords private; use an explicit shared password for external access. See [OpenCode compatibility](docs/opencode-compatibility.md).
102
+ On OpenCode v2, replies steer ongoing work, and background results can return to the thread. V1 interrupts the current turn when a new message arrives. Replies missed during a disconnect or restart are not recovered. After restart, send another message in the thread to resume background forwarding. Failed Slack deliveries are not replayed.
121
103
 
122
- 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.
104
+ Startup waits for OpenCode and Slack to be ready, with no default overall timeout. Ctrl+C stops startup and processes Pipa owns, not attached servers. See [OpenCode compatibility](docs/opencode-compatibility.md) for startup, session, and upgrade details.
123
105
 
124
- Incoming messages can include up to Slack's 10-file limit, with a maximum size of 10 MiB (10,485,760 bytes) per file. Pipa checks both declared size and downloaded bytes before sending the prompt. Attachments require a text prompt and are copied to a temporary directory only for the duration of the turn. Outgoing artifact limits remain 10 files and 100 MB per file or response.
106
+ ### Files
125
107
 
126
- For owned OpenCode v2 servers, Pipa defaults `BUN_JSC_maxRegExpStackSize` to `536870912` (a 512 MiB on-demand regular-expression stack ceiling), preserving any explicit override. This works around native 2.0.29 rejecting valid large base64 attachments. An independently launched attached v2 server needs the same setting in **its server process**, for example `BUN_JSC_maxRegExpStackSize=536870912 opencode serve`; setting it only on the attaching Pipa client cannot configure that server. The model's context/media capabilities still determine which admitted files it can process.
108
+ Include a text prompt with attachments. Incoming messages allow up to 10 files, each at most 10 MiB. Temporary copies are removed after the turn. Your model must support the files you send.
127
109
 
128
- ### Recovering a blocked OpenCode turn
110
+ Generated files must stay inside Pipa's private artifact directory under `.pipa/artifacts`. Pipa checks paths, file identity, type, count, and size before sending them. Outgoing limits are 10 files and 100 MB per file or response. If file delivery fails, Pipa retries the summary without files. Attached servers on non-loopback hosts return inline text instead.
129
111
 
130
- If v2 reports that cleanup failed and new intake is blocked, restore the selected server's connectivity and let any independently submitted work finish, then restart Pipa with `pipa restart`. Use `pipa restart --status` to confirm the outcome. If Pipa already exited, run `pipa start` with the same profile and working directory instead.
131
-
132
- Startup reconciles the profile's private `~/.pipa/opencode-recovery.json` before accepting Slack or routine work. It removes only owned instructions/admissions and waits for owned execution to settle; it does not replay the failed prompt. Keep the recovery file and session mappings intact. If startup still blocks, resolve the reported server/workspace or foreign-writer conflict before trying again; deleting the recovery file would discard the evidence needed for safe cleanup. Review any partial side effects before manually retrying the original request.
112
+ Attached v2 servers may need `BUN_JSC_maxRegExpStackSize=536870912` in the **server process** to handle large attachments. Pipa sets this by default for v2 servers it starts, unless overridden. See [attachment guidance](docs/opencode-compatibility.md) for details.
133
113
 
134
114
  ### Access control
135
115
 
136
- By default Pipa answers any human user who mentions it in a channel it can see, excluding DMs and external channels. In a shared workspace, restrict who can use it by listing the allowed Slack channel and user IDs. `pipa init` asks for these, and they are stored in the config:
116
+ By default, Pipa answers human users in channels it can see, excluding DMs and external channels. Use channel and user allowlists to restrict access. `pipa init` asks for these and saves them in the config:
137
117
 
138
118
  ```json
139
119
  {
@@ -147,13 +127,14 @@ By default Pipa answers any human user who mentions it in a channel it can see,
147
127
  }
148
128
  ```
149
129
 
150
- A human user's mention is only handled when the channel and user pass their respective allowlists. An absent or empty `allowedSlackChannelIds` allows any otherwise eligible channel; an absent or empty `allowedSlackUserIds` allows any human user. You can also set them non-interactively during setup with `PIPA_ALLOWED_CHANNEL_IDS` and `PIPA_ALLOWED_USER_IDS` (comma-separated).
151
-
152
- 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).
130
+ - Human requests must pass both the channel and user allowlists. Missing or empty lists allow all otherwise eligible channels or people.
131
+ - Other bots are blocked unless listed in `allowedSlackBotIds`. Use the sender's `bot_id` (`B…`), not its app ID (`A…`) or user ID (`U…`). Bots must pass the channel list but do not need a user-list entry.
132
+ - For scripted setup, use comma-separated `PIPA_ALLOWED_CHANNEL_IDS`, `PIPA_ALLOWED_USER_IDS`, and `PIPA_ALLOWED_BOT_IDS`.
133
+ - Restart Pipa after editing the config. Access is checked again for each turn, interaction, and delivery.
153
134
 
154
135
  #### Mention-only mode
155
136
 
156
- 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:
137
+ Set `mentionOnly` to `true` to require an @-mention for every turn, even in an existing thread:
157
138
 
158
139
  ```json
159
140
  {
@@ -161,15 +142,11 @@ By default, once Pipa is mentioned in a thread it subscribes to that thread and
161
142
  }
162
143
  ```
163
144
 
164
- `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.
145
+ `pipa init` asks for this. For scripted setup, use `PIPA_MENTION_ONLY` (`1`, `true`, or `yes`). Missing or `false` keeps thread-following on. Routines are unaffected.
165
146
 
166
147
  #### Find the sender's bot ID
167
148
 
168
- 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:
169
-
170
- 1. Open the **sender app** at [Slack Apps](https://api.slack.com/apps), not Pipa's app.
171
- 2. Under **OAuth & Permissions**, copy its **Bot User OAuth Token** (`xoxb-…`). If needed, install the app in the workspace via **Install App** first.
172
- 3. Set that token locally in `SLACK_SENDER_BOT_TOKEN`, then call [Slack `auth.test`](https://docs.slack.dev/reference/methods/auth.test/):
149
+ Open the **sender app** at [Slack Apps](https://api.slack.com/apps). Under **OAuth & Permissions**, get its installed Bot User OAuth Token. Set it locally in `SLACK_SENDER_BOT_TOKEN`, then call [Slack `auth.test`](https://docs.slack.dev/reference/methods/auth.test/):
173
150
 
174
151
  ```sh
175
152
  curl --silent --show-error --request POST \
@@ -177,48 +154,38 @@ curl --silent --show-error --request POST \
177
154
  https://slack.com/api/auth.test
178
155
  ```
179
156
 
180
- No Slack CLI is needed. Keep the token out of config examples, shared output, and commits. A successful response includes fields like:
157
+ Use the response's `bot_id` in `allowedSlackBotIds`. Keep the token out of config examples, shared output, and commits.
181
158
 
182
- ```json
183
- {
184
- "ok": true,
185
- "user_id": "U0123456789",
186
- "bot_id": "B0123456789"
187
- }
188
- ```
189
-
190
- Use `bot_id` (`B0123456789`) in `allowedSlackBotIds`; `user_id` identifies the bot's user account and is not the bot allowlist ID.
159
+ **Incoming webhooks:** use the posted message's actual `bot_id`; it may differ from `auth.test`. Read it from the event or [conversation history](https://docs.slack.dev/reference/methods/conversations.history/) with the required access and history scope.
191
160
 
192
- **Incoming webhooks:** the posted message's `bot_id` can differ from the sender app's OAuth `bot_id` returned by `auth.test`. Allow the actual incoming message/event's `bot_id`. If you do not have the event payload, find the posted message with [Slack `conversations.history`](https://docs.slack.dev/reference/methods/conversations.history/) (or [`conversations.replies`](https://docs.slack.dev/reference/methods/conversations.replies/) for a thread reply), using a token with access to that conversation and the required history scope, and read its `bot_id`.
161
+ Allowed bots still need to mention Pipa or reply in a subscribed thread. Webhooks must put the mention in `text`. Only allow bots whose messages you trust as agent requests.
193
162
 
194
- After saving the config, restart Pipa to load the updated allowlist. The allowed bot can start a conversation by posting `<@PIPA_BOT_USER_ID> triage this alert` in an allowed channel, or continue one by replying in a thread Pipa has subscribed to. For an incoming webhook, send that mention in the payload's `text` field. Allowlisting a bot does not make Pipa handle every message it posts in the channel; the normal mention/thread routing still applies. Only allow bots whose messages you trust as requests to your agent.
163
+ ### Use an existing OpenCode server
195
164
 
196
- To use an existing OpenCode server instead, set its URL before starting Pipa. Pipa checks that the server can serve the configured workspace but does not start or stop it. If the server uses authentication, also set `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`:
165
+ Set the server URL before starting Pipa. Pipa checks the workspace but does not start or stop that server. If it requires authentication, also set `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`:
197
166
 
198
167
  ```sh
199
168
  export PIPA_OPENCODE_ATTACH_URL=http://localhost:5555
200
169
  pipa start
201
170
  ```
202
171
 
203
- ### Choosing a model
204
-
205
- Type your installation's command followed by `model` in an allowed Slack channel: `/chopper model` for `Chopper`, `/pipwick model` for `Pipwick`, or the `/pipa model` compatibility alias when registered to that app. Both forms use the same private native modal, authorization checks, and setting. A loading window opens before catalog discovery, then fills with models grouped by provider. Browse or type to filter, choose a model, and Save. Save closes the window promptly; a private channel message confirms success only after fresh validation and persistence, or explains a failure. Wait for that confirmation before testing the new selection. Cancel leaves the setting unchanged. Existing channel and human-user allowlists are rechecked after discovery, on Save, during persistence, and before delivering the private result.
172
+ **External clients of a Managed profile:** set an explicit shared `OPENCODE_SERVER_PASSWORD` in the server/restart environment and every client. On v2, `OPENCODE_PASSWORD` takes precedence; match it or remove conflicting values. Otherwise Pipa generates a private password for each launch, and external clients cannot connect. Keep passwords private. See [OpenCode compatibility](docs/opencode-compatibility.md).
206
173
 
207
- The command is computed from your configured `botName`, not a hardcoded list of bot names. Pipa decomposes accented Latin characters, removes combining marks, lowercases the name, replaces runs of spaces/punctuation/other non-ASCII characters with `-`, trims edge hyphens, and limits the part after `/` to 31 characters (trimming any resulting trailing hyphen). For example, `Workshop "Bot"` becomes `/workshop-bot` and `Café 🧪` becomes `/cafe`. A valid display name with no usable ASCII slug, such as `🤖` or `東京`, falls back to `/pipa` so this optional feature cannot prevent an old profile from starting. Existing display-name validation still applies. Generated commands use a conservative lowercase-letter/digit/hyphen subset within Slack's 32-character limit including `/`.
174
+ ### Choosing a model
208
175
 
209
- **Alias collision:** [Slack slash commands are not namespaced](https://docs.slack.dev/interactivity/implementing-slash-commands/#naming_your_command). If multiple apps register `/pipa`, Slack routes it to the most recently installed app; Pipa cannot redirect it to another installation. In a multi-app workspace, keep distinct named commands and omit the generic alias from other apps' Slack manifests, or assign `/pipa` to exactly one app. Fallback-only installations also share `/pipa`; use a name with an ASCII slug if you need a distinct command. Check the installation name shown in the modal before saving. Case, punctuation, or truncation can also make different names normalize identically; choose distinct resulting names.
176
+ In an allowed channel, type your app's command followed by `model`: `/chopper model` for `Chopper`, or `/pipa model` when registered. Search by model name, ID, or provider. Choose a model, save, and wait for the private confirmation. Cancel leaves the setting unchanged.
210
177
 
211
- The default for new threads is stored as optional `defaultModel: { "providerID": "openai", "modelID": "your-model-id" }` in the existing `.pipa/config.json`. It takes effect without restarting Pipa. Existing threads keep the model recorded in their OpenCode conversation history, including across restarts, so different threads can use different models. New or empty sessions use the current default; when unset, OpenCode chooses its default. If a saved OpenCode session is no longer available, its replacement is a new session and uses the current default. This setting does not select models for separate subagents or external clients.
178
+ The choice applies to new threads without restarting Pipa. Existing threads keep their model across replies and restarts. New routines save the current choice; existing routines keep theirs. Routines with no saved model use OpenCode's default. With no selection, new threads also use OpenCode's default. Changing this setting does not change subagents or external clients.
212
179
 
213
- New routines snapshot the selection when created; preview JSON shows that snapshot. Existing routines and their saved model are unchanged by later saves or routine edits. A routine with no saved model uses OpenCode's default, never the current installation setting. Human replies to routine results retain the model recorded in that conversation. If a thread's provider stops working, reconnect it or choose a different default and start a new thread.
180
+ To use a different model, start a new thread. Changing an existing v2 thread's model still requires OpenCode.
214
181
 
215
- The picker preloads the configured OpenCode model catalog into a native Slack dropdown, grouped by provider. Open the dropdown to browse immediately, or type to filter models; no search callback is needed. Groups contain up to 100 models each, with at most 100 groups. Empty catalogs or catalogs exceeding Slack's limits get a private explanation instead of an empty or truncated list. A listed model may still lack credentials or quota; saving never runs inference to check it. The provider shown beneath each result identifies the connection: `opencode` and `openai` use separate credentials, even for similarly named models. Turn failures identify the provider and HTTP status when available; authentication failures give reconnection guidance, and an explicitly expired API key is reported as expired. Raw upstream errors and credentials are not posted, and Pipa never silently switches models. Abandoned pickers expire after 30 minutes; reopen your installation's model command to continue.
182
+ The picker shows up to 100 matches; narrow your search for more. A listed model may still lack credentials or quota. Saving does not test it. Providers such as `opencode` and `openai` use separate credentials. Reconnect failed providers in OpenCode. Pipa never silently switches models.
216
183
 
217
- If the model window cannot open, its private error distinguishes saved-settings problems, model-catalog loading, configured access restrictions, and Slack window failures. It confirms that the saved model is unchanged; it does not expose raw upstream errors or credentials.
184
+ **Multiple Slack apps:** give each a distinct command. Slack sends a shared `/pipa` command to the most recently installed app. Register that alias with only one app, and check the app name in the picker before saving.
218
185
 
219
186
  ### Upgrading an existing installation
220
187
 
221
- **An npm upgrade updates local code only. It does not update the installed Slack app, register commands, or grant scopes.** Existing mentions and thread replies still work without model-command registration. Do not rerun `pipa init` or replace credentials to add this feature.
188
+ **An npm upgrade does not update your Slack app, register commands, or grant scopes.** Mentions and thread replies still work without the model command. Do not rerun `pipa init` or replace credentials to add it.
222
189
 
223
190
  To upgrade to `0.5.6`, use the same `PIPA_HOME` as your existing installation (leave it unset for the default `~/.pipa` profile):
224
191
 
@@ -228,35 +195,27 @@ pipa --version
228
195
  pipa manifest > "$HOME/pipa-slack-manifest-0.5.6.json"
229
196
  ```
230
197
 
231
- `pipa manifest` reads the existing profile and prints the current **local template** without tokens. It does not write config, sessions, routines, or the cached manifest, call Slack, or run inference. It is not an export of your app's current remote/custom configuration.
198
+ `pipa manifest` prints a local template without tokens. It does not change your profile or contact Slack. It is not an export of your app's current Slack settings.
232
199
 
233
- 1. Open your **existing app** in [Slack App Management](https://api.slack.com/apps). Keep a copy of its current remote manifest.
234
- 2. In **App Manifest**, merge the generated `features.slash_commands` entries you want (the named command and optionally `/pipa`) and add `commands` to `oauth_config.scopes.bot`. Preserve unrelated remote settings, existing commands, scopes, Socket Mode, and interactivity. **Do not replace a customized remote manifest wholesale with the local template.** Alternatively, add the matching commands under **Slash Commands** and add the bot scope under **OAuth & Permissions**.
235
- 3. Save, then reinstall or reauthorize that same app. Retain your current tokens unless Slack rotates them; if it does, update the existing local config securely rather than reinitializing the profile.
236
- 4. Restart the same profile to load the upgraded runtime:
200
+ 1. Open your **existing app** in [Slack App Management](https://api.slack.com/apps). Back up its current manifest.
201
+ 2. Merge the desired `features.slash_commands` entries and add `commands` to `oauth_config.scopes.bot`. Keep existing settings, commands, scopes, Socket Mode, and interactivity. **Do not replace a customized Slack manifest with the local template.**
202
+ 3. Save and reinstall or reauthorize the same app. Keep your tokens unless Slack rotates them. If it does, update the existing local config securely.
203
+ 4. Restart the same profile:
237
204
 
238
205
  ```sh
239
206
  pipa restart
240
207
  pipa restart --status
241
208
  ```
242
209
 
243
- Restart reports **requested** first; inspect status for completion. Then try `/chopper model` (for configured `Chopper`) and `/pipa model` if the alias is registered to that app. Merely recognizing an alias in Pipa cannot bypass missing Slack registration. A known missing `commands` scope produces a warning at startup; scope metadata alone cannot verify command registration, and an absent warning does not prove it is installed.
244
-
245
- Before npm publication, preview the feature branch from this repo without reinstalling or reinitializing your profile:
246
-
247
- ```sh
248
- npm ci
249
- node bin/pipa.mjs --version
250
- node bin/pipa.mjs manifest > "$HOME/pipa-slack-manifest-preview.json"
251
- ```
210
+ Wait for restart completion, then try the registered model command. The absence of a startup warning does not prove the command is installed. Renaming the bot in Slack does not update Pipa's `botName` or command registration; keep them aligned and restart.
252
211
 
253
- For running the unpublished branch, use the separate test app/profile procedure in `CONTRIBUTING.md`; do not start a second Socket listener with a running installation's credentials. Renaming an app/bot in Slack alone does not update command registration or Pipa's local `botName`. A local name change needs matching Slack registration and an installation restart.
212
+ To try an unpublished branch, follow the isolated test-app steps in [CONTRIBUTING.md](CONTRIBUTING.md). Never start a second Socket listener with a running installation's credentials.
254
213
 
255
214
  ### Routines
256
215
 
257
- Local Pipa can save timezone-aware work that runs through the same OpenCode agent and delivers to one exact Slack channel or existing thread. Replies to a routine result continue the OpenCode session that produced it. Routines use the configured working directory, tools, permissions, channel allowlist, and responder allowlist.
216
+ Routines run scheduled work and send results to a channel or existing thread. Replies continue that session. Routines use the profile's directory, tools, permissions, and allowlists.
258
217
 
259
- Preview agent-assisted changes first, inspect the normalized JSON, then create only after confirmation:
218
+ Preview agent-assisted changes, check the JSON, and confirm before saving:
260
219
 
261
220
  ```sh
262
221
  pipa routine create \
@@ -269,7 +228,7 @@ pipa routine create \
269
228
  --json
270
229
  ```
271
230
 
272
- Remove `--preview` to save the routine. Use `--prompt-file` when exact multiline text or shell-like characters must be preserved. Timezones must be IANA names such as `America/New_York` or `UTC`; aliases such as `EST` are not accepted.
231
+ Remove `--preview` to save. Use `--prompt-file` for exact multiline text or shell characters. Prompt files may be outside the starting folder; generated-file restrictions still apply. Use IANA timezones such as `America/New_York` or `UTC`, not `EST`.
273
232
 
274
233
  Supported schedules:
275
234
 
@@ -282,14 +241,11 @@ pipa routine create --prompt "Follow up" --timezone UTC --channel C0BSE2JTYPR --
282
241
 
283
242
  # Tuesday, Thursday, and Saturday at three local times
284
243
  pipa routine create --prompt "Post status" --timezone America/New_York --channel C0BSE2JTYPR --every 1w --weekdays 2,4,6 --times 09:00,15:00,18:00
285
-
286
- # Daily through the inclusive local date September 5
287
- pipa routine create --prompt "Evening close" --timezone America/New_York --channel C0BSE2JTYPR --every 1d --times 19:00 --until 2030-09-05
288
244
  ```
289
245
 
290
- Use `pipa routine list`, `show`, `edit`, `run`, and `delete` for the lifecycle. Deactivate or reactivate with `edit --status inactive|active`. Completed one-time and final recurring routines remain inspectable until deleted. `routine run` requests one execution without changing the saved schedule or status.
246
+ Use `pipa routine list`, `show`, `edit`, `run`, and `delete`. Pause or resume with `edit --status inactive|active`. Completed routines stay until deleted. `routine run` requests one execution without changing the schedule or status.
291
247
 
292
- Routines run only while the Socket Mode `pipa start` process is running and the machine is awake. Restart skips missed scheduled occurrences instead of backfilling them. Explicit run requests survive restart, but can repeat if the process crashes after agent side effects or Slack delivery and before completion is saved. Managed profiles do not execute routines. Run `pipa routine --help` for the complete syntax and JSON contract.
248
+ Routines need Socket Mode `pipa start` running and the machine awake. Missed scheduled runs are skipped. Explicit run requests survive restart, but a crash can cause repeated actions or deliveries. Managed profiles do not run routines. Use `pipa routine --help` for all options.
293
249
 
294
250
  ### Restarting Pipa
295
251
 
@@ -300,17 +256,13 @@ pipa restart
300
256
  pipa restart --status
301
257
  ```
302
258
 
303
- Anyone allowed by the existing Slack user and channel controls can request a restart; there is no separate restart approval. The first command reports **requested**, not completed. The read-only status command shows the latest request ID, state (`requested`, `running`, `completed`, `failed`, or `unconfirmed`), phase, and any failure guidance. An expired handoff is unconfirmed, never assumed successful. Private records under `.pipa/restarts` remain available after the initiating turn exits.
304
-
305
- The running Pipa launches a detached worker before stopping intake, cleaning up, and releasing its instance lock. The worker waits for the original process and lock to disappear, then starts a detached replacement and confirms workspace readiness (and Slack readiness for Socket Mode). The replacement continues in the background without terminal output; use `pipa stop` to stop it. This works for Socket and Managed profiles on supported macOS, Linux, and Windows systems. Attached OpenCode servers remain externally owned and are never stopped by Pipa.
259
+ Anyone allowed by Slack user and channel controls can request a restart. There is no separate approval. **Requested does not mean completed.** Check status; if failed or unconfirmed, inspect the reported phase and running instance before starting another process.
306
260
 
307
- On Windows, `pipa stop` forcibly terminates Pipa's owned process tree and clears only its unchanged instance lock after exit. It can interrupt active work; `pipa restart` uses the cooperative restart handoff instead.
261
+ The replacement runs in the background. Use `pipa stop` to stop it. A Slack restart posts to the same thread when ready. Pipa never stops an attached OpenCode server. On Windows, `pipa stop` forcibly stops owned processes and can interrupt work; use `pipa restart` for a cooperative restart.
308
262
 
309
- When a restart is requested from Slack, the bot reports that it is restarting and posts to the same thread after the replacement is ready. A manual stop instead reports that the bot will not respond until it starts again.
263
+ Do not chain `pipa stop` and `pipa start` inside an agent turn: stopping owned OpenCode kills that turn. OpenCode's `/instance/dispose` does not restart the server.
310
264
 
311
- Do not chain `pipa stop` and `pipa start` inside an agent turn: stopping owned OpenCode also kills that turn. OpenCode's `/instance/dispose` disposes an instance; it does not restart the server.
312
-
313
- Commands must use the same `PIPA_HOME` (the parent of `.pipa`) as the running profile. Pipa passes the resolved absolute home to its owned OpenCode and restart processes. With an attached server, ensure the agent's command environment uses that home; a remote server needs command access to the Pipa host. An older running Pipa needs one manual stop/start after upgrading. If status reports failure or an unconfirmed handoff, inspect the reported phase and current instance before attempting a manual start.
265
+ Use the running profile's `PIPA_HOME` (the parent of `.pipa`) for all commands. An attached server's agent needs that environment and command access to the Pipa host. Older running versions need one manual stop/start after upgrading.
314
266
 
315
267
  ## Commands
316
268
 
@@ -318,8 +270,8 @@ Commands must use the same `PIPA_HOME` (the parent of `.pipa`) as the running pr
318
270
  pipa init Configure Slack and the local working directory
319
271
  pipa start Start the configured Slack runtime
320
272
  pipa stop Stop the running local Pipa process
321
- pipa restart [--channel <id> [--thread <ts>]] Request a detached restart
322
- pipa restart --status Inspect the latest durable restart outcome
273
+ pipa restart [--channel <id> [--thread <ts>]] Request a restart
274
+ pipa restart --status Check the latest restart
323
275
  pipa routine Create and manage local scheduled routines
324
276
  pipa manifest Print the current local Slack manifest template for an existing profile
325
277
  pipa --version Print the installed version
@@ -333,13 +285,7 @@ npm test
333
285
  npm run test:pack
334
286
  ```
335
287
 
336
- `npm run test:slack:routines` is a manual real-service smoke test. `npm run test:slack:release -- --plan` lists the shared live gates without contacting Slack. The opt-in `--run` collector requires an isolated running Socket candidate and private inputs from `.env.example`; see the testing guide. Human/client and integration evidence remain separate mandatory gates.
337
-
338
- See the [testing strategy](docs/pipa-testing.md) for repeatable real-runtime and Slack validation, existing-app reuse, evidence, and cleanup.
339
-
340
- See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
341
-
342
- See the [repository overview](docs/repository-overview.md) for a file-by-file explanation of how Pipa works.
288
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. The [testing guide](docs/pipa-testing.md) covers real OpenCode and Slack checks, isolated test profiles, and cleanup. The [repository overview](docs/repository-overview.md) explains the code.
343
289
 
344
290
  ## Releases
345
291
 
package/bin/pipa.mjs CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  import crossSpawn from "cross-spawn";
4
4
  import { constants } from "node:fs";
5
- import { lstat, open, readFile, realpath } from "node:fs/promises";
5
+ import { open, readFile, realpath, stat } from "node:fs/promises";
6
6
  import { randomUUID } from "node:crypto";
7
7
  import path from "node:path";
8
8
  import os from "node:os";
@@ -214,18 +214,13 @@ async function readPromptFile(file, workingDirectory) {
214
214
  const maxBytes = 1024 * 1024;
215
215
  const root = await realpath(workingDirectory);
216
216
  const requested = path.resolve(root, file);
217
- const beforeOpen = await realpath(requested);
218
- if (!isInside(root, beforeOpen)) cliError("--prompt-file must be inside the configured working directory");
219
- const initial = await lstat(requested, { bigint: true });
220
- if (initial.isSymbolicLink()) cliError("--prompt-file cannot be a symbolic link");
217
+ const initial = await stat(requested, { bigint: true });
221
218
  if (!initial.isFile()) cliError("--prompt-file must be a regular file");
222
- const handle = await open(requested, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
219
+ const handle = await open(requested, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
223
220
  try {
224
221
  const opened = await handle.stat({ bigint: true });
225
- const resolved = await realpath(requested);
226
- if (!isInside(root, resolved)) cliError("--prompt-file must be inside the configured working directory");
227
- const current = await lstat(requested, { bigint: true });
228
- if (!opened.isFile() || current.isSymbolicLink()
222
+ const current = await stat(requested, { bigint: true });
223
+ if (!opened.isFile()
229
224
  || initial.dev !== opened.dev || initial.ino !== opened.ino
230
225
  || current.dev !== opened.dev || current.ino !== opened.ino) cliError("--prompt-file must be an unchanged regular file");
231
226
  if (opened.size > BigInt(maxBytes)) cliError("--prompt-file must be no larger than 1 MB");
@@ -247,11 +242,6 @@ async function readPromptFile(file, workingDirectory) {
247
242
  }
248
243
  }
249
244
 
250
- function isInside(root, candidate) {
251
- const relative = path.relative(root, candidate);
252
- return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
253
- }
254
-
255
245
  function scheduleFromOptions(values, now) {
256
246
  if (values.at !== undefined) {
257
247
  rejectRecurringOptions(values);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usepipa/pipa",
3
- "version": "0.6.0-beta.1",
3
+ "version": "0.6.0-beta.3",
4
4
  "description": "Run Pipa through Slack Socket Mode with OpenCode",
5
5
  "keywords": [
6
6
  "slack",