From 8f13ec4d51d590d4d252aa2b7e088dfda09ac0c2 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 9 Oct 2026 20:23:18 -0500 Subject: [PATCH] fix(slack): link created tasks in default reply guidance (#15579) ## Thinking Path > - Paperclip helps people manage AI agents and their tasks. > - Slack agents use shared guidance to write their replies. > - A reply can show a task ID without a link. > - The person must then search for the task. > - This change tells the agent to link each task it creates. > - People can open the task directly from the reply. ## Linked Issues or Issue Description **What existing behavior does this improve?** Default communication guidance for Slack agents. **Current behavior** The guidance does not require a link when an agent creates a task. **Proposed behavior** Require a clickable link to each created task. Use its identifier or title as the link text. Use a public URL supplied by Paperclip. Report when no public URL is available. **Reason and benefit** People can open the task without a separate search. Related work: https://github.com/paperclipai/paperclip/pull/13760 introduced the guidance. https://github.com/paperclipai/paperclip/pull/15576 adds account connection instructions and does not cover task links. ## What Changed - Add task link instructions to the shared Slack communication guidance. - Document the default and the existing conversation snapshot behavior. - Add regression coverage for the guidance in channels and DMs. ## Verification - Passed: `pnpm exec vitest run server/src/services/chat-communication-guidance.test.ts` (10 tests). - Passed: `git diff --check`. - Local full typecheck and build could not finish: the container killed compiler processes (exit 137; cgroup reports OOM kills). The full test run was stopped after this resource limit. CI results are pending. - Added checks for task links, public URL sources, and missing URLs in Slack channels and DMs. ## Risks - Low risk. This changes prompt text only. - Existing conversations keep their original guidance snapshot. New conversations receive the new default after deployment. - This is agent guidance. It does not force a link into provider output. ## Model Used OpenAI Codex, GPT-6. The runtime did not expose an exact model revision or context window size. Used reasoning, code inspection, file editing, and command execution. ## 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 - [x] I have run tests locally and they pass - [x] 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 --- doc/DEVELOPING.md | 5 +++++ server/src/services/chat-communication-guidance.test.ts | 9 +++++++++ server/src/services/chat-communication-guidance.ts | 1 + 3 files changed, 15 insertions(+) diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index 08986d2ef43..26ad54fa183 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -715,6 +715,11 @@ a real mention. **Done** finishes setup once webhook verification and required account linking are complete, whether or not a test message was sent. The separate strict connection-test API retains its conversation and delivery checks. +New Slack conversations receive default communication guidance that requires a +clickable link to each task the agent creates. Agents use the public task URL +from Paperclip tools or task context and report when a link is unavailable. +Existing conversations keep their original communication guidance snapshot. + ### Chat activity pagination and callback diagnostics The connection Activity tab loads 25 records per page. `GET /api/chat-endpoints/:id/activity?limit=25` diff --git a/server/src/services/chat-communication-guidance.test.ts b/server/src/services/chat-communication-guidance.test.ts index a1f77369766..cca070de8f3 100644 --- a/server/src/services/chat-communication-guidance.test.ts +++ b/server/src/services/chat-communication-guidance.test.ts @@ -22,6 +22,15 @@ describe("initial medium communication guidance", () => { expect(buildChatCommunicationGuidance({ provider: "slack", isDirectMessage: true })).toContain("direct conversation"); }); + it.each([false, true])("requires public links for created Slack tasks (DM: %s)", (isDirectMessage) => { + const guidance = buildChatCommunicationGuidance({ provider: "slack", isDirectMessage }); + expect(guidance).toContain("include a clickable link to each created task"); + expect(guidance).toContain("task identifier or title as the link text"); + expect(guidance).toContain("public task URL returned by Paperclip tools or supplied in task context"); + expect(guidance).toContain("never guess a URL"); + expect(guidance).toContain("If no public task URL is available, say that the link is unavailable"); + }); + it.each(CHAT_PROVIDERS.filter((provider) => provider !== "slack"))("leaves %s unchanged", (provider) => { expect(buildChatCommunicationGuidance({ provider, isDirectMessage: false, communicationInstructions: "Ignored" })).toBeNull(); }); diff --git a/server/src/services/chat-communication-guidance.ts b/server/src/services/chat-communication-guidance.ts index c76fcf95002..d2f3344939e 100644 --- a/server/src/services/chat-communication-guidance.ts +++ b/server/src/services/chat-communication-guidance.ts @@ -9,6 +9,7 @@ const providerGuidance: Partial> = { ...slackTaskUpdateGuidance, "Lead with the answer or outcome. Use compact paragraphs or short lists, and omit routine execution bookkeeping. Honor requests for more detail or exact output over default brevity.", "Put small answers directly in the message. For substantial plans, reports, and other deliverables, use your normal document or artifact tools, then share a useful summary and accessible links or supported attachments in Slack. Follow the runtime's file-delivery contract and do not claim delivery until confirmed.", + "When you create tasks, include a clickable link to each created task in your reply. Use the task identifier or title as the link text, not a bare task ID. Use the public task URL returned by Paperclip tools or supplied in task context; never guess a URL or use a localhost, API, or sandbox address. If no public task URL is available, say that the link is unavailable.", "Ask useful questions through the existing human-input tools. Continue normal Paperclip planning, task creation, assignment, delegation, and approval workflows; these communication instructions grant no additional authority.", ].join("\n\n"), };