pi-ultraplan

A provider-agnostic /ultraplan pattern: fire a heavy "planning" agent off to the background, keep your terminal free, poll for a structured plan, gate it on human approval with an interactive dialog, optionally execute it in an isolated worktree.

Works as a Pi extension with full TUI integration, slash commands, and automatic plan export. Also runs standalone via CLI and HTTP API.

The reference provider is custom model fairy-tales-deepseek-openai running deepseek-v4-pro — but the engine not include it. Swap the provider, keep the engine.

Architecture

trigger (CLI / API / Pi extension)   ← swappable surface
        │
        ▼
   Dispatcher  (dispatcher.ts)        ← 100% generic engine
   ├─ idempotency lock (set before any await)
   ├─ detached poll loop + timeout
   ├─ status-guarded delivery (late polls can't resurrect killed jobs)
   ├─ orphan reaping on error
   └─ event bus: ready / progress / phase / gate / approved / failed / killed
        │
        ▼
   AgentProvider  (types.ts)          ← the ONLY thing you implement per backend
        │
        ▼
   DeepSeek Provider (providers/deepseek/)
   ├─ chat.ts         ← OpenAI-compatible transport + cost metering
   ├─ planners.ts     ← multi-lens fan-out (pragmatist, adversary, scale, maintainer)
   ├─ synthesis.ts    ← structured JSON reconciliation with parse-retry
   ├─ repair.ts       ← fold verification critique into plan
   └─ index.ts        ← AgentProvider orchestrator (launch/poll/approve/reject/execute)
        │
        ▼
   file-backed store (store.ts)       ← every state claim verifiable on disk

The ultra pipeline (plan mode)

1. Fan out — N planners in parallel, each a different lens (pragmatist, adversary, scale, maintainer). PI_PLANNERS controls N (default 3, max 4). One planner failing doesn't sink the run; all-fail → failed.
2. Synthesize — reconcile the drafts into one structured StructuredPlan JSON with parse-retry and prose fallback.
3. Adversarial verify — 4-lens panel (correctness, security, feasibility, completeness). Tie or majority refute triggers repair. Configurable via PI_VERIFIERS and PI_VERIFY_ROUNDS.
4. Repair — fold critique back into the plan, re-verify. Loops up to PI_VERIFY_ROUNDS (default 2) before gating regardless.
5. Gate — interactive dialog: Approve & Execute, Approve only, Reject. Plans exported to ~/Documents/ultraplan-plans/ on approve.

Pi Extension

Load automatically (symlinked at .pi/extensions/) or via -e:

pi -e extensions/ultraplan.ts

Slash Commands

Command	Description
/ultraplan <prompt>	Dispatch a plan — fan-out → synthesize → verify → gate
/ustatus [suffix]	List recent sessions, filter by sessionId suffix
/uview <suffix>	View full plan details for a specific session

Tools (LLM-callable)

Tool	Description
ultraplan_plan	Start planning — returns sessionId immediately, runs in background
ultraplan_status	Read persisted state of any session
ultraplan_approve	Approve a plan at the gate
ultraplan_reject	Reject with a note (feeds cross-run memory)
ultraplan_execute	Execute approved plan → worktree PR/patch
ultraplan_stop	Halt a running job
ultraplan_eval	Run benchmark suite with LLM-judge scoring
ultraplan_audit	Read append-only audit log

TUI Surfaces

• Footer — live session tracker, store-reconciled against disk state
• Widget — progress stream above editor (planning 0/3 → synthesizing → verifying)
• Status line — active job count
• Gate dialog — select() with Approve & Execute / Approve only / Reject
• Plan export — .md files written to ~/Documents/ultraplan-plans/ on approve

CLI

# Launch — returns immediately, prints plan at the gate
npx tsx src/cli.ts plan "Add Redis rate limiting to POST /api/login"

# Execute an approved plan
npx tsx src/cli.ts execute <sessionId>

# Inspect persisted state
npx tsx src/cli.ts status <sessionId>

# Human gate
npx tsx src/cli.ts approve <sessionId>
npx tsx src/cli.ts reject  <sessionId> "use sliding window, not fixed"

# Cancel a running job
npx tsx src/cli.ts stop <sessionId>

# Run benchmark eval
npx tsx src/cli.ts eval benchmarks/sample.json

# Read audit log
npx tsx src/cli.ts audit

# HTTP API (SSE + web UI)
npx tsx src/cli.ts serve 8080

Swapping providers

Implement AgentProvider (see src/types.ts) against any backend — OpenAI Assistants, Gemini, a queue+worker pod — and pass it to new Dispatcher(...). Nothing else changes.

Env

var	default	meaning
PI_BASE_URL	http://localhost:8000/v1	OpenAI-compatible base
PI_API_KEY	—	bearer token
PI_MODEL	deepseek-v4-pro	default model
PI_PLANNERS	3	fan-out width (1–4)
PI_VERIFIERS	3	verification panel size (1–4)
PI_VERIFY_ROUNDS	2	max verify→repair loops (1–3)
PI_MAX_TOOL_STEPS	12	max tool calls per planner
PI_COST_CEILING_USD	—	hard cost cap per run
PI_COST_JSON	—	per-model pricing overrides
PI_FALLBACK_MODELS	—	comma-separated fallback chain
PI_PLAN_DIR	~/Documents/ultraplan-plans	plan export directory
PI_ALLOW_UNSOUND_EXEC	—	set to 1 to execute plans that failed verification
PI_SESSION_DIR	~/.pi/ultraplan/sessions	where session records persist