Agent proofs assert the Generic chart 1.x contract: HelmRelease → AgentTemplate + per-agent RemoteMCPServer, commit-pinned skills, 1.x range; one agent helper; the v1alpha2 proofs, dispatch and heals retire with 4.0

[teemow]

Plan: giantswarm/bumblebee-plans#51 (PRD: D7, D8, D12, D14; grill Q4 "Generic chart 1.x stays"; "agent-manager (D8, D10, D11)") · Epic: giantswarm/giantswarm#37705

Problem

agentlab's v2 proofs (v0.28) assert the POC's agent shape: agent-manager and the portal path write an AgentTemplate plus a toolset-carrier RemoteMCPServer muster-<agent> directly, admitted by the label kagent.dev/harness: kagent. The released-line proofs (*_v1.go: Agent CRs delivered as HelmReleases, A2A through the kagent UI route) run behind a served-CRD dispatch (agentCRDServed()), and the Agent-CR heals (the golang-adk image heal, the iconUrl CRD patch) are skipped when the CRD is absent.

The decided shape is different (D7, D8, D12, grill Q4): the Generic chart 1.x stays the agent unit. A HelmRelease per agent renders the AgentTemplate (description, system prompt, model, tools, skills, display-name annotation, a new icon-URL annotation, the Harness label) and — unless the toolset is preset:none — a RemoteMCPServer named after the agent carrying X-Muster-Toolset. Skills are {name, git: {url, commit}, path} (or {name, oci: <digest>}) entries pinned at write time: agent-manager's create_agent/update_agent pin them, list_skills returns the default branch's commit, update_agent gains refreshSkills. agent-manager reads readiness from status.harnesses[] and reports ready/progressing/failed. The per-namespace OCIRepository carries the range 1.x, not x.x.x. Once meta chart 4.0 is the released line and the lab's default chart version is 4.x, no released kagent serves agents.kagent.dev any more: the dispatch, the v1 proofs and the heals are dead code the PRD removes ("the v1alpha2 CRD probe is removed; a single helper knows how an agent is created and when it is ready", D14). Today three spellings of "create an agent and know when it is ready" coexist (agent-manager's get_agent_status, the direct AgentTemplate helper, the portal composer).

Proposed solution

agents-test, toolsets-test and models-test assert the 1.x contract on the line that ships it (dev builds first, the released 4.0 after): agent-manager's create writes a HelmRelease as the caller (managedFields) whose render is the AgentTemplate on the platform Harness — the admission label as connectivity 4.0 and chart 1.x define it (the PRD names agent-platform.giantswarm.io/harness: kagent; the dev channel today uses kagent.dev/harness) — and the per-agent RemoteMCPServer with the toolset header, none for preset:none; the HelmRelease's values.toolset stays the stable anchor; the OCIRepository range is 1.x; a create with a git skill from a public repository lands a full-commit entry on the template (the fixture of #137), list_skills returns commits, refreshSkills re-pins to the current head; get_agent_status agrees with status.harnesses[]; get_agent/update_agent keep their shape minus the runtime field. One helper in the lab knows how an agent is created and when it is ready, and every proof uses it (models-test's throwaway, toolsets-test's fixtures, backstage-test's own template). When 4.0 is the released line: DefaultChartVersion moves to 4.x; the served-CRD dispatch, *_v1.go, the iconUrl CRD patch and the golang-adk heal are deleted with their tests; docs/agents.md describes API v2 as the only line; the related HACKS entries are closed or re-scoped; the stable and dev channels run the same proofs.

Dependencies: giantswarm/agent#25 (chart 1.0), agent-manager 1.0 (giantswarm/agent-manager#37), connectivity 4.0 for the Harness label (#138). Until they ship, the proofs stay on the dev channel's POC shape; the helper consolidation can start now.

Acceptance criteria

• On a lab running Generic chart 1.x, agent-manager 1.0 and connectivity 4.0, agents-test, toolsets-test and models-test pass asserting: the HelmRelease written by agent-manager as the caller; the rendered AgentTemplate with the Harness label, Ready on the platform Harness; the per-agent RemoteMCPServer with the toolset header and none for preset:none; the OCIRepository range 1.x; values.toolset on the HelmRelease. — proven 2026-09-11 18:51Z on agentlab-dev2 (agent-platform 4.7.11, agent-manager 1.1.1, chart 1.1.0, agentlab v0.35.0): agents-test 36 s (6 PASS; 37 s again after the rebase onto main), toolsets-test 82 s (11 PASS), models-test --backend ollama 47 s (4 PASS); connectivity 4.7.11, OCIRepository agent at 1.x → 1.1.0, values.toolset on every HelmRelease, RemoteMCPServer with X-Muster-Toolset and none for preset:none.
• Skills: a create with a git skill from a public repository lands a full-commit entry on the AgentTemplate, list_skills returns the commit, update_agent with refreshSkills re-pins, and the template reaches Ready with the skill. — proven 2026-09-11 18:51Z on agentlab-dev2 (agent-platform 4.7.11, agent-manager 1.1.1, chart 1.1.0, agentlab v0.35.0): agents-test 36 s (list_skills returns https://github.com/giantswarm/agent-skills @ cb1fb768bbbb, the create lands agent-self-awareness @ cb1fb768bbbb on the AgentTemplate, update_agent with refreshSkills re-pins to that head, Ready on Harness kagent) and skills-test 34 s (Ready in 14 s, the turn answers from the skill).
• get_agent_status agrees with status.harnesses[] for ready, progressing and failed (a template no Harness admits is reported not ready with a reason — user story 14). — proven 2026-09-11 18:51Z on agentlab-dev2 (agent-platform 4.7.11, agent-manager 1.1.1, chart 1.1.0, agentlab v0.35.0): agents-test 36 s: ready on revision 4a4904753187 agrees with status.harnesses[]; a template on Harness agentlab-no-such-harness is reported failed with the not-admitted reason. Progressing is passed through during the same wait, not asserted as a separate state.
• One helper creates an agent and waits for its readiness for every proof; the three spellings are gone. — done in feat(proofs): the agent proofs assert the Generic chart 1.x contract — one agent helper, the v1alpha2 dispatch and heals retire #155 (merged 2e775a3, v0.35.0): internal/lab/agent.go (agentSpec, agentWriter, waitAgentReady) is the one path for agents-test, toolsets-test, models-test, skills-test and backstage-test.
• With 4.0 as the released line: DefaultChartVersion is 4.x; the served-CRD dispatch, *_v1.go, the Agent-CR heals and their tests are removed; docs and HACKS are updated; every proof passes on a fresh lab from published artifacts only, on both channels. — partly done: DefaultChartVersion is 4.7.11 (feat(platform): the lab runs the 4.x line as an installation does — Substrate and the platform Postgres from the chart, JWT Strict on the controller route, a measured preflight budget, every image side-loaded #156, v0.34.0); the served-CRD dispatch, *_v1.go, the Agent-CR heals and their tests are removed and docs/HACKS updated (feat(proofs): the agent proofs assert the Generic chart 1.x contract — one agent helper, the v1alpha2 dispatch and heals retire #155, v0.35.0); every agent proof passes on agentlab-dev2 (see above). Still open: a run of every proof on a fresh lab from published artifacts only. "On both channels" is obsolete — the dev channel was retired with feat(platform): the lab runs the 4.x line as an installation does — Substrate and the platform Postgres from the chart, JWT Strict on the controller route, a measured preflight budget, every image side-loaded #156. — the last part done 2026-09-12: every proof passed on a lab brought up from published artifacts only (agentlab down && up on the released 3.23.1, upgraded in place to the released 4.7.15 — the migration rehearsal, Migration rehearsal: a 3.x lab seeded with v1alpha2 agents in the four fleet shapes upgrades in place to meta chart 4.0 and agent-manager's migrate Job, before any installation does #143 / feat(proofs): the migration rehearsal — a 3.x lab seeded with the four fleet shapes upgrades in place to the 4.x line and agent-manager's migrate Job is asserted through expand, contract and no-op #162, recipe in v0.40.0), agentlab v0.39.1: platform-test 2 s, test 0 s, agents-test 27 s, toolsets-test 71 s, skills-test 41 s, a2a-test 43 s, backstage-test 74 s (25 checks), klaus-gateway-test 43 s, models-test --backend ollama 63 s, each leaving the lab as it found it. Not claimed for "both channels": the dev channel is retired (feat(platform): the lab runs the 4.x line as an installation does — Substrate and the platform Postgres from the chart, JWT Strict on the controller route, a measured preflight budget, every image side-loaded #156), the released channel is the only one.

Working rule: kagent, Substrate and related upstream projects

General rule of epic giantswarm/giantswarm#37705, carried on every sub-issue.

Implementing this epic will surface bugs and gaps in kagent, Substrate and the projects around them (kmcp, agentgateway, the Go ADK, the harnesses). For each of them:

1. Check upstream first. Search the upstream repository's issues and pull requests, open and closed (kagent-dev/kagent, kagent-dev/substrate, kagent-dev/kmcp, …), and the rows already collected in giantswarm/giantswarm#37742. If upstream tracks it or a pull request is in flight, we align with that work — test it, review it, add our evidence — rather than open a competing change.
2. Change it in our fork. A change we need lands as a carried patch on the consumed branch of our line — giantswarm/kagent-upstream for kagent, giantswarm/substrate for Substrate, the giantswarm/ fork of any other upstream project (created on the same pattern when there is none). One commit per patch, written upstream-ready (upstream's conventions and tests, DCO sign-off, nothing Giant Swarm-specific in it), recorded in the fork's ledger (FORK.md).
3. Prepare the upstream pull request in the fork; do not open it yet. The upstream-facing branch and pull-request text are prepared in the fork and listed as a row in giantswarm/giantswarm#37742 — that list is the review queue. Nothing is opened against upstream before the team has reviewed it there. We send in considered batches and only what is useful to upstream, never a stream of Giant Swarm-specific changes.
4. Giant Swarm-specific behaviour never goes upstream. It lives in the meta chart, the connectivity chart, or in a patch the ledger marks as ours to keep.

Upstream issues we want to file follow the same path: collected in giantswarm/giantswarm#37742, reviewed by the team, then filed.

[teemow]

Evidence from the first lab on a released 4.x chart (agentlab v0.32.0, configure --chart-version 4.5.2 --substrate, a platform.valuesFiles overlay for what the release requires — kagent.harness.snapshotLocation, substrate.rustfs.enabled, the JWKS of the controller route, gateway.jwksEgress, kagent.substrateWorkerPool.workerImage at the chart's Substrate pin; 2026-09-11):

• platform-test 4/4 and test 10/10 pass; backstage-test passes every sign-in and muster hop and fails only in its trailing v2 step: it writes the AgentTemplate with kagent.dev/harness=kagent, the platform Harness of 4.x admits agent-platform.giantswarm.io/harness: kagent (agenttemplate.go harnessLabel), so status.harnesses[] stays empty for 4 min.
• agents-test fails at create_agent: agent-manager 1.1.1 reports created={helmRelease:true, ociRepository:true} — the Generic chart 1.x contract — where the proof wants the AgentTemplate and its toolset carrier written directly. The release path works: the HelmRelease (agent chart 1.0.3) reconciled to the AgentTemplate + per-agent RemoteMCPServer, Ready on Harness kagent ("ActorTemplate golden snapshot is ready"), and a turn through the gateway (JWT Strict, trusted-proxy controller) completed.
• skills-test fails for two dev-channel shapes: the template binds RemoteMCPServer muster (ResolvedRefs=False … "muster": not found — 4.x renders no shared server, the agent chart renders one per agent) and the cleanup reads Substrate through the REST path /kagent (HTTP 406 — the route is a GRPCRoute now). Through agent-manager the same skill agent (agent-self-awareness @ cb1fb768) was Ready in <30 s and answered the skill's fact through the gateway.
• The lab's own Substrate (dev pin …h213d76b) was adopted by the chart's substrate component by release name and upgraded to 0.0.27-gs.2 — so --substrate on a ≥4.3 chart already rehearses an installation's hand-over; The lab runs the meta chart 4.0 topology as an installation will: Substrate and the platform Harness from the chart (up stops installing Substrate), JWT Strict on the controller route, a measured preflight budget, every image side-loaded #138's "up stops installing Substrate" is the clean variant.

Also seen, outside this issue: the first turn on a cold worker hit Substrate's un-retried 5 s ResumeActor deadline (oci_unpack of the Go ADK image 4.94 s) and wedged its AgentInstance; every later restore took 0.25 s (giantswarm/giantswarm#37742 row 12).