@usepipa/pipa 0.6.0-beta.2 → 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 continue it. On OpenCode v2, messages steer native work and later background responses return to the same Slack 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.2` 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.2
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,29 +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 thread. Port `0` asks the operating system for an available port; no port configuration is required. Follow-up messages reuse the same OpenCode session without another mention. On v2, they enter OpenCode's native steering queue without Pipa cancelling the current execution. V1 retains its interrupt-and-replace behavior. Different threads remain independent.
117
-
118
- For v2, Pipa keeps following live native session events after the first reply. The agent can say a render is running, resume when it finishes, and send the result into the same Slack thread without another message from you. Replies missed during a disconnect or restart are not recovered. Restarting preserves the conversation mapping, but background forwarding starts again only when you send another message in that thread. Pipa does not scan response history or maintain a second execution or delivery journal. Failed Slack deliveries are reported when possible, not replayed; later live replies can still arrive.
119
-
120
- 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.
121
-
122
- **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).
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.
123
101
 
124
- Pipa keeps naturally short answers inline. For deeper work, OpenCode can return a concise summary with generated files. Files are read only from a private session directory under `.pipa/artifacts` in the configured working directory and validated against the existing path, type, identity, count, and size limits. V2 keeps that directory available for later background responses; v1 clears it around each turn. 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.
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.
125
103
 
126
- 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.
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.
127
105
 
128
- 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.
106
+ ### Files
129
107
 
130
- ### Native v2 session context
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.
131
109
 
132
- Slack routing and attachment guidance live in a stable native session instruction entry. They remain available when background work resumes; Pipa no longer installs and removes temporary instructions around each response. Restart instructions are not repeated in every turn—an agent can use `pipa restart` and its CLI help like any other command.
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.
133
111
 
134
- Pipa no longer reads or writes `~/.pipa/opencode-recovery.json`, rejects native activity as a competing writer, or blocks unrelated threads after one session fails. Old journal files are left untouched. Existing Slack-to-session mappings are preserved.
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.
135
113
 
136
114
  ### Access control
137
115
 
138
- 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:
139
117
 
140
118
  ```json
141
119
  {
@@ -149,13 +127,14 @@ By default Pipa answers any human user who mentions it in a channel it can see,
149
127
  }
150
128
  ```
151
129
 
152
- 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).
153
-
154
- 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.
155
134
 
156
135
  #### Mention-only mode
157
136
 
158
- 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:
159
138
 
160
139
  ```json
161
140
  {
@@ -163,15 +142,11 @@ By default, once Pipa is mentioned in a thread it subscribes to that thread and
163
142
  }
164
143
  ```
165
144
 
166
- `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.
167
146
 
168
147
  #### Find the sender's bot ID
169
148
 
170
- 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:
171
-
172
- 1. Open the **sender app** at [Slack Apps](https://api.slack.com/apps), not Pipa's app.
173
- 2. Under **OAuth & Permissions**, copy its **Bot User OAuth Token** (`xoxb-…`). If needed, install the app in the workspace via **Install App** first.
174
- 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/):
175
150
 
176
151
  ```sh
177
152
  curl --silent --show-error --request POST \
@@ -179,48 +154,38 @@ curl --silent --show-error --request POST \
179
154
  https://slack.com/api/auth.test
180
155
  ```
181
156
 
182
- No Slack CLI is needed. Keep the token out of config examples, shared output, and commits. A successful response includes fields like:
183
-
184
- ```json
185
- {
186
- "ok": true,
187
- "user_id": "U0123456789",
188
- "bot_id": "B0123456789"
189
- }
190
- ```
157
+ Use the response's `bot_id` in `allowedSlackBotIds`. Keep the token out of config examples, shared output, and commits.
191
158
 
192
- 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.
193
160
 
194
- **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.
195
162
 
196
- 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
197
164
 
198
- 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`:
199
166
 
200
167
  ```sh
201
168
  export PIPA_OPENCODE_ATTACH_URL=http://localhost:5555
202
169
  pipa start
203
170
  ```
204
171
 
205
- ### Choosing a model
206
-
207
- 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 becomes a searchable picker. Search by model name, ID or provider, 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 each search, 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).
208
173
 
209
- 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
210
175
 
211
- **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.
212
177
 
213
- 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.
214
179
 
215
- 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.
216
181
 
217
- The picker loads the configured OpenCode model catalog once per window, with up to 30 seconds for discovery. Searches use that cached catalog without contacting OpenCode again. Slack displays up to 100 matches at a time; type more specific terms to find models anywhere in a large catalog. Search is case-insensitive and matches all entered terms across model names, IDs and providers. The saved model remains selected even when it is outside the first 100 results. Empty catalogs get a private explanation. Save checks the current OpenCode catalog again before persisting. 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.
218
183
 
219
- 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.
220
185
 
221
186
  ### Upgrading an existing installation
222
187
 
223
- **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.
224
189
 
225
190
  To upgrade to `0.5.6`, use the same `PIPA_HOME` as your existing installation (leave it unset for the default `~/.pipa` profile):
226
191
 
@@ -230,35 +195,27 @@ pipa --version
230
195
  pipa manifest > "$HOME/pipa-slack-manifest-0.5.6.json"
231
196
  ```
232
197
 
233
- `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.
234
199
 
235
- 1. Open your **existing app** in [Slack App Management](https://api.slack.com/apps). Keep a copy of its current remote manifest.
236
- 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**.
237
- 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.
238
- 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:
239
204
 
240
205
  ```sh
241
206
  pipa restart
242
207
  pipa restart --status
243
208
  ```
244
209
 
245
- 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.
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.
246
211
 
247
- Before npm publication, preview the feature branch from this repo without reinstalling or reinitializing your profile:
248
-
249
- ```sh
250
- npm ci
251
- node bin/pipa.mjs --version
252
- node bin/pipa.mjs manifest > "$HOME/pipa-slack-manifest-preview.json"
253
- ```
254
-
255
- 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.
256
213
 
257
214
  ### Routines
258
215
 
259
- 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.
260
217
 
261
- 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:
262
219
 
263
220
  ```sh
264
221
  pipa routine create \
@@ -271,7 +228,7 @@ pipa routine create \
271
228
  --json
272
229
  ```
273
230
 
274
- 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`.
275
232
 
276
233
  Supported schedules:
277
234
 
@@ -284,14 +241,11 @@ pipa routine create --prompt "Follow up" --timezone UTC --channel C0BSE2JTYPR --
284
241
 
285
242
  # Tuesday, Thursday, and Saturday at three local times
286
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
287
-
288
- # Daily through the inclusive local date September 5
289
- pipa routine create --prompt "Evening close" --timezone America/New_York --channel C0BSE2JTYPR --every 1d --times 19:00 --until 2030-09-05
290
244
  ```
291
245
 
292
- 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.
293
247
 
294
- 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.
295
249
 
296
250
  ### Restarting Pipa
297
251
 
@@ -302,17 +256,13 @@ pipa restart
302
256
  pipa restart --status
303
257
  ```
304
258
 
305
- 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.
306
-
307
- 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.
308
260
 
309
- 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.
310
262
 
311
- 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.
312
264
 
313
- 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.
314
-
315
- 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.
316
266
 
317
267
  ## Commands
318
268
 
@@ -320,8 +270,8 @@ Commands must use the same `PIPA_HOME` (the parent of `.pipa`) as the running pr
320
270
  pipa init Configure Slack and the local working directory
321
271
  pipa start Start the configured Slack runtime
322
272
  pipa stop Stop the running local Pipa process
323
- pipa restart [--channel <id> [--thread <ts>]] Request a detached restart
324
- 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
325
275
  pipa routine Create and manage local scheduled routines
326
276
  pipa manifest Print the current local Slack manifest template for an existing profile
327
277
  pipa --version Print the installed version
@@ -335,13 +285,7 @@ npm test
335
285
  npm run test:pack
336
286
  ```
337
287
 
338
- `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.
339
-
340
- See the [testing strategy](docs/pipa-testing.md) for repeatable real-runtime and Slack validation, existing-app reuse, evidence, and cleanup.
341
-
342
- See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
343
-
344
- 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.
345
289
 
346
290
  ## Releases
347
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.2",
3
+ "version": "0.6.0-beta.3",
4
4
  "description": "Run Pipa through Slack Socket Mode with OpenCode",
5
5
  "keywords": [
6
6
  "slack",