PaperClipAI/doc/grok-bot-agent.md

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.

New assignments remain in the durable queue while the Grok connection is unverified, revoked, or held for recovery. Readiness is checked before claiming a new run or allocating its Runner. Already-admitted session reconciliation keeps its recorded authority; it does not gain permission to start new work. A configured AI connection pool selects its own provider. Its native tasks use the pool's normal admission checks and do not require an unused Grok connection.

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.