When a Turn Must Survive the Process: The Durable AgentHarness
The current AgentHarness direction in Pi Agent Core addresses a boundary that an ordinary live agent loop cannot solve: what should the system do when the process disappears while a model request or tool effect is in flight? This chapter follows the durable harness from operation admission through lane state, recovery, and terminal settlement. The aim is to distinguish a recoverable record of intent from a volatile provider call, and to show what Pi can safely infer after a crash or cancellation.
The established Agent and AgentSession surfaces coordinate a live turn well. They keep messages, emit events, execute tools, and connect the result to a local session. But a live call stack is not a durable explanation of what the system intended to do. If a process stops between a tool request and its result, blindly starting the tool again could duplicate an external effect. If the system only keeps the last partial response, it may mistake visible text for evidence that the provider completed. The durable harness begins by recording enough intent to classify those cases.
A durable operation is admitted before it runs
The durable harness is built on the current v4 Session, SessionRepo, and storage contract rather than on the older coding-agent JSONL manager. Its main unit is a named lane. A lane has a branch tip, configuration, an inbox for queued messages or writes, an active operation when work is in progress, and a result record after that operation settles. The harness owns the lane objects, while the session owns the committed entries and values from which those objects can be restored.
An operation is first admitted. The request can be a prompt, a skill invocation, a prompt template, compaction, or tree navigation. Admission assigns an operation identifier, records the lane and source tip, captures the operation's intent, and stores the relevant configuration. Only then does a drive procedure begin the live work. This order changes the recovery question. After a process loss, the runtime does not need to guess whether a request was accepted from an incomplete stream; it can inspect the committed operation state and decide which procedure is allowed to continue.
The captured configuration includes the model identity, thinking level, active tool names, stream options, retry policy, compaction settings, queue modes, and tool-execution mode relevant to the operation. That snapshot prevents a later global change from silently rewriting an earlier operation. Suppose a user switches from a hosted model to a local model while a retry is waiting. The retry should not accidentally use the new model unless the operation's rules say so. Likewise, adding a tool to the current harness should not turn a previously admitted operation into a different capability set.
The durable state is a flat union of operation leaves. It can represent an operation that is starting, waiting at a checkpoint, ready to request an assistant response, waiting for a retry, holding an effect-pending assistant request, executing a tool batch, waiting on deferred work, generating a structural summary, waiting to commit navigation, or ready to finish. Cancellation is orthogonal control state: an operation can be marked as cancel-requested while the harness still has to settle effects that were already admitted.
The driver dispatches based on that persisted state. A checkpoint procedure prepares the next step. An assistant-generation procedure resolves the captured model, tools, context, and system prompt, then records the provider intent before making the request. A tool procedure converts the assistant's call into a durable tool plan, executes the allowed effect, and commits its outcome. Structural procedures handle compaction or branch summaries. Retry and recovery procedures advance the operation without requiring the original in-memory call stack.