Make installing the repo give you the Go node as swe-planner, with the bundled coding engine as an opt-in preview

.env.example

@@ -1,21 +1,26 @@
-# --- Required (one of these) ---
+# --- Required: exactly one LLM provider key ---
+#
+# Uncomment ONE of the options below. Leave the others commented out: any
+# non-empty ANTHROPIC_API_KEY — including a leftover placeholder — makes
+# SWE-AF pick the claude_code runtime, which is exactly what you don't want
+# on an OpenRouter-only deployment.
+
+# Option A (recommended): OpenRouter — 200+ open and proprietary models
+# (DeepSeek, Qwen, Llama, MiniMax, GLM, Kimi, …). This is the only secret
+# needed to get started; GH_TOKEN below is optional.
+# With ONLY an OpenRouter key set (no ANTHROPIC_API_KEY, no SWE_DEFAULT_RUNTIME),
+# SWE-AF auto-selects the open_code runtime and defaults every role to
+# openrouter/deepseek/deepseek-v4-flash. Override with SWE_DEFAULT_MODEL.
+# OPENROUTER_API_KEY=sk-or-v1-...
 
-# Option A: Anthropic API key — used by claude-agent-sdk for all coding agents
-ANTHROPIC_API_KEY=sk-ant-api03-...
+# Option B: Anthropic API key — used by claude-agent-sdk for all coding agents
+# ANTHROPIC_API_KEY=sk-ant-api03-...
 
-# Option B: Claude Code subscription OAuth token (run `claude setup-token` to get it)
+# Option C: Claude Code subscription OAuth token (run `claude setup-token` to get it)
 # Uses your Pro/Max subscription credits instead of API billing
 # CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
 
-# Option C: Open-source models (DeepSeek, Qwen, Llama, MiniMax, etc.)
-# Access 200+ open-source and proprietary models via OpenRouter, OpenAI, or Google
-# Configure one or more API keys:
-
-# OpenRouter (recommended - 200+ models including DeepSeek, Qwen, Llama, MiniMax)
-# OPENROUTER_API_KEY=sk-or-v1-...
-# With ONLY an OpenRouter key set (no ANTHROPIC_API_KEY, no SWE_DEFAULT_RUNTIME),
-# SWE-AF auto-selects the open_code runtime and defaults to
-# openrouter/deepseek/deepseek-v4-flash. Override the model with SWE_DEFAULT_MODEL.
+# --- Optional: additional providers ---
 
 # OpenAI API-platform billing for OpenAI models and Codex api_key mode.
 # OPENAI_API_KEY=sk-...
@@ -52,6 +57,10 @@ ANTHROPIC_API_KEY=sk-ant-api03-...
 # AI_MODEL overrides the default model for the direct-LLM path (default gpt-4o).
 #   The coding loop passes the qa_synthesizer role model (default "haiku"), which
 #   WithModel overrides per call, so AI_MODEL is only the fallback default.
+#   WARNING: AI_MODEL is ALSO the second step of the role-model cascade
+#   (SWE_DEFAULT_MODEL → AI_MODEL → HARNESS_MODEL), so setting it here
+#   repoints every agent role too. To pick a model for the roles, set
+#   SWE_DEFAULT_MODEL instead and leave this one unset.
 # AI_MODEL=anthropic/claude-haiku-4.5
 
 # --- Optional: Web search (open runtime) ---
@@ -71,8 +80,11 @@ ANTHROPIC_API_KEY=sk-ant-api03-...
 # --- Optional: GitHub integration ---
 
 # GitHub personal access token (repo scope) — for draft PR creation
-# Only needed if using repo_url + enable_github_pr
-GH_TOKEN=ghp_...
+# Optional: builds on local and public repos run without it. Needed to clone
+# private repos, push branches, and open pull requests. Leave commented out
+# unless you have a real token — a placeholder value is worse than none,
+# because git and gh will try to authenticate with it and fail.
+# GH_TOKEN=ghp_...
 
 # --- Optional: Build-time test database ---
 
@@ -112,17 +124,22 @@ GH_TOKEN=ghp_...
 
 # Default runtime when callers don't pass a `runtime` in the request config.
 # Lets the deployer pick the runtime once instead of every caller threading
-# a config through. Falls back to claude_code if unset; an invalid value is
-# logged as a warning and ignored.
+# a config through. Unset = auto: open_code when an OpenRouter key is the
+# only provider credential, else claude_code. An invalid value is logged as
+# a warning and ignored. Leave this UNSET on an OpenRouter-only deployment —
+# auto-select already picks open_code and the deepseek-v4-flash default.
 # SWE_DEFAULT_RUNTIME=claude_code  # or: open_code, codex
 
 # Default model when callers don't pass `models` in the request config.
 # Applies to all 16 agent roles for whichever runtime is active. Caller
 # config (`models.default` or per-role keys) overrides this. Set this on
 # the deployment to pin a model without code changes — e.g. swap from
-# minimax-m2.5 to a newer release. Empty / unset → use the runtime's
-# baked-in defaults.
-# SWE_DEFAULT_MODEL=openrouter/minimax/minimax-m2.6
+# deepseek-v4-flash to a newer release. Empty / unset → use the runtime's
+# baked-in defaults (openrouter/deepseek/deepseek-v4-flash on open_code).
+# This is the variable to use for role model selection; AI_MODEL below is
+# part of the same cascade but is also the direct-LLM fallback, so prefer
+# this one.
+# SWE_DEFAULT_MODEL=openrouter/deepseek/deepseek-v4-flash
 
 # Per-tier models. Each of the 17 agent roles belongs to one of three tiers:
 #   high = planning-heavy reasoning (pm, architect, tech_lead, replan)
@@ -168,10 +185,43 @@ GH_TOKEN=ghp_...
 # {"runtime": "codex", "models": {"default": "gpt-5.3-codex"}}
 
 # Available open runtime model IDs (format: provider/model-name):
+#   openrouter/deepseek/deepseek-v4-flash  # the open_code default
 #   deepseek/deepseek-chat      # DeepSeek via OpenRouter
 #   minimax/minimax-m2.5        # MiniMax M2.5 via OpenRouter
 #   qwen/qwen-2.5-72b-instruct  # Qwen via OpenRouter
 #   openai/gpt-4o               # GPT-4 via OpenAI
 #   anthropic/claude-sonnet-4   # Claude via Anthropic
 #   zhipuai-coding-plan/glm-4.7 # GLM-4.7 via Z.AI direct (set ZHIPU_API_KEY)
 #   openrouter/z-ai/glm-5       # GLM-5 via OpenRouter (set OPENROUTER_API_KEY)
+
+# --- High-performance coding engine (Go node, ON by default) ---
+#
+# The Go node ships prebuilt coding engines — one per supported platform, at
+# go/bin/swe-pro-darwin-arm64 and go/bin/swe-pro-linux-amd64 — that take over
+# per-issue coding work. `af install` turns this on for you (the manifest
+# defaults it to 1): the engine registers as its own node on the control plane
+# and builds route their coding through it. Set it to 0 to use the classic
+# coding loop instead. If the binary is missing, the node logs a warning and
+# keeps using the classic loop.
+# SWE_PRO_ENGINE=0
+
+# Engine sidecar identity and reachability. In containers, set the public URL
+# so the control plane can reach the engine's callback (mirrors
+# AGENT_CALLBACK_URL on the SWE-AF nodes); the engine otherwise advertises
+# http://localhost:8801, which a control-plane container cannot reach.
+# SWE_PRO_NODE_ID=swe-pro
+# SWE_PRO_PORT=8801
+# SWE_PRO_PUBLIC_URL=http://swe-agent-go:8801
+# Only needed to point at an engine build outside the shipped layout: the node
+# already finds /usr/local/bin/swe-pro (Docker) or the swe-pro-<GOOS>-<GOARCH>
+# binary next to itself (an `af install` checkout).
+# SWE_PRO_BIN=/usr/local/bin/swe-pro
+
+# Engine model pools and reasoning effort. Unset keeps the engine's own
+# defaults (all OpenRouter ids, so an OpenRouter key is all it needs).
+# SWE_PRO_MODELS_HIGH=openrouter/deepseek/deepseek-v4-pro
+# SWE_PRO_MODELS_LOW=openrouter/deepseek/deepseek-v4-flash
+# SWE_PRO_VARIANT=low
+# Per-run USD ceiling. Unset = no per-run cap; set this on shared or
+# unattended deployments so a wide issue DAG cannot run away.
+# SWE_PRO_MAX_COST=5

README.md

@@ -232,7 +232,7 @@ af install https://github.com/Agent-Field/SWE-AF
 af run swe-planner
 ```
 
-`af install` clones the repo, provisions an isolated Python environment, and registers the `swe-planner` node with your control plane. On first `af run` you're prompted for the required secrets — an LLM provider key (`ANTHROPIC_API_KEY` **or** `OPENROUTER_API_KEY`) plus `GH_TOKEN` — which are stored encrypted and reused across every node, so you enter each only once. Then kick off a build:
+`af install` clones the repo, provisions an isolated Python environment, and registers the `swe-planner` node with your control plane. On first `af run` you're prompted for the one required secret — an LLM provider key (`ANTHROPIC_API_KEY` **or** `OPENROUTER_API_KEY`) — which is stored encrypted and reused across every node, so you enter it only once. (Add `GH_TOKEN` when you want builds to clone private repos and open pull requests.) Then kick off a build:
 
 ```bash
 af call swe-planner.build --in '{"goal": "Add JWT auth", "repo_url": "https://github.com/user/my-repo"}'
@@ -244,10 +244,14 @@ New to AgentField? Install the control plane first with `curl -fsSL https://agen
 
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/swe-af)
 
-One click deploys SWE-AF + AgentField control plane + PostgreSQL. Set two environment variables in Railway:
+One click deploys SWE-AF + AgentField control plane + PostgreSQL. Exactly **one** environment variable is required in Railway — an LLM provider key:
 
-- `CLAUDE_CODE_OAUTH_TOKEN` — run `claude setup-token` in [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (uses Pro/Max subscription credits)
-- `GH_TOKEN` — GitHub personal access token with `repo` scope for PR creation
+- `OPENROUTER_API_KEY` — **recommended, simplest**. One key, 200+ open and proprietary models. With only this set (no `ANTHROPIC_API_KEY`, no `SWE_DEFAULT_RUNTIME`), SWE-AF auto-selects the `open_code` runtime and defaults every role to `openrouter/deepseek/deepseek-v4-flash` — no further configuration needed.
+- *Alternative:* `ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token` in [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (uses Pro/Max subscription credits), to run the `claude_code` runtime instead.
+
+Optional:
+
+- `GH_TOKEN` — GitHub personal access token with `repo` scope. Needed only to clone **private** repos, push branches, and open pull requests; builds against public repos work without it.
 
 Once deployed, trigger a build:
 
@@ -509,16 +513,22 @@ Benchmark assets, logs, evaluator, and generated projects live in [`examples/age
 
 ```bash
 cp .env.example .env
-# Add your API key: ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY
-# Optionally add GH_TOKEN for PR workflow
+# Uncomment exactly ONE provider key: OPENROUTER_API_KEY (recommended),
+# ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, or GOOGLE_API_KEY
+# Optionally add GH_TOKEN (private-repo clones, pushing branches, opening PRs)
 
 docker compose up -d
 ```
 
+> `.env.example` ships with **every** provider key commented out — uncomment
+> exactly one. In particular, don't leave a placeholder `ANTHROPIC_API_KEY`
+> value in place: any non-empty value forces the `claude_code` runtime and
+> breaks an OpenRouter-only setup.
+
 Submit a build:
 
 ```bash
-# Default (Claude)
+# Default runtime (auto-selected from whichever provider key is in .env)
 curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \
   -H "Content-Type: application/json" \
   -d @- <<'JSON'
@@ -600,7 +610,9 @@ JSON
 
 Requirements:
 
-- `GH_TOKEN` in `.env` with `repo` scope
+- `GH_TOKEN` in `.env` with `repo` scope — required for *this* workflow, since
+  it clones private repos, pushes the branch, and opens the PR. Builds that
+  stay local (`repo_path`) or target a public repo don't need it.
 - Repo access for that token
 
 ### Post-PR CI gate
@@ -735,8 +747,8 @@ Notes for main-harness authors:
 - Cap your fan-out: each delegation is a paid multi-agent run. A handful of
   concurrent issues per repo is the sweet spot — the node also bounds its own
   concurrency.
-- Available identically on `swe-fast.implement_issue` and, in the Go port, on
-  `swe-planner-go` / `swe-fast-go`.
+- Available identically on `swe-fast.implement_issue`, and on the Go
+  implementation under those same node ids.
 
 A ready-made Claude Code skill for this flow ships in
 [`.claude/skills/delegate-issue/`](.claude/skills/delegate-issue/SKILL.md).
@@ -920,17 +932,33 @@ make clean-examples
 
 ---
 
-## Go implementation (opt-in)
+## Go implementation
 
-This repo also ships a Go port of the node under [`go/`](go/README.md). The
-**Python implementation is the default** — everything above is unchanged and
-still runs as `swe-planner` (`:8003`) / `swe-fast` (`:8004`). The Go port
-registers **separately** as `swe-planner-go` (`:8005`) and `swe-fast-go`
-(`:8006`), so both stacks can run against one control plane simultaneously.
-Opt in by targeting the `-go` reasoner path (e.g.
-`POST /api/v1/execute/async/swe-planner-go.build`). See
+The node under [`go/`](go/README.md) is what `af install` gives you, and it
+registers under the same ids as everything above — `swe-planner` and
+`swe-fast` — so no trigger, reasoner name, or API shape changes with it. The
+repo-root manifest declares itself `superseded_by` `//go`, so
+`af install https://github.com/Agent-Field/SWE-AF` lands there and replaces an
+existing Python install in place, keeping its node-scoped secrets.
+
+The Python implementation is unchanged and still what `python -m swe_af` and
+the compose stack in `docker-compose.yml` run. Because the two now answer to
+the same node ids, running both against one control plane needs an explicit
+`NODE_ID` on one of them — `docker-compose.go.yml` does that. See
 [`go/README.md`](go/README.md) for build, run, and Docker instructions.
 
+### Coding engine (opt-in preview)
+
+The Go node ships a prebuilt high-performance coding engine next to the
+classic coding loop. It is **inert by default** — nothing changes unless you
+set `SWE_PRO_ENGINE=1`. With the flag set, builds route per-issue coding
+through the engine; unset it and the node returns to the classic
+coder → reviewer/QA loop. If the binary isn't present, the node logs a
+warning and keeps using the classic loop, so the flag is safe to leave on.
+Tuning knobs (`SWE_PRO_VARIANT`, `SWE_PRO_MAX_COST`, `SWE_PRO_PUBLIC_URL`)
+and the full env surface are documented in
+[`go/docs/pro-engine.md`](go/docs/pro-engine.md).
+
 ---
 
 ### Also built on AgentField

agentfield-package.yaml

@@ -4,6 +4,21 @@ version: 0.1.0
 description: SWE planning/execution agent node (plans and executes software-engineering tasks)
 author: Agent-Field
 
+# The Go node in go/ is the maintained SWE node: same reasoners, same
+# interface, one static binary, and it ships the coding engine. Installing this
+# repo installs that instead — so `af install https://github.com/Agent-Field/SWE-AF`
+# is the one thing a user has to know, before and after the switch.
+#
+# go/ declares this same name deliberately, so the switch is a replacement in
+# place: same node id, same triggers, node-scoped secrets kept. Only one of the
+# two can be installed at a time, which is the point.
+#
+# This manifest stays here as the redirect, so the Python node is still what
+# `python -m swe_af` and the Docker images run. The redirect is a git-install
+# behaviour only: to install this node deliberately, clone the repo and install
+# the checkout as a local path.
+superseded_by: https://github.com/Agent-Field/SWE-AF//go
+
 entrypoint:
   start: python -m swe_af
   healthcheck: /health
@@ -28,16 +43,17 @@ user_environment:
           description: OpenRouter API key (DeepSeek/Qwen/Llama/… — 200+ models)
           type: secret
           scope: global
-  required:
-    # SWE-AF's core loop clones a repo, pushes a branch, and opens a pull
-    # request — all of which need GitHub write access. `gh`/`git` read this
-    # token for authentication (see prompts/github_pr.py). Required so setup
-    # prompts for it up front rather than failing partway through a build.
+  optional:
+    # `gh`/`git` read this token for authentication (see prompts/github_pr.py).
+    # Optional so an LLM key is the only secret needed to get started: builds
+    # on local/public repos run without it; it is needed to clone private
+    # repos, push branches, and open pull requests.
     - name: GH_TOKEN
-      description: GitHub token (repo scope) for cloning repos and opening pull requests
+      description: GitHub token (repo scope) — needed to clone private repos, push branches, and open pull requests
       type: secret
       scope: global
-  optional:
+    - name: SWE_DEFAULT_RUNTIME
+      description: Coding runtime for every role (claude_code | open_code | codex)
     - name: SWE_DEFAULT_MODEL
       description: Override the model id for every role (e.g. openrouter/deepseek/deepseek-v4-flash)
     - name: AGENTFIELD_SERVER

docker-compose.go.yml

@@ -2,8 +2,11 @@
 #
 # The Python docker-compose.yml is the DEFAULT stack (control plane + the Python
 # swe-planner/swe-fast nodes) and is left 100% untouched. This file adds ONLY
-# the two Go nodes, registered under DISTINCT identities so both stacks can run
-# against one control plane simultaneously:
+# the two Go nodes. Both implementations now default to the SAME node ids
+# (swe-planner / swe-fast) — they are one node, not siblings — so running them
+# together requires overriding NODE_ID here, which is what the services below
+# do. That override exists solely for side-by-side comparison; an installed Go
+# node keeps its own default ids.
 #
 #     swe-agent-go  ->  node id "swe-planner-go", :8005
 #     swe-fast-go   ->  node id "swe-fast-go",    :8006
@@ -45,11 +48,30 @@ services:
       - NODE_ID=swe-planner-go
       - PORT=8005
       - AGENT_CALLBACK_URL=http://swe-agent-go:8005
-      - SWE_DEFAULT_RUNTIME=${SWE_DEFAULT_RUNTIME:-claude_code}
+      # Empty = auto: open_code when only an OpenRouter key is present,
+      # else claude_code. A baked claude_code fallback here would break
+      # OpenRouter-only deployments.
+      - SWE_DEFAULT_RUNTIME=${SWE_DEFAULT_RUNTIME:-}
       - SWE_DEFAULT_MODEL=${SWE_DEFAULT_MODEL:-}
       - SWE_CODEX_AUTH_MODE=${SWE_CODEX_AUTH_MODE:-auto}
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
       - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN:-}
+      - GH_TOKEN=${GH_TOKEN:-}
+      # High-performance coding engine. The on-by-default behaviour belongs to
+      # `af install` alone (its manifest injects SWE_PRO_ENGINE=1); a checkout
+      # running in production keeps the binary's own default — off — so export
+      # SWE_PRO_ENGINE=1 to enable it here. The public URL must be
+      # container-reachable: the engine otherwise advertises
+      # http://localhost:8801, which the control plane cannot reach from its
+      # own container.
+      - SWE_PRO_ENGINE=${SWE_PRO_ENGINE:-}
+      - SWE_PRO_PUBLIC_URL=${SWE_PRO_PUBLIC_URL:-http://swe-agent-go:8801}
+      - SWE_PRO_MODELS_HIGH=${SWE_PRO_MODELS_HIGH:-}
+      - SWE_PRO_MODELS_LOW=${SWE_PRO_MODELS_LOW:-}
+      - SWE_PRO_VARIANT=${SWE_PRO_VARIANT:-}
+      - SWE_PRO_MAX_COST=${SWE_PRO_MAX_COST:-}
       # Go direct-LLM path (run_qa_synthesizer via the SDK ai.DefaultConfig
       # client). An OPENAI/OPENROUTER key enables it; AI_BASE_URL/AI_MODEL
       # override the endpoint/default model. No key -> deterministic fallback.
@@ -76,9 +98,9 @@ services:
       - NODE_ID=swe-fast-go
       - PORT=8006
       - AGENT_CALLBACK_URL=http://swe-fast-go:8006
-      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
-      - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN}
-      - GH_TOKEN=${GH_TOKEN}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN:-}
+      - GH_TOKEN=${GH_TOKEN:-}
       - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
       - GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
@@ -87,7 +109,8 @@ services:
       - AI_BASE_URL=${AI_BASE_URL:-}
       - AI_MODEL=${AI_MODEL:-}
       - OPENCODE_MODEL=${OPENCODE_MODEL:-}
-      - SWE_DEFAULT_RUNTIME=${SWE_DEFAULT_RUNTIME:-claude_code}
+      # Empty = auto (see swe-agent-go note).
+      - SWE_DEFAULT_RUNTIME=${SWE_DEFAULT_RUNTIME:-}
       - SWE_DEFAULT_MODEL=${SWE_DEFAULT_MODEL:-}
       - SWE_CODEX_AUTH_MODE=${SWE_CODEX_AUTH_MODE:-auto}
       # build-db lives in the Python stack; reachable over the shared network.