Documentation for AgentRun 0.1.0-beta.27. Use the matching setup instructions → GitHub’s main branch may include unreleased changes.
Contributing
Use Node 22.19+ and npm 11.21.0. From the repository root:
npm install --global npm@11.21.0 --ignore-scripts
npm ci --ignore-scripts
npm run check
npm run verify:packages
Tests use scripted adapters and must not require model credentials. Package verification installs built tarballs into a separate application and needs network access to download dependencies. Live examples are opt-in.
Keep provider configuration and application policy outside the interpreter. Integrate through runNode, runJudge, or runEffect. For a behavior change, add a test that reproduces the failure and checks the result a caller depends on. Keep expected outcomes independent of the implementation. Mock external services at adapter boundaries.
Record a change in changes/<slug>.md, one file per pull request (front matter naming its packages and kind, then the text of one changelog bullet; see changes/README.md). Never edit an Unreleased section: node scripts/changes.mjs --check fails a change that does, and the release folds the files into the changelogs. Document breaking changes and failure behavior there. After changing workflow types, regenerate the editor schema with node scripts/generate-schema.mjs. For installation or packaging changes, also run npm run export:source and npm run verify:source. The source verifier builds the exported archive in an empty directory and exercises the offline examples.
Changing workflow behavior
The optional Lean specification is a contributor tool for checking selected execution rules. It is not a runtime dependency. Its proofs apply to the model under stated assumptions; shared tests check agreement with TypeScript on a finite set of cases, not equivalence for every workflow.
When changing validation, state paths, branch merges, loops, or desugaring:
- Add a TypeScript regression test with an independently chosen expected result.
- Check whether the change affects the model or its assumptions. Update the Lean definitions and proofs when it does, and add a shared conformance case where applicable.
- Install elan, then run these checks after
npm run build:
node --test packages/dsl/test/lean-conformance.test.mjs packages/dsl/test/lean-findings.test.mjs
node spec/lean/sweep/collect.mjs spec/lean/.lake/validator-corpus.json
cd spec/lean
lake build
lake exe conformance
lake exe validator-sweep .lake/validator-corpus.json
The collector runs the DSL, Pi and example suites with a plain node --test, so at node's default concurrency (every core). On a shared machine pass --test-concurrency <n> (node spec/lean/sweep/collect.mjs --test-concurrency 8 spec/lean/.lake/validator-corpus.json) or set TEST_CONCURRENCY=<n>; the flag wins, and with neither node's default is unchanged.
lake build checks the proofs and their assumptions. Conformance cases compare execution results; the sweep checks that workflows accepted by TypeScript in the collected corpus are also accepted by the model. Review expected-result changes before accepting them. Do not update fixtures merely to make a changed implementation pass.
Changing recovery behavior
spec/receipts/Receipts.tla and spec/lean/AgentRunRecovery/Frozen.lean model what a recovery driver does with effects across crashes, failed commits and the host's cancel. A change to modeled behavior changes the model in the same pull request: the recovery hooks in workflow.ts, the RecoveryStore contract in packages/dsl/src/recovery/, or a driver over it. With Java 11+ and tla2tools.jar:
TLA2TOOLS=/path/to/tla2tools.jar scripts/spec/check-receipts.sh
TLA2TOOLS=/path/to/tla2tools.jar node scripts/spec/receipts-mutants.mjs
cd spec/lean && lake build
If the model does not need to change, say why in the pull request. Never delete a property to make a check pass: fix the code, or record the counterexample with a test that reproduces it. CI runs the TLA+ checks when a change touches spec/receipts/ or scripts/spec/, and every night on main.
The findings table distinguishes runtime fixes, validation gaps, and documented limits. Documentation-only changes do not require installing Lean. CI runs the Lean checks separately from npm run check.
The website is maintained separately in a private repository. Send website feedback through this repository's issues. Documentation illustrations in this repository have their own asset instructions.
Code and documentation use Apache-2.0. Unless you explicitly state otherwise, contributions submitted for inclusion use that license. Preserve third-party notices. This repository requires no separate contribution licensing agreement.