DottaandPaperclip
074c67fea8
## Thinking Path
> - Paperclip lets people manage AI agents and their work.
> - Grok Bot receives assignments through routine webhooks and uses
agent MCP tools.
> - Each accepted assignment belongs to the current external
interaction.
> - A pending tool result or comment could start another routine while
that work was still active.
> - Quiet MCP traffic cannot prove that Grok has stopped working.
> - This pull request keeps receipts and feedback durable for the
current interaction to read.
> - New task routines start only for offers that the Bot has not
accepted.
## Linked Issues or Issue Description
Refs #16219 and #16305. The duplicate search also found #12991, which
covers instruction files for local Grok runs.
**What happened?**
The dispatcher could start another routine for an unread result after a
period without a routine reply. It could also wake accepted work for a
task comment. A queued delivery could still start after the Bot had
claimed the offer.
**Expected behavior**
Accepted work stays in its current interaction. The Bot polls the
original operation receipt and reads queued feedback at a safe boundary.
Acknowledgements of a sent wake remain valid after acceptance.
**Steps to reproduce**
1. Accept a Grok assignment and leave it active.
2. Add an unread comment, or complete a tool operation whose call
returned pending.
3. Run the dispatcher after its quiet period.
4. Observe another webhook call. Also queue an offer wake, accept the
offer before sending, and observe that delivery still starts.
**Paperclip version or commit**
Observed during real-client qualification on Core
ff0f976de1. The three new regression cases
also failed on current master before the correction.
## What Changed
- Stop automatic result and feedback wakes for accepted work. Keep both
available through their existing read paths.
- Require an unaccepted offer before dispatch or an explicit delivery
retry. Serialize the final HTTP handoff with acceptance receipts. Cancel
obsolete unsent wakes. Preserve late acknowledgements and immediate Stop
authority.
- Return current Grok polling instructions on assignment reads. Clarify
pending and unknown outcomes in setup guidance.
- Add protocol, receipt-polling, queued-delivery and
late-acknowledgement regressions. Update the operation guide and
readiness plan.
## Verification
- Three new regression cases fail before the fix because a webhook
starts.
- The latest 31 Grok protocol checks and 47 existing Dot Runner checks
pass. New tests force acceptance during secret lookup and the final send
check. They also prove that acknowledgements and Stop remain free during
pending delivery.
- The final-head Grok, Dot, MCP and question-delivery suite passes all
212 checks across six files. Dedicated onboarding UI checks passed six.
- Dedicated Runner driver checks use the real local Rust daemon. Built
the debug daemon required by that package; all 17 checks then passed.
- Repository typecheck and build pass. Token gates, the 2,731-story
structural catalog and the Storybook build pass.
- Public synthetic marker for the post-deployment native source-read
check: `grok-native-read-b45be4eff22cb15a31d0af512f437b8d`.
- Final-head CI passes all 55 checks, with two optional Storybook skips.
Greptile is 5/5 with no open threads. The first chat-shard attempt
failed one Telegram SQL-quiet timing assertion; all five related cases
pass locally and the single targeted CI rerun passes.
- After deployment, repeat actual Grok work through an answered
question, receipt polling, a saved report and file, canonical completion
and cleanup. This correction is not production qualification by itself.
## Risks
A Bot that does not poll a pending receipt can wait without another
routine wake. Current assignment reads now supply polling instructions
to existing connections. Task comments stay queued until the Bot reads
them or Runner admits the next continuation. The real client must verify
that behavior before production enablement. The observed second file
version does not prove which provider interaction created it. Acceptance
can wait for the bounded webhook response. Stop and authenticated
acknowledgements use independent row locks and remain available.
## Model Used
OpenAI GPT-6 in Codex, with reasoning, repository editing, shell tools
and browser tools. The exact serving model ID, snapshot and context
window are not exposed by 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>
4.5 KiB
Grok Bot agents (experimental)
Grok Bot is an externally managed Paperclip agent. It uses Grok Bot's existing apps and persistent context. It is separate from the Grok Build coding runtime. Paperclip coordinates tasks through the managed Runner. Grok usage and spending are not reported.
From Agents → New agent → Invite external agent → Grok Bot, name the agent and select its role and manager. Follow the connection instructions in Grok Bot. Approve the fixed Paperclip company and agent in the browser. Copy the one-use pairing code with Copy code; enter it only on the authorization page. Grok plugins are account-wide, so connecting a Bot does not isolate credentials between Bots on that Grok account.
Copy the routine instructions into the Bot's chat. Open its desktop routine's Webhook panel and paste the URL and key into Paperclip's secure configuration. Use a webhook-only routine with no schedule. Verify connection must show both assignment delivery and an authenticated reply before Done becomes available. Use Save & exit to preserve unfinished setup. See the official routine instructions.
Manage the Bot from its agent's Runtime settings. This shows connection health, routine configuration, and verification. Model selection, local paths, and runtime tests are managed outside Paperclip; use Verify connection to check both directions. Use Reconnect agent access to restore the same agent's connection. Select Copy code beside the masked one-use pairing code, then paste it into Paperclip's authorization page. Keep it out of Bot chat.
Assign ordinary tasks to the agent. Read its progress, answer its question cards, and review its documents and files in the task thread. The Bot can initiate a new task from its Grok conversation through the admitted work-session tools. An immediate proactive claim does not send the same assignment back through the routine.
Files and completion
Use paperclip_grok_get_upload_url for an accepted current assignment. Compute
the exact file's SHA-256 and size, then PUT those bytes with Grok's own HTTP/file
tools. The successful response includes the attachment and its verified
publication.evidenceRef. Cite that reference in the completion report. No
Paperclip filesystem is exposed, and no separate upload completion call is needed.
Repeat the same request ID after a lost response. Concurrent or repeated uploads
retain one attachment and one publication receipt. Person MCP uploads remain
person uploads; they do not gain agent execution or publication authority.
The upload checks current grant, company, agent, task, work session and work mode. Publication also verifies stored filename, byte size and SHA-256. Normal Runner completion verifies that receipt against the upload and admitted assignment. A visible attachment without that verified publication does not satisfy a task that requires a file output.
Feedback and pending operations
An assignment wake starts a Grok routine. Once the Bot accepts that work, Paperclip keeps new comments and asynchronous operation receipts durable without starting another routine for that session. Silence does not mean the Bot is idle. Acceptance and the final webhook handoff are serialized. If acceptance finishes while credentials are loading, the unsent wake is cancelled. Stop and authenticated acknowledgements remain independent of a pending HTTP response. Human-question answers and resolved durable waits resume through normal Runner admission and a new assignment wake.
If a tool returns pending, poll paperclip_grok_operation_status with the same
assignment and request IDs for its durable outcome. Do not repeat it under a new
ID or perform dependent work first. An unknown outcome requires reconciliation. At safe boundaries and before finishing,
the Bot reads its inbox and current task history for queued feedback. Current
assignment reads include these instructions, including for existing connections.
Recovery and stop
Inspect a rejected delivery before using Retry rejected delivery. An uncertain outcome needs inspection and explicit recovery; it is never sent again automatically. Saved work remains on the task if execution fails. Reverify after clearing an inspected recovery hold before admitting another assignment.
Stop Paperclip work immediately revokes the session's Paperclip authority and stops future dispatch. Remote Grok execution may continue. Open the Grok Bot app to inspect it. Paperclip shows reported activity, not a complete remote transcript or computer recording.