DottaandPaperclip
5a9e6b6315
## Thinking Path > - Paperclip lets people manage AI agents and their work. > - Grok Bot uses a managed Runner and a fixed external work session. > - Its admitted contract gives it no access to Paperclip workspace files. > - The Runner still has a sync descriptor to support durable recovery. > - Cancellation treated that descriptor as proof that files needed repair. > - This pull request uses the admitted access contract while preserving ownership settlement. > - Users get the correct recovery action after Stop, with native file safeguards intact. ## Linked Issues or Issue Description Refs #16219 and #16422. The duplicate search found no open Grok workspace correction. **What happened?** A real Grok Stop test cancelled its run, fenced its assignment, denied a stale progress update and cleaned up the sandbox. Paperclip also created a file-repair hold. The recovery panel told the user to recover workspace files, although the admitted external contract has workspace access set to none. **Expected behavior** Keep the stopped session fenced and require inspection before new work. Keep failed-run ownership settlement. Do not invent a file export obligation for a session that cannot access the workspace. Native sessions with writable or unknown workspace access must keep their file safeguards. **Steps to reproduce** 1. Connect a Grok Bot and assign a task. 2. Let it accept the task and save a Paperclip checkpoint document. 3. Use Stop while it is working. 4. Inspect the task recovery panel. It asks for file repair after sandbox cleanup succeeds. **Paperclip version or commit** Observed on Core11d69d04c7through the actual Grok client. Reproduced against master with database-backed regressions. ## What Changed - Match the admitted native input to its run, company, agent, task and external driver before treating workspace access as disabled. - Keep coordinator ownership checks and failure settlement. Skip file retention and the false file-repair obligation for that exact contract. - Add inspection-only settlement for old Grok file holds through Runtime recovery. Verify exact run ownership, fenced assignments, terminal coordinators and managed lease stop receipts. Archive the false file evidence and preserve no-replay. - Keep historical Dot recovery controls. Do not claim global external-provider termination. - Fix the later dispatch-failure owner so it cannot retain a no-workspace external sandbox for a false file obligation. - Cover both Grok and Dot, mismatched access evidence, native file recovery and the assembled heartbeat cleanup path. - Update the Grok guide and the existing release evidence plan. ## Verification - Four database regressions fail before the correction. - 68 file-recovery and cancellation checks pass. Grok, Dot and the shared recovery notice pass 98 checks. The assembled heartbeat selection passes both cases; 404 unrelated cases were not selected in that local command. - The lifecycle regression caught an unsafe early-return prototype. The final code keeps coordinator settlement for both workspace cases. A separate assertion was corrected for the run-state projection's explicit nulls. The failed attempts remain in the private evidence record. - Repository typecheck and build, token gates and Storybook build pass. The branch was rebased fromea4aa185b0onto7420af26fc, whose additional change affects CI profile exports. The core recovery checks are repeated after rebase. - On the earlier deployed source, a real 824-second task survived an actual same-image controller restart with its original run, assignment, process and lease. It completed canonically and cleaned up without an extra wake. The active Stop test denied a real stale update and completed connection inspection and authenticated re-verification. These results establish the observed baseline and defect; they do not qualify this patch's deployed behavior. - Review found two valid gaps: the old file obligation still blocked fresh input, and dispatch failure could request retention earlier. Both are corrected. The follow-up passes 128 focused tests and server typecheck. The recovery test proves fresh user continuation after inspection, authenticated re-verification, and managed Runner cleanup while the old assignment stays fenced. - A second review found a partial-transaction gap. Routine readiness now commits as invalid before task holds retire. All 43 Grok routine tests pass, including a held task lock and an unrelated active assignment. - Repository typecheck and build pass after the first review corrections; final server typecheck also passes. The full local suite is still running and is not claimed as passed. The first follow-up CI timed out at 15 seconds in one unchanged run-history case; all 91 cases pass locally. The cause is unproven. - The final head,33e4361911, passes 54 checks plus one successful status context. Two optional Storybook jobs are skipped. Greptile reviewed that exact head at 5/5 with no unresolved threads. All source CI suites pass on this final head without retry. The earlier runner-shutdown and timeout attempts remain recorded. - An actual deployed historical recovery and fresh Stop repeat are still required. ## Risks An incomplete or mismatched contract must retain file safeguards. The change uses stored admission evidence rather than current agent configuration. Historical records stay auditable and do not gain automatic replay or a generic Retry action. Operator inspection and a fresh authenticated verification remain required before new Grok work. Global Grok termination remains unconfirmed. No schema migration is needed. ## Model Used OpenAI GPT-6 in Codex, with reasoning, repository editing, shell tools and computer use. 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>
6.1 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. The originating conversation checks the same request while admission is queued. Neither immediate nor delayed Bot-initiated admission sends that assignment back through the routine. Grok keeps the request ID stable until admission succeeds or fails. Human-assigned work and continuations after an answered question still use their normal assignment wakes.
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.
The admitted Grok execution contract has no access to the Runner's workspace files. Its managed Runner still keeps durable recovery state, but stopping that session does not require workspace file repair. Inspect the Bot in Grok, clear the connection's recovery hold in the agent's Runtime settings, and verify the routine again before assigning new work. This records inspection without asserting global Grok termination.
Historical stopped Grok runs can have an incorrect workspace-file hold from an earlier release. Runtime shows Recovery needed for these runs even when the routine is healthy. After inspecting Grok, use Clear recovery hold and verify the connection again. Paperclip retires the false file obligation only when the original admission denied workspace access, the assignment is fenced, the coordinator has settled, and the exact managed Runner leases have stop receipts. Connection readiness is invalidated before task inspection, so a partial failure cannot retain an old verified connection while removing a task hold. The inspection preserves the old result, action uncertainty, and no-replay hold. Send a new task message to request fresh work. Inspection does not certify global Grok termination or delete any previously retained allocation. Such allocations still use the existing environment cleanup controls.