Long-Horizon

Long-Horizon keeps the agent on a large task over many turns. It stops the agent when the task finishes or cannot continue.

@pi-unipi/long-horizon · part of UniPi

What it does

• Gives four modes for long work: goal, ralph, swarm and graph. The none mode is a normal session.
• Lets one owner control the session at a time. An owner is the active long-run task. One more owner can wait in the park slot.
• In goal mode, continues turns until an independent verifier accepts the goal. The goal can also stop as blocked, stalled or over budget.
• Shows only the tools of the current mode to the model.
• Can use a judge to select a mode for each new prompt. The judge is off by default.
• Shows a goal progress estimate to you only. The model does not get it.

Mode	Use it for
goal	One objective that you can verify, over many turns.
ralph	A checklist file that the agent completes over many iterations.
swarm	Independent items that parallel workers do, then one summary.
graph	Steps where later steps need the results of earlier steps.

Quick start

1. Install UniPi: pi install npm:@pi-unipi/unipi. You can also install this package alone: pi install npm:@pi-unipi/long-horizon.
2. Type /unipi:goal <objective>. The agent creates a goal and continues.
3. Type /unipi:goal status to see the owner and the progress.
4. Type /unipi:goal stop to end the goal.

Commands

Command	What it does
/unipi:goal <prompt>	Runs the prompt in goal mode.
/unipi:ralph start <name> <content>	Starts a loop with a Markdown checklist of - [ ] items.
/unipi:ralph <prompt>	Runs the prompt in ralph mode.
/unipi:swarm <prompt>	Runs the prompt in swarm mode.
/unipi:graph <prompt>	Runs the prompt in graph mode.
/unipi:<mode> status	Shows the owner, the park slot and the judge settings. For graph and swarm, also the graph's step counts.
/unipi:graph history, /unipi:swarm history	Lists past agent graphs and the results each one selected.
/unipi:<mode> stop	Ends the active owner. For ralph, it parks the loop.
/unipi:<mode> resume	Starts the parked owner again.
/unipi:<mode> clear	Removes the parked owner.
/unipi:regular	Ends the active owner. Sets the session to none mode.

When you start a new mode, the active owner goes to the park slot. If the park slot is full, the command fails. Resume or clear the parked owner first.

Agent tools

Each tool shows only in its mode. todowrite shows in all four modes.

Tool	Mode	What it does
create_goal, get_goal, update_goal	goal	Creates, reads and finishes the goal. Also changes the token budget.
ralph_done, loop_status	ralph	Ends one iteration. Reads the loop state.
update_agent_graph, view_agent_graph, yield_agent_graph, agent_output, agent_swarm_status	graph, swarm	Adds, stops or finishes work on the agent graph. Reads the graph, a step's result and the swarm status. Ends the turn while steps run.

graph and swarm share one durable agent graph (the Maka model). The model adds work with dependencies (input_ids), and the host runs each step as a background subagent. The model yields, and pi wakes it once at each checkpoint: a failure, nothing left to run, or everything settled. A graph closes only when the model finishes it with the results it chose. The graph is saved in the project's state folder, so it survives a restart. Steps that were running resume once in their own subagent session. | todowrite | all | Replaces the visible task list. |

Settings

Namespace long-horizon. Open it with /unipi:settings.

Key	Default	What it does
judge.enabled	false	Lets the judge select a mode for new prompts.
judge.threshold	0.8	Minimum judge confidence. Below it, the default mode applies.
decisionModel.source	inherit	inherit uses the shared decision-model settings. custom sets a judge model.
defaultMode	none	Mode when the judge is off or gives no verdict.
verifierModel	empty	Model that verifies goal completion. Empty uses the session model.
goalProgress	loop	loop estimates after each goal turn. status estimates on status only. off stops it.
progressModel	empty	Model for the estimate. Empty uses the verifier model.

Judge keys and models

The judge finds its API key in this order:

1. The stored key (/unipi:settings → Decision Model → API key).
2. The environment: TYPESAFE_API_KEY for typesafe, OPENROUTER_API_KEY for openrouter and custom.
3. Pi's own model registry. If a Base URL is set, the judge uses the key of the pi model that has that Base URL. If no Base URL is set, it uses pi's stored key for the provider (openrouter or typesafe).

UniPi does not know about any one gateway or provider extension. A third-party extension supplies keys and models through pi itself: it calls pi.registerProvider(name, { baseUrl, apiKey, models }), or the user adds the provider to ~/.pi/agent/models.json / auth.json. Then set the decision model's provider to custom and its Base URL to that provider's URL (for example https://gateway.example/v1). The judge uses the key that pi resolves for it. If no key is found, the judge is off and defaultMode applies.

How it works

At the start of each turn, the gate selects the mode. An explicit command wins. Next comes the active owner, then the judge, then defaultMode. The gate adds the mode prompt and filters the tool list. Within one mode, the tool list stays the same, so the prefix cache stays valid.

The engine keeps owner state in ~/.unipi/workspace/<id>/state/long-horizon/sessions/<sessionId>/ — a run belongs to the session that started it, so a new session starts clean (it gets a one-line note when another session holds a live graph; resuming the owning session continues it, and the first resume of the owning session picks up pre-3.0.1 runs). Ralph checklists are in the ralph/ folder there. Owners do not start inside a child agent.

Read Long-horizon architecture and Turn arbiter.

See also

• Delegation
• Prefix cache
• Commands reference
• Tools reference