Agent Runtime Guide

Paperclip does not run agents as permanently active daemons. It runs them in bounded execution windows called heartbeats. This guide explains the runtime contract between the control plane, the adapter, and the agent process.

​

Runtime Model

The runtime layer exists to do five things reliably:

• wake an agent when work or policy requires it
• start the configured adapter with the right context
• preserve session continuity when the adapter supports it
• capture run evidence, logs, and usage
• publish durable state back to the board-facing control plane

The control plane owns work selection, checkout semantics, policy, and persistence. The agent owns the work performed inside the heartbeat window.

​

Wake Sources

An agent can be woken in four primary ways:

• timer for scheduled periodic execution
• assignment when work is assigned or checked out to the agent
• on_demand for manual invocation from the UI or API
• automation for system-triggered wakeups tied to routines or future scheduler behavior

If an agent is already active, new wakeups are coalesced instead of launching duplicate runs. Wake source is a runtime policy input, not just a log field.

​

Adapter Layer

Built-in adapter types include:

• claude_local
• codex_local
• opencode_local
• hermes_local
• cursor
• pi_local
• openclaw_gateway
• process
• http

Adapters are execution backends only. They do not own task assignment, budgets, approvals, or run history.

​

Local adapter assumptions

For local CLI adapters (claude_local, codex_local, opencode_local, hermes_local):

• the CLI must already be installed on the host
• the CLI must already be authenticated on the host
• the configured working directory must exist and be accessible

For opencode_local, adapterConfig.model must be a valid provider/model string returned by opencode models.

​

What To Configure Per Agent

​

Runtime policy

Runtime settings control when the agent is allowed to run:

• enabled
• intervalSec
• wakeOnAssignment
• wakeOnOnDemand
• wakeOnAutomation

​

Execution limits

For local adapters, configure:

• cwd
• timeoutSec
• graceSec
• environment variables and extra adapter args when required

Use the environment test flow in agent configuration before saving a new runtime.

​

Prompt and instruction surface

Set:

• promptTemplate for the recurring run prompt shape

Use managed instruction bundles when possible. bootstrapPromptTemplate is legacy and should not be the default for new agents.

​

Heartbeat Lifecycle

Each heartbeat follows the same shape:

1. create or reuse a runtime session
2. launch the adapter
3. present the current prompt and context
4. let the agent inspect assignments and approvals
5. attempt checkout of one unit of work
6. capture stdout, stderr, usage, and structured results
7. persist run status, events, and evidence
8. update live board-facing state

​

Session Continuity

Paperclip stores session IDs for resumable adapters.

• The next heartbeat reuses the saved session automatically.
• Session reuse gives continuity across multiple bounded heartbeats.
• Reset the session when prompt strategy changes materially or the runtime drifts into a bad loop.

Use session reset when:

• context is stale or confused
• prompt strategy changed significantly
• the agent repeats the same failed loop

​

Runtime Data Model

The runtime substrate is split across canonical tables and heavier evidence stores. The run row is the summary. The event stream, artifact tables, and log store hold the detailed evidence. For the broader schema around runtime, evaluation, and memory, see Data Model. For the route and service owner map, see Schema Map.

​

Live UI Behavior

Paperclip pushes runtime and activity updates back into the browser. Operators should see live changes for:

• agent status
• heartbeat run status
• task and activity updates caused by the run
• dashboard and control-room summaries

If the browser connection drops, the client reconnects automatically and backfills state from the persisted run model.

​

Common Operating Patterns

​

Simple autonomous loop

1. enable timer wakeups
2. keep assignment wakeups enabled
3. use a focused prompt template
4. review logs and adjust prompt/config over time

​

Event-driven loop

1. disable timer or make it infrequent
2. keep wake-on-assignment enabled
3. use manual invoke for operator nudges

​

Safety-first loop

1. use short timeouts
2. keep the prompt conservative
3. monitor repeated errors closely
4. reset sessions when drift appears

​

Control-plane-aware loop

1. treat wake source as policy context, not trivia
2. prefer one checkout at a time
3. treat 409 Conflict as a handoff signal
4. leave comments before exit so the next run inherits durable context
5. use work evidence, not raw success counts, when deciding a task is done

​

Failure Modes

Typical failures include:

• CLI not installed or not authenticated
• invalid working directory
• malformed adapter config
• timeout too low for the workload
• prompt too broad or underspecified
• stale resumable session

Runtime-specific notes:

• If a local adapter reports No API key available for Paperclip authentication, the host is missing PAPERCLIP_AGENT_JWT_SECRET, so Paperclip cannot mint the short-lived PAPERCLIP_API_KEY.
• If opencode_local fails with Request contains an invalid argument, validate adapterConfig.model against opencode models.
• If runs keep coalescing or skipping unexpectedly, check whether an earlier run is still marked active.

​

Security Notes

Local CLI adapters run unsandboxed on the host machine. That means:

• prompt instructions matter
• environment variables are sensitive
• working-directory permissions matter
• host credentials should be scoped tightly

Use least privilege where possible and keep broad reusable prompts free of secrets unless a secret is intentionally required for the job.

​

Minimal Runtime Checklist

1. choose an adapter
2. set the working directory
3. configure prompt or instruction bundle
4. set heartbeat policy
5. invoke a manual heartbeat
6. verify run success, usage capture, and live updates
7. iterate on prompt, timeout, and session policy

​

Responsibility Split