feat: make AForge exec the default runtime

[AbirAbbas]

Status update — agentfield v0.1.130 is released; this PR is ready

Everything below the line was written against the 0.1.129 pin and is kept for history. What is true on the current head:

• Pins bumped: Python agentfield>=0.1.130 (pyproject, requirements.txt, requirements-docker.txt); Go sdk/go v0.1.130 (go/go.mod/go.sum), go/Dockerfile + .github/workflows/ci.yml + go/Makefile AGENTFIELD_SDK_REF → the v0.1.130 commit. This bump was required, not optional: the Go node's new aforge default was unusable on the July SDK pin (unknown harness provider: "aforge"). The ~25-release SDK jump needed zero source changes.
• "Known gaps" resolved: 0.1.130 reads AGENTFIELD_AFORGE_COMMAND (exec default), honours AFORGE_BIN, and passes --timeout/--turns. README/.env.example/go README wording updated. sdk/go/vX.Y.Z tags now exist (release workflow publishes them).
• Live verification (real OpenRouter key, ANTHROPIC_API_KEY unset, no runtime override): both images built with default args from agentfield.ai + PyPI (aforge v0.1.0, agentfield 0.1.130; go version -m on the Go binary shows sdk/go v0.1.130); all four nodes registered on a fresh agentfield/control-plane:latest. Go swe-planner-go.implement_issue on a tiny repo → success: true, correct add() + passing pytest, 2 commits, 60 s; Python swe-fast.build → success: true, verification 3/3, 333 s. .aforge/trace/1.trace.log present in both worktrees; live argv aforge exec --json … --timeout 1795 --turns … --context-fill 60 --completion-reserve 65536. SWE_DEFAULT_RUNTIME=claude_code flips runtime/harness provider (Py + Go tests). CI (make check 1211 passed; Go build/vet/test -race) green on the pushed head.

---

What & why

Makes AForge the default SWE runtime, and — new in this revision — makes the PR
actually installable and buildable.

Three things in the original revision could not work:

1. The image did not exist. The Dockerfile did
   FROM ghcr.io/agent-field/aforge-v2:chat-v2-exec. The aforge-v2 source repo
   is private and no such image is published, so the build could never succeed
   for anyone.
2. The dependency pin was not installable. All three dependency files
   pointed at agentfield @ git+...@bfd34426#subdirectory=sdk/python — a commit
   that exists only on the draft agentfield#905 branch, on no published index.
3. Only half the product moved. go/ was untouched, so the Go
   implementation of swe-planner still resolved OpenRouter-only installs to
   open_code while the shared README and manifests said aforge.

Distribution: download + verify, not a container image

The Dockerfile now has an aforge fetch stage that downloads the released
binary and checksum-verifies it before it enters the image:

ARG AFORGE_BASE_URL=https://agentfield.ai/downloads/aforge
ARG AFORGE_VERSION=v0.1.0

1. GET ${AFORGE_BASE_URL}/${AFORGE_VERSION}/aforge-linux-${TARGETARCH}.gz
2. gunzip to /out/aforge
3. GET .../checksums.txt — its hashes are of the decompressed binaries —
   rewrite the matching "<sha256> aforge-linux-<arch>" line to name the local
   file, sha256sum -c
4. chmod +x + aforge --help smoke, so a corrupt or wrong-arch download fails
   the build, not the deploy

COPY --from=aforge /out/aforge /usr/local/bin/aforge as before. Both ARGs stay
overridable for mirrors/air-gapped registries, and AFORGE_VERSION is part of
the layer cache key — bumping it is what pulls a newer AForge; a floating URL
alone would keep restoring the cached binary. Applied to go/Dockerfile too,
and ca-certificates is now explicit in the Python runtime stage (aforge speaks
HTTPS to openrouter.ai).

Commits

Commit	Scope
feat(runtime): add aforge as a runtime and default it on OpenRouter	Python: runtime vocabulary, mappings, model table, default flip
feat(go): mirror the aforge runtime and default on the Go node	go/internal/{runtimex,config,fast,orch,roles}
build(docker): fetch and checksum-verify the released aforge binary	Dockerfile, go/Dockerfile
build(deps): re-pin agentfield to the published PyPI release	pyproject.toml, requirements*.txt
feat(runtime): prefer OpenRouter over Anthropic when both keys are set	isolated behaviour change — see below
docs(config): document the aforge default, the download pinning, and the gaps	READMEs, .env.example, manifests, compose
ci: build the aforge fetch stage when the download host is reachable	.github/workflows/ci.yml

The precedence change is its own commit

feat(runtime): prefer OpenRouter over Anthropic when both keys are set is
deliberately isolated so it can be reviewed — or reverted — on its own.

Before, _openrouter_only_env() returned False whenever ANTHROPIC_API_KEY was
non-empty, so a deployment holding both keys resolved to claude_code.
After, only an explicit SWE_DEFAULT_RUNTIME vetoes the OpenRouter choice.

Anyone with both keys set and no SWE_DEFAULT_RUNTIME silently switches harness
and model family (sonnet/haiku → openrouter/deepseek/deepseek-v4-flash-0731)
and starts spending on OpenRouter instead of Anthropic. Opt-out:
SWE_DEFAULT_RUNTIME=claude_code. Reverting that one commit restores the old
precedence and leaves the rest of the aforge work intact.

Validation contract

Observable behaviours this change must exhibit:

• With OPENROUTER_API_KEY set and no SWE_DEFAULT_RUNTIME, both nodes resolve
  the default runtime to aforge on the main, fast, issue and planning paths.
• With only ANTHROPIC_API_KEY, the default stays claude_code.
• With both keys and no SWE_DEFAULT_RUNTIME, the default is aforge
  (the isolated precedence commit; reverting it returns claude_code).
• SWE_DEFAULT_RUNTIME=open_code still resolves to open_code — the rollback
  is configuration-only and OpenCode stays installed in the image.
• The aforge runtime maps to a harness provider the pinned SDK actually
  registers, and resolves to openrouter/deepseek/deepseek-v4-flash-0731.
• A stock docker build . produces an image with a working aforge on PATH
  whose sha256 equals the release checksums.txt entry for aforge-linux-amd64.
• A tampered/absent download fails the build rather than shipping.
• pip install -e . resolves from PyPI, with no VCS dependency.
• Python and Go implementations of swe-planner agree on every resolution above.

How this was verified

Every gate the CI workflow runs, plus real container runs.

CI gates (workflow steps run literally, Python 3.12 / Go 1.23 semantics):

• pip install -e ".[dev]" → resolves agentfield-0.1.129 from PyPI.
• make check → 1211 passed, 1 skipped + compileall clean.
• gofmt -l . clean · go build ./... ok · go vet ./... ok ·
  go test -race -count=1 ./... all packages ok.
• ruff check . — 789 findings, byte-identical to the count on origin/main
  (pre-existing; CI does not run ruff).

Fetch stage, against a local mirror of the published layout:

#7 [aforge 4/4] RUN set -eu; arch="amd64"; curl -fsSL .../aforge-linux-${arch}.gz ...
#7 1.548 aforge: OK          <- sha256sum -c against the release checksums

Python image (docker build ., then run):

$ docker run --rm --entrypoint sh <img> -c 'command -v aforge; sha256sum /usr/local/bin/aforge'
/usr/local/bin/aforge
61217a18135f392d50c337d971fa5b228f436f8df144800b37fbb340020c79f5  /usr/local/bin/aforge

That hash is exactly the release checksums.txt line for aforge-linux-amd64.
aforge --help prints the CLI usage; pip show agentfield → 0.1.129.

Real end-to-end exec inside the image (OPENROUTER_API_KEY supplied at run
time, tiny budget):

$ docker run --rm -e OPENROUTER_API_KEY --entrypoint sh <img> \
    -c 'mkdir -p /tmp/w && echo "Reply with exactly OK" | aforge exec --json -w /tmp/w --timeout 120 --budget 20000 --turns 3'
{"text":"OK","stop":"done","usage":{"calls":1,"prompt_tokens":3548,"completion_tokens":2,"cost":0.000279172992},"artifacts":[],"turns":1,"elapsed_ms":14789}
EXIT=0

Default resolution inside the container (no test tree in the image, so the
config surface is exercised directly):

OPENROUTER_API_KEY only:
  _default_runtime()        : aforge
  BuildConfig().runtime     : aforge -> ai_provider aforge
  ExecutionConfig().runtime : aforge
  FastBuildConfig().runtime : aforge
  harness adapter           : aforge
  SDK SUPPORTED_PROVIDERS   : ['aforge', 'claude-code', 'codex', 'gemini', 'grok', 'opencode']
  built provider            : AforgeProvider  bin=aforge
both keys                   : aforge
ANTHROPIC_API_KEY only      : claude_code
SWE_DEFAULT_RUNTIME=open_code: open_code

Go image (docker build -f go/Dockerfile .): same verified aforge binary at
/usr/local/bin/aforge (identical sha256), AGENTFIELD_AFORGE_COMMAND=exec,
swe-planner / swe-fast / swe-pro all present.

Go default resolution vs. the pinned SDK (throwaway probe, not committed):

DefaultRuntime()      = "aforge"
DefaultFastRuntime()  = "aforge"
harness adapter       = "aforge"
BuildProvider("aforge") err = unknown harness provider: "aforge" (supported: claude-code, codex, gemini, opencode)

That last line is the Go-side gap, called out below.

CI job bash was executed under bash --noprofile --norc -eo pipefail before
committing: the probe correctly reports available=false for the not-yet-live
public host and available=true against a reachable one.

Test images and containers were removed afterwards.

Known gaps — these are what keep the PR in draft

1. The download host does not serve this version yet. The Dockerfile
default AFORGE_BASE_URL / AFORGE_VERSION point at
https://agentfield.ai/downloads/aforge/v0.1.0/ — aforge-v2's first semver
release. The host is live and already serves the older build-<sha>
coordinate, but v0.1.0/checksums.txt is still a 404 there. Everything above
was verified against a local mirror of exactly that layout via
--build-arg AFORGE_BASE_URL=.... Nothing in the tree references anything but
the public URL.

2. AFORGE_BIN and AGENTFIELD_AFORGE_COMMAND are no-ops today. On
agentfield 0.1.129 the aforge provider always runs
aforge exec --json -w <root> and always resolves the binary as aforge from
PATH; neither env var is read. They are accepted by the deployment surface and
documented as no-ops. It also passes no --timeout, so aforge's own
15-minute wall fires before the SDK-side AGENTFIELD_HARNESS_TIMEOUT_SECONDS
(default 1800s). Both start working with the release carrying agentfield#905.

Exact lines to bump when that release lands:

pyproject.toml:13            "agentfield>=0.1.129",
requirements.txt:5           agentfield>=0.1.129
requirements-docker.txt:5    agentfield>=0.1.129

3. The Go node's aforge default cannot run yet. The Go SDK pinned by
AGENTFIELD_SDK_REF has no aforge harness provider —
harness.BuildProvider("aforge") returns
unknown harness provider: "aforge" (supported: claude-code, codex, gemini, opencode).
The default is flipped for parity and the gap is documented at DefaultRuntime
and in go/README.md; until the pin moves, the Go node must be pointed at
another runtime with SWE_DEFAULT_RUNTIME. Three lines move together:

go/go.mod:8                          github.com/Agent-Field/agentfield/sdk/go v0.0.0-20260723130821-20955b2637b4
go/Dockerfile (ARG AGENTFIELD_SDK_REF=20955b2637b4708758c328a4f64fe460c7d4b772)
.github/workflows/ci.yml (env AGENTFIELD_SDK_REF: 20955b2637b4708758c328a4f64fe460c7d4b772)

4. CI cannot build the full image yet. The new aforge-fetch-stage job
probes the download host and, while it is unreachable, emits a notice and
passes. It reads the coordinates out of the Dockerfile so it cannot drift from
what the image builds. Once the host is live, swap --target aforge for a full
docker build . and this becomes the image-build gate.

5. Not touched, on purpose. sec-af/… is not applicable to this change.
AForge already embeds swe-pro (AFORGE_SWEPRO=1), so SWE-AF's own pro-engine
vendoring (go/bin/swe-pro-*, SWE_PRO_ENGINE) is deliberately left exactly as
it is — collapsing the two is a separate decision.

Un-drafting checklist

• https://agentfield.ai/downloads/aforge/v0.1.0/ serves the gzipped
  binaries + checksums.txt (the release assets exist; publishing them to
  the download host is the remaining step)
• agentfield#905 is merged and released; bump the three agentfield>=…
  lines above
• bump the three AGENTFIELD_SDK_REF / go.mod locations to that release,
  so the Go node's aforge default resolves to a real provider
• flip the CI job from --target aforge to a full image build

Follow-ups (out of scope here)

• The image bakes ENV HARNESS_MODEL=openrouter/moonshotai/kimi-k2.6 for
  OpenCode's small_model interpolation, and HARNESS_MODEL sits in the
  SWE_DEFAULT_MODEL → AI_MODEL → HARNESS_MODEL cascade. So inside the image
  every role resolves to kimi-k2.6, not the
  openrouter/deepseek/deepseek-v4-flash-0731 the docs advertise. Pre-existing
  on main, unrelated to this change, but worth a dedicated fix.
• Multi-arch: the fetch stage already keys on TARGETARCH and the release ships
  linux/arm64, but nothing here builds or publishes an arm64 image.

🤖 Generated with Claude Code