DottaandPaperclip
2cbca4ceb0
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Chat channels give an agent tools for its assigned task. > - Each later run must resolve the task and its accepted requester again. > - Some native runs store the task in a database column without the older JSON fields. > - Tool discovery read only the JSON fields. GitHub calls also required a new inbound comment. > - This pull request uses the durable task binding and accepted request history. > - Later runs retain their channel tools while current access checks still apply. ## Linked Issues or Issue Description **What happened?** A GitHub task can find `begin_review` on its first run, then receive an empty tool list on a later native run. If discovery is repaired alone, a call can still fail because the later run has no new inbound comment. Slack and voice tool access also read the older JSON task fields. **Expected behavior** A later run for the same task can find and call its assigned channel tools. The current requester, task, company, agent, endpoint, and access rules must still allow the call. Revoked access must fail. **Steps to reproduce** 1. Start a GitHub task and accept its linked requester. 2. Confirm that the runtime can find `begin_review`. 3. Start a later native run with `nativeIssueId`, accepted parent identity, and no JSON task ID or new wake comment. 4. Search for `begin_review` again. Before this change, the search returns an empty list. 5. Repair discovery alone and call `read_pull_request`. Before the request-history fix, the call fails with no active conversation capability. **Paperclip version or commit** Reproduced in source tests before this patch. The branch includes master at `fa50cab5685b9cdbb26ad9c610cc5b6c373d3ff4`. **Additional context** This is a core run-binding bug. The tests use PostgreSQL and synthetic provider responses. They do not send live reviews, Slack messages, or phone calls. ## What Changed - Resolve run task IDs from durable columns, with legacy JSON fields as a fallback. - Use the same binding in the gateway, access policy, identity service, and channel runtime preparation. - Recover accepted channel request history across later runs. Keep company, task, agent, and requester boundaries. - Recover older wake sources through verified parent runs, including after same-user board follow-ups. Clear the board message’s own legacy wake fallback. Keep cycle checks without a fixed limit on valid task history. - Retain the GitHub origin after a board comment from the same accepted user. Skip GitHub origin lookup results from other providers. - Keep ordinary board tools available when the requester changes. Accept legacy user comments without an author-type field. Still reject explicit malformed task IDs. - Prevent a later failure reply from replacing an earlier final GitHub answer. Recheck this rule under the publication lease. - Rotate the native tool contract to replace retained sessions with an older tool list. - Add continuation, publication, revocation, and boundary tests. Update the access and feature maps. ## Verification - Red: the later GitHub assigned-tool search returned an empty list before the binding fix. - Red: the later GitHub read failed with no active conversation capability before the request-history fix. - Green: runtime MCP discovery, GitHub read/begin/submit review, and response publication pass for monitor and same-user board continuations. - Green: Slack history, retained access controls, revocation, and voice gateway continuation pass. - Green: 35 channel, failure-publication, legacy-origin, long-history, and provenance tests pass. Both review findings had failing tests before their fixes. - Green: 107 gateway, operation-credential, identity, and provenance tests pass. These cover both first-run CI failures without changing their tests. - Green: 122 runtime, discovery-policy, and native-session tests pass; 2 unrelated tests are skipped. - Map checks and whitespace checks pass. - Updated to master in `cfcaba22628772d7fe1fb32b57ff7031c7072781`. The sole conflict was two tests added at the same location. Both the continuation test and the publication 403/401 test are retained. - Current local verification: all 179 gateway, credential, requester-identity, access-policy, runtime-context, and session-resume tests passed. Repository typecheck and build passed. Map and whitespace checks passed. - The new review regression first returned no source for a same-user board follow-up over legacy wake metadata. After the repair, all 27 provenance and channel cases passed. The combined GitHub discovery/read/begin/submit path and revoked access are covered. - The broader local channel run passed 176 cases and failed four timing/setup cases: a 15-second Slack authorization timeout, webhook-verification polling, a Slack acknowledgement deadline, and Discord setup polling. All four passed in isolation without source, assertion, or deadline changes. The earlier failure record is retained; the exact load/order cause is not established. Full CI must pass on the latest commit. - Current head: `7b9a08dcbc7b8140b589742f136944270b0496bb`. Repository typecheck and build pass on this commit. Greptile completed on this exact commit with 5/5; all four review threads are resolved. The final-head [CI run](https://github.com/paperclipai/paperclip/actions/runs/39278921653) passed: 55 checks passed and 2 intentionally skipped, with no failures or pending checks. This includes the full sharded test matrix, browser tests, typecheck, build, and Runner verification. Results were delayed during the [GitHub Actions incident](https://www.githubstatus.com/incidents/8tzbpcnl75jp). An additional unsharded local full test run has not completed; the completed full-suite evidence is CI. - Earlier verification: the first PR commit failed two server suites. Those failures were fixed and verified before this update. The original 4 GiB sandbox could not complete full local typechecking or tests; the current checkout completed typechecking and build. The full test suite runs through the CI shards. No full local test-suite pass or live provider delivery is claimed. ## Risks - Request history can restore the wrong authority if its scope is too broad. The resolver checks each accepted parent against the task, company, agent, and requester. Tests cover invalid and cyclic history. - The native contract change starts a new provider session for older contracts. - No database migration or public API schema changes are required. Each tool call still checks live access. ## Model Used - OpenAI Codex, GPT-6 family. The runtime does not expose the exact deployment model ID or context-window size. The agent used reasoning, repository tools, code edits, and local test 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
10 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
External chat and email
People can talk to an assigned agent through configured external channels, bind their identity, exchange files, and inspect delivery state. Each provider has a different identity, threading, and attachment contract.
Implementation: endpoint setup, endpoint detail, email setup.
Agent access: companion.
Sub-features
providers: configure the available Slack, Discord, Microsoft Teams, Telegram, GitHub, AgentMail, and experimental iMessage Photon and Speko paths; availability still depends on gates and provider support.identity: link the external sender to the intended authorized Paperclip identity.conversation: route inbound messages to the selected agent and send replies to the correct thread.attachments: transfer supported files with inspectable delivery and failure states.lifecycle: inspect endpoint activity, repair auth, and disable delivery when required.
How to get to it (user POV)
external-thread
Message the configured bot/address from its external provider and follow the corresponding Paperclip conversation/task.
endpoint-management
Open /apps/chat/:endpointId/settings and the endpoint’s other available tabs; identity confirmation uses /chat-identity/confirm.
Driving it with Playwright and provider clients
Preconditions: follow the baseline. Use a
test provider account/channel with permission to send messages. Gates differ:
AgentMail bypasses the chat-connectors UI gate, GitHub uses
enableGitHubReviewBots, and other chat providers use enableChatConnectors.
Setup is covered in connection setup.
external-thread
Automated: channel integration uses provider fixtures; it does not prove a live Slack, Discord, Teams, Telegram, GitHub, email, or Photon delivery.
Manual: For each supported provider being changed, send a unique message, verify the intended agent/company receives it, and inspect the actual external reply in the original thread. Repeat with an unlinked/unauthorized sender, duplicate inbound delivery, and one supported attachment. Record provider-specific results separately.
For Slack, enable Require at-mention and Allow direct messages. Send a plain DM and follow up without a mention: both should reach the agent, with top-level replies to top-level DMs. Channel messages and thread replies still require a mention when that setting is enabled. Disable direct messages and confirm a plain DM is rejected. Use a private channel for threaded conversations.
For Slack acknowledgement latency, mention the bot with and without an attachment.
Eyes should appear after authorized task/comment persistence, independently of
file preparation, subscription and agent startup. Duplicate delivery must keep
one receipt; the final reply must remove only its source message's eyes. Record
live mention-to-reaction timing separately from the PostgreSQL fixture tests and
the chat.slack.receipt transport span described in Observability.
During a top-level DM run, verify that the bot adds eyes to the source message and removes them when the final reply arrives. The pinned Slack SDK encodes a linear DM with an empty thread timestamp; receipt transport accepts that address while still validating the channel and the source message timestamp.
For an agent with two linked Slack endpoints, compare assignment preparation and tool discovery in the run trace. Endpoint checks may overlap in pairs. Confirm that both permitted tool sets remain available, then revoke one linked identity and confirm that the next preparation excludes it. The database regression uses real PostgreSQL with one connection and controlled credential resolution; it does not prove live provider latency or an end-to-end response target.
Catalog discovery rechecks live authority and current credentials without computing the unused compatibility fingerprint. Assignment snapshots and governed calls retain full revision resolution. The same regression verifies identical catalog membership, absence of digest SQL during discovery, and revocation on the next preparation. A faster component is not proof of a faster Slack reaction or final reply; measure those separately on the deployed revision.
For GitHub and Slack tool continuity, start a task from the channel, then admit a later monitor or retry run for the same task. Check that the later run can discover and call its channel tools without a new inbound message. For GitHub, also continue from a board message by the same accepted requester and complete the review in the original conversation, including when the original source is recorded only in legacy wake metadata. Revoke the linked identity and check that the next call fails. Repeat the boundary checks with another task, agent, company, and requester. The channel and provenance fixtures above cover these contracts with synthetic providers; record a live journey separately. For a long-lived task, repeat more than 100 continuations and check that tool access remains available. Fail a later GitHub run after a final answer and check that the earlier answer remains intact.
endpoint-management
Automated: channel integration covers shared endpoint/delivery behavior; live credential repair and provider ownership remain manual checks.
Manual: Inspect the bound agent and identity, recent activity, and delivery failure details. Repair a disposable credential, retry a safe message when offered, and verify exactly one external reply. Disable the endpoint and confirm new traffic is not silently processed.
For publication failures, reject one operation with a provider 403 and verify that its failure remains visible while unrelated tools and publications continue. Repeat with an authentication failure: the endpoint must require attention and stop provider traffic, while the connection's enabled setting remains unchanged. Reconcile persistent receivers and restart the service; authentication failures must remain stopped while transient disconnections can still recover. The PostgreSQL suite uses controlled provider failures for these cases; live provider credential repair remains a separate acceptance check.
For GitHub, submit a disposable PR and verify the summary heading uses the bot's display name and the check remains Paperclip Review. For two separate bots on one PR, verify their App-scoped checks and comments remain independent.
For GitHub publication recovery, interrupt a response after GitHub accepts a write and verify one summary, finding, and App-scoped check. Retry the same tool call and verify it returns the saved receipt. Leave a transient failure queued, restart the instance, and verify publication resumes at its saved deadline without another inbound message. Revoked access and permanent rejections must stop retries. These recipes are separate from live provider proof.
Configure optional project and workspace defaults at the connection and destination levels. Start a new conversation and inspect its task workspace. Verify that inheritance, an explicit selection, and clearing a default remain distinct. Changing defaults must not move an existing conversation or interrupt its run.
For experimental Speko, enable chat connectors, choose an agent during setup, and verify the provider credentials. On an assigned task, use Talk to agent to open browser voice controls. Check microphone denial, mute, end/restart, navigation during a call, and access revocation. Inspect transcripts and the connection's call history. Callback preferences, incoming phone configuration, and incoming-call approval are separate settings and authorization journeys. The voice components and fixture tests cover presentation; they do not establish live answer retrieval or telephone playback. Those provider outcomes remain explicit release gates.
Gotchas
-
Visibility flags do not pause existing delivery. Disable the disposable endpoint itself to test stopped traffic.
-
One provider’s passing fixture does not qualify another provider or live delivery.
-
An accepted send request does not prove the recipient received the message or file.
-
Use steering and questions for their channel-specific interaction checks.
Storybook verification
attachments
Scope: ui Storybook: Mount TaskChatBubble attachments and ChatEndpointDetail provider-specific consent/upload/delivery failure and unknown-outcome states. Local email attachment dialog remains a prototype. Production: Transfer a disposable supported file through each affected provider; verify recipient delivery, read scope, duplicate/replay handling and failure/unknown state without treating notification as file-upload proof. Sources: Source: TaskChatBubble.tsx, ChatEndpointDetail.tsx, chatEndpoints.ts, chat-channels.ts. Tests: TaskChatBubble.test.tsx, task-chat-attachments.test.ts, chat-channels.integration.test.ts, issue-attachment-routes.test.ts
Documentation scope: Chat and email channel setup
Shared recipes name provider checks; each provider transport/thread/identity/file-size/type combination needs separate live evidence and deeper instructions.