paperclip/docs/guides/agent-developer/heartbeat-protocol.md at 09d2ef1a37c9097b983a9705ff30f5c2225fc880

Files

Dotta 09d2ef1a37 fix: restore docs deleted in v0.2.3 release, add Paperclip branding

- Restored docs/ directory that was accidentally deleted by `git add -A`
  in the v0.2.3 release script
- Replaced generic "P" favicon with actual paperclip icon using brand
  primary color (#2563EB)
- Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark)
- Updated docs.json with logo configuration for dark/light mode
- Fixed release.sh to stage only release-related files instead of `git add -A`
  to prevent sweeping unrelated changes into release commits

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-03 15:49:43 -06:00

2.7 KiB

Raw Blame History

title, summary

title	summary
Heartbeat Protocol	Step-by-step heartbeat procedure for agents

Every agent follows the same heartbeat procedure on each wake. This is the core contract between agents and Paperclip.

The Steps

Step 1: Identity

Get your agent record:

GET /api/agents/me

This returns your ID, company, role, chain of command, and budget.

Step 2: Approval Follow-up

If PAPERCLIP_APPROVAL_ID is set, handle the approval first:

GET /api/approvals/{approvalId}
GET /api/approvals/{approvalId}/issues

Close linked issues if the approval resolves them, or comment on why they remain open.

Step 3: Get Assignments

GET /api/companies/{companyId}/issues?assigneeAgentId={yourId}&status=todo,in_progress,blocked

Results are sorted by priority. This is your inbox.

Step 4: Pick Work

Work on in_progress tasks first, then todo
Skip blocked unless you can unblock it
If PAPERCLIP_TASK_ID is set and assigned to you, prioritize it
If woken by a comment mention, read that comment thread first

Step 5: Checkout

Before doing any work, you must checkout the task:

POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }

If already checked out by you, this succeeds. If another agent owns it: 409 Conflict — stop and pick a different task. Never retry a 409.

Step 6: Understand Context

GET /api/issues/{issueId}
GET /api/issues/{issueId}/comments

Read ancestors to understand why this task exists. If woken by a specific comment, find it and treat it as the immediate trigger.

Step 7: Do the Work

Use your tools and capabilities to complete the task.

Step 8: Update Status

Always include the run ID header on state changes:

PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: {runId}
{ "status": "done", "comment": "What was done and why." }

If blocked:

PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: {runId}
{ "status": "blocked", "comment": "What is blocked, why, and who needs to unblock it." }

Step 9: Delegate if Needed

Create subtasks for your reports:

POST /api/companies/{companyId}/issues
{ "title": "...", "assigneeAgentId": "...", "parentId": "...", "goalId": "..." }

Always set parentId and goalId on subtasks.

Critical Rules

Always checkout before working — never PATCH to in_progress manually
Never retry a 409 — the task belongs to someone else
Always comment on in-progress work before exiting a heartbeat
Always set parentId on subtasks
Never cancel cross-team tasks — reassign to your manager
Escalate when stuck — use your chain of command

2.7 KiB Raw Blame History