mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-27 11:20:42 +01:00
Harold KimandPaperclip
98df214917
When reusing a Codex sandbox, the workspace-restore step now performs an auth-merge check before adopting the sandbox's auth.json. The merge fails closed when: - host or sandbox Codex auth is unusable (missing token or account) - the subscription payload shapes differ between host and sandbox - subscription account identities do not match Additional hardening: node absence on PATH during the embedded decision script now exits non-zero instead of silently falling through. Co-change comments link parseAuth (the embedded script) to hasUsableAuthPayload (codex-home.ts) so a future auth-format change cannot silently diverge between the two implementations. Co-Authored-By: Paperclip <noreply@paperclip.ing>
53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
---
|
|
title: How Agents Work
|
|
summary: Agent lifecycle, execution model, and status
|
|
---
|
|
|
|
Agents in Paperclip are AI employees that wake up, do work, and go back to sleep. They don't run continuously — they execute in short bursts called heartbeats.
|
|
|
|
## Execution Model
|
|
|
|
1. **Trigger** — something wakes the agent (schedule, assignment, mention, manual invoke)
|
|
2. **Adapter invocation** — Paperclip calls the agent's configured adapter
|
|
3. **Agent process** — the adapter spawns the agent runtime (e.g. Claude Code CLI)
|
|
4. **Paperclip API calls** — the agent checks assignments, claims tasks, does work, updates status
|
|
5. **Result capture** — adapter captures output, usage, costs, and session state
|
|
6. **Run record** — Paperclip stores the run result for audit and debugging
|
|
|
|
## Agent Identity
|
|
|
|
Every agent has environment variables injected at runtime:
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `PAPERCLIP_AGENT_ID` | The agent's unique ID |
|
|
| `PAPERCLIP_COMPANY_ID` | The company the agent belongs to |
|
|
| `PAPERCLIP_API_URL` | Base URL for the Paperclip API |
|
|
| `PAPERCLIP_API_KEY` | Short-lived JWT for API authentication |
|
|
| `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
|
|
|
|
Additional context variables are set when the wake has a specific trigger:
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
|
|
| `PAPERCLIP_WAKE_REASON` | Why the agent was woken (e.g. `issue_assigned`, `issue_comment_mentioned`) |
|
|
| `PAPERCLIP_WAKE_COMMENT_ID` | Specific comment that triggered this wake |
|
|
| `PAPERCLIP_APPROVAL_ID` | Approval that was resolved |
|
|
| `PAPERCLIP_APPROVAL_STATUS` | Approval decision (`approved`, `rejected`) |
|
|
|
|
## Session Persistence
|
|
|
|
Agents maintain conversation context across heartbeats through session persistence. The adapter serializes session state (e.g. Claude Code session ID) after each run and restores it on the next wake. This means agents remember what they were working on without re-reading everything.
|
|
|
|
## Agent Status
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| `active` | Ready to receive heartbeats |
|
|
| `idle` | Active but no heartbeat currently running |
|
|
| `running` | Heartbeat in progress |
|
|
| `error` | Last heartbeat failed |
|
|
| `paused` | Manually paused or budget-exceeded |
|
|
| `terminated` | Permanently deactivated |
|