mdx-rust

A Rust-native safety loop for improving LLM agents.

mdx-rust points at an existing Rust agent, runs it on a small evaluation set, diagnoses weak behavior, proposes narrow edits, validates those edits in isolation, and only lands changes that pass Rust gates and improve the score.

The CLI is the supported product surface. The library crates are published for installation and inspection, but their APIs remain unstable before 1.0.

Current Scope

mdx-rust is an early public beta. It is useful for experimentation and dogfooding on Rust agent crates, but it is intentionally conservative. In plain terms: v0.2 is good at single-file, safety-gated prompt and fallback behavior improvements for Rust agents. It is not a general Rust refactoring engine yet.

Today it supports:

• Rust-aware source analysis with syn and tree-sitter-rust.
• Process-based agent invocation with lifecycle traces.
• Prompt and AST-guarded fallback-behavior improvement strategies.
• Single-file accepted edits only.
• Isolated validation with cargo check and cargo clippy -- -D warnings.
• Net-positive scoring, final real-tree validation, and rollback on failure.
• Versioned audit packets for accepted changes.
• JSON Schema derivations for agent-facing records such as candidates, hooks, traces, eval datasets, audit packets, and validation command records.
• Human CLI output plus machine-parseable --json output.
• Deterministic static audit checks for risky agent surfaces.

Not yet supported:

• Arbitrary multi-file accepted edits.
• General autonomous refactoring.
• Stable library APIs.
• Complete standalone scored mdx-rust eval.
• External hook runners.
• Multi-language optimization.

Safety Model

The acceptance contract is the center of the project:

1. Build a targeted ProposedEdit for one file.
2. Run pre-edit and pre-command hooks.
3. Apply the edit in an isolated workspace.
4. Run cargo check and cargo clippy -- -D warnings with timeouts.
5. Score the patched isolated workspace.
6. Require a strictly positive score delta.
7. Run pre-accept hooks.
8. Land the already validated edit on the real tree.
9. Run final validation on the real tree.
10. Roll back if final validation fails or times out.
11. Count the change as accepted only after landing and final validation pass.

The full non-bypass contract lives in SAFETY_INVARIANTS.md.

The implementation also uses typed rejection records and internal stage wrappers so accepted changes cannot be represented the same way as proposed or rejected candidates.

v0.2 ships with a narrow but parser-validated structural rewrite for common fallback patterns. Broader native Rust refactoring is planned for future releases.

Quick Start

Install the CLI:

cargo install mdx-rust

Try the built-in example from a checkout:

git clone https://github.com/dhotherm/mdx-rust
cd mdx-rust

cargo run -p mdx-rust -- init
cargo run -p mdx-rust -- register example examples/rig-minimal-agent
cargo run -p mdx-rust -- optimize example --iterations 2
cargo run -p mdx-rust -- audit example
cargo run -p mdx-rust -- invoke example --input '{"query":"What is 9 + 10?"}'

For your own Rust agent:

cd your-rust-agent
mdx-rust init
mdx-rust register my-agent .
mdx-rust optimize my-agent --iterations 3 --budget medium --review

Artifacts are written under .mdx-rust/agents/<name>/.

Key Commands

mdx-rust init
mdx-rust register my-agent ./path/to/agent
mdx-rust spec my-agent
mdx-rust doctor my-agent
mdx-rust audit my-agent
mdx-rust eval my-agent --dataset .mdx-rust/agents/my-agent/dataset.json
mdx-rust optimize my-agent --iterations 3 --budget medium --review
mdx-rust schema audit-packet --json

Every command intended for automation supports --json.

Audit Packets

Accepted changes produce versioned JSON audit packets in the experiment directory. The 0.2 schema records:

• Agent name and iteration.
• Single-file edit scope contract.
• Accepted diff and diff hash.
• Dataset version and hash.
• Policy path and hash when available.
• Scorer id and version.
• Diagnosis model metadata and whether a live model was used.
• Hook decisions.
• Isolated and final validation command outcomes.
• Baseline, patched, delta, and holdout scores.
• Rollback status if rollback was attempted.

See docs/provenance.md for the schema contract. Print the current audit-packet JSON Schema with:

mdx-rust schema audit-packet --json

API Stability

mdx-rust, mdx-rust-core, and mdx-rust-analysis are all published so the CLI can be installed from crates.io.

For 0.2.x:

• The mdx-rust CLI is supported.
• The mdx-rust-core and mdx-rust-analysis APIs are unstable.
• Public library types may change before 1.0.
• The intended facade is documented on docs.rs, but direct module usage is not a stability promise.

See docs/api-stability.md.

Project Docs

• SAFETY_INVARIANTS.md - acceptance loop and non-bypass rules.
• docs/architecture.md - module and lifecycle overview.
• docs/provenance.md - audit packet schema.
• docs/release-readiness.md - release gates and manual checks.
• ROADMAP.md - current scope and next work.
• CONTRIBUTING.md - development and safety expectations.

Contributor Rails

This repo uses a Justfile as the canonical local command surface:

just ci
just audit
just machete
just release-candidate

These commands mirror the public CI expectations and keep coding agents from guessing which checks matter.

Status

v0.2.0 is the first serious safety-first release. It is scoped, conservative, and ready for real users who are comfortable with an early public beta.

License

MIT