feat(substrate): bump agent substrate to 0.0.8

Adapts kagent for substrate v0.0.8's atespace-scoped ActorRef identity
model (rename of ActorId→ActorRef{Atespace,Name} on all actor RPCs). Maps
atespace 1:1 to the SandboxAgent/AgentHarness Kubernetes namespace, adds
an EnsureAtespace idempotent helper, and updates the atenet-router Host
header shape to include the atespace label.

Also fixes a pre-existing kagent bug that PR #2109's ActorTemplate spec
immutability change surfaced: SnapshotsConfig.{OnPause,OnCommit} were
left zero-value in kagent's desired spec but the API server defaults
them to "Full" on admission, causing apiequality.Semantic.DeepEqual to
report drift every reconcile and hot-loop delete/recreate the
ActorTemplate CR.

Verified end-to-end on colima+kind with substrate v0.0.8 published
charts: SandboxAgent (declarative Go) and AgentHarness (openclaw) both
reach Ready=True and chat round-trip works.

Author: jjamroga

Makefile

@@ -150,6 +150,7 @@ KMCP_VERSION ?= $(shell $(AWK) '/github\.com\/kagent-dev\/kmcp/ { print substr($
 # Substrate
 SUBSTRATE_ENABLED ?= false
 SUBSTRATE_VERSION ?= $(shell $(AWK) '/github\.com\/kagent-dev\/substrate/ { print substr($$5, 2) }' go/go.mod) # Substrate version defaults to the replace target in go.mod
+SUBSTRATE_REPO ?= oci://ghcr.io/kagent-dev/substrate/helm # Override for local dev when consuming a locally-published chart, e.g. oci://localhost:5001/kagent-dev/substrate/helm
 
 HELM_ACTION=upgrade --install
 
@@ -453,8 +454,8 @@ helm-tools: ## Package all tool Helm charts into the dist folder
 .PHONY: helm-version
 helm-version: ## Stamp chart versions, update dependencies, and package kagent + kagent-crds
 helm-version: helm-cleanup helm-agents helm-tools
-	VERSION=$(VERSION) KMCP_VERSION=$(KMCP_VERSION) SUBSTRATE_VERSION=$(SUBSTRATE_VERSION) envsubst < helm/kagent-crds/Chart-template.yaml > helm/kagent-crds/Chart.yaml
-	VERSION=$(VERSION) KMCP_VERSION=$(KMCP_VERSION) SUBSTRATE_VERSION=$(SUBSTRATE_VERSION) envsubst < helm/kagent/Chart-template.yaml > helm/kagent/Chart.yaml
+	VERSION=$(VERSION) KMCP_VERSION=$(KMCP_VERSION) SUBSTRATE_VERSION=$(SUBSTRATE_VERSION) SUBSTRATE_REPO=$(SUBSTRATE_REPO) envsubst < helm/kagent-crds/Chart-template.yaml > helm/kagent-crds/Chart.yaml
+	VERSION=$(VERSION) KMCP_VERSION=$(KMCP_VERSION) SUBSTRATE_VERSION=$(SUBSTRATE_VERSION) SUBSTRATE_REPO=$(SUBSTRATE_REPO) envsubst < helm/kagent/Chart-template.yaml > helm/kagent/Chart.yaml
 	helm dependency update helm/kagent
 	helm dependency update helm/kagent-crds
 	helm package -d $(HELM_DIST_FOLDER) helm/kagent-crds

examples/substrate-openclaw/README.md

@@ -6,14 +6,37 @@ Follow these instructions to install Substrate on a kind cluster. This feature a
 
 This assumes you've configured a kind cluster using `make create-kind-cluster`.
 
-Create a `substrate-values.yaml` file:
+### Image-pull args for a local (kind) registry
+
+atelet is what pulls the ActorTemplate container image for each golden actor. It uses
+`go-containerregistry` directly (not containerd), so containerd's registry-mirror
+config on the kind node does **not** apply to atelet — you have to tell atelet how to
+reach the local kind registry with its own flags:
 
 ```yaml
 atelet:
+  # Skip the GCP application-default-credentials probe. Substrate defaults this
+  # to true (for GKE + Artifact Registry); on kind it just adds latency and a
+  # noisy log line before falling back to anonymous auth.
+  gcpAuthForImagePulls: false
+
+  # Rewrite `localhost:PORT/...` image refs (which is what `make helm-install`
+  # renders when `--set registry=localhost:5001` is in effect) to a hostname
+  # that atelet's puller can actually resolve from inside its pod. atelet also
+  # applies `name.Insecure` for any ref that was originally `localhost:*`, so
+  # the rewritten `kind-registry:5000` ref is fetched over HTTP (kind-registry
+  # is `registry:2` with no TLS by default). Without both parts of this — the
+  # rewrite AND the insecure flag it triggers — atelet errors out with either
+  #   `dial tcp [::1]:5001: connect: connection refused`  (no rewrite), or
+  #   `http: server gave HTTP response to HTTPS client`   (rewrite without Insecure).
   extraArgs:
     - --localhost-registry-replacement=kind-registry:5000
 ```
 
+When installing Substrate as a **subchart** of kagent (i.e. `--set substrate.enabled=true`
+on the kagent chart), prefix these keys with `substrate.` — e.g.
+`--set-json 'substrate.atelet.extraArgs=["--localhost-registry-replacement=kind-registry:5000"]'`.
+
 Then install the Substrate platform and kagent:
 
 ```bash

go/api/httpapi/substrate.go

@@ -37,6 +37,7 @@ type SubstrateActorTemplateEntry struct {
 // SubstrateActorEntry is runtime state from ate-api (redis).
 type SubstrateActorEntry struct {
 	ActorID                string `json:"actorId"`
+	Atespace               string `json:"atespace,omitempty"`
 	Status                 string `json:"status"`
 	ActorTemplateNamespace string `json:"actorTemplateNamespace,omitempty"`
 	ActorTemplateName      string `json:"actorTemplateName,omitempty"`

go/core/internal/a2a/substrate_sandbox_transport.go

@@ -72,7 +72,7 @@ func (t *substrateSandboxSessionRoundTripper) RoundTrip(req *http.Request) (*htt
 
 	// Proxy the A2A request through atenet-router to the session actor. The router
 	// selects the actor by HTTP Host; actor ID comes from EnsureSessionActor above.
-	actorRT, err := newSubstrateAgentRoundTripper(t.routerURL, res.Handle.ID, t.base)
+	actorRT, err := newSubstrateAgentRoundTripper(t.routerURL, res.Handle.Atespace, res.Handle.ID, t.base)
 	if err != nil {
 		return nil, err
 	}

go/core/internal/a2a/substrate_transport.go

@@ -14,8 +14,8 @@ type substrateAgentRoundTripper struct {
 	base      http.RoundTripper
 }
 
-func newSubstrateAgentRoundTripper(routerURL, actorID string, base http.RoundTripper) (http.RoundTripper, error) {
-	target, host, err := substrate.GatewayRouterTarget(routerURL, actorID)
+func newSubstrateAgentRoundTripper(routerURL, atespace, actorID string, base http.RoundTripper) (http.RoundTripper, error) {
+	target, host, err := substrate.GatewayRouterTarget(routerURL, atespace, actorID)
 	if err != nil {
 		return nil, err
 	}

go/core/internal/httpserver/handlers/agentharness_gateway.go

@@ -83,7 +83,7 @@ func (h *Handlers) HandleAgentHarnessGateway(w ErrorResponseWriter, r *http.Requ
 		return
 	}
 
-	target, upstreamHost, err := h.resolveSubstrateGatewayTarget(r.Context(), ensureRes.Handle.ID)
+	target, upstreamHost, err := h.resolveSubstrateGatewayTarget(r.Context(), ensureRes.Handle.Atespace, ensureRes.Handle.ID)
 	if err != nil {
 		log.Info("resolve substrate gateway target failed", "error", err)
 		http.Error(w, err.Error(), http.StatusServiceUnavailable)
@@ -99,19 +99,20 @@ func (h *Handlers) HandleAgentHarnessGateway(w ErrorResponseWriter, r *http.Requ
 	// explicitly suspends a session via the suspend endpoint.
 }
 
-func (h *Handlers) resolveSubstrateGatewayTarget(ctx context.Context, actorID string) (*url.URL, string, error) {
+func (h *Handlers) resolveSubstrateGatewayTarget(ctx context.Context, atespace, actorID string) (*url.URL, string, error) {
 	cfg := h.AgentHarnessGateway
 	if cfg == nil {
 		return nil, "", fmt.Errorf("substrate gateway is not configured")
 	}
 
 	actorID = strings.TrimSpace(actorID)
-	target, host, err := substrate.GatewayRouterTarget(cfg.AtenetRouterURL, actorID)
+	target, host, err := substrate.GatewayRouterTarget(cfg.AtenetRouterURL, atespace, actorID)
 	if err != nil {
 		return nil, "", fmt.Errorf("substrate actor %q: %w", actorID, err)
 	}
 	ctrllog.FromContext(ctx).WithName("agentharness-gateway").Info(
 		"proxying via atenet-router",
+		"atespace", atespace,
 		"actor", actorID,
 		"router", target.String(),
 		"host", host,

go/core/internal/httpserver/handlers/agentharness_gateway_test.go

@@ -14,7 +14,7 @@ import (
 
 func TestACPProxyForwardsToAtenetRouterWithActorHost(t *testing.T) {
 	t.Parallel()
-	const actorHost = "ahr-kagent-my-claw.actors.resources.substrate.ate.dev"
+	const actorHost = "ahr-kagent-my-claw.kagent.actors.resources.substrate.ate.dev"
 
 	var gotHost, gotAuth, gotPath string
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -56,9 +56,9 @@ func TestACPProxyForwardsToAtenetRouterWithActorHost(t *testing.T) {
 
 func TestACPProxyRewriteTargetsAtenetRouterHost(t *testing.T) {
 	t.Parallel()
-	const actorHost = "ahr-kagent-my-claw.actors.resources.substrate.ate.dev"
+	const actorHost = "ahr-kagent-my-claw.kagent.actors.resources.substrate.ate.dev"
 
-	target, host, err := substrate.GatewayRouterTarget(substrate.DefaultAtenetRouterURL, "ahr-kagent-my-claw")
+	target, host, err := substrate.GatewayRouterTarget(substrate.DefaultAtenetRouterURL, "kagent", "ahr-kagent-my-claw")
 	if err != nil {
 		t.Fatal(err)
 	}

go/core/internal/httpserver/handlers/substrate.go

@@ -205,6 +205,7 @@ func (h *SubstrateHandler) listAteAPIState(ctx context.Context, namespaces []str
 func actorEntryFromPB(a *ateapipb.Actor) api.SubstrateActorEntry {
 	return api.SubstrateActorEntry{
 		ActorID:                a.GetActorId(),
+		Atespace:               a.GetAtespace(),
 		Status:                 substrate.ActorStatusLabel(a.GetStatus()),
 		ActorTemplateNamespace: a.GetActorTemplateNamespace(),
 		ActorTemplateName:      a.GetActorTemplateName(),

go/core/pkg/sandboxbackend/async.go

@@ -9,8 +9,12 @@ import (
 
 // Handle is the opaque identifier an AsyncBackend uses to address a sandbox
 // it owns on an external control plane. Persisted in AgentHarness.Status.BackendRef.
+//
+// For Substrate backends, Atespace scopes the ID — an actor's identity on
+// substrate is (Atespace, ID). Non-substrate backends may leave Atespace empty.
 type Handle struct {
-	ID string
+	ID       string
+	Atespace string
 }
 
 // EnsureResult is returned by EnsureAgentHarness. Endpoint (if set) is surfaced

go/core/pkg/sandboxbackend/substrate/actor_reachability.go

@@ -18,7 +18,7 @@ const (
 )
 
 type actorGetter interface {
-	GetActor(ctx context.Context, actorID string) (*ateapipb.Actor, error)
+	GetActor(ctx context.Context, atespace, actorID string) (*ateapipb.Actor, error)
 }
 
 // waitForActorReachableViaAtenet blocks until ate-api reports the actor RUNNING and
@@ -27,7 +27,7 @@ func waitForActorReachableViaAtenet(
 	ctx context.Context,
 	actors actorGetter,
 	httpClient *http.Client,
-	routerURL, actorID string,
+	routerURL, atespace, actorID string,
 ) error {
 	if actors == nil {
 		return fmt.Errorf("substrate ate-api client is required")
@@ -43,7 +43,7 @@ func waitForActorReachableViaAtenet(
 	waitCtx, cancel := context.WithTimeout(ctx, defaultActorReachabilityTimeout)
 	defer cancel()
 
-	target, host, err := GatewayRouterTarget(routerURL, actorID)
+	target, host, err := GatewayRouterTarget(routerURL, atespace, actorID)
 	if err != nil {
 		return err
 	}
@@ -53,7 +53,7 @@ func waitForActorReachableViaAtenet(
 	defer ticker.Stop()
 
 	for {
-		actor, getErr := actors.GetActor(waitCtx, actorID)
+		actor, getErr := actors.GetActor(waitCtx, atespace, actorID)
 		if getErr == nil && actor.GetStatus() == ateapipb.Actor_STATUS_RUNNING {
 			statusCode, probeErr := probeActorViaAtenetRouter(waitCtx, httpClient, probeURL, host)
 			if probeErr == nil && statusCode < http.StatusInternalServerError {