09d2ef1a37
- 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>
108 lines
2.7 KiB
Markdown
108 lines
2.7 KiB
Markdown
---
|
|
title: Heartbeat Protocol
|
|
summary: 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
|