ai-agent/runner/README.md

pi runner — the ai-agent's second harness

Runs viewer-spawned sessions on pi (@earendil-works/ pi-coding-agent) instead of the claude CLI, with open models: Qwen 3.8 (or 3.6) via OpenRouter (hosted) or the EVOX2 box's LM Studio (local, free).

How harness switching works

The model chip in the composer is the harness switch. /api/models returns every pickable model tagged with its harness (claude | pi); picking a qwen chip routes the session through this runner, picking a Claude family runs claude exactly as before. The chain:

composer chip → POST /api/spawn {model, harness}
             → sidecar /spawn  → harness == "pi" ? RUNNER_BIN : CLAUDE_BIN
             → runner: pi --mode json --session-id <uuid> …
             → transcript mirrored to ~/.pi-runner/transcripts/<cwd>/<uuid>.jsonl
             → container watches it (PI_TRANSCRIPTS_DIR mount) → SSE → viewer

• The spawn stamps harness into the conversation metadata sidecar, so a resume with no model picked continues on the same harness (backend fallback); picking a chip from the other harness switches mid-conversation.
• The runner accepts the same flag shape as claude (-p --session-id/--resume --model), so the sidecar treats both harnesses identically — pidfiles, launch probe, SIGINT interrupt, reused idempotency all work unchanged.
• Transcript compatibility is the design: the runner translates pi's message_end events (user / assistant / toolResult) into Claude-Code-schema JSONL, so the viewer's parser, cost-by-tool, SSE streaming, DONE detection and lifecycle checks need no pi-specific code. Adding a third harness = another runner that writes the same schema.
• Built-in tool calls are remapped to Claude's shape (mapToolCall in cli.mjs): pi's lowercase read/write/edit/bash/grep/find/ls with path/edits[] become Read/Write/Edit|MultiEdit/Bash/Grep/Glob/LS with file_path/old_string/new_string (bash timeout s→ms). That's what makes the viewer's cost-by-tool buckets, per-extension sub-breakdowns, auto project/service tags, bash cards and Read image previews light up for pi sessions. Unknown (extension) tools pass through and render as generic cards.
• Real cost, not estimates: each assistant record carries pi's own per-message provider cost as costUSD (omitted when pi reports none). The parser (backend/conversations.py) prefers it over its price table — so OpenRouter runs show the billed amount and free local EVOX2 runs cost $0 (ids the picker declares provider: "evox2", plus any bare qwen id, also price at 0 in the fallback table).

Model → provider routing

model id	provider
any id listed under a provider in ~/.pi/agent/models.json — ggml-org/qwen3.8-27b, qwen3.6-35b-a3b, laguna-s-2.1	that provider: EVOX2 LM Studio (evox2) or EVOX2 llama.cpp (evox2-laguna); the box is WoL-woken automatically
everything else with a vendor prefix — openai/gpt-oss-20b, qwen/qwen3.8-27b, …	OpenRouter (OPENROUTER_API_KEY, auto-loaded from ~/homelab/.env.claude)

pi's own registry decides, and the id shape is only the fallback. It has to: LM Studio serves the local Qwen 3.8 as ggml-org/qwen3.8-27b — vendor prefix and all — while OpenRouter has a qwen/qwen3.8-27b of its own, so the two differ by provider, not by shape. A model must be listed in that file for pi to run it locally anyway, which is what makes it the authority; anything unlisted falls back to "has a / ⇒ OpenRouter", so any of the several hundred OpenRouter models still runs here with no runner change. Registering a new local model means adding it under its provider's models array there (id, contextWindow, compat.thinkingFormat, zero cost) and adding a chip for it in backend/models.py. Two pickers feed the composer: the curated chips in backend/models.py (PI_MODELS_DEFAULT, override with PI_MODELS_JSON) and the composer's OpenRouter browser, which lists the whole catalogue with per-model prices from backend/openrouter.py (sourced from APPE). Those same prices cost the session's transcript, so a run's $ figure is the model's real rate even before pi reports its own costUSD.

Permissions

extensions/folder-permissions.ts blocks tool calls outside the session's scope (PI_PERM_SCOPE, default = the run's cwd): write/edit only inside the scope, reads inside PI_PERM_READ roots (default $HOME) + system prefixes, bash commands may not reference paths outside the readable roots, and a deny-always list protects .env/credentials/.ssh from writes. This is stricter than the claude harness's bypassPermissions — pi itself has no permission system, so the extension is the enforcement point.

pi session state

pi sessions persist under ~/.pi-runner/sessions/ keyed by the same UUID the viewer uses (--session-dir + --session-id), so resume is stateless: the same id simply reopens the session. Skills load from ~/.claude/skills via ~/.pi/agent/settings.json; pi reads the repo CLAUDE.md natively.

Files

• cli.mjs — the runner (arg parsing, EVOX2 wake, pi spawn, transcript writer).
• extensions/folder-permissions.ts — the permission gate.
• Env knobs: PI_BIN, PI_RUNNER_ROOT, RUNNER_DEFAULT_MODEL, RUNNER_PERM_EXT, RUNNER_ENV_FILE, EVOX2_URL/EVOX2_MAC/EVOX2_BCAST, and on the sidecar side RUNNER_BIN, SIDECAR_PI_MODEL.

Setup (already done on this host)

cd services/ai-agent/runner && npm install --ignore-scripts
# ~/.pi/agent/models.json     — evox2 provider (LM Studio token inside)
# ~/.pi/agent/settings.json   — {"skills": ["~/.claude/skills"]}
# OPENROUTER_API_KEY          — in ~/homelab/.env.claude