DOCUMENTATION / PROJECT

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:

  1. Add a TypeScript regression test with an independently chosen expected result.
  2. 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.
  3. 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.