From a company task to a heartbeat run
Paperclip's next problem is the handoff from organizational work to external execution. This chapter follows that handoff through the adapter boundary and the heartbeat lifecycle, so the reader can tell which decisions Paperclip owns before a provider starts, what a normal run records, and why a heartbeat ends even when an agent keeps a provider session.
The distinction matters because “the agent is working” can describe several different things. It might mean that Paperclip has admitted a task, that a provider process is currently running, that a remote service has received a request, or that a previous session can be resumed. Those are related states, but they are not interchangeable. Paperclip's control plane needs a lifecycle that makes the relationships explicit without pretending to own the agent's internal reasoning.
The adapter is a boundary, not a second organization
An adapter is the component that translates Paperclip's control-plane request into a runtime-specific invocation. The smallest useful contract is intentionally modest: start an agent cycle, report whether it is running or finished, and support a graceful stop when the control plane needs to pause or cancel it. Paperclip's current adapter interface is richer than that minimum. It can carry run-scoped context, session state, cancellation signals, logging callbacks, runtime events, usage, cost, and a structured result. But those additions are capabilities around the core boundary, not a requirement that every provider expose the same internal model.
This is what lets different execution styles participate. A process adapter can start a command in a working directory. An HTTP adapter can send a request to an already-running agent. A local coding-tool adapter can start or resume a provider session. A gateway-style integration can notify an external agent. Plugin-backed adapters can add another runtime without hard-coding every provider into the central server. From Paperclip's perspective, these are different ways of crossing the same boundary: an authorized run is turned into provider work, and the provider returns enough information for the control plane to update its records.
The boundary has two owners. The adapter owns provider-specific identity and behavior: how a command is assembled, which endpoint is called, how a session is resumed, and which provider conventions apply. Paperclip owns the company, agent, task, run, policy, and attribution context around that invocation. The adapter does not decide which company a run belongs to, silently substitute a different agent, or turn a provider response into an unreviewed change to the organizational model.
That division is more important than the number of supported adapters. If every provider required its own company model, Paperclip would become a collection of unrelated integrations. If Paperclip tried to dictate every provider's internal loop, it would lose the ability to coordinate runtimes that behave differently. The adapter boundary keeps the shared contract small enough for variety while leaving the organization in one place.
What crosses the boundary
The handoff is not a transfer of the entire company database to an agent. Paperclip constructs a run-scoped execution context. It identifies the run and agent, supplies the relevant runtime and task context, exposes the session state that the adapter is allowed to use, and provides control paths for cancellation, logging, and runtime events. The adapter then turns that context into the provider-specific command, request, or session operation. This shaped handoff is what allows Paperclip to preserve a common authority model while changing the transport.
The return path is shaped as well. A provider does not directly rewrite Paperclip's company or task model simply because it sent a response. The adapter returns an execution result that the server can persist and interpret: an exit code or signal where those exist, timeout and error information, usage, cost, session parameters, and structured result data. A local process may supply detailed output and a process identifier. An HTTP adapter may supply a response and a provider-defined result. The control plane can record both, but it should not pretend that the second response proves what happened after the remote endpoint accepted the request.
Cancellation illustrates why ownership must remain explicit. Paperclip can send a run-scoped cancellation signal or invoke the adapter's stop path, but stopping a provider is a lifecycle operation, not deletion of a row. The adapter must settle the provider-side operation before returning, and the server must then record the resulting cancelled, interrupted, failed, or otherwise terminal state. That sequence gives an operator a meaningful answer to “what happened when I stopped it?” instead of replacing a live external process with a misleading database status.
This boundary also limits what can be normalized. Paperclip can normalize who initiated a run, which task it belongs to, when it started, and what result the adapter reported. It cannot normalize the meaning of every provider's session identifier, usage counter, refusal, or partial output. Those details remain attached to the adapter's evidence and should be interpreted with the adapter's own guarantees.
Three levels of integration
Not every agent can report the same amount of information. Paperclip's specification distinguishes a minimum callable integration from progressively richer ones. At the minimum, Paperclip can start an agent. A more integrated runtime reports success, failure, or in-progress state. A fully instrumented runtime can also report task updates, token usage, logs, and other execution details.
That progression prevents a useful abstraction from becoming a false promise. A callable HTTP endpoint may accept a request and return a response without exposing the provider's internal steps. A local session adapter may provide session identifiers and cumulative usage. A richer adapter may stream events and structured output. Paperclip can coordinate all three, but the quality of its visibility depends on what crosses the adapter boundary.
This also explains why adapter configuration is part of the agent's identity. The same organizational role can behave differently depending on its adapter type and configuration. Changing the adapter is not necessarily a cosmetic provider choice; it can change how work is invoked, what state can be observed, how cancellation works, and what evidence is available. The server therefore treats the selected adapter as a claimed execution identity and rejects a mismatch between a run's recorded adapter and the agent configuration that is used to dispatch it.
The practical rule is simple: Paperclip can standardize the control questions, not every provider answer. It can ask whether a run was admitted, who owns it, when it started, and what result was recorded. It cannot require a remote agent to reveal internal reasoning that the adapter never exposes.
The heartbeat lifecycle
A heartbeat is a finite execution cycle. A task assignment, timer, mention, or other event makes work eligible; Paperclip creates or admits a queued run; the run is claimed; the server prepares the context; an adapter invokes the external agent; events and usage are recorded; and the run reaches a terminal result. The provider may preserve a session for a later cycle, but the Paperclip run itself has a beginning and an end.
The sequence is easier to understand if each transition has a different purpose.
Admission creates an accountable attempt. The control plane does not treat a request to wake an agent as proof that execution has begun. It records enough information to identify the company, agent, source, and context of the requested work. The run can remain queued while Paperclip checks whether the work is eligible and whether another execution path already exists.
Claiming establishes ownership of execution. A queued run is moved into active execution through a guarded state change. This is where Paperclip turns an intention to run into an execution attempt that the rest of the system can observe. Claiming is distinct from invoking the provider: a run can be admitted or claimed before the external process has completed, and a failure in the next step must remain visible as a failure of that attempt.
Preparation assembles the control-plane context. Before dispatch, Paperclip validates the current agent and the claimed adapter identity. It resolves the task context and prepares the workspace, secrets, skills, and applicable policy information for the run. These are not details owned by the provider. They are the conditions under which the provider is allowed to work. A run that cannot satisfy them should fail or be blocked rather than silently changing its execution target.
Invocation crosses the adapter boundary. The adapter receives a run-scoped execution context. That context can include the task, session information, cancellation signal, logging and event callbacks, and the runtime-specific configuration. A process-backed adapter may start a local child process; an HTTP-style adapter may perform a remote request. The control plane waits for the adapter's execution result while receiving whatever logs, events, usage, or progress the adapter is able to report.
Finalization turns provider output into durable run state. The adapter returns an execution result that can include an exit status, signal, timeout, error information, usage, cost, session state, and structured result data. Paperclip records the result and terminal timestamps, publishes the corresponding status to its observers, and releases or updates the surrounding execution state. A successful provider return is evidence about the run's outcome; it is not automatically proof that the task was strategically correct or that every external side effect was desirable.
The normal path in one sequence
The diagram leaves out many provider-specific details on purpose. It shows the authority boundary: Paperclip owns the durable run state; the adapter owns the translation to provider work; the provider owns the actual agent cycle. The arrows also explain why a run can be observable without being transparent. Paperclip may receive an event stream or only a final response, depending on the adapter's integration level.
What persists when the run ends
The heartbeat record is more than a start and stop timestamp. It carries company and agent ownership, invocation source, status, responsibility, context, start and finish times, error and result data, usage, session identifiers, runtime information, retry ancestry, liveness information, and log references. These fields let the control plane distinguish a queued attempt from a running attempt and a terminal result from a missing or interrupted execution.
Persistence also changes how a provider session should be understood. A provider may return session parameters that let a later run continue a conversation or task. Paperclip can preserve that session information while still closing the current heartbeat. The durable unit is the run and its recorded context; provider continuity is an additional capability that belongs to the adapter and runtime.
This separation helps with restarts. If the server process stops, the company does not have to infer all history from whether a child process still exists in memory. The run record can say that work was queued, started, failed, or completed, and the surrounding control services can decide whether another action is eligible. That does not mean every interrupted provider session can be resumed. It means the control plane has a durable object from which to make the next decision.
The same distinction prevents a misleading success signal. A process can exit with code zero while producing no useful work. An HTTP request can return successfully while the remote agent has only accepted a job. A provider can preserve a session while the current task remains unfinished. Paperclip can record these outcomes and apply its execution policies, but the adapter's result and the task's actual completion are not identical concepts.
What the boundary cannot guarantee
The adapter design makes execution replaceable, not execution infallible. A provider may be unavailable, credentials may be missing, a workspace may not be usable, or the runtime may expose too little information to support rich monitoring. A callable adapter can be enough to start work but not enough to report detailed cost or progress. A session-aware adapter can resume context but still return an incorrect answer. The control plane can preserve the distinction and surface the failure; it cannot supply evidence that the provider never produced.
This is also why Paperclip's “any agent” language has a condition attached to it. An agent must be callable, and useful coordination requires some degree of observation and authorization. The richer the integration, the more precisely Paperclip can connect provider activity to tasks, costs, and decisions. The poorer the integration, the more the organization must treat the run as a bounded external operation with limited visibility.
The finite heartbeat model is therefore a deliberate compromise. It gives Paperclip a stable unit for admission, attribution, cancellation, result recording, and later recovery. It does not force every provider to become a resident worker inside the server. The organization gets a durable execution boundary while the agent remains free to use its own runtime and session model.
The next question is what happens when that boundary is stressed: when two executions want the same task, when a queued request arrives during active work, or when a run ends without a clear path forward. To answer that, the normal lifecycle must be connected to the different kinds of state that Paperclip retains.