agent-run

Imported from DKotsyuba/agent-run (AGENTS.md). Install upstream with npx skills add DKotsyuba/agent-run. Copyright stays with the author.

Working on agent-run

agent-run is a Rust supervisor for other coding agents. Reliability, durable evidence, process ownership, and secret safety are product requirements.

Ground rules

• Use the pinned Rust toolchain and the committed Cargo.lock. Prefer the standard library and existing workspace dependencies.
• Keep modules focused. Add tests for every behavior change.
• Agent-task harnesses are created only through adapters and the supervisor. Configured quota commands use the bounded external collector runner; shipped collectors query metadata without starting model turns.
• Preserve unrelated work and never weaken lifecycle assertions to hide flakes.
• Release workflows publish only the qualified macOS Apple-silicon artifact. Linux x86-64 remains visible as non-blocking validation; its release and qualification are deferred.

Invariants

• The domain dispatcher owns one public tool table shared by CLI, MCP, and the Unix-socket JSON-RPC server.
• agent-run start submits through the resident broker; it never silently runs asynchronous work under the one-shot CLI process.
• SQLite schema changes require a numbered migration, current-schema update, version bump, and historical migration tests.
• Bad inputs and domain failures remain typed across all transports.
• A successful outcome must be derivable from durable answer, completion, process-identity, and cleanup evidence.
• Process groups are signalled only while the recorded leader identity is verified alive. Do not trade PID-reuse safety for unconditional cleanup.
• Delivery diagnostics are immutable, bounded to 4096 UTF-8 bytes, and never persist messages, session ids, arguments, environment values, or credentials.
• Configuration reloads compare the file SHA-256 every 60 seconds and at request boundaries. Invalid revisions never replace the last valid configuration.
• Release directories remain immutable and must pass manifest plus COMPLETE verification before pointer switching.

Layout

Verification

cargo xtask check
cargo xtask archive --verify
cargo build --locked --release --package agent-run --bin agent-run
node --test scripts/check-desktop-transport.cjs

If a transport changed, add a live API/MCP smoke. If an adapter or supervisor changed, identify the fixture or real-engine run proving it. agent-run doctor must remain clean. Release and deployment procedures are in docs/releasing.md.