mirror of
https://github.com/paperclipai/paperclip
synced 2026-04-25 17:25:15 +02:00
236d11d36f
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Heartbeat runs are the control-plane record of each agent execution window. > - Long-running local agents can exhaust context or stop while still holding useful next-step state. > - Operators need that stop reason, next action, and continuation path to be durable and visible. > - This pull request adds run liveness metadata, continuation summaries, and UI surfaces for issue run ledgers. > - The benefit is that interrupted or long-running work can resume with clearer context instead of losing the agent's last useful handoff. ## What Changed - Added heartbeat-run liveness fields, continuation attempt tracking, and an idempotent `0058` migration. - Added server services and tests for run liveness, continuation summaries, stop metadata, and activity backfill. - Wired local and HTTP adapters to surface continuation/liveness context through shared adapter utilities. - Added shared constants, validators, and heartbeat types for liveness continuation state. - Added issue-detail UI surfaces for continuation handoffs and the run ledger, with component tests. - Updated agent runtime docs, heartbeat protocol docs, prompt guidance, onboarding assets, and skills instructions to explain continuation behavior. - Addressed Greptile feedback by scoping document evidence by run, excluding system continuation-summary documents from liveness evidence, importing shared liveness types, surfacing hidden ledger run counts, documenting bounded retry behavior, and moving run-ledger liveness backfill off the request path. ## Verification - `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts server/src/__tests__/run-continuations.test.ts server/src/__tests__/run-liveness.test.ts server/src/__tests__/activity-service.test.ts server/src/__tests__/documents-service.test.ts server/src/__tests__/issue-continuation-summary.test.ts server/src/services/heartbeat-stop-metadata.test.ts ui/src/components/IssueRunLedger.test.tsx ui/src/components/IssueContinuationHandoff.test.tsx ui/src/components/IssueDocumentsSection.test.tsx` - `pnpm --filter @paperclipai/db build` - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts ui/src/components/IssueRunLedger.test.tsx` - `pnpm --filter @paperclipai/ui typecheck` - `pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts server/src/__tests__/run-continuations.test.ts ui/src/components/IssueRunLedger.test.tsx` - `pnpm exec vitest run server/src/__tests__/heartbeat-process-recovery.test.ts -t "treats a plan document update"` - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts server/src/__tests__/heartbeat-process-recovery.test.ts -t "activity service|treats a plan document update"` - Remote PR checks on head `e53b1a1d`: `verify`, `e2e`, `policy`, and Snyk all passed. - Confirmed `public-gh/master` is an ancestor of this branch after fetching `public-gh master`. - Confirmed `pnpm-lock.yaml` is not included in the branch diff. - Confirmed migration `0058_wealthy_starbolt.sql` is ordered after `0057` and uses `IF NOT EXISTS` guards for repeat application. - Greptile inline review threads are resolved. ## Risks - Medium risk: this touches heartbeat execution, liveness recovery, activity rendering, issue routes, shared contracts, docs, and UI. - Migration risk is mitigated by additive columns/indexes and idempotent guards. - Run-ledger liveness backfill is now asynchronous, so the first ledger response can briefly show historical missing liveness until the background backfill completes. - UI screenshot coverage is not included in this packaging pass; validation is currently through focused component tests. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5.4, local tool-use coding agent with terminal, git, GitHub connector, GitHub CLI, and Paperclip API access. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge Screenshot note: no before/after screenshots were captured in this PR packaging pass; the UI changes are covered by focused component tests listed above. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
126 lines
4.8 KiB
Markdown
126 lines
4.8 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,in_review,blocked
|
|
```
|
|
|
|
Results are sorted by priority. This is your inbox.
|
|
|
|
### Step 4: Pick Work
|
|
|
|
- Work on `in_progress` tasks first, then `in_review` when you were woken by a comment on it, 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", "in_review"] }
|
|
```
|
|
|
|
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. If the issue is actionable, take a concrete action in the same heartbeat. Do not stop at a plan unless the issue asked for planning.
|
|
|
|
Leave durable progress in comments, documents, or work products, and include the next action before exiting. For parallel or long delegated work, create child issues and let Paperclip wake the parent when they complete instead of polling agents, sessions, or processes.
|
|
|
|
### 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
|
|
- **Start actionable work** in the same heartbeat; planning-only exits are for planning tasks
|
|
- **Leave a clear next action** in durable issue context
|
|
- **Use child issues instead of polling** for long or parallel delegated work
|
|
- **Always set parentId** on subtasks
|
|
- **Never cancel cross-team tasks** — reassign to your manager
|
|
- **Escalate when stuck** — use your chain of command
|
|
|
|
## Run Liveness
|
|
|
|
Paperclip records run liveness as metadata on heartbeat runs. It is not an issue status and does not replace the issue status state machine.
|
|
|
|
- Issue status remains authoritative for workflow: `todo`, `in_progress`, `blocked`, `in_review`, `done`, and related states.
|
|
- Run liveness describes the latest run outcome: for example `completed`, `advanced`, `plan_only`, `empty_response`, `blocked`, `failed`, or `needs_followup`.
|
|
- Only `plan_only` and `empty_response` can enqueue bounded liveness continuation wakes.
|
|
- Continuations re-wake the same assigned agent on the same issue when the issue is still active and budget/execution policy allow it.
|
|
- `continuationAttempt` counts semantic liveness continuations for a source run chain. It is separate from process recovery, queued wake delivery, adapter session resume, and other operational retries.
|
|
- Liveness continuation wake prompts include the attempt, source run, liveness state, liveness reason, and the instruction for the next heartbeat.
|
|
- Continuations do not mark the issue `blocked` or `done`. If automatic continuations are exhausted, Paperclip leaves an audit comment so a human or manager can clarify, block, or assign follow-up work.
|
|
- Workspace provisioning alone is not treated as concrete task progress. Durable progress should appear as tool/action events, issue comments, document or work-product revisions, activity log entries, commits, or tests.
|