The Evolution of Harness Through the Lens of Pi Durable

In common Harness architectures (such as pi coding agent), memory, brain, and hands are all crammed into the same Node.js process, with a strong dependency on a VM.

Pi Durable changes this design.

Starting with Durable, this article breaks down the evolution of Harness: what Durable solves, what else has changed in pi beyond Durable, and finally, an attempt to design a scalable, long-running Harness architecture and examine its impact on our business.

First, Break Down Harness

Harness is a complex concept, often defined simply as “everything outside the model.” This definition is crude and says nothing useful.

In the context of Pi, let’s break it down further:

• Persistence system: Persistent files required for the agent to run, including transcripts, skills, and so on

• agent loop: A Node.js process

• execution environment: Filesystem + shell (bash tool)

These three components can be thought of as the Harness’s memory, brain, and hands.

In common Harness architectures (pi coding agent), all three are coupled within a single Node.js process and strongly depend on a VM. Durable changes this design, bringing many changes.

Why durable?

Decoupling the persistence system from the OS filesystem

In Durable, Pi separates the persistence system from Node, storing transcripts (sessionLog) in SQLite. This solves two problems:

• The persistence system—the prerequisites for starting and resuming sessions—is decoupled from the filesystem. This directly removes one prerequisite for starting an agent: “a VM with a filesystem.” Agents can run on a wider range of cloud services, substantially reducing costs

• It solves the previous problem of memory usage growing continuously as a single session accumulates data in session.jsonl

Decoupling the execution environment from the operating system

In an agent, a shell tool is essential: the agent can complete a substantial portion of its work through the shell. But at what cost? A dependency on a complete operating system environment.

Durable gives special treatment to tools that depend on FS and bash, while also providing an env package with the basic components needed to isolate execution environments:

• The agent loop has no dependency on FS or shell, allowing deployment on a wider range of compute nodes, such as serverless

• A single loop can switch between multiple environments, and pi’s toolkit already handles various edge cases, preventing issues such as hallucinations

Impact on our business: For personal agents, a substantial portion of tasks can be completed using tools and MCP configurations that do not depend on an execution environment. For example, many research tasks only require a combination of web search, RAG MCP, and similar tools.

Assuming 70% of scenarios follow this pattern, we can serve user requests with just a Node process, saving substantial hardware resources.

Lossless state recovery

Durable redesigns the state model within Harness: strict idempotency, writes first. It provides a doc API that allows developers to write extension state into the transcript as persistent state.

• All state storage is externalized and can be recovered without loss, making our compute node scheduling strategies more flexible

• Scenarios involving critical state, such as subagents and HITL, can be handled more flexibly and with greater fault tolerance, enabling lossless recovery from failures

Beyond durable

Durable is released as a standalone package, while the original pi coding agent package remains available. Beyond Durable, pi itself has also undergone a major version update with many changes, and these changes apply to both Durable and pi coding agent.

MCP Support

In the new version of pi, MCP has native support from pi itself, which is closely related to codemode, discussed below.

• We can remove our existing third-party MCP solution

• The author offers several recommendations for implementing MCP servers that are worth learning from: structured responses Stable data structures: do not return different data structures just because the types or quantities of the actual returned data differ MCP does not support large binary data, which limits many interesting implementations

codemode

The model can write trusted JS in pi (using the QuickJS engine) to call tools.

Why is codemode effective? After extensive training, today’s LLMs are very good at using bash and can efficiently perform a series of operations through scripts. But some capabilities are beyond bash, such as reading images or performing Linear MCP operations.

The model may well need to invoke tools in batches to complete a task. In the original architecture, the agent can call only a few tools per turn, then wait for their results before starting the next turn. This is a fairly poor pattern in terms of both time and cache reads (each turn appends a batch of tool returns to the end of the context).

With codemode, take a Linear task as an example: if I ask the model to summarize ticket completion for this month, it first makes a round of exploratory calls to understand the API and return schema, then writes a substantial block of JS to invoke tools concurrently and completes the task within a few turns.

• codemode saves context and suits our RAG MCP and the more complex MCPs we introduce later

• It is also a more efficient approach overall

• codemode is already supported in pi coding agent, but is not yet fully supported in Durable

server & client & protocol

Once Durable is up and running, the next question is: where does Harness run, and who views it? server & client & protocol separate “running” from “viewing”: the worker contains the loop & execution env, and combining it with the server solves many problems.

• protocol is just the envelope; it does no work: packages/[email protected] CBOR + 4-byte length framing, hello{version=8, serverId} handshake Routing {serverId/sessionId/attachmentId} Payloads are all opaque strict-JSON; semantics are delegated to chord 16MiB limit, no authentication, no compatibility guarantees

• server/client do the actual work: packages/server + packages/[email protected] unix transport, defaults to ~/.pi/server The server manages the Session directory + worker lifecycle; attach/detach delivers live routes; durable sessions stay local to the worker coding-agent/rpc-entry is the programmatic entry point included in dist/bundle

Impact on our business: Multiple users and devices. A persistent server supports long sessions + SQLite recovery, while clients attach on demand to view the same viewState. The presentation layer can be any client we implement.

Once computation and presentation are separated, scheduling becomes more like a web service, rather than being tightly bound to a VM. This also allows us to experiment with more product features, such as shared sessions and public sessions.

An Attempt to Design a Scalable, Long-Running Harness Architecture

This architecture has the following characteristics:

• Persistence lives in an independent database

• By default, starting a bot requires only a standalone agent loop, meaning a Node.js process. In theory, this process can be flexibly scheduled, destroyed, and restored

• Bots have no fs or shell tools by default. This also aligns with our previous business design: the main loop handles relatively lightweight tasks. A single loop + MCP can still accomplish a great deal of work (expected to handle at least 50% of tasks)

• fs + shell are tied to subagents, which handle medium and large tasks and are destroyed after use. At the infrastructure level, consider preparing a pool of blank sandbox instances with low resource allocations for flexible scheduling. Subagent transcripts can be persisted; nothing else needs to be persisted

• The main loop’s existing persistence needs are handled by artifact MCP + truth fs. Memory state is also externalized into a separate service

The goal of this architecture is to reduce hardware resource consumption by an order of magnitude while maintaining the same product experience. A conventional VM architecture is clearly beyond what most companies’ hardware resources can support.