mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
refactor(slack): correct stale status comment and add production acceptance checklist (#20840)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Slack chat connector lets people talk to their agents in Slack > - The connector is close to production, but its live evidence is out of date > - The September live results use old revisions, and the October setup run did not test follow-up, reauthorization, or removal > - Cloud managed setup has never run against real Slack, and its docs say not to enable it until it has > - This pull request adds one checklist for a fresh live pass on current master, and corrects one stale code comment > - The benefit is a clear finish line for Slack production readiness on self-hosted and Cloud ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** `doc/connections/SLACK-AUTOMATIC-SETUP.md`, `doc/plans/chat-adapters/2026-09-05-slack-live-qualification-result.md`, `doc/testing/slack-cloud-qualification.md`, and `server/src/services/chat-channels.ts`. **What's wrong?** The Slack live qualification is spread over three documents. Their evidence uses older revisions. No document lists what a production pass must cover for Cloud managed setup. A code comment says the manifest does not request `assistant:write`, but the manifest does request it. **Suggested fix** Add one dated acceptance checklist with pass conditions per row. Correct the comment. ## What Changed - Added `doc/plans/2026-11-11-slack-production-acceptance.md`. It has sections for self-hosted automatic setup, manual and existing apps, conversation behavior, Cloud managed setup on staging, and distribution questions (Marketplace-only workspaces, non-Marketplace rate limits, scope justification, zero-copy). - Corrected the comment in `server/src/services/chat-channels.ts`. It now says that Slack shows the working state through `agents.sessions.setStatus` and the lifecycle reply. No code behavior changed. ## Verification - Documentation and a comment only. No runtime behavior changed. - I checked the doc links and the referenced files against current master. ## Risks - Low risk. The change is documentation and one comment. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and web search. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e5158293c5
commit
cfa959add7
2 files changed
+133
-4
No files matched your search
@@ -0,0 +1,129 @@
|
||||
# Slack chat connector production acceptance
|
||||
|
||||
Status: draft checklist, not yet run.
|
||||
|
||||
## Why this exists
|
||||
|
||||
The Slack chat connector is close to production, but its live evidence is out of
|
||||
date:
|
||||
|
||||
- The [September live results](chat-adapters/2026-09-05-slack-live-qualification-result.md)
|
||||
were recorded on September revisions. Since then Slack moved into channel
|
||||
modules and gained sealed Cloud events, durable form custody and receipts, and
|
||||
faster acknowledgements. That evidence no longer covers the code we ship.
|
||||
- The [automatic setup run of 2026-10-07](../connections/SLACK-AUTOMATIC-SETUP.md)
|
||||
was partial. Same-thread follow-up, reauthorization, and removal were never
|
||||
run live.
|
||||
- The [Cloud qualification harness](../testing/slack-cloud-qualification.md) is
|
||||
local and never calls Slack. It is fixture coverage, not live evidence.
|
||||
- Managed setup (Cloud one-click) has never run against real Slack.
|
||||
[slack-setup.md](../connections/slack-setup.md) says not to enable its tenant gate
|
||||
until it has.
|
||||
|
||||
This checklist replaces the old matrices with one fresh pass on current
|
||||
`master`. It is done when every row in sections A–E has a recorded outcome on
|
||||
one tested revision, and every failure is either fixed (with a regression test)
|
||||
or written up as a known limitation that we accept.
|
||||
|
||||
## Evidence rules
|
||||
|
||||
- Record the tested `master` SHA, the instance URL, and the date for each section.
|
||||
- Use a dedicated test Slack workspace and dedicated test apps. Never use a
|
||||
customer workspace.
|
||||
- Record sanitized IDs and links (task, run, Slack permalink) and the outcome.
|
||||
Never record tokens, signing secrets, OAuth codes, or provider payloads.
|
||||
- Keep live results separate from fixture results. A Storybook story or Vitest
|
||||
case does not satisfy a row here.
|
||||
- A failed attempt stays failed. If a later retry passes, record both.
|
||||
- After a fix lands, rerun only the rows whose code paths changed, on the new SHA.
|
||||
|
||||
## A. Self-hosted automatic setup
|
||||
|
||||
Instance: isolated HTTPS self-hosted Paperclip with `enableChatConnectors` on.
|
||||
The tester enters the App Configuration Token directly.
|
||||
|
||||
| # | Check | Pass when | Result |
|
||||
| --- | --- | --- | --- |
|
||||
| A1 | Create the app from the wizard | One app exists in Slack with the agent's name, icon, and slash command; no duplicate app after any retry | |
|
||||
| A2 | OAuth install and return | Consent returns to the wizard and the setup advances without a manual refresh | |
|
||||
| A3 | Request URL verification | Slack's signed challenge succeeds, or the first signed event advances setup on its own | |
|
||||
| A4 | Installer linking and welcome DM | The installer is linked and receives exactly one welcome DM | |
|
||||
| A5 | First real message | A DM to the bot creates a task, the assigned agent's run succeeds, and the reply appears in the same Slack thread | |
|
||||
| A6 | Same-thread follow-up | A second message in that thread reaches the same task and gets a reply in the thread | Never run live |
|
||||
| A7 | Interrupted setup | Closing the browser mid-setup and reopening resumes at the right step, without creating a second app | |
|
||||
| A8 | Reauthorize the same app | Reauthorization keeps the same app and connection, and messages still flow afterward | Never run live |
|
||||
| A9 | Remove the connection | Removing it in Paperclip stops delivery. Any outstanding attempt ends cleanly, with no retry storm and no orphaned task | Never run live |
|
||||
| A10 | Uninstall from Slack | `app_uninstalled` / `tokens_revoked` marks the connection disconnected. The UI offers a working reconnect | |
|
||||
|
||||
## B. Self-hosted manual and existing app
|
||||
|
||||
Run against the same instance as section A.
|
||||
|
||||
| # | Check | Pass when | Result |
|
||||
| --- | --- | --- | --- |
|
||||
| B1 | Manual: create an app from the generated manifest, paste the bot token and signing secret | Setup completes and A5 passes for this app | |
|
||||
| B2 | Existing app: paste credentials for an app created outside Paperclip | Setup completes and A5 passes, or setup explains exactly which scope or event is missing | |
|
||||
| B3 | Wrong signing secret | Setup reports the error in plain language, never a raw ID or provider error text | |
|
||||
|
||||
## C. Conversation behavior
|
||||
|
||||
All setup methods share one runtime, so run this once on the section A app and
|
||||
spot-check C1, C2, C5, and C6 on the section D app. Cloud handles slash commands
|
||||
apart from events, and they need a synchronous response. So for C5 on Cloud, also
|
||||
send a slash command while the tenant sleeps, and require both the command response
|
||||
and its task thread to arrive.
|
||||
|
||||
| # | Check | Pass when | Result |
|
||||
| --- | --- | --- | --- |
|
||||
| C1 | Channel root mention | Creates a task, and the reply lands in the thread | |
|
||||
| C2 | Message during a run | Is queued in order and answered without being batched with another conversation | |
|
||||
| C3 | Working status | The Agents & AI Apps status shows working while the run is active and clears when it finishes | |
|
||||
| C4 | Stop from Slack | `agent_session_stopped` stops the run, and Slack shows that it stopped | |
|
||||
| C5 | Slash command | Starts work from the command and creates its thread | |
|
||||
| C6 | Agent question | The agent's question arrives as a Slack form, and the answer continues the same task | |
|
||||
| C7 | Files in and out | An uploaded file reaches the agent. A file the agent produces appears in Slack | |
|
||||
| C8 | Receipt reaction | The receipt reaction appears on intake and is removed or replaced on completion | |
|
||||
| C9 | Unlinked guest | A message from an unlinked user is handled by the guest policy, with a clear message and no internal jargon | |
|
||||
| C10 | Deploy mid-run | Restarting the server during a run finishes the run or resumes it. The Slack reply arrives exactly once, and Retry is never needed | |
|
||||
| C11 | Agent read tools | Channel and thread read tools return results. Record the latency of a thread read and any `ratelimited` responses (see E2) | |
|
||||
|
||||
## D. Cloud managed setup on staging
|
||||
|
||||
Prerequisites (blockers until done):
|
||||
|
||||
- Slack has granted the `managed_apps:install` partner scope to Paperclip's
|
||||
manager app.
|
||||
- The staging Cloud broker has the `slack.manager` profile enabled, with the
|
||||
manager app's client secret in the broker secret store.
|
||||
- The staging tenant has `PAPERCLIP_SLACK_MANAGED_SETUP_ENABLED=true` and the
|
||||
chat-connector gate on.
|
||||
|
||||
| # | Check | Pass when | Result |
|
||||
| --- | --- | --- | --- |
|
||||
| D1 | Manager grant | A user authorizes the manager app once. The grant is bound to that user, company, and workspace | |
|
||||
| D2 | One-click agent install | **Continue** creates and installs a child app for the agent without pasting any keys. A5 passes | |
|
||||
| D3 | Second agent | A second agent uses the existing grant and gets its own child app, with no second consent | |
|
||||
| D4 | Second user | Another company member must authorize their own grant. The first user's grant is not reused | |
|
||||
| D5 | Workspace requires admin approval | Installation falls back to Slack's admin approval, and the UI explains what is pending | |
|
||||
| D6 | Grant revoked in Slack | The next install asks for authorization again, in plain language. Existing bots keep working or report clearly that they are disconnected | |
|
||||
| D7 | Sealed events while the tenant sleeps | A message sent while the tenant is idle is delivered once after wake, and the reply arrives | |
|
||||
| D8 | Remove and reinstall | Removing a managed bot clears its saved secrets and pending setup attempts, stops Cloud delivery, and keeps the user's manager grant. The child app stays in Slack; delete it separately through its Slack management URL. A fresh managed setup creates a working bot | |
|
||||
|
||||
## E. Distribution questions to answer with evidence
|
||||
|
||||
These decide whether Cloud can launch before the Slack Marketplace listing.
|
||||
|
||||
| # | Question | How to answer | Result |
|
||||
| --- | --- | --- | --- |
|
||||
| E1 | Can a workspace set to **Only allow apps from the Slack Marketplace** install a managed child app? | Turn on that setting in the test workspace and repeat D2 | |
|
||||
| E2 | Do managed child apps get the non-Marketplace `conversations.history` / `conversations.replies` limits (1 request per minute, 15 messages)? | Measure C11 on a managed app, and ask our Slack contact | |
|
||||
| E3 | Which approval did Slack agree to: the partner scope, a Marketplace listing, or both? | Written confirmation from our Slack contact | |
|
||||
| E4 | Is each scope justified for Marketplace review? | Write a one-line justification per scope in `slack-app-manifest.ts` and `slack-tools.ts`. Move non-core tool scopes to optional or drop them | |
|
||||
| E5 | Do we meet zero-copy (store metadata, not Slack content)? | Inventory what receipts, form custody, and task comments store from Slack messages | |
|
||||
|
||||
## Not covered here
|
||||
|
||||
- Marketplace listing assets (landing page, support page, privacy policy,
|
||||
screenshots, video). Track these separately once E3 is answered.
|
||||
- The Slack tool connector (Slack MCP / aggregator sign-in), which has its own
|
||||
setup paths.
|
||||
@@ -2650,10 +2650,10 @@ export function chatChannelService(db: Db, options: ChatChannelServiceOptions) {
|
||||
thread,
|
||||
})
|
||||
: Promise.resolve()),
|
||||
// Slack implements this through assistant.threads.setStatus, which
|
||||
// requires assistant:write. The least-privilege Paperclip manifest
|
||||
// deliberately does not request that scope; the coalesced lifecycle
|
||||
// reply below is the visible working state instead.
|
||||
// Slack shows the working state through the Agents & AI Apps session
|
||||
// status (agents.sessions.setStatus, set from the publication's
|
||||
// progressState in chat-channels/slack/session-status.ts) and the
|
||||
// coalesced lifecycle reply below, so no separate typing indicator.
|
||||
endpoint.provider === "slack"
|
||||
? Promise.resolve()
|
||||
: thread.startTyping("Working…"),
|
||||
|
||||
Reference in new issue
Block a user