PyPI version Python 3.12+ License

Millrace signal mark

Millrace

Millrace is a durable runtime for compiler-validated agent workflows.

Millrace v0.22.3 provides governed context and durable public controls. Install the exact millrace==0.22.3 bundle on Python 3.12 or newer; see Getting Started. Existing v0.22.2 workspaces use store schema 8; this release requires fresh schema-11 state and provides no in-place migration. Finish or retire old work with its matching runtime, preserve its workspace, and initialize a new one. See compatibility.

Ever find yourself doing the same thing over and over with AI agents?

You construct the plan. You tell it to execute the plan, then you have another agent check the first agent's work. It finds issues, so you tell it to fix those issues. Any time a new blocker comes up, you ask it to troubleshoot the issue and fix it before moving on. You rinse and repeat until there's no more bugs and everything matches the initial plan.

All you did was manage which agent performs which role at which time. If you sketched the entire process on paper, you would find a manually driven workflow graph: stages connected by completion, failure, recovery, and escalation outcomes. An agent can generally be relied upon to execute any single step on its own, but owning the entire workflow end to end? No agent is owning that reliably (yet). And this is where Millrace comes in.

flowchart TD
    W["Workflow package<br/>stages, routes, rules"] --> C["Compiler<br/>validate and freeze"]
    C --> P["Selected plan<br/>immutable authority"]
    P --> R["Durable runtime<br/>queues, runs, waits"]
    R -->|"bounded dispatch"| A["Agent runner<br/>Codex, Millforge"]
    A -->|"candidate evidence"| V{"Valid under<br/>selected plan?"}
    P -.->|"governs"| V
    V -->|"yes"| T["Commit state transition"]
    T --> R
    V -->|"no"| X["Refuse, retry,<br/>or wait for operator"]
    X --> R

If your workflow can be described as stages, outcomes, and transitions, Millrace can compile it into an executable plan. Completion moves to the next step, failure moves to bugfixing, and a hard blocker escalates to automated recovery. You can have as many recovery mechanisms or branching paths as you like, and the compiler makes sure you're only running valid plans.

Millrace made its compiled workflow graph authoritative over agent execution on April 23, 2026, months before "graph engineering" became a category. A prior-art audit found only one earlier comparable open-source implementation: Dagu v2.5.0. Review the definition, dated evidence, and prior-art audit.

For more information, check out the FAQ.

Start With Your Agent

Millrace is agent-first. Give this repository to a capable local agent:

Install Millrace for me in this workspace using https://github.com/tim-osterhus/millrace. Read its README and published instruction manual first. Check the CLI, workspace, workflows, and runners. Report what you installed and what you need next. Do not store credentials in workflow assets or start unattended work.

Then delegate work:

Use Millrace to govern this work: <goal and constraints>. Choose an official workflow, explain why, start with a bounded run, and report the selected plan, state, waits, and evidence.

Manual setup is documented in Getting started.

Runtime Rules

  • The selected plan defines legal stages, routes, assets, runners, and outcomes.
  • Queues, runs, waits, traces, and artifacts survive restarts.
  • Each stage receives only its selected assets and context.
  • Model output is evidence, not runtime truth.
  • Retries, reroutes, pauses, and operator decisions remain on record.
  • Exact run pause/resume preserves authority and budgets for supported unstarted/native states; pending acceptance is distinct from verified pause. See control boundaries.
  • Operator dispatch suspension gates only new claim acceptance. Already accepted or active work keeps its durable authority.
  • Queue cancellation closes eligible workflow work through the normal audited close-work transition. It never deletes queue state or signals a runner.
  • Supported commands change state; direct file edits do not.

Governed Context

Millrace v0.22.3 is a general governed-context/runtime-integrity release. Compiled bindings distinguish required files from catalog-only discoverable material. Catalog content stays in CAS until an exact, bounded millrace context select request hydrates a read-only selection.

The runtime enforces selected-root mutation policy before applying runner results, records source-backed attribution without turning unavailable values into zeros, and removes only derived session material after durable completion. Compiled plans advance to schema 18. Context-bound plans using the unreleased schema-17 shape are historical evidence, not compatible plans; import and select a schema-18 plan before running it.

See the v0.22.3 release notes.

Workflows

millrace-plus provides:

  • simple_loop: plan, run, review, and bounded recovery;
  • planning.lad and execution.lad: separate planning and execution graphs;
  • execution.lad_integrator and lad.full: integrated LAD workflow variants;
  • vendor_selection: policy checks, parallel evaluation, and an operator gate.

These are package data, not hard-coded kernel behavior.

Documentation

Getting started · How Millrace works · Graph authority and prior art · Runner-session architecture · Daemon lifecycle · Workflow packages · Millforge runner · Codex runner · Errors · Migrating from v0.21 · v0.22 support

Millrace v0.22 is local and single-operator. Foreground execution supports Linux, macOS, and WSL. The new public daemon lifecycle controls currently qualify process identity on macOS only.

License

Apache License 2.0

Project links

Data verified by PyPI on Sep 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tim-osterhus from gravatar.com tim-osterhus

Credits

Author: Tim Osterhus

GitHub Statistics

Data verified by PyPI on Sep 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

millrace_ai-0.22.3.tar.gz (634.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

millrace_ai-0.22.3-py3-none-any.whl (657.0 kB view details)

Uploaded Python 3

File details

Details for the file millrace_ai-0.22.3.tar.gz.

File metadata

  • Download URL: millrace_ai-0.22.3.tar.gz
  • Upload date:
  • Size: 634.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for millrace_ai-0.22.3.tar.gz
Algorithm Hash digest
SHA256 4f500e6e474fa087dbc0f8a5d8f8f137370a71d9a04d4663f67eb6af37acf6eb
MD5 cd77278055b56596a23cea1c4f163ce2
BLAKE2b-256 4ae124ba6e7bb44770bdee755e7cc60d651959703f869d2a3e471759da547248

See more details on using hashes here.

Provenance

The following attestation bundles were made for millrace_ai-0.22.3.tar.gz:

Publisher: publish-to-pypi.yml on tim-osterhus/millrace

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file millrace_ai-0.22.3-py3-none-any.whl.

File metadata

  • Download URL: millrace_ai-0.22.3-py3-none-any.whl
  • Upload date:
  • Size: 657.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for millrace_ai-0.22.3-py3-none-any.whl
Algorithm Hash digest
SHA256 5e87f92f2330af30395f35860d319db7e5574367da7995a3613276d0a08f163d
MD5 2a2d37b889d2b3b5f0fbb61dad83c393
BLAKE2b-256 95a4851b5eec3fe71a7305e1e7b90f3382fc4eba704788e1aca4606c5c14b3e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for millrace_ai-0.22.3-py3-none-any.whl:

Publisher: publish-to-pypi.yml on tim-osterhus/millrace

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.22.3 This release

2 files

0.22.2

2 files

0.22.0

2 files

0.21.1

2 files

0.21.0

2 files

0.20.3

2 files

0.20.2

2 files

0.20.1

2 files

0.20.0

2 files

0.19.0

2 files

0.18.6

2 files

0.18.5

2 files

0.18.4

2 files

0.18.3

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

1 file

0.16.3

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.9

2 files

0.15.8

2 files

0.15.7

2 files

0.15.6

2 files

0.15.5

2 files

0.15.4

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

0.13.0

2 files

0.12.5

2 files

0.12.4

2 files

0.12.3

2 files

0.12.2

2 files

0.12.1

2 files

0.12.0

2 files

0.11.5

2 files

0.11.4

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page