DottaandPaperclip
db32bdf98b
<!-- entire-trail-link-start --> https://entire.com/gh/paperclipai/-/trails/8/changes/paperclip/8 <!-- entire-trail-link-end --> ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - GitHub tools save review assessments and publish their confirmed receipts. > - A timeout before publication staging can leave an invocation with no saved publication. > - Exact replay must repeat only the authorized preflight and converge on one publication. > - PR requests also share an App-owned summary comment. Progress and maintenance must preserve its final content. > - A native turn can intentionally wait for an author without sending another reply. > - This pull request repairs unstaged replay and prevents queued or passive-wait notices from replacing a published assessment. ## Linked Issues or Issue Description Related repairs: Refs #16883, Refs #16284, Refs #16275 recover saved publication receipts. Refs #17183 covers unavailable approved replay output. Refs #17714 fixes a separate publication lock-order problem. **What happened?** Exact review retries can return null `begin_review` output or `github_publication_unavailable` after an upstream read times out before publication staging. Separately, response maintenance can replace a completed PR assessment with “Review queued…” or a generic missing-response notice after an authorized no-new-work reply. The latter run can correctly commit a passive wait while its external summary is still overwritten. **Expected behavior** Exact retries repeat only the authorized preflight. A saved or uncertain publication keeps its existing recovery owner. Queued acknowledgements preserve final App-owned summary content. A committed native passive wait settles its current acknowledgement without writing a response or treating an old summary as a new-run reply. Success before presentation remains held until a durable decision exists; exact current-run confirmed receipts can retire their placeholders. Genuine missing/error responses retain fallback handling. **Steps to reproduce** 1. Hold a GitHub metadata read until an authorized gateway call times out before publication staging. Repeat the exact request. 2. Publish a valid PR assessment. Send an ordinary author reply that asks for no new work and no duplicate comment. 3. Commit the native `response_wake` with a no-comment server presentation decision. Run response maintenance twice. 4. The base returns the invalid replay result or replaces the assessment with progress/fallback text. **Paperclip version or commit** Replay regression: `41c42895fa862c586ff841f8c50200d93ffc83a4`. Maintenance regression: the previous PR head `c7553d2325df53d98d9febff7023ade4b1e704eb`. Both use real PostgreSQL and simulated GitHub responses. The maintenance failure was also observed in normal hosted use. **Deployment mode** Source checkout on macOS arm64 with isolated PostgreSQL 18, followed by a dedicated QA qualification. No production rollout is included. ## What Changed - Route exact `begin_review` replay through its typed owner. Repeat unstaged preflight only with the complete request digest and no successful invocation result. - Preserve current policy, immutable assessments, unique action keys, receipt recovery, and provider leases. - Preserve a verified App/marker-owned final shared PR comment during acknowledgements. New canonical assessments can still replace it at the same or a new head. - Project only a bounded server-committed native wait decision. Settle the current main-PR acknowledgement without provider writes or a fabricated current-run reply receipt. - Hold succeeded native runs while presentation is undecided, including the committed-before-presentation window. An exact current-run confirmed receipt can still retire its placeholder. - Keep missing/error fallback and uncertain publication checks. Update the bot guide, execution semantics, maps, and real-database regressions. ## Verification - **Causal RED:** exact begin replay returned null; exact unstaged submit replay returned unavailable. The new real-database maintenance test then reproduced the exact generic summary overwrite. Its first repair also exposed an earlier queued-acknowledgement overwrite. Both publication boundaries are repaired. Four additional ordering regressions reproduced the generic PATCH while native presentation was undecided; the corrected tests hold until the same row settles. - **Local GREEN:** 196 complete GitHub workflow cases pass on an empty migrated PostgreSQL fixture. This includes queued/running preservation, both success-before-presentation windows, null/scalar/invalid decisions, exact-current versus predecessor receipts, durable acknowledgement settlement, repeated no-op maintenance, eventual genuine missing/error fallback, pending writes and same/new-head canonical replacement. Workspace typecheck, exact-head build, maps and whitespace checks pass. The real database respects the actual selected-column projection. - **Command:** `PAPERCLIP_TEST_DATABASE_URL=<owned-postgres-18> pnpm --filter @paperclipai/server exec vitest run src/__tests__/chat-channels.integration.test.ts -t 'GitHub agent review workflow'`. - **CI/review:** historical heads `c7553d2325df53d98d9febff7023ade4b1e704eb` and `4d00d3af6f2ccbda8f38a98f81d392d82dd3c59c` had Greptile 5/5. Final readiness head `2d267f1e4aa0b835a11aede97798fbd800d9cd96` passed independent source review with no actionable finding and fresh Greptile 5/5 with zero unresolved threads; all 54 check runs pass with 2 intended skips; Snyk is successful and the merge state is CLEAN. The dedicated QA destination acceptance also passed. - **Full-suite limitation:** the earlier `pnpm test:run` attempt produced no final summary. Its retained log reports failures in unchanged workspace-runtime tests and 15-second gateway-audit and stale-question timeouts. Their cause remains unknown. Do not treat the targeted results as a full local-suite pass. - **Live evidence and limits:** normal native OpenCode/DeepSeek review delivery published a useful assessment, inline finding and App check at the exact reviewed head. A separate ordinary author reply delivered a useful answer and settled. Those are ordinary delivery proofs, not live injected-timeout proofs. A later no-new-work reply exposed the maintenance overwrite. The final combined source `070e9c4ead9341cd497b23f533a91bf194475e79` includes the exact publication repair and passed normal review → ordinary author reply → quiet destination acceptance. A normal current-head review restored the legitimate assessment; the ordinary no-new-work reply then committed a passive wait without new GitHub tools. The same 1,436-character summary stayed identical while queued/running, after terminal settlement, and more than 3 minutes 50 seconds after successful cleanup. Review rows and receipts stayed unchanged, with no owner, live run or queued input. The timeout fault fixtures prove replay and single-publication safety. The historical first upstream timeout producer remains unknown. The live board reads do not expose the raw acknowledgement action row: its terminal cancellation and next-pass no-op are real-PostgreSQL fixture proofs, while the hosted checks prove actual destination stability. The hosted journey did not inject a timeout or pause the terminal/presentation writer window. Private destinations, raw receipts and internal task identifiers remain outside this PR. ## Risks - Original and repeated metadata reads can overlap. The immutable assessment, action uniqueness and publication lease must remain authoritative. - Missing complete request identity or a deleted completed receipt remains held. The gateway does not reconstruct receipts or relax approval. - Passive suppression requires actual native mode/committed phase, current source ownership and the server's no-comment decision. It applies only to the main PR review surface. Uncertain current writes stay held; other surfaces keep normal placeholder retirement. - There is no migration, credential change, dependency or new retry scheduler. ## Model Used OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) in Codex assisted with diagnosis, implementation, tests, and source review. It used reasoning, repository tools and code execution. The context window size is not exposed in this session. ## 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>
19 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.
Feature ID: chat-channels.
Implementation: endpoint setup, endpoint detail, email setup.
Agent access: companion.
Sub-features
providers:chat-channels/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:chat-channels/identity— link the external sender to the intended authorized Paperclip identity.conversation:chat-channels/conversation— route inbound messages to the selected agent and send replies to the correct thread.attachments:chat-channels/attachments— transfer supported files with inspectable delivery and failure states.lifecycle:chat-channels/lifecycle— inspect endpoint activity, repair auth, and disable delivery when required.outbound-email:chat-channels/outbound-email— start a task-bound AgentMail conversation, reply to its exact message, and inspect deduplicated publication and provider delivery.
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.
outbound-agentmail
Use paperclipai email inboxes --company-id <company-id>, then email send --company-id <company-id> --file <new-email.json> or email reply --company-id <company-id> --file <reply.json>. Inspect email thread <email-task-id> --company-id <company-id> and email delivery <publication-id> --company-id <company-id>. Agent mutations must provide --run-id or the active PAPERCLIP_RUN_ID.
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.
Monitor continuation regression: database checks verify the exact originating conversation, rejected forged/mismatched receipts, one working publication, no completion for a yielded run, and saved-response recovery. In a disposable live thread, request work that needs deferred repository preparation. Verify a useful continuation explanation, automatic resumption, and the final result in that same thread. A successful provider turn alone is insufficient.
GitHub review comment regression (2026-10-19): repeated PR review requests reuse
one main App comment, including across restart and reconnect. Test a leading
request for an external bot (@greptile review) and verify it creates no wake or
acknowledgement. Stop execution before a milestone is staged, run maintenance,
and verify the existing comment reports the stop; saved requests on a blocked
task show paused state. Preserve newer progress and confirmed or uncertain replies.
Repeat terminal reconciliation with native identity and no legacy wake fields.
Check delayed acknowledgements, check-only assessments followed by formal reviews,
and combined requests with separate pre-upgrade placeholders.
GitHub review attention regression: publish a 3/5 assessment, then wait for the next provider event. The task stays in review without a completion card or Mine entry. A later 5/5 review with passing required checks can finish quietly. A real repository-access request enters Mine until resolved. The native external-chat database suite checks these states and revoked endpoints using stored provider receipts; live model adherence remains a separate check. It also checks saved monitors, disabled repositories, multiple reviewed heads, read-only finish validation, withdrawal rollback, and separate approval gates. Repeat the review wait after a tree resume and a same-agent continuation with no new provider message. Accepted requester lineage and the latest saved review publication keep the task in review without a self-wake or duplicate publication. A newer unreviewed head, changed requester/repository, or revoked access cannot inherit the prior head's passive wait. Omitted/null yielded continuation is filled from authorized server task context after a current-head review, an accepted tree resume inheriting it, or a same-head follow-up with this run's processed useful reply bound to its exact current source. Pending or ambiguous replies and acknowledgements do not authorize this fallback. A malformed first report can recover by omitting the continuation; explicit malformed input remains rejected. Revocation between context read, finish and commit preserves the task without self-waking. Done policy is unchanged.
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.
GitHub review prompt regression: open a PR and push twice. Each task message contains the event and commit identifiers; configuration comes from the admitted delivery snapshot and the PR description is fetched when needed. Inspect the native provider's submitted envelopes: a verified resume sends only the current batch and any changed configuration, while a fresh session receives full review instructions and task context. Change configuration between pushes and verify the queued older request retains its original snapshot. Integration fixtures cover the database and prompt contracts; they do not prove live provider delivery.
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. After publishing a PR assessment, deliver an ordinary no-new-work author reply. Hold native presentation after execution succeeds. Verify maintenance makes no provider write while undecided, including repeated passes and the explicit fallback path. Commit either a passive wait, genuine missing response, or failure and verify that the same request settles once with the corresponding behavior. Verify the actual shared summary stays unchanged during queued/running acknowledgements and after the committed passive wait, including maintenance, restart and cleanup. Confirm the per-request acknowledgement is terminal and a second maintenance pass makes no write. Then request a real same-head and changed-head assessment and confirm canonical publication can replace it. Real-PostgreSQL provider fixtures cover this producer and missing/error/unknown write safety; record hosted destination acceptance separately.
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.
GitHub connections in attention or revoked state show a repair notice above the settings. Reconnect GitHub → Reconnect saved App checks the same App with stored credentials and repairs delivery. Replace App credentials is the fallback, with the saved App ID, a link to its GitHub settings, and PEM upload or paste instructions. The production management Storybook's 04 Recovery group covers these views, pending/failure/success, mobile, and light theme with simulated provider responses. Verify actual credential validity and restored delivery separately against GitHub; a Storybook success does not establish live recovery.
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. Include text longer than 500
characters and coverage with more than 50 entries. Change only the text suffix
or final coverage entry and verify rejection without another write. Remove the
completed durable publication and verify that a retry cannot dispatch a new write.
Also interrupt metadata reads before publication staging, repeat the exact
begin_review and submit_review requests, and verify typed results and one
assessment publication. Let the original metadata read finish alongside its
retry and verify that both converge on the same publication. Changed requests
and revoked access must still stop preflight recovery.
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.
outbound-agentmail
Automated: Email channel integration uses controlled providers to test durable child tasks/intents, deduplication, reply binding, attachments, delivery, revocation, budgets, run authority, and company boundaries. No dedicated end-to-end CLI email test was identified; these fixtures do not establish actual recipient delivery.
Manual: Use a disposable parent task, authorized AgentMail inbox, and recipient you own. Put endpointId, a stable UUID idempotencyKey, text, parentIssueId, to, and subject in the new-message JSON; supply eligible attachmentIds only if needed. Send, inspect the child conversation/publication, and verify actual received mail. Repeat the identical request/key and confirm one child and provider send; changed content with that key must conflict. Reply with endpointId, conversationId, exact replyToMessageId, text, and a fresh stable idempotencyKey; inspect the actual recipients and received reply. Replies must reject caller-supplied recipient/subject/parent overrides. Test wrong inbox/task/company/run, a canceled task, revoked access/credentials, and an inaccessible attachment. Inspect uncertain provider outcomes before using the administrative resolution path.
Sources: Email CLI, request schema, email routes, and email authority/publication.
Gotchas
-
New outbound email requires a parent task. A reply binds to its stored conversation/message and cannot replace recipients or subject; a queued 202 is not a delivered message.
-
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
Capability ID: chat-channels/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.
Saved-input Retry regression: fail a disposable GitHub turn, change the configured instruction skill, and send a new authorized request while an agent budget gate blocks admission. Clear that gate and use the task thread's ordinary Retry control. Verify the new saved message and its admitted skill snapshot reach one run, rather than replaying the previous failed request. Preserve both original receipts. With a committed failed native result, continuation requires verified controller and environment cleanup; an unknown executor remains held. After successful admission, reload and verify that the prior skipped receipt does not strand a later real provider reply or tree resume. Provider fixtures support this behavior; live fixed-source runtime and destination proof remain separate.