From cfa959add769f9ab280a0c7bc3f36c67cdb6d5f9 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:54:50 -0600 Subject: [PATCH] refactor(slack): correct stale status comment and add production acceptance checklist (#20840) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- .../2026-11-11-slack-production-acceptance.md | 129 ++++++++++++++++++ server/src/services/chat-channels.ts | 8 +- 2 files changed, 133 insertions(+), 4 deletions(-) create mode 100644 doc/plans/2026-11-11-slack-production-acceptance.md diff --git a/doc/plans/2026-11-11-slack-production-acceptance.md b/doc/plans/2026-11-11-slack-production-acceptance.md new file mode 100644 index 00000000000..da4869a3e30 --- /dev/null +++ b/doc/plans/2026-11-11-slack-production-acceptance.md @@ -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. diff --git a/server/src/services/chat-channels.ts b/server/src/services/chat-channels.ts index 55fb04afc3f..95c093a8e7e 100644 --- a/server/src/services/chat-channels.ts +++ b/server/src/services/chat-channels.ts @@ -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…"),