mirror of
https://github.com/paperclipai/paperclip
synced 2026-04-25 17:25:15 +02:00
a957394420
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Operators supervise that work through issues, comments, approvals, and the board UI. > - Some agent proposals need structured board/user decisions, not hidden markdown conventions or heavyweight governed approvals. > - Issue-thread interactions already provide a natural thread-native surface for proposed tasks and questions. > - This pull request extends that surface with request confirmations, richer interaction cards, and agent/plugin/MCP helpers. > - The benefit is that plan approvals and yes/no decisions become explicit, auditable, and resumable without losing the single-issue workflow. ## What Changed - Added persisted issue-thread interactions for suggested tasks, structured questions, and request confirmations. - Added board UI cards for interaction review, selection, question answers, and accept/reject confirmation flows. - Added MCP and plugin SDK helpers for creating interaction cards from agents/plugins. - Updated agent wake instructions, onboarding assets, Paperclip skill docs, and public docs to prefer structured confirmations for issue-scoped decisions. - Rebased the branch onto `public-gh/master` and renumbered branch migrations to `0063` and `0064`; the idempotency migration uses `ADD COLUMN IF NOT EXISTS` for old branch users. ## Verification - `git diff --check public-gh/master..HEAD` - `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts packages/mcp-server/src/tools.test.ts packages/shared/src/issue-thread-interactions.test.ts ui/src/lib/issue-thread-interactions.test.ts ui/src/lib/issue-chat-messages.test.ts ui/src/components/IssueThreadInteractionCard.test.tsx ui/src/components/IssueChatThread.test.tsx server/src/__tests__/issue-thread-interaction-routes.test.ts server/src/__tests__/issue-thread-interactions-service.test.ts server/src/services/issue-thread-interactions.test.ts` -> 9 files / 79 tests passed - `pnpm -r typecheck` -> passed, including `packages/db` migration numbering check ## Risks - Medium: this adds a new issue-thread interaction model across db/shared/server/ui/plugin surfaces. - Migration risk is reduced by placing this branch after current master migrations (`0063`, `0064`) and making the idempotency column add idempotent for users who applied the old branch numbering. - UI interaction behavior is covered by component tests, but this PR does not include browser screenshots. > 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-class coding agent runtime. Exact model ID and context window are not exposed in this Paperclip run; tool use and local shell/code execution were enabled. ## 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 - [ ] 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
129 lines
5.4 KiB
Markdown
129 lines
5.4 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.
|
|
|
|
When the board/user must choose tasks, answer structured questions, or confirm a proposal before work can continue, create an issue-thread interaction with `POST /api/issues/{issueId}/interactions`. Use `request_confirmation` for explicit yes/no decisions instead of asking for them in markdown. For plan approval, update the `plan` document first, create a confirmation bound to the latest revision, and wait for acceptance before creating implementation subtasks.
|
|
|
|
### 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
|
|
- **Use `request_confirmation`** for issue-scoped yes/no decisions and plan approval cards
|
|
- **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.
|