External chat integrations
External chat integrations let people start and continue Paperclip work from Slack, GitHub, Discord, Microsoft Teams, Telegram, iMessage Photon, or Speko. Paperclip keeps provider identity, access rules, task state, agent work, and external results in one controlled flow. See Organization work management for the wider task model. See External app connections and Issue execution for related connection and work flows.
Integration model
An external chat endpoint is the provider-facing boundary for one assigned agent. It joins provider identity, allowed destinations, external people, conversations, tool access, and delivery records so an external message can become authorized Paperclip work. A provider thread extends a Paperclip task instead of creating a second task system.
The endpoint runtime carries a generation, a local runtime epoch, and a credential fingerprint. A callback or provider action is accepted only when the relevant values still match the endpoint. Reconnects and credential changes therefore fence off older provider sessions. Managed Slack Cloud events and form work also carry durable binding and instance identity.
For providers that require one live receiver, Paperclip keeps durable ownership of the provider session. It retains ownership through runtime construction, checks it again before admitting work, and stops the listener before releasing it. This gives another server a clean takeover path without overlapping receiver sessions.
| State | Meaning |
|---|---|
draft or verifying | Setup is incomplete. Normal work is not enabled. |
active | Inbound work and outbound publication are enabled. |
paused | New work is fenced off. Late callbacks are acknowledged but do not create work. |
attention or revoked | The connection needs repair or has lost provider authority. |
archived | Paperclip has removed the endpoint. The provider app or bot can still exist outside Paperclip. |
Provider events can also change one destination without changing the endpoint. A removed channel, chat, or repository becomes unavailable while other destinations remain usable.
Connection setup
Connection setup creates an endpoint for an active, invokable agent. It proves that the provider credentials identify the intended bot, app, account, or phone resource. It also defines where the endpoint may receive work and which people may use it.
The common setup path is:
- A connection manager selects a provider and an assigned agent.
- Paperclip stores credentials in its secret store and verifies the provider identity.
- Paperclip discovers provider destinations. The manager enables the destinations that may receive work.
- The manager links external people to Paperclip users when member identity is required.
- A test message or conversation proves the inbound and outbound path before activation.
Managed Slack Cloud setup adds an enrollment step after the local endpoint is qualified. Paperclip records an enrollment intent with the endpoint generation, Cloud instance, company, endpoint, connection, workspace, and app identity. A background owner registers or retires that binding and commits the receipt only when Cloud returns the same identity. This prevents a delayed Cloud response from activating a replaced or retired endpoint.
Paperclip checks native bot identity for uniqueness before it accepts a connection. Credential changes use a mutation guard so a concurrent reconnect cannot replace the secret binding that another operation is using. Human-entered signing or webhook credentials cannot be supplied by an agent management request.
Reconnect preserves the existing provider identity and scope. It repairs credentials or callback settings instead of silently installing a different app. Pause, resume, and removal change the Paperclip endpoint and its retained authority. They do not automatically uninstall a provider app. Removing the last connection to an app also archives the Paperclip app record, while provider-side resources remain the provider's responsibility. Slack Cloud enrollment is retired separately so the Cloud receiver cannot keep sending events for an old runtime.
The shared setup flow serves both the Apps area and task-hosted connection requests. It keeps access choices and OAuth handoff state across redirects. OAuth completion is accepted only after the server confirms durable connection state. A browser callback or popup message alone does not grant access.
Provider surfaces
Each provider presents a different external work surface, but every surface maps back to the same endpoint, task, authorization, and publication model. The provider catalog records only capabilities that the active runtime can support.
Slack
Slack supports channel threads, direct messages, mentions, slash commands, interactive replies, files, reactions, and streamed safe response text. A signed Slack callback is accepted only for the configured workspace and current endpoint runtime. In the managed Cloud path, Paperclip first validates the Cloud binding and then validates Slack's original signature before forwarding the event to the local webhook. Slack shows working state through its session status and a coalesced lifecycle reply instead of a separate typing indicator.
The manager chooses the channels that can receive work and whether direct messages are allowed. The bot must have access to a channel before it can read or write there. A Slack identity link maps an external person to a Paperclip user. Unlinked guest access is a narrower, sponsor-backed option. A slash-command task start records the provider's starter message before Paperclip admits the task, so a retry after a crash does not post a second starter message.
Slack can show questions, confirmations, task suggestions, and item decisions as buttons or selection controls. A selection change does not resolve work. Only the explicit submit action does. Slack session-stop actions target the exact authorized run or pending wakeup, so a later session cannot cancel different work.
Managed Slack Cloud also carries a separate form lane for question forms and modal actions. Paperclip binds each form to the current Cloud instance, endpoint generation, workspace, app, credentials, conversation, publication, and external user. A form open or submit is accepted only when its current or retained binding proves the same identity. Paperclip records provider evidence and terminal receipts before it retires the form work, which lets a later worker finish acknowledgement or cleanup without opening or submitting the form again.
The Cloud path checks coverage for every configured ingress lane that the endpoint needs. Those lanes include events, commands, actions, forms, modal close and submit, and option lookups. A connection is not considered fully covered when the broker proof omits a lane required by its enabled capabilities.
References: server/…/cloud-callback.ts• L7-55 server/…/cloud-event.ts• L40-84 server/…/cloud-enrollment.ts• L32-71 server/…/form-owner.ts• L39-61 server/…/form-delivery.ts• L21-84 server/…/form-ack-work.ts• L56-145 server/…/configured-coverage.ts• L15-65 server/…/chat-channels.ts• L2653-2659
GitHub
GitHub turns issue comments, pull request comments, and review events into conversations for one assigned agent. The endpoint represents one GitHub App installation and only the repositories enabled for that installation.
Manual work needs an authorized GitHub person. Automatic issue or pull request work also needs an enabled repository, an active responsible user, enabled bot tools, and a review policy that matches the event. The policy controls invocation mode, events, authors, branches, labels, draft pull requests, paths, findings, summaries, checks, and formal review actions.
GitHub policy instructions are trusted configuration. Text from a GitHub message or repository is untrusted data and cannot install skills, select tools, or grant access. Review assessments must name the current pull request head. Findings must use allowed paths and valid diff lines.
GitHub uses one App-owned working comment for an accepted request. Progress edits that comment. The final discussion reply or review replaces it. Review work is tied to one exact pull request head. A changed head supersedes older review work instead of allowing findings, checks, or formal actions for old code to appear on the new head.
GitHub review checks are status views of the same review work. They publish only after Paperclip confirms the endpoint, repository resource, tools, runtime generation, delivery, and exact pull request head. A completed run can still report an incomplete assessment when it produced no accepted review result. A terminal response can remain pending until the task or blocked issue reaches a terminal state, so a late monitor does not publish a stale working reply.
GitHub webhook handling limits secret access to the step that needs it. Initial admission uses the webhook secret to verify the signed request, then reads the App identity only when it must check the installation or recover a failed delivery. Recovery asks GitHub to redeliver only a recent failed created-comment event that still matches the current endpoint, repository, callback, and source comment. If the redelivery request may have reached GitHub but its result is unknown, Paperclip keeps the recovery action unresolved instead of issuing an unsafe duplicate.
A passive wait after a published review inherits the source requester only when the connection, repository, pull-request head, task, agent, and processed publication still match. It is a continuation signal, not permission to publish a new review or reuse old attachments.
References: server/…/review-check-state.ts• L7-44 server/…/review-check-state.ts• L101-139 server/…/review-wait.ts• L144-185 server/…/terminal-response-work.ts• L40-70 server/…/terminal-response-work.ts• L88-117 server/…/task-retry-authorization.ts• L81-106 server/…/webhook-ingress.ts• L242-333 server/…/webhook-ingress.ts• L1249-1453
Discord
Discord connects a bot to one configured server and its discovered channels. The Gateway provides inbound events and lifecycle signals, while Paperclip keeps one durable receiver owner for that endpoint.
Only the server that holds the current Gateway lease may construct and run the live receiver. The lease is renewed during normal operation and at message admission. If renewal fails or the runtime no longer matches the lease, Paperclip fences the listener and releases ownership so a standby server can take over without two active Gateway sessions.
References: server/…/ownership.ts• L76-117 server/…/ownership.ts• L272-411 server/…/chat-channels.ts• L999-1127
Microsoft Teams
Microsoft Teams supports direct messages, channels, group chats, cards, actions, files, and message lifecycle events. Paperclip defers inbound processing into its durable work path and keeps the current Bot Framework route for the conversation.
Channels use explicit destination enablement. Group chats use the endpoint group-chat setting because they are a reach class rather than a simple discovered channel list. File delivery has a separate consent and transfer flow. It sends consent first and transfers or reports the file only after the stored authority for that exact publication remains valid.
References: server/…/surfaces.ts• L137-155 server/…/envelope.ts• L120-159 server/…/file-delivery.ts• L227-385
Telegram
Telegram uses a bot webhook for direct messages, group chats, topics, files, cards, actions, and safe streaming where the provider surface supports it. Setup verifies the bot, registers the webhook, and keeps provider update types aligned with enabled features.
A chat or topic is admitted only when its destination and address rules allow it. If an inbound message contains only an unsupported attachment, Paperclip records the delivery as handled and publishes a safe resend notice without waking the agent. This avoids treating an empty turn as work.
References: server/…/configuration.ts• L574-591 server/…/attachment-failure.ts• L47-153 server/…/surfaces.ts• L41-45
iMessage Photon
iMessage Photon provides a phone-based external conversation surface. A channel can use a dedicated line or a shared project scope. Setup checks that the selected project and line are not already owned by another endpoint.
The receiver checks endpoint ownership and active agent work before it advances its checkpoint or accepts a recovered runtime. A Photon reply finishes a turn but does not by itself release the conversation's task binding. A durable /new or /close control completion is required before a linear Photon surface can move to another task.
References: server/…/runtime-callbacks.ts• L18-63 server/…/events.ts• L714-903
Speko
Speko is the voice-facing provider surface in the chat connection family. It assigns a voice agent, configures signed session callbacks, and exposes direct voice interaction rather than a threaded text channel.
Its work still uses endpoint identity, sponsor, authorization, task, question, and publication controls. Provider setup installs the voice tools needed by the assigned agent and requires an explicit public HTTPS callback origin.
References: server/…/chat-channels.ts• L538-556 server/…/configuration.ts• L107-110
Inbound event handling
Inbound handling turns an authenticated provider event into a durable delivery before normal task processing continues. The provider runtime normalizes the event. Paperclip records the provider event identity, external person, destination, conversation thread, runtime fence, and admission result.
The admission decision checks these facts together:
- endpoint status and current runtime credentials
- provider destination availability and Paperclip enablement
- direct-message, group, mention, or address rules
- external identity links or sponsor-backed guest access
- provider-specific task or review policy
- duplicate event and lifecycle ordering
Paperclip keeps only identifiers and runtime proof for a destination that has not passed the reach gate. It retains message text, attachments, and the external person profile only after the destination is admitted. This limits the data retained from provider traffic that the operator has not enabled.
An admitted delivery first creates a durable inbound wakeup. The wakeup must be accepted under current authorization before Paperclip queues agent work. This separates provider receipt from task scheduling. Retries can reuse the stored receipt instead of creating a second task turn. For GitHub, a queued comment can continue an eligible active native run when its task, conversation, author, trust level, and comment state still match. Otherwise Paperclip keeps it as a separate deferred request.
Each external conversation has an ordered delivery queue and a short-lived lease. Different conversations can proceed in parallel. Later messages in one conversation cannot overtake an earlier delivery that is still being processed. Edits, deletes, and restores become lifecycle records that can add or remove task context without admitting unauthorized new work. A lifecycle record waits for its exact message dependency when that dependency has not finished admission.
This diagram shows the common path from provider callback to an assigned-agent run.
sequenceDiagram
participant P as Provider
participant E as Endpoint runtime
participant L as Durable delivery
participant W as Inbound wakeup
participant Q as Conversation queue
participant T as Paperclip task
participant A as Assigned agent
P->>E: Signed or owned event
E->>E: Verify provider identity and runtime
E->>L: Record event and deduplicate
L->>L: Check destination, person, policy, and endpoint state
L->>W: Record accepted work request
W->>Q: Accept durable wakeup
Q->>T: Create or resume task conversation
T->>A: Wake assigned agent
A-->>T: Produce task or review result
Late callbacks from a paused, replaced, revoked, or archived runtime are filtered. A provider retry can receive a safe acknowledgement without reopening stopped work.
References: server/…/chat-channels.ts• L794-833 server/…/envelope.ts• L86-117 server/…/delivery-ledger.ts• L127-182 server/…/conversation-queue.ts• L379-437 server/…/conversation-queue.ts• L452-705 server/…/wakeups.ts• L65-185 server/…/wakeups.ts• L211-451 server/…/wakeups.ts• L453-574 server/…/inbound-steering.ts• L35-52 server/…/inbound-steering.ts• L159-234 server/…/chat-channels.ts• L1471-1612
Identity and tool access
External identity is checked at admission and again at later action boundaries. A provider person can be linked to a Paperclip member, admitted as a restricted guest with a live sponsor, or denied. A previous authorization snapshot does not remain valid after revocation.
The assigned agent receives only tools that match the endpoint, task, provider destination, and current tool policy. Provider content is untrusted input. It cannot select another connection, change the repository or conversation binding, export credentials, or grant a new permission.
Interactive provider actions use an opaque binding to the original Paperclip publication and interaction. Paperclip checks the current endpoint runtime, person, conversation, destination, publication, and pending interaction before it accepts a click or form answer. A stale or unauthorized action is recorded as denied and cannot resolve a newer question.
GitHub tools require the active assigned-agent run, the originating conversation, the enabled repository, the current review policy, and the same endpoint runtime. Read tools return provider data as untrusted data. Write tools publish comments or review results through the endpoint's repository access. Formal review actions require separate policy permission.
Configured GitHub skill links are carried into the task prompt only from the saved connection policy. A /skill reference in a GitHub message or repository cannot add a skill or tool.
References: server/…/authorization.ts• L175-275 server/…/authorization.ts• L277-354 server/…/wakeup-authorization.ts• L167-194 server/…/callbacks.ts• L563-736 server/…/callbacks.ts• L924-975 server/…/chat-github-review-policy.ts• L243-263
Task and review publication
Task replies, progress, questions, confirmations, files, and review results use durable publication records. Paperclip checks the current endpoint, conversation, destination, identity, task binding, and runtime before provider I/O. It records the provider receipt before it marks the publication complete.
Publication order protects the conversation from stale or duplicate output. A later result can replace an earlier working message when the provider supports edits. Provider limits can split a long safe message into ordered parts. A provider response with no usable receipt becomes uncertain and requires inspection before replay.
Paperclip prepares the durable provider payload before it spends a delivery attempt. This includes validating the saved payload, splitting text when the provider has size limits, and preparing provider-specific cards or drafts. A publication attempt then claims its own lease and makes one final authorization check before provider I/O.
Paperclip exposes only coarse run milestones outside the system. It can publish queued, working, waiting-for-input, completed, or failed state. Raw agent output, errors, tool events, and reasoning stay in Paperclip unless a separately authorized provider action publishes them. An explicitly authored provider response suppresses a generic completion or progress message, so one task turn does not produce competing final answers.
Slack can publish the latest safe progress note from an agent run without creating a new message for every progress event. It redacts run secrets, waits until the base publication settles, and spaces later progress updates so the external thread remains useful rather than noisy. A contextual fast-response acknowledgement can also qualify for this progress path when the run ended before normal publication.
Questions and confirmations use provider-specific cards, buttons, forms, or links. Their action tokens point to one durable interaction and expire when the interaction is resolved or replaced. A provider callback rechecks the current person, conversation, publication, and interaction before it changes the task. When a person resolves an interaction, the resolution wakes the owning task through the same conversation lineage.
Completion of a delegated Paperclip task can publish a result back to its originating chat conversation. The completion notice links to the saved task and recorded decisions. It is a notification of existing work, not a new review request or permission to change that work.
GitHub uses a related but distinct review path. A validated review assessment can publish a summary, inline findings, and a review check for the exact commit. The check reports the task and review state but does not create the task run. The review heading identifies the GitHub bot rather than the assigned agent and marks incomplete assessments as incomplete. A native run that has finished execution but has not committed its presentation remains undecided. A passive response wait is recognized only after Paperclip commits the no-publication decision. A later review wait inherits the source requester only when the connection, repository, pull-request head, task, and processed publication still match.
This diagram shows the durable publication path and its safe handling of uncertain provider results.
flowchart LR
A[Task or review result] --> B[Durable publication]
B --> C[Current authorization claim]
C --> D[Provider send or edit]
D --> E{Usable receipt?}
E -- Yes --> F[Published record and task settlement]
E -- No or timeout --> G[Delivery unknown]
G --> H[Inspect provider before replay]
Provider errors are separated into safe retry, endpoint attention, destination unavailable, definite failure, and delivery unknown. Rate-limit hints control the retry time. A network failure remains uncertain because the provider may have accepted the write. A destination-unavailable result closes the affected conversation and marks its resource unavailable. An endpoint-attention result disables the connection and removes its runtime only when the failed runtime is still current.
References: server/…/preparation.ts• L44-155 server/…/worker.ts• L221-353 server/…/worker.ts• L670-907 server/…/failures.ts• L56-145 server/…/failures.ts• L190-254 server/…/review-check-state.ts• L111-139 server/…/terminal-response-work.ts• L58-117 server/…/native-progress.ts• L8-51
Conversation lifecycle
A provider thread is linked to a Paperclip task conversation. The link stores the provider conversation and thread, destination, assigned agent, task, session generation, and publication history.
Native provider threads usually stay bound to one task. Linear surfaces such as some direct messages, group chats, topics, or explicit new-task controls can advance to a new task generation while retaining the provider surface. Before that advance, Paperclip checks durable task-control completion rather than relying on a final-looking reply. A recent deferred message can also reopen a closed task when its endpoint, agent, conversation, and authorization still match; older or changed work settles without reopening the task.
A later authorized message resumes a waiting conversation or starts a new task when the surface rules require it. Linear surfaces treat a completed conversation or completed task as closed before binding the next message, while native provider threads remain bound to their task. Conversation state follows durable task and publication evidence. A final-looking message does not close a conversation while a run, question, approval, retry, blocker, or newer inbound delivery remains open.
Slack session stop is part of this lifecycle. The stop event records its event time and exact run or wakeup target. Processing cancels only work that still belongs to the same active endpoint, conversation generation, task, and authorized person. A superseded target is settled without cancelling newer work.
Automatic monitors, task completion handoffs, and other continuations retain the exact originating conversation only when their durable identity lineage proves the same task, agent, company, and requester. A completed delegated task can therefore report back to its source conversation without reopening the completed task.
References: server/…/conversation-binding.ts• L15-71 server/…/surfaces.ts• L111-135 server/…/conversation-queue.ts• L118-135 server/…/wakeups.ts• L453-574 server/…/session-stop.ts• L203-315 server/…/chat-completion-delivery.ts• L24-75
Recovery and retries
Recovery treats a saved provider request as evidence, not as permission to repeat work. Paperclip can retry a failed chat run only when it can prove the exact task, agent, endpoint, conversation, requester, accepted inbound batch, and runtime state. A task retry also needs a user-owned retry intent when the provider supports that path. It does not turn caller text or a provider redelivery into new authority.
Some failures occur before provider work starts. Paperclip can retry those attempts only when the saved run, wakeup, cleanup, and resource records prove that no provider session, result, or active execution lease exists. A failure that reached an uncertain executor remains held until recovery evidence settles it.
GitHub retries may include deferred user messages that were not run because of budget or agent availability. Paperclip selects the full source queue on the server and records it as a retry snapshot. It can coalesce those source requests into one retry without losing older messages. If the retry is not admitted, the source requests return to their deferred state.
A retry cannot replay a recorded result without new authorized input. It also cannot repeat a prior response or interaction. The retry keeps the original provider, endpoint, destination, requester, conversation, and runtime fence. If the old execution may still be running, or its workspace and provider cleanup are not proven, the retry waits or is denied instead of starting a second execution.
Provider recovery uses durable action records and receipts. GitHub publication can recover a working comment or review part by its marker. A completed assessment without a processed publication action is not treated as delivered. If a send may have reached the provider but Paperclip lacks a receipt, the result stays delivery unknown until provider history is checked. The same rule applies when GitHub steers a queued comment into an active run: Paperclip records the run and comment proof before delivery and consumes the wakeup only after the provider acknowledges the turn. An uncertain steering result remains unresolved instead of starting another turn.
GitHub webhook recovery uses the same durable action model as other provider effects. A bounded scan finds eligible failed callbacks, records the exact recovery window and current runtime fence, and requests a provider redelivery only after the source comment and enabled repository still match. The recovery action is marked as delivery unknown when transport starts without a confirmed result, so operators must resolve that state before another replay.
Deferred inbound wake recovery also checks that the task still has the same agent and endpoint scope. It may coalesce recent compatible messages into one wakeup, but it does not replay a stale or already-owned request.
Idle history proof
Idle history proof lets background workers sleep only after saved chat work has a terminal, linked outcome. It checks deliveries, actions, publications, and task completion notices together, so a processed receipt cannot hide an unconsumed wakeup or an unfinished external effect.
The proof treats a rejected delivery, an expired interaction, a cancelled publication, and a completed provider action as different valid terminal outcomes. Slack form enrollment, grant, session, acknowledgement, and retirement work also need a settled receipt or an explicit attention state before the worker can treat their history as idle.
References: server/…/idle-history-proof.ts• L19-67 server/…/idle-history-proof.ts• L70-133 server/…/form-idle-history.ts• L16-70
Configuration changes notify the work queues that own receivers, provider recovery, voice runtime, Discord command registration, Slack Cloud enrollment, form work, and delivery work. This keeps a pause, reconnect, removal, or company change from leaving maintenance work attached to old authority.
References: server/…/failed-run-retry.ts• L759-841 server/…/task-retry-authority.ts• L13-29 server/…/cloud-enrollment.ts• L73-141 server/…/form-owner.ts• L189-229 server/…/configuration-work-notifications.ts• L8-38 server/…/webhook-ingress.ts• L1134-1184
Connection-management UI
The connection manager is the operator view of one endpoint. It combines provider setup with the controls needed to keep external work safe: destination scope, identity access, tool state, review policy, conversations, activity, health, and lifecycle actions.
The shared setup UI supports standalone and task-hosted connection requests. It filters provider choices by instance rollout state, keeps access selection across redirects, and confirms completion from durable server state. It does not treat a browser callback or popup message as a connection grant.
The endpoint detail UI supports pause, resume, reconnect, removal, resource changes, identity links, test messages, conversation history, activity, replay, and resolution. Activity brings together deliveries, publications, provider replies with unknown delivery, failed GitHub ingress, Slack session actions, provider recovery work, and Slack form work. Operators must inspect the provider before retrying an uncertain send.
The server routes protect these operations by separating read, configure, test, audit, and connection-management permissions. Agent-initiated setup can return a saved user handoff when a human must enter credentials or approve provider access. Provider creation is also gated by instance rollout settings, so an agent cannot turn on an unavailable connector.
References: server/…/ConnectionSetupFlow.tsx ui/…/ChatEndpointDetail.tsx server/…/chat-channels.ts• L101-215 server/…/chat-channels.ts• L425-519 server/…/chat-channels.ts• L593-647
Change checklist
When these files or sections are changed, remember to consider these:
- Keep provider capabilities, normalized callback events, active runtime behavior, receiver ownership, and the connection UI capability view aligned. A capability shown to an operator must be usable after runtime and provider receipt checks.
- Keep credential verification, stable provider identity, secret bindings, runtime generations, fingerprints, and reconnect rules aligned. A repair must not bind an endpoint to a different provider bot or app.
- Keep Slack Cloud enrollment intent, Cloud binding receipt, instance identity, original Slack signature, and local webhook generation aligned. Cloud events must not cross endpoint, app, workspace, or runtime boundaries.
- Keep Slack form enrollment, current and retained form bindings, Cloud instance identity, signed original evidence, terminal receipts, acknowledgement transfer, and retirement work aligned. A form must not be opened, submitted, acknowledged, or retired under a different binding.
- Keep Slack configured coverage aligned with endpoint capabilities and broker proof. Adding a modal, option, command, or event path must also update the required ingress lane set.
- Keep receiver lease acquisition, runtime construction, lease renewal, message admission, listener stop, and standby takeover aligned. Ownership loss must fence callbacks before another server takes over.
- Keep configuration changes connected to receiver, delivery, GitHub recovery, Discord command, Slack Cloud enrollment, Slack form, voice, and company-level maintenance work. A status change must not leave old maintenance work active.
- Keep provider inventory refresh separate from Paperclip destination enablement. A newly discovered channel, chat, or repository must not become a publication target by discovery alone.
- Keep external identity links, membership roles, guest sponsors, task trust, tool access, and publication authorization aligned. Revocation must affect work that is still running.
- Keep event IDs, thread identity, delivery order, lifecycle revisions, wakeup receipts, and conversation leases aligned. A duplicate, edit, delete, or out-of-order callback must not create a second task turn.
- Keep publication idempotency keys, provider markers, receipts, replacement links, uncertain states, retry windows, and replay actions aligned. A timeout must not silently become a duplicate message, comment, file, or review.
- Keep GitHub policy snapshots, reviewed heads, bot display names, response comments, inline findings, checks, terminal response work, and publication receipts aligned. New commits must supersede old assessments, and review output must use the current bot identity.
- Keep GitHub webhook signature checks, staged request bodies, installation checks, recovery scans, source-comment validation, and redelivery receipts aligned. A recovery path must not decrypt unused secrets or adopt a callback from an older endpoint generation.
- Keep GitHub configured instruction sources separate from provider event data. Provider text must not select skills, tools, connections, or review authority.
- Keep Slack native progress eligibility, safe progress filtering, run-secret redaction, publication settlement, and progress timing aligned. A progress note must not expose run data or race a normal task result.
- Keep task retry intent, server-selected retry input, committed run context, and run-origin lineage aligned. A retry or completion notice must not acquire a new requester or publish through a different conversation.
- Keep GitHub steering markers, run identity contexts, comment update and content proof, source trust, attachment state, and queued wake receipts aligned. A queued comment must not join a changed run or conversation.
- Keep deferred wake recovery, closed-task reopen windows, same-conversation batching, and coalesced wake receipts aligned. Recent compatible messages may combine safely, but stale or reassigned work must settle without reopening a task.
- Keep pre-provider failure evidence, cleanup receipts, execution leases, and retry admission aligned. A retry must not start a second provider session when the first attempt may still be active.
- Keep idle-history proofs aligned with every chat action's terminal result and its owning delivery. A worker must not sleep while a wakeup, publication, completion notice, or Slack form receipt still needs work.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Provider credentials identify a different bot or app | Reconnect could move an endpoint to another external identity | Stable identity verification and connection-level uniqueness checks |
| Callback arrives after pause, removal, or credential replacement | Old work could reopen a stopped endpoint or use old authority | Endpoint status, runtime generation, credential fingerprint, and receiver ownership fences |
| Slack Cloud receipt names a different binding, instance, app, or runtime | A Cloud event could reach the wrong workspace or an old endpoint | Durable enrollment identity, binding checks, original Slack signature validation, and generation checks |
| Slack Cloud enrollment is retired or unsettled | Cloud events could continue after removal, or valid events could be dropped without operator signal | Durable active or retired enrollment intent and receipt commit only after matching Cloud confirmation |
| Slack form binding or terminal evidence changes | A modal callback could open, submit, or acknowledge a form from another endpoint or runtime | Current or retained binding checks, signed original evidence, immutable operation identity, and terminal receipt proof |
| Required Slack ingress coverage is missing | Events or form actions can be accepted by the provider but never reach the configured endpoint | Capability-derived lane requirements and verified configured-coverage fingerprint |
| Another server owns a leased provider receiver | A local runtime could open a second live provider session | Durable lease acquisition, ownership checks during admission, and stop-before-release takeover |
| External person is unlinked, revoked, or has viewer-only membership | A later task action or publication could use stale member authority | Current identity and membership checks at admission and action time |
| Destination is removed or disabled | Paperclip could read from or publish to an unavailable channel, chat, or repository | Provider lifecycle updates plus Paperclip resource enablement checks |
| Provider accepts a write but the receipt is lost | Automatic retry could create duplicate output | Delivery-unknown state, provider markers where supported, and inspect-before-retry resolution |
| Inbound events arrive out of order or more than once | A duplicate task turn or stale edit could change task context | Provider event deduplication, ordered conversation delivery, lifecycle dependencies, and durable wakeup receipts |
| A provider action callback no longer matches its original publication | A stale click could answer a newer question or change a closed task | Opaque action binding plus current principal, conversation, publication, and interaction checks |
| Slack task start is confirmed by Slack but Paperclip admission fails | A retry could post a second starter message or lose the original task request | Provider-confirmed action state with Paperclip-only admission retry |
| GitHub policy or reviewed head changes during review | Findings, checks, or formal actions could describe old code | Policy snapshots, exact-head validation, and publication authority checks |
| A GitHub webhook recovery uses an old source comment or endpoint epoch | A failed callback could be replayed into current work or produce a duplicate task turn | Current runtime fence, enabled-resource check, source-comment recheck, durable recovery receipt, and delivery-unknown state |
| A completed GitHub run has no committed presentation decision | Paperclip could report missing output as a failure or publish an unintended response | Presentation-pending and passive-wait projections require a committed presentation state |
| Slack progress reads an unsafe or unsettled run event | External chat could expose secret text or show progress after the final result | Public progress event filter, run-secret redaction, base-publication eligibility, and spaced delivery schedule |
| GitHub retry input is truncated, changed, or not admitted | Deferred external requests could be stranded or replayed under a different source | Server-selected full input snapshot and source-action coalescing rules |
| A failed attempt has provider or execution evidence | Retry could start duplicate agent or provider work | Pre-provider and native recovery proofs plus active lease checks |
| A queued GitHub comment no longer matches the active run or its source comment changed | The comment could steer work into the wrong run or make review state describe different input | Exact task, conversation, responsible author, trust, attachment, run identity, timestamp, and content checks |
| A deferred chat wake belongs to a reassigned, backlogged, or long-closed task | Old external input could reopen work that no longer belongs to the chat endpoint | Current task and agent checks plus the bounded closed-task reopen window |
| GitHub steering reaches an uncertain provider state | Recovery could send the same comment turn twice | Durable steering marker, provider acknowledgement, and unresolved delivery state |
| A completion notice loses its source conversation or generation | A result could publish to the wrong chat or revive completed work | Handoff ownership and session-generation checks |
| Idle history marks a receipt complete before dependent work settles | A worker could sleep and leave external work stranded | Domain-owned terminal proofs across deliveries, actions, publications, completion notices, and Slack form work |
Key files
| File | Why to read it |
|---|---|
| server/…/chat-channels.ts | Shows the provider ingress boundary and the permission model for setup, review, replay, and connection management. |
| server/…/chat-channels.ts | Shows how endpoint runtimes, inbound processing, publication work, retries, and shutdown join into one service. |
| server/…/configuration.ts | Shows provider setup, identity checks, pause, resume, reconnect, removal, and runtime activation. |
| server/…/cloud-enrollment.ts | Shows managed Slack Cloud enrollment, retirement, identity custody, and retry ownership. |
| server/…/cloud-event.ts | Shows Cloud receipt checks and revalidation of Slack's original signed event. |
| server/…/form-owner.ts | Shows the durable owner, grant, retirement, and form publication lifecycle for managed Slack forms. |
| server/…/form-delivery.ts | Shows how current and retained form authority resolves provider callbacks without replaying the original action. |
| server/…/form-ack-work.ts | Shows durable form acknowledgement receipts and transfer of terminal evidence. |
| server/…/configured-coverage.ts | Shows how enabled Slack capabilities map to required broker ingress lanes. |
| server/…/ownership.ts | Shows durable receiver ownership, renewal, admission checks, and safe takeover. |
| server/…/envelope.ts | Shows normalized provider identity and the reduced record retained before destination admission. |
| server/…/delivery-ledger.ts | Shows delivery ordering, lifecycle dependencies, retry readiness, and runtime fences. |
| server/…/conversation-queue.ts | Shows per-conversation serialization with parallel work across separate conversations. |
| server/…/authorization.ts | Shows current identity, membership, sponsor, destination, and action authorization. |
| server/…/wakeup-authorization.ts | Shows the live checks before an accepted message can start work. |
| server/…/wakeups.ts | Shows the durable boundary between an accepted provider delivery and task scheduling. |
| server/…/inbound-steering.ts | Shows how compatible queued GitHub comments continue an active run and how uncertain steering is recovered. |
| server/…/callbacks.ts | Shows how questions, forms, and confirmations bind external actions to current Paperclip work. |
| server/…/preparation.ts | Shows durable payload preparation and provider-size splitting before delivery. |
| server/…/worker.ts | Shows publication leases, final authorization, provider I/O, receipts, and settlement. |
| server/…/failures.ts | Shows publication retry, delivery-unknown, endpoint-attention, and resource-unavailable outcomes. |
| server/…/review-check-state.ts | Shows how GitHub review checks reflect current endpoint, delivery, run, and pull-request state. |
| server/…/webhook-ingress.ts | Shows signed GitHub webhook admission, selective credential reads, durable ingress retry, and bounded redelivery recovery. |
| server/…/review-wait.ts | Shows how a published GitHub review can be inherited only for the same current pull-request head and source lineage. |
| server/…/terminal-response-work.ts | Shows recovery of GitHub replies that wait for a task or issue to reach a terminal state. |
| server/…/failed-run-retry.ts | Shows exact-source validation for failed chat run retries and recovery proof. |
| server/…/native-progress.ts | Shows how Slack selects safe public run progress and spaces progress publications around the main result. |
| server/…/task-retry-authority.ts | Shows retry intent binding and containment checks before a task retry can proceed. |
| server/…/idle-history-proof.ts | Shows how idle checks prove that chat receipts and dependent work have settled. |
| ui/…/ConnectionSetupFlow.tsx | Shows shared setup, access selection, provider filtering, redirects, and durable completion checks. |
| ui/…/ChatEndpointDetail.tsx | Shows endpoint operations, provider settings, conversations, activity, and recovery controls. |