agent.run()
DOCUMENTATION / PROJECT
View MarkdownSource on GitHub

Based on AgentRun release · Synced .

Contributing

Use Node 24.11 or newer (.nvmrc pins 24.21.0) 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 build:daemon -w @parcha/agentrun-computer
npm run verify:packages

npm run verify:packages needs the computer daemon built first: npm run build:daemon -w @parcha/agentrun-computer (after the build, with Go on PATH, the version packages/computer/daemon/go.mod names or newer) writes dist/computerd-linux-amd64 and -arm64, which @parcha/agentrun-computer's archive must hold, and verification stops without them.

npm run build builds the console (apps/console, outside the workspaces, with its own lockfile) before the packages, so the server's build carries it. It installs the console's dependencies when npm's record of them differs from its lockfile, and skips the console's build when apps/console/dist was built from the same sources (a hash of them, written beside the build).

  • npm test runs every workspace's tests, several workspaces at once, with at most one test file per core in all (AGENTRUN_TEST_TOTAL=<n> sets that total, AGENTRUN_TEST_JOBS=<n> how many workspaces, 1 one by one), and ends with each one's result and time.
  • npm run test:changed runs only the workspaces changed since origin/main (npm run test:changed -- --base <ref> for another base), and every workspace that depends on them.
  • npm test -w @parcha/agentrun-dsl runs one workspace's tests.

Rounds run the affected suites; CI runs everything. npm run test:affected runs only the test files a change reaches since its merge base with origin/untangle/cutover (else origin/main; -- --base <ref> for another, or -- <path>... for given paths): a changed test file, every test that imports a changed source file directly or through other files (read from the imports, with dist/ mapped back to src/ and workspace names resolved through exports), every test of a package whose package.json, tsconfig or build script changed, and the tests that name a changed file where an import can't say (a fixture read by path). A change to the root manifests, scripts/ or .github/ adds only the tests that import it. A fast smoke file per package always runs. node scripts/test-affected.mjs prints the command per suite without running it, --list the files, --json why each was picked; --concurrency <n> caps each command on a shared machine. It is a round's check, not the record: CI on the pushed head runs every suite.

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.

A test that fails twice on CI with no cause in the change is flaky. Its owner can quarantine it, which skips it on CI only, for at most 24 hours: node scripts/quarantine.mjs --add <flake id> <file> <owner> "<test name>" "<why>" lists it in scripts/quarantine.json and prints the skip: to put on the test. At most three tests are quarantined at once. Once an entry expires, scripts/quarantine.test.mjs fails every pull request until the test is fixed and its entry removed. Locally the test still runs, and AGENTRUN_RUN_QUARANTINED=1 runs it on CI too.

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.