Prompt Runner SDK

Prompt Runner SDK

Packet-first prompt execution for Elixir, Mix, and local CLI workflows

GitHubLicense

Prompt Runner SDK executes packetized prompt workflows against local repositories. This README targets prompt_runner_sdk ~> 0.8.0.

The packet-first design introduced in 0.7.0 carries forward unchanged:

0.8.0 moves the runtime onto agent_session_manager ~> 0.12.1 and cli_subprocess_core ~> 0.4.1, and publishes the normalized option surface those releases added. See the CHANGELOG for the full list.

The same runtime is exposed through public Elixir modules and the CLI.

Highlights

Installation

def deps do

  [

    {:prompt_runner_sdk, "~> 0.8.0"}

  ]

end

mix deps.get

Prompt Runner is an explicit agent_session_manager core-lane client. Host projects do not need codex_sdk, claude_agent_sdk, amp_sdk, cursor_cli_sdk, or antigravity_cli_sdk just to use Prompt Runner.

gemini_cli_sdk is retired. Antigravity is the Google coding-agent provider; gemini_ex remains a separate model API SDK and is not a Prompt Runner coding agent provider.

For recovery demos and onboarding, Prompt Runner also ships a built-in simulated provider that requires no external CLI or API credentials. That provider is package-local support for retry, repair, and resume behavior; cross-stack service-mode proofs should use configured ASM and cli_subprocess_core runtime profiles instead of treating :simulated as an end-to-end provider substitute.

Quick Start

Initialize Prompt Runner once per machine:

mix prompt_runner init

mix prompt_runner template list

That creates:

Start with the simulated path first. It is the shortest way to learn the packet model and authoring workflow.

Create a simulated packet with repos and a default prompt template in one command:

mix prompt_runner packet new demo \

  --profile simulated-default \

  --provider simulated \

  --model simulated-demo \

  --repo app=/path/to/repo \

  --default-repo app \

  --prompt-template from-adr

Create a prompt from that template:

mix prompt_runner prompt new 01 \

  --packet demo \

  --phase 1 \

  --name "Capture runtime boundaries" \

  --targets app \

  --commit "docs: add runtime boundaries summary"

If you want a real provider packet after that, switch the packet to a real profile/provider/model or start with codex-default.

The generated prompt is template-based. It should then be finished by adding:

Example:

---

id: "01"

phase: 1

name: "Capture runtime boundaries"

template: "from-adr"

targets:

  - "app"

commit: "docs: add runtime boundaries summary"

references:

  - "docs/adr-001-runtime-boundaries.md"

required_reading:

  - "docs/adr-001-runtime-boundaries.md"

context_files:

  - "workspace/README.md"

depends_on: []

verify:

  files_exist:

    - "RUNTIME_BOUNDARIES.md"

  contains:

    - path: "RUNTIME_BOUNDARIES.md"

      text: "Prompt Runner owns packet orchestration."

  changed_paths_only:

    - "RUNTIME_BOUNDARIES.md"

---

# Capture runtime boundaries



## Required Reading



- `docs/adr-001-runtime-boundaries.md`



## Mission



Read ADR 001 and create `RUNTIME_BOUNDARIES.md` in the target repo.



## Deliverables



- `RUNTIME_BOUNDARIES.md` summarizing the runtime boundary split



## Non-Goals



Do not modify any other files. Respond with exactly `ok`.

Turn the verification contract into a human checklist:

mix prompt_runner checklist sync demo

mix prompt_runner packet preflight demo

mix prompt_runner packet doctor demo

Inspect, run, and check status:

mix prompt_runner list demo

mix prompt_runner plan demo

mix prompt_runner run demo

mix prompt_runner status demo

Packet-local runtime state is written to demo/.prompt_runner/.

For a ready-made authoring walkthrough from ADRs/docs to finished prompts, see examples/authoring_packet/.

Packet Model

A packet directory is the primary unit of work:

demo/

  prompt_runner_packet.md

  templates/

    from-adr.prompt.md

  docs/

    adr-001-runtime-boundaries.md

  prompts/

    01_capture_runtime_boundaries.prompt.md

    01_capture_runtime_boundaries.prompt.checklist.md

  .prompt_runner/

    state.json

    progress.log

    logs/

Core files:

Programmatic API

The CLI is a thin layer over public modules:

{:ok, _paths} = PromptRunner.Profile.init()

{:ok, packet} = PromptRunner.Packet.new("demo", root: "/tmp")

{:ok, packet} = PromptRunner.Packet.add_repo(packet.root, "app", "/path/to/repo", default: true)



{:ok, _prompt_path} =

  PromptRunner.Packets.create_prompt(packet.root, %{

    "id" => "01",

    "phase" => 1,

    "name" => "Create hello file",

    "targets" => ["app"],

    "commit" => "docs: add hello file"

  })



{:ok, plan} = PromptRunner.plan(packet.root, interface: :cli)

{:ok, run} = PromptRunner.run(packet.root, interface: :cli)

{:ok, status} = PromptRunner.status(packet.root)

For embedded use, PromptRunner.run/2 defaults to an in-memory runtime store plus a no-op committer:

{:ok, run} =

  PromptRunner.run("/path/to/packet",

    provider: :codex,

    model: "gpt-5.4",

    committer: :noop,

    runtime_store: :memory

  )

Verification, Retry, and Repair

Prompt Runner no longer equates provider success with completion.

Each prompt can declare a deterministic completion contract with checks such as:

After every attempt, the runner verifies the contract:

Generate checklist views from the contract:

mix prompt_runner checklist sync demo

The checklist is derived output for humans. The verifier report in .prompt_runner/state.json remains the actual completion source of truth.

mix prompt_runner packet doctor also flags common authoring gaps before a packet run:

mix prompt_runner packet preflight is the machine-readable runtime readiness gate. It checks packet-local repo paths and git readiness, prints JSON, exits 0 when runtime-ready, and exits non-zero when the provider run should not start yet. CLI run calls packet preflight before invoking a provider; pass --skip-preflight only when you intentionally want the run path to handle packet readiness failures itself. Setup remains explicit: if a packet documents a setup command such as bash examples/.../setup.sh, run it before preflight.

CLI Entry Points

Use any of these:

Examples

Documentation

Development

mix test

mix format

mix credo --strict

mix dialyzer

mix docs

Dependency Sources

agent_session_manager and cli_subprocess_core resolve through the shared build_support/dependency_sources.exs helper, the same one vendored by the other repositories in this stack. Sibling checkouts win automatically when they exist next to this repository, then GitHub, then Hex:

mix deps.sources

# dependency sources:

#   agent_session_manager -> path (../agent_session_manager) -> 0.12.1

#   cli_subprocess_core -> path (../cli_subprocess_core) -> 0.4.1

To resolve against the published releases instead — which is what you want before packaging, and what CI sees — create a local, gitignored override:

# .dependency_sources.local.exs

%{

  deps: %{

    agent_session_manager: %{source: :hex},

    cli_subprocess_core: %{source: :hex}

  }

}

mix deps.get

mix test

mix hex.build

Packaging tasks (hex.build, hex.publish, hex.package) always resolve Hex sources regardless of the override, so package metadata stays Hex-clean. Note that the two modes share deps/ and mix.lock, so re-run mix deps.get after switching. Delete the override file to return to sibling checkouts.

License

MIT