feat: full Go port of SWE-AF on the AgentField Go SDK

[AbirAbbas]

Summary

Complete 1:1 port of SWE-AF from Python to Go using the AgentField Go SDK, per the full-transition plan. The Python implementation stays untouched during the transition; the Go module lives under go/ with two binaries (swe-planner :8003, swe-fast :8004).

Parity contract honored:

• Every reasoner is separately registered under its exact Python name — swe-planner exposes 30 (build, plan, execute, resolve, resume_build + 25 roles), swe-fast exposes 29 (25 roles + fast build/fast_plan_tasks/fast_execute_tasks/fast_verify). No grouping, no simplification.
• All inter-reasoner calls go through agent.Call (control-plane routed), so the execution DAG renders identically — the control plane builds edges solely from X-Run-ID/X-Parent-Execution-ID, which the Go SDK sets identically to Python.
• API surface unchanged: same input parameter names/defaults, same snake_case result JSON (pydantic non-zero defaults reproduced via UnmarshalJSON seeding), same registration tags as Python's routers.
• Prompts ported byte-verbatim (golden tests fixture-generated from the live Python builders), checkpoint JSON round-trips Python-written checkpoint.json for resume compatibility, verbatim error strings and note messages throughout.

Update (2026-07-10): repositioned as an opt-in sibling, not a drop-in replacement

The Go port no longer shadows the Python node's identity. It now registers under distinct default identities so both stacks can run against a single control plane at the same time: swe-planner-go on :8005 and swe-fast-go on :8006 (the Python nodes remain the default — swe-planner :8003 / swe-fast :8004 — and are completely untouched). Callers opt in per request by targeting the -go reasoner path, e.g. POST /api/v1/execute/async/swe-planner-go.build; NODE_ID/PORT env overrides still work.

docker-compose.go.yml is now an add-on to the Python stack rather than a parallel copy of it: bring up the Python stack first (docker compose up -d, which owns the control plane), then docker compose -f docker-compose.go.yml up -d to add the Go nodes (they join the Python stack's network/volume as external references). All Python code, the root Dockerfile/compose, and existing instructions are byte-for-byte unchanged — every diff lives under go/, docker-compose.go.yml, and a single new root-README section.

Also since the last push: a zero-LLM e2e harness (go/test/e2e-fast/run.sh, mock claude CLI) that runs the full pipeline (plan → DAG → control loops → verify → push → PR → CI gate) in ~60s and passes against the new -go identity, plus a CI-gate fix (gh pr checks invalid headSha JSON field; benign "no checks reported" now yields no_checks instead of error).

Key implementation notes

• HITL: the Go SDK has no Agent.Pause(); the plan-approval and ask-user flows use the SDK's poll-based RequestApproval/WaitForApproval (execution still shows waiting in the UI). Hax is called via its REST API directly, replicating the Python SDK's payload.
• ReasonerFailed(result=...): replicated without SDK changes — the node posts status=failed + structured result + error to the executions status endpoint, then errors (contract verified against a live control plane).
• Deployment: af install is Python-only, so the Go nodes ship via go/Dockerfile (multi-stage; agentfield SDK pinned via AGENTFIELD_SDK_REF build arg for cache-busting) and docker-compose.go.yml mirroring the Python stack. Dev builds use a go.work + replace directive against the sibling repo.
• Bug found by the functional suite: the nodes now register AGENT_CALLBACK_URL as their public URL — without it every containerized deployment got 504 agent_unreachable from the control plane.

Known accepted differences (documented in go/docs/port/)

• Poll-based HITL resume (latency) instead of webhook-instant.
• Harness metrics carry no cost_usd (Go SDK gap; candidate SDK patch).
• Harness schema_mode="incremental" has no Go counterpart (single-shot + schema retries instead).
• A few empty-collection edges marshal null where pydantic emits [] (role fallbacks seed the important ones explicitly).

Test plan

• go build ./... && go vet ./... && go test ./... — whole module green (27 packages, includes -race on concurrency-heavy packages).
• Black-box functional suite (go test -tags functional ./go/test/functional/) against a live compose stack: health, exact registration parity (30+29 names), result key-set parity, failed-with-result status contract. All PASS; stack torn down after.
• docker build -f go/Dockerfile . succeeds; docker compose -f docker-compose.go.yml config validates.
• Python suite untouched and green in a clean env (python3.12 -m pytest tests/, compileall): zero Python files changed; the only local failures reproduce identically on unmodified main (env leakage from .env via load_dotenv + a sibling repo's editable install shadowing tests.conftest) and cannot occur in CI.
• LLM-gated end-to-end build + DAG-parity test (SWE_FUNCTIONAL_LLM=1, implemented in go/test/functional/build_llm_test.go) — requires an Anthropic key; run before flipping production traffic.

Docs

go/docs/port/ carries the design doc, work breakdown, and the two research reports (Python inventory, Go SDK gap analysis) the port was executed from; go/README.md covers build/run/deploy.

Update: external-review fixes (2026-07-10)

Adversarial review of the port surfaced six fixes, applied against the pinned SDK
(agentfield PR #750, feat/install-path-selector @ 45311737), which now adds a
native result-carrying agent.ReasonerFailed, real JSON-schema validation inside
the harness retry loop, and codex/opencode structured-output fixes. This supersedes
the two "known differences" above about the manual ReasonerFailed carrier and
null empty collections.

1. Null lists → [] — a reflection walker (schemas.EmptyForNilSlices) plus
   DAGState.MarshalJSON and harnessx.Run normalization ensure every list field
   serialises as [] (pydantic rejects present-but-null lists); dict|None fields
   (workspace_manifest, git_init_result, tests_passed, …) legitimately stay null.
2. Pydantic-faithful schemas — now that the SDK validates harness output against
   the reflected schema, schemaFor adds enum constraints (via JSONSchemaExtend),
   replaces invopop's all-fields required with the pydantic no-default set, relaxes
   additionalProperties, and makes Optional/map fields nullable — so valid output
   is no longer over-rejected while invalid enum values now are.
3. QA-synthesizer LLM path — BuildAgent now sets AIConfig (guarded; nil when
   no key), making the direct-LLM branch reachable; short model aliases
   (haiku/sonnet/opus) are mapped to provider ids when the client targets
   OpenRouter. Env vars documented in .env.example and docker-compose.go.yml.
4. Native agent.ReasonerFailed — the empty-build guard returns the SDK's
   result-carrying &agent.ReasonerFailed; the manual internal/reasonerfail
   POST-then-error carrier is deleted.
5. Data race + gofmt — mutex-guarded the fast/orch concurrent test doubles so
   go test -race ./... is clean; formatted the two gofmt-flagged files.
6. SDK pin + CI — bumped AGENTFIELD_SDK_REF to 45311737 (Dockerfile + Makefile,
   plus the new indirect santhosh-tekuri/jsonschema dep the SDK harness pulls in),
   and added a go CI job (sparse-clone the SDK at the pin, then
   gofmt/build/vet/test -race; the existing Python job is untouched).

Also normalized mockclaude output so the zero-LLM e2e harness stays schema-valid
under the new SDK validation. Validation: gofmt / go build / go vet /
go test -race green in both workspace and GOWORK=off modes;
docker compose -f docker-compose.go.yml config valid; the full mock e2e pipeline
(go/test/e2e-fast/run.sh) passes end-to-end against a live control plane with
zero schema-validation retries; Python suite unchanged and green.

---

🤖 Generated with Claude Code

[AbirAbbas]

Update: SDK-native parity landed on this branch — the poll-based HITL workaround has been replaced with the Go SDK's new webhook-resumed Agent.Pause() (commit 2a47045), so approval resume is now instant, matching Python's app.pause exactly.

Merge-order dependency:

1. Merge feat(sdk/go): Agent.Pause webhook approvals, harness cost reporting, incremental schema mode agentfield#744 first (Agent.Pause + harness cost_usd + incremental SchemaMode — all CI green).
2. Then bump AGENTFIELD_SDK_REF in go/Dockerfile on this branch to the post-merge agentfield SHA (one line; cache-busts the SDK layer).
3. feat(control-plane): af install support for Go agent nodes agentfield#745 (af install Go-node support, also green) is independent — it unlocks installing this node via af install with the Go manifest documented there.

Schema-mode and cost needed no SWE-AF changes: Python SWE-AF's effective schema mode is single-shot (never passes schema_mode; SDK default), which Go's unset default already matches, and Result.CostUSD flows through the harness layer automatically.