Architecture

Prompt Runner 0.12.1 is organized around one packet runtime with both CLI and SDK entry points.

Runtime Flow

packet dir
  -> PromptRunner.Packet / PromptRunner.Source.PacketSource
  -> PromptRunner.Plan
  -> PromptRunner.Runner
  -> PromptRunner.Session
  -> PromptRunner.Verifier
  -> PromptRunner.Runtime + RuntimeStore + Committer

Core Concepts

• PromptRunner.Profile home-scoped defaults
• PromptRunner.Packet packet manifest loader, runtime preflight, and doctor surface
• PromptRunner.PacketLint static authoring-hazard analysis
• PromptRunner.Packets prompt creation and checklist sync
• PromptRunner.Plan fully resolved execution plan
• internal runner pipeline preflight, execution, retry, repair, and completion logic
• PromptRunner.AgentControl authenticated per-iteration directives for movement through a linear prompt sequence, plus an independent repeatable nonterminal progress record
• PromptRunner.Verifier deterministic completion contracts, with Verifier.Doc and Verifier.ReposClean implementing the artifact-quality and repository-discipline clauses
• PromptRunner.Runtime packet-local attempt history and status state
• PromptRunner.Watch supervision facts for a long unattended run

Completion Model

Prompt Runner no longer treats provider success as completion.

Completion is owned by the verifier:

• provider success + verifier pass => complete
• provider success + verifier fail => repair, while the repair budget lasts
• transient provider failure + verifier pass => complete
• verifier fail with the repair budget spent => fail
• terminal provider or policy failure => fail

Every branch terminates. Repair is bounded by recovery.repair.max_attempts, and the exhausted case fails with the unmet verifier items rather than starting another attempt.

An agent-controlled packet adds one linear transition after an ordinary prompt iteration verifies: continue, repeat, finish, or blocked. Repeat opens a fresh provider session on the same prompt. Finish is accepted only when the separate packet-level completion contract passes. The agent never marks its own work complete and never terminates the runner process.

Live project progress is deliberately not a fifth transition. Each controlled invocation receives a separate authenticated progress path and may atomically replace its own cursor record many times. Terminal request storage stays exclusive and first-wins. Workspace status accepts only a record matching the current durable run and prompt, and identifies a retained prior-iteration record as stale.

Recovery Model

Prompt Runner prefers provider-native session continuation for recoverable transport failures. Repair is a separate higher-level step driven by unmet verifier items.

Run Bounds

PromptRunner.Session derives every time bound from the single timeout key: the stream timeout, the transport timeout, the derived stream idle timeout, and ASM's run_deadline_ms. An unset timeout means the seven-day emergency bound on all four, not ASM's 600s default for the run deadline. See the Packet Manifest Reference.

Observability

A run with a file-backed state directory writes .prompt_runner/run.pid for its duration, .prompt_runner/state.json for attempt and verifier history, and .prompt_runner/logs/ for per-prompt transcripts and JSONL events. PromptRunner.Watch reads the first and third of those. See Supervising A Long Run.