paratenic

Plate II · Why

A host that doesn’t own the agent.

Most agent hosts are the agent’s home: they start it, run it and end it. Paratenic does something narrower, and for agents people already run, more useful: it keeps a life cycle going that it was never needed to start.

The name

Not needed to grow the agent. Needed to keep it going.

In ecology a paratenic host carries a parasite between the hosts it actually develops in. The parasite does not mature there, yet without that host its life cycle would stall.

An agent develops in its runtime: that is where the model is called, where tools run and where files change. Paratenic is not that place. It carries the session outward — to a phone, a watch, a browser, a second terminal — and keeps it reachable, ordered and recoverable while the runtime does the work.

Two kinds of host

Owning hosts and paratenic hosts speak the same protocol

An owning host beside a paratenic host Left: an owning agent host, such as VS Code's Agent Host, runs its agent adapters (Copilot, Claude, Codex) inside its own process next to the session state that editor and browser windows subscribe to. Right: a paratenic host keeps only the session state; the runtimes run beside it as separate processes — Pi in a terminal over a socket, and Pi agents the Paratenic Pi provider started in tmux for AHP createSession, over the same kind of socket — so the agent carries on if the host stops. editor window browser window sessions and state Copilotadapter Claudeadapter Codexadapter Culture Petri sessions and state Piin your terminal Pi in tmuxcreated by a client ONE PROCESS: THE AGENT HOST ONE PROCESS: PARATENIC OTHER PROCESSES socket socket stop the host and the agent stops with it stop the host and the agent carries on
Fig. II.1VS Code’s Agent Host runs its Copilot, Claude and Codex adapters in-process. Paratenic keeps the state and leaves the agent where it is.

The Agent Host Protocol was designed so that an agent does not depend on any one window: the host owns sessions, clients come and go, and a turn can finish with nobody watching. VS Code’s Agent Host achieves that by becoming the agent’s home. Its adapters translate each runtime into the common session model inside the host process.

That model assumes the host started the agent. Many agents are already running somewhere else — a Pi in a terminal with a human at the keyboard. Paratenic is the same protocol from the other direction: it adopts those sessions where they live and makes them first-class AHP sessions without moving them — and when a client asks for a new session, it starts an ordinary Pi rather than running the agent itself.

Three tenancies

One plane, three kinds of ownership

Who owns each layer A matrix of five layers — what you look at; session state, order and replay; life cycle; the process; model and tools — against three Paratenic tenancies and VS Code's Agent Host. For attached sessions Paratenic owns only the session-state layer and your Pi process owns everything below it. Host-created sessions are the same, except that an AHP client asked for them and the Paratenic Pi provider started their Pi in tmux. Offline sessions are ones whose Pi has exited: Paratenic keeps their state and history, and nothing runs. In VS Code's Agent Host the host owns every layer from session state down to the in-process adapter. Attached Host-created Offline VS Code Agent Host What you look at clients and the Pi TUI clients and tmux clients editor windows Session state, order, replay Paratenic Paratenic Paratenic Agent Host Life cycle you, in the terminal AHP client asks provider pi starts ended; history kept Agent Host The process your Pi process a Pi in tmux none Agent Host process Model and tools Pi Pi none in-host adapter Paratenic holds one layer; the runtime keeps everything beneath it.
Fig. II.2Read down a column to see who owns each layer of a session. Paratenic’s band is the only one it shares across all three tenancies.

Attached sessions are ordinary Pi processes. You started them; the terminal stays authoritative, and every keystroke there still runs exactly once in that process. Paratenic mirrors the conversation and routes remote turns back into it.

Host-created sessions are the closest thing to an owning host’s agents: an AHP client calls createSession on a provider, chooses the URI, and can later dispose of it. The provider — paratenic provider pi — starts an ordinary Pi with the Paratenic extension in its own tmux session, which claims that URI. The Pi still owns its tools, model and transcript, keeps running if Paratenic stops, and a person can attach to it at any time.

Offline sessions are ones whose Pi has exited. Paratenic keeps their state and history and still answers reads while holding no runtime; resuming the conversation in Pi returns it to the same URI. Another host’s sessions — pi-daemon’s, for example — are not carried here: Culture connects to that host directly and merges the hosts on the client.

To a client they are all just sessions. The differences surface as capabilities — whether a session can be disposed, which providers accept createSession, whether a chat is fully interactive or read-only — not as separate APIs.

Why AHP, not ACP

A session several people watch is not an editor’s subprocess

The Agent Client Protocol connects one editor to one agent, usually an agent process the editor launched and talks to over stdio. That is the right shape for bringing your own agent into your editor, and the wrong one here: the session already exists, it has a human at a terminal, and a phone and a browser want to watch the same turn.

AHP gives exactly what that needs — host-owned state, snapshots at a sequence number, ordered actions that every client reduces the same way, idempotent dispatch and reconnect with replay. Paratenic implements AHP 0.8 completely and does not speak ACP at all; where a runtime exposes an ACP stream, it may check parity, but it never owns commands.

Local first

What survives what

If…the turnyour terminalother clientsthe session URI
Paratenic restartscarries oncarries onreconnect; snapshot if past replayunchanged; offline until the runtime re-registers
a client dropscarries oncarries onunaffectedunchanged
you quit piendsendssee it offlinekept; resuming the conversation returns to it
the Pi provider restartscarries onstill attachable in tmuxunaffectedunchanged
a stale adapter speaks——unaffectedthe newer incarnation keeps it; the old one is fenced

The extension reconnects with exponential backoff, from 100 ms up to five minutes, and re-registers the same conversation at the same URI. While it is away its outbound queue is bounded; complete transcript resynchronisation after that queue overflows is not built yet.

Principles

Nine rules the code keeps

  1. The runtime stays the runtime. Paratenic never calls a model, runs a tool or starts a second Pi to stand in for the one you have.
  2. One owner per conversation. A session joins through exactly one backend. A newer registration for the same source fences the old one, and a Pi runtime hosted by another AHP host sets PI_DISABLE_AHP=1 so the extension cannot become a second owner.
  3. Local first. Losing Paratenic never makes a terminal Pi unusable.
  4. Admission is not completion. Accepted, settled and indeterminate are separate states. An unusable response is reconciled against its receipt, never resent.
  5. AHP is the only authority. AG-UI and A2UI are projections a client can rebuild; neither can settle a turn, an input or a tool.
  6. The mesh lives in the client. Hosts never federate. Each keeps its own sequence, authentication and replay, and Culture merges what it sees.
  7. Neutral by construction. No orchestrator, lifecycle manager or consumer package has a concept in the host or the backend protocol.
  8. Everything is bounded. 1 MiB frames, 1,024 connections, 4,096 logical clients, 10,000 sessions, 256 chats a session. A slow client disconnects alone.
  9. Owner-private by default. Loopback listener, owner-only state and sockets. Non-loopback plaintext needs a strict token file and an explicit trusted-proxy flag.

What it isn’t

Deliberately missing

NotBecause
an agent frameworkPi decides how agents think, call tools and store sessions.
a schedulerQueues, concurrency and resumption belong to the runtime, or to another host such as pi-daemon.
an orchestratorLifecycle systems such as Cacophony bind their agents to AHP URIs from outside; Paratenic never learns their concepts.
a federation protocolHosts do not peer. Clients connect to each host they trust.
an internet serviceThere is no built-in TLS. Put it behind an authenticated tunnel or a TLS proxy you control.