Automation and control
Paperclip turns schedules, external events, task changes, and human choices into controlled agent work. It keeps each request durable, checks whether work may start, runs the work with the right task context, and sends unfinished or blocked work to a safe next step.
Coordination model
Paperclip separates a request to consider work from the agent attempt that performs it. A wake is the durable request. A heartbeat run is one recorded attempt. This split lets the system delay, merge, retry, or recover work without losing why it started.
| Signal or condition | Control path | Result |
|---|---|---|
| Time or external event | Timer, monitor, webhook, or routine | Durable wake |
| Queued wake | Admission and dispatch checks | Run, wait, or visible refusal |
| Run outcome | Completion and continuation | Task result, retry, or attention item |
| Human choice | Decision or approval | Controlled continuation or hold |
| Restart or lost delivery | Recovery workers | Reconciliation without duplicate work |
This diagram shows how a signal becomes an admitted run and then a result or another control step.
flowchart TD
S[Time, event, task change, or human choice] --> W[Durable wake]
W --> A{Admission checks}
A -->|Hold or refuse| H[Queued or visible attention]
A -->|Allow| R[Heartbeat run]
R --> X[Build context and run agent work]
X --> O[Record outcome]
O --> N{Next control step}
N -->|Continue| W
N -->|Retry or recover| Q[Scheduled recovery]
N -->|Decision or approval| D[Human choice]
N -->|Complete| C[Task or stage result]
Q --> W
D --> W
Durable work requests
A durable wake preserves the request until the system settles it. Repeated signals can reuse an existing request, while missed notifications can be rebuilt from stored work. Scheduling suppression therefore delays new starts without deleting due work.
The queue carries both ordinary work and recovery work through the same admission boundary. It checks task state, dependencies, agent readiness, limits, workspace use, interaction authority, and service state before provider work starts.
References: server/…/queue.ts• L403-428 server/…/queue.ts• L1017-1090 server/…/run-state.ts• L1133-1149
Dispatch order
Dispatch order controls which ready work starts when an agent has limited capacity. Work requested by a person comes first. Ordinary work follows. System recovery receives a bounded share, and aged work receives a bounded oldest-run share so it cannot wait forever.
The order also carries person origin through retries and continuation chains. A task created by a person keeps that priority even when a later wake performs the work. The Board's queue position uses the same ordering facts as dispatch, so the visible line matches the starts the server will make.
References: server/…/queued-run-dispatch-order.ts• L40-84 server/…/queued-run-dispatch-order.ts• L97-113 server/…/queued-run-dispatch-order.ts• L191-220 server/…/queued-run-line.ts• L116-120 server/…/queued-run-line.ts• L122-219
Run provenance
Run provenance records where a continuation came from and why it exists. This lets dispatch distinguish a person-requested continuation from system recovery and lets clean continuations avoid consuming the same recovery share.
The provenance rule is narrow. A continuation must have the expected wake reason and source marker, and it must not also look like a retry or another inherited continuation. This prevents a recovery classification from spreading through unrelated run chains.
References: server/…/queued-run-provenance.ts• L9-35 server/…/queued-run-line.ts• L42-67 server/…/queued-run-line.ts• L151-199
Scheduling and recurring work
Scheduling creates regular agent turns and event-driven follow-up work. A due schedule only asks the system to consider work; current admission rules still decide whether it may start.
Timer and monitor cycles
Agent timers create regular turns for agents that can act and have an enabled heartbeat policy. Issue monitors inspect active or review work at planned times, then wake the relevant participant for the next check. Claims guard the expected schedule state so overlapping schedulers do not duplicate a timer or overwrite newer task state.
Recurring schedules and composed stages are described in Routines and pipelines. That page covers routine configuration, webhooks, catch-up behavior, and stage flow.
References: server/…/queue.ts• L403-428 server/…/task-context.ts• L430-435 server/…/run-state.ts• L780-831
Retry and continuation lanes
Retries preserve the task scope and link the successor to the prior run. The system chooses a bounded lane based on the cause: a normal transient failure, a server restart, an interrupted preparation, a provider wait, or another controlled continuation.
Each lane has a limit and a due time. The first continuation can start at once when no provider work began. Later attempts wait longer when needed. When the limit ends, the system records exhaustion and routes the work to recovery or attention rather than retrying without bound.
Provider allowance waits hold ordinary new work until the reported reset time. Manual work, recovery, conversation turns, and account routing can still proceed when their path has authority to test or repair the provider.
References: server/…/retries.ts• L148-202 server/…/retries.ts• L433-470 server/…/retries.ts• L500-721 server/…/provider-limit-wait.ts• L26-60 server/…/provider-limit-wait.ts• L61-113
Run lifecycle
The run lifecycle gives each agent attempt a stable task boundary. Paperclip rebuilds the task view, prepares the execution target, runs the agent, records the outcome, and releases task ownership before another valid continuation can proceed.
Task context
Task context is the server-owned view given to the agent. It combines the current task, parent context, wake comments, continuation history, plan or review state, and the authority that requested the work.
The service rebuilds this view on each wake. It keeps user-authored task content separate from trusted control data, preserves admitted choices during recovery, and adds guidance for questions, plans, approvals, routines, automation conversations, and status work when those paths apply.
References: server/…/task-context.ts• L59-123 server/…/task-context.ts• L142-185 server/…/task-context.ts• L265-409 server/…/task-markdown.ts• L152-157 server/…/task-markdown.ts• L228-261
Execution boundary
The execution boundary turns admitted task state into provider work. It delivers the run's selected tools, runtime access, workspace, identity, and task context only after the run passes its admission checks.
Provider dispatch remains separate from preparation. If a permission, interaction, or control check changes before dispatch, the run can stop without claiming that provider work began. Once dispatch starts, runtime events, usage, progress, and cleanup contribute to the durable run outcome.
References: server/…/runtime-execution.ts• L122-225 server/…/runtime-execution.ts• L249-269 server/…/runtime-execution.ts• L540-559 server/…/runtime-execution.ts• L658-810 server/…/runtime-execution.ts• L893-982
Session continuity
Session continuity decides whether a later turn can reuse the prior agent session. A stable task key lets issue-scoped work continue in the same task session, while an unscoped timer wake uses a separate heartbeat identity and starts fresh to avoid accumulating unrelated inbox work.
An explicit fresh-session request or a change to the task's execution conditions can reset the session. This keeps conversational continuity useful without allowing a changed execution boundary to reuse an incompatible session.
References: server/…/run-state.ts• L780-831 server/…/run-state.ts• L928-1087 server/…/runtime-execution.ts• L607-714
Run outcomes
Run state records whether work succeeded, failed, was cancelled, was interrupted, or timed out. It also keeps enough result, usage, session, and liveness data for the Board and recovery workers to explain what happened.
Agent status returns to an idle or error state only after its runs and related cleanup settle. A reconciliation pass repairs a stale running status when no unsettled execution remains, so a lost delivery does not leave the agent shown as active forever.
References: server/…/run-state.ts• L69-125 server/…/run-state.ts• L208-338 server/…/agent-status.ts• L43-76 server/…/agent-status.ts• L87-124 server/…/agent-status.ts• L126-202
Recovery and attention
Recovery handles work left by provider failure, server replacement, lost delivery, temporary infrastructure limits, or incomplete cleanup. The system prefers a durable hold and a clear operator signal over an unverified continuation.
Infrastructure waits
Infrastructure waits keep a run visible when the provider, workspace, storage, or another required service cannot safely support execution. The run records the wait cause and a bounded next check instead of presenting the outage as a task failure.
Provider-limit waits are one example. The run is settled before the retry is scheduled, and the provider identity and reset evidence remain attached to the next check. If scheduling the check fails, the task lock is released rather than leaving hidden work behind.
References: server/…/provider-limit-wait.ts• L34-60 server/…/provider-limit-wait.ts• L61-113 server/…/retries.ts• L723-843
Configuration holds
Configuration holds surface missing or unsafe run prerequisites before provider work starts. The hold can identify missing bindings, credentials, or required scoped settings and gives an owner a clear repair path.
This boundary keeps a configuration problem separate from a provider failure. It also applies trust rules to low-trust task input and prevents that input from supplying protected runtime credentials or control values.
References: server/…/run-preparation.ts• L151-165 server/…/run-preparation.ts• L315-403 server/…/run-preparation.ts• L404-481 server/…/task-context.ts• L108-116
Human decisions and attention
A decision is a structured request for a human choice. An approval is a governance gate around a controlled request. The attention view gathers work that needs a choice, review, repair, or explicit next step.
Human actions can approve, reject, request changes, dismiss, or snooze the visible item. The answer creates a continuation wake that returns through normal admission. If accepted work cannot resume, bounded retry records the failure and keeps the task in attention instead of hiding the incomplete continuation.
See Decisions, approvals, and attention for the full decision lifecycle, approval paths, and attention behavior.
References: server/…/task-markdown.ts• L293-364 server/…/task-context.ts• L379-408 server/…/queue.ts• L295-315 server/…/retries.ts• L634-669
Change checklist
When these files or sections are changed, remember to consider these:
- Queue ordering changes must keep person origin, task-tree origin, recovery shares, oldest-run aging, readiness, and the Board's visible line aligned.
- New continuation causes must define their provenance, retry lane, idempotency rule, task-state gate, and attention path.
- Provider or infrastructure waits must settle the current run before scheduling the next check and preserve the resource identity through the wait.
- Admission changes must keep pre-dispatch refusal distinct from provider execution and must not consume user input when a run is cancelled before start.
- Context changes must preserve the separation between task content, trusted control state, wake comments, interaction answers, and recovery snapshots.
- Session changes must keep timer task identity, issue task identity, explicit fresh-session requests, and resume state consistent.
- Runtime changes must keep the dispatch-start proof, result recording, usage capture, cleanup work, and agent status settlement in agreement.
- Configuration changes must keep missing prerequisites visible as operator holds and must not allow low-trust input to provide protected credentials or control values.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A person-created task continuation loses its origin | Work a person is waiting on can wait behind newer work | Preserve person origin through source and retry chains and task ancestry |
| Recovery work consumes every available start | Failed or repair work can block ordinary progress, or ordinary work can starve recovery | Use bounded shares for recovery and oldest waiting work |
| The queue line uses different facts from dispatch | The Board shows a position that does not match the next start | Build both views from the same dispatch facts and counters |
| A retry is created after task ownership or status changes | A successor can act on stale or invalid task state | Lock and validate the task before creating the successor |
| Provider allowance is exhausted before a new run starts | Repeated runs fail until the same provider limit is hit again | Record a provider wait and retry after the reported reset |
| A retry is scheduled without proving whether provider work began | Automatic retry can duplicate unknown work | Keep pre-dispatch evidence and use an explicit path for unresolved outcomes |
| A run is cancelled before dispatch but its user message is consumed | The user's request disappears while the task remains incomplete | Release the message receipt so normal delivery can try again |
| A task context mixes user content with control data | Task text can bypass authority, safety, or approval rules | Rebuild trusted context on the server and isolate low-trust content |
| Required runtime configuration is missing | A setup problem appears as an opaque provider failure | Stop before dispatch and create a visible configuration hold |
| A stale agent remains marked as running after execution settles | The Board shows work that no longer exists | Reconcile running agents only when no unsettled execution remains |
| An accepted decision cannot resume its work | The choice appears complete while the task remains unfinished | Bound continuation retries and route exhaustion to attention |
Key files
| File | Why to read it |
|---|---|
| server/…/queue.ts | Connects wake admission, queue dispatch, suppression, task checks, and continuation handling. |
| server/…/queued-run-dispatch-order.ts | Defines the high-level fairness rules for person work, ordinary work, recovery, and aged runs. |
| server/…/queued-run-line.ts | Builds the dispatch facts used for both actual starts and the visible queue position. |
| server/…/queued-run-provenance.ts | Identifies clean continuations and the context fields that affect queue order. |
| server/…/retries.ts | Defines bounded retry lanes, successor creation, infrastructure waits, and retry exhaustion. |
| server/…/provider-limit-wait.ts | Shows how provider allowance limits become durable waits instead of repeated failures. |
| server/…/task-context.ts | Rebuilds the server-owned task view for each wake and continuation. |
| server/…/task-markdown.ts | Shows the high-level guidance delivered for tasks, questions, plans, approvals, and automation conversations. |
| server/…/run-preparation.ts | Defines the pre-dispatch configuration and trust boundary for runtime work. |
| server/…/runtime-execution.ts | Shows the boundary between prepared work, provider dispatch, result capture, and cleanup. |
| server/…/run-state.ts | Defines run retrieval, result presentation, usage state, and session continuity. |
| server/…/agent-status.ts | Shows how settled work updates agent status and repairs stranded running states. |