UHP and Pi

Choose a supported Pi interface

The current Pi release is v1.0.2, observed 4 October 2026. The upstream README requires Node.js 22.19+ and distinguishes its dependency-pinning installer from a direct npm install. The older 0.85.x sections below are historical package evidence.

Integration need	Documented surface	Ownership implication
One task and final text	pi --print	Caller owns the process and exit handling
Progressive machine-readable output	pi --mode json	Caller parses JSONL rather than terminal rendering
Long-lived host-controlled process	pi --mode rpc	Caller sends JSONL commands and correlates replies/events
In-process application	TypeScript SDK	Application owns session lifecycle and persistence
A UHP HTTP endpoint	Pi through HarnessRouter	UHP server owns external Response/session semantics

The versioned CLI reference makes a subtle distinction: --mode text selects output format but does not force a one-shot terminal run; --print does. A wrapper that waits for --mode text to exit can therefore wait on an interactive process. JSON/RPC reserve stdout for protocol records; keep diagnostics and your own logging elsewhere.

For an authenticated, disposable project, the documented JSON-mode form is:

pi --mode json "Inspect this repository" > events.jsonl

This can execute a model turn; it is source-checked here, not run. Inspect actual event/terminal behavior and confirm the working directory: it controls project resources and session grouping. HarnessRouter installs the Pi npm package without an explicit version in its stable entrypoint, so a CE image tag alone is insufficient to identify Pi’s binary.

Pi’s README says it has no built-in filesystem/process permission system. Treat the OS/container and any deliberately installed extension as separate enforcement boundaries; an RPC interface does not itself provide a sandbox. See remote execution boundaries before exposing a host-controlled Pi runtime.

What Pi is

Pi is an upstream agent harness project. HarnessRouter describes it as an extensible agent harness that can be driven as one of its backends. This page is about the verified relationship between UHP, HarnessRouter and Pi; it does not speak for the Pi project’s own roadmap or protocol choices.

Upstream Pi observability is now more explicit

Upstream Pi has continued to evolve independently of HarnessRouter. At the historical 5 September review, the latest observed Pi release was v0.85.1, published that day. The vendor-neutral telemetry work was already included in v0.84.0 on 6 August and was present in the then-reviewed @earendil-works/pi-telemetry package at version 0.85.1.

That package defines an explicit callback-based TelemetryContext / TelemetrySpan contract, a no-op context, an in-memory reference adapter, serializable typed schemas and an adapter conformance suite. Pi deliberately does not couple this contract to one exporter or backend: applications can bridge it to OpenTelemetry, Sentry, logs or another telemetry system, while Pi packages propagate the telemetry context explicitly.

Pi’s agent package also publishes typed schema-v1 instrumentation including pi.ai.request and pi.harness.run, with fields for provider/model/usage/cost/error data and harness operation/session/outcome data. This is useful interoperability at the observability adapter boundary: a backend can implement the Pi telemetry contract and run its conformance cases without changing Pi’s emitted vocabulary.

Note

Telemetry is not UHP or ATIF. Pi’s telemetry contract describes process-local diagnostic spans and adapter semantics inside/upstream of Pi. UHP standardizes the client↔server harness execution contract, while ATIF standardizes portable whole-run trajectory records for replay/evaluation/training. The Pi telemetry package does not create a UHP wire binding, does not change the UHP conformance suite, and is not evidence that Pi natively adopted UHP.

v0.85.1 fixes the public SDK distribution boundary

Pi v0.85.1, released 5 September 2026, fixes SDK import failures caused by internal experimental code and dependencies being unintentionally published in v0.85.0. The release now keeps the experimental client and experimental/plugin subpaths plus server/client commands source-only through pi-test.sh; Pi explicitly says the supported local SDK and stdio RPC API are unchanged.

This matters to harness integration because source presence and supported distribution are different compatibility contracts. Pi’s remote server/client work remains available for source development, but v0.85.1 makes the supported-package boundary explicit rather than leaving consumers to infer stability from accidentally published files.

The same release adds GPT-6 Astra for OpenAI API keys and OpenAI Codex subscriptions and corrects long prompt-cache requests for GPT-5.6+ Responses models to use prompt_cache_options.ttl: "30m". Those provider/catalogue changes are Pi capabilities, not UHP model-selection semantics.

Note

Upstream Pi packaging/provider behavior is not UHP behavior. The source-only experimental boundary, GPT-6 Astra availability and prompt-cache policy belong to Pi’s own distribution/provider surfaces. They do not establish native Pi UHP adoption or a new HarnessRouter conformance result.

v0.85.0 adds externally restorable SDK sessions

Pi v0.85.0 adds a host-facing session capability that matters to embedded integrations: SessionManager.inMemory() can now restore externally managed session entries, allowing an application to resume a Pi session whose persisted transcript is kept outside Pi’s filesystem, such as in an application database.

The same release fixes several session-integrity edges around that host boundary. Concurrent session shares no longer overwrite one another; importing a session no longer overwrites an existing session with the same filename; session forks retain their compaction boundary; in-memory session forks are repaired when requested before the active turn has settled; and RPC abort now cancels an in-progress manual compaction instead of reporting success without cancelling it. The release also preserves selected Anthropic thinking effort across supported transports and fixes proxied assistant responses dropping persisted provider-native thinking levels.

Note

Upstream Pi SDK/session semantics, not a UHP version change. Restoring externally stored Pi entries and the associated fork/share/abort fixes belong to Pi’s own SDK, session and RPC surfaces. This guide has not found evidence that HarnessRouter’s UHP→Pi backend exposes or maps these exact controls as UHP objects, and the release does not establish native Pi UHP adoption.

v0.84.4 sharpens host lifecycle and replay boundaries

Pi v0.84.4 adds host-facing lifecycle and queue controls that matter to integrations even though they are not UHP protocol primitives. New ui_prompt_start and ui_prompt_end extension events let an embedding host distinguish active agent execution from time spent waiting on a user-facing ctx.ui prompt. The same release adds RPC clear_queue, allowing an RPC client to retrieve and remove queued steering and follow-up messages.

The release also fixes three replay/session-integrity paths that are easy to misclassify as transport failures: resumed JSONL sessions that lack a trailing newline no longer corrupt the next appended entry; extension messages emitted with triggerTurn: false during an active run are held until the current tool-call/results sequence is complete so providers that validate message ordering can replay the history; and large tool results that cross the auto-compaction threshold are compacted before the next provider response instead of being sent first.

Note

Upstream Pi host semantics, not a UHP version change. These events, RPC controls and replay fixes belong to Pi’s own host/session surface. This guide has not found evidence that HarnessRouter’s UHP→Pi backend exposes or maps these exact controls as UHP objects, and the release does not establish native Pi UHP adoption.

No newer UHP conformance report tied specifically to Pi v0.85.1 was identified in this pass. The verified UHP evidence for the Pi path therefore remains HarnessRouter’s v0.7.0 Full 52/52 run described below.

What HarnessRouter added

HarnessRouter Community Edition tagged v0.7.0 on 20 August 2026 and added Pi as a backend. The tag’s conformance commit reports a Full-class UHP run with 52/52 checks executed through the new Pi backend path, with task checks run on gpt-5.4-mini via TokenRouter.

Conformance evidence through Pi

The v0.7.0 evidence is a published Full-class 52/52 UHP conformance report executed through the Pi harness path. It demonstrates that HarnessRouter’s Pi integration satisfies the same Full-class behavioral expectations as its earlier backends. It does not, by itself, expand the UHP conformance suite beyond 52 checks.

The MCP adapter is part of the HarnessRouter path

In HarnessRouter’s Pi integration, an MCP adapter is installed alongside Pi. That adapter belongs to the HarnessRouter integration, not to the upstream Pi project. Do not describe this as native MCP support by Pi unless the Pi project states so in its own primary source.

What is not proven

Caution

No native-adoption claim: this guide has not found primary evidence, as of 5 September 2026, that the Pi project independently publishes UHP as a native protocol. The verified UHP claim remains support through HarnessRouter’s implementation, including a Full 52/52 conformance run.

Why the distinction matters

A reference implementation can adapt an existing harness without that harness vendor changing its own API. Native adoption would be a stronger ecosystem signal: it would mean a vendor, tool or independent runtime exposes or consumes UHP directly, reducing dependence on one adapter implementation.

Related pages

Read HarnessRouter Community Edition, conformance, the adoption tracker, the ecosystem map, UHP vs ATIF, and the other harness pages: Codex, Claude Code, Hermes, and DeepSeek Harness.

Primary sources

• HarnessRouter v0.7.0 release
• HarnessRouter Community Edition repository
• Pi v0.85.1 release
• Pi v0.85.1 coding-agent changelog
• Pi v0.85.0 release
• Pi v0.85.0 coding-agent changelog
• Pi v0.85.0 SDK session documentation
• Pi v0.84.4 release
• Pi v0.84.0 release
• Pi telemetry contract and adapter-conformance documentation
• Pi agent telemetry schema reference
• Pi repository (upstream agent harness)