Merge branch 'main' into jetc/feat/a2a-v1-migration-a

Author: jmhbh

.github/workflows/ci.yaml

@@ -81,7 +81,7 @@ jobs:
       - name: Install agent-sandbox
         run: |
           kubectl apply -f "https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml"
-          kubectl wait --for=condition=Established crd/sandboxes.agents.x-k8s.io --timeout=90s
+          timeout 90s bash -c 'until [ "$(kubectl get crd sandboxes.agents.x-k8s.io -o jsonpath="{.status.conditions[?(@.type==\"Established\")].status}" 2>/dev/null)" = "True" ]; do sleep 1; done'
           kubectl rollout status deployment/agent-sandbox-controller -n agent-sandbox-system --timeout=120s
           kubectl wait --for=condition=Ready pod -l app=agent-sandbox-controller -n agent-sandbox-system --timeout=120s
 

Makefile

@@ -279,7 +279,7 @@ build-golang-adk-full: buildx-create
 .PHONY: build-skills-init
 build-skills-init: ## Build and push the skills-init image
 build-skills-init: buildx-create
-	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) -t $(SKILLS_INIT_IMG) -f docker/skills-init/Dockerfile docker/skills-init
+	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) -t $(SKILLS_INIT_IMG) -f docker/skills-init/Dockerfile ./go
 	$(DOCKER_PUSH) $(SKILLS_INIT_IMG)
 
 .PHONY: push

docker/skills-init/Dockerfile

@@ -1,24 +1,39 @@
-### Stage 0: build krane
-FROM golang:1.26-alpine AS krane-builder
-
-ENV KRANE_VERSION=v0.21.2
-WORKDIR /build
-
-RUN apk add --no-cache git && \
-    git clone --depth 1 --branch $KRANE_VERSION \
-    https://github.com/google/go-containerregistry.git
-
-WORKDIR /build/go-containerregistry/cmd/krane
-
-RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /build/krane .
-
+### Stage 0: build the skills-init Go binary
+ARG BASE_IMAGE_REGISTRY=cgr.dev
+ARG BUILDPLATFORM
+FROM --platform=$BUILDPLATFORM $BASE_IMAGE_REGISTRY/chainguard/go:latest AS builder
+ARG TARGETARCH
+ARG TARGETOS
+
+WORKDIR /workspace
+
+COPY go.mod go.sum ./
+RUN --mount=type=cache,target=/root/go/pkg/mod,rw \
+    --mount=type=cache,target=/root/.cache/go-build,rw \
+    go mod download
+
+COPY api/ api/
+COPY core/ core/
+COPY adk/ adk/
+
+ARG LDFLAGS
+RUN --mount=type=cache,target=/root/go/pkg/mod,rw \
+    --mount=type=cache,target=/root/.cache/go-build,rw \
+    CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} \
+    go build -a -trimpath -ldflags "$LDFLAGS" -o /skills-init ./core/cmd/skills-init
+
+### Stage 1: runtime
 FROM alpine:3.23
 
 ARG PYTHON_UID=1001
 ARG PYTHON_GID=1001
 
-RUN apk upgrade --no-cache && apk add --no-cache git jq
-COPY --from=krane-builder /build/krane /usr/local/bin/krane
+# git is invoked by skills-init via exec.Command with an argv vector — never
+# through a shell — so the only attack surface here is git itself. OCI fetch
+# uses the in-process go-containerregistry library, so krane and jq are gone.
+RUN apk upgrade --no-cache && apk add --no-cache git openssh-client ca-certificates
+
+COPY --from=builder /skills-init /usr/local/bin/skills-init
 
 # Run as the same UID/GID as the main agent container (python user) so that
 # files written to the shared /skills volume are readable by the main container.
@@ -28,3 +43,5 @@ RUN addgroup -g ${PYTHON_GID} pythongroup && \
     adduser -u ${PYTHON_UID} -G pythongroup -s /bin/sh -D python
 
 USER ${PYTHON_UID}:${PYTHON_GID}
+
+ENTRYPOINT ["/usr/local/bin/skills-init"]

docs/substrate-agentharness-lifecycle.md

@@ -0,0 +1,60 @@
+# Substrate AgentHarness Lifecycle
+
+This branch should use a single ownership model for `runtime: substrate` harnesses.
+
+## Ownership
+
+- Platform/Helm owns `WorkerPool` capacity.
+- kagent owns the generated per-harness `ActorTemplate`.
+- kagent owns the per-harness actor lifecycle through `ate-api`.
+- Substrate owns the `WorkerPool` deployment and the `ActorTemplate` golden snapshot process.
+
+kagent should not create or delete `WorkerPool` resources from the `AgentHarness` reconciler. A chart may optionally install a default `WorkerPool`, and the controller may use that default when `spec.substrate.workerPoolRef` is unset.
+
+## Spec Shape
+
+`AgentHarness.spec.substrate` should contain only harness-level inputs:
+
+- `workerPoolRef`, optional; falls back to the configured controller default.
+- `snapshotsConfig`, optional; defaults to `gs://ate-snapshots/<namespace>/<name>`.
+- `workloadImage`, optional.
+- exactly one of `gatewayToken` or `gatewayTokenSecretRef`.
+
+There is no `actorTemplateRef`. kagent always generates the `ActorTemplate`, so adopting an external template is not part of the workflow.
+
+## Status
+
+Use top-level Kubernetes conditions for progress:
+
+- `Accepted`
+- `ActorTemplateReady`
+- `ActorReady`
+- `Ready`
+
+`Ready` is the aggregate condition. Specific blockers should be reflected in `reason` and `message`.
+
+Do not store ownership booleans or cleanup markers in annotations or status. Ownership is deterministic:
+
+- `WorkerPool` is external.
+- generated `ActorTemplate` is owned by the `AgentHarness` through an owner reference.
+
+## Reconcile
+
+The substrate reconcile path should:
+
+1. Resolve `workerPoolRef` from spec or controller default.
+2. Verify the `WorkerPool` exists.
+3. Create or update the generated `ActorTemplate` with an owner reference to the `AgentHarness`.
+4. Wait for `ActorTemplate.status.phase == Ready`.
+5. Create or resume the actor through `ate-api`.
+6. Mark `ActorReady` and aggregate `Ready`.
+
+## Delete
+
+The finalizer should:
+
+1. Delete the harness actor recorded in `status.backendRef.id`.
+2. Read the generated `ActorTemplate` and delete `status.goldenActorID`, if present.
+3. Remove the finalizer.
+
+Kubernetes garbage collection deletes the generated `ActorTemplate` through the owner reference. kagent does not delete `WorkerPool`.

examples/modelconfig-with-tls.yaml

@@ -386,5 +386,5 @@ roleRef:
 # 6. Troubleshooting:
 #    - See https://kagent.dev/docs for detailed debugging steps
 #    - Check agent logs: kubectl logs deployment/agent-<name>
-#    - Verify Secret is mounted: kubectl exec deployment/agent-<name> -- ls /etc/ssl/certs/custom/
-#    - Test certificate: kubectl exec deployment/agent-<name> -- openssl x509 -in /etc/ssl/certs/custom/ca.crt -text -noout
+#    - Verify Secret is mounted: kubectl exec deployment/agent-<name> -- ls /etc/ssl/certs/custom/corp-ca/
+#    - Test certificate: kubectl exec deployment/agent-<name> -- openssl x509 -in /etc/ssl/certs/custom/corp-ca/ca.crt -text -noout

examples/substrate-openclaw/README.md

@@ -0,0 +1,144 @@
+# OpenClaw on Agent Substrate
+
+## 1. Install Substrate on your Kind cluster
+
+You can clone the kagent fork of substrate [here](https://github.com/kagent-dev/substrate).
+
+These instructions use a Kind cluster called `kind` (`KIND_CLUSTER_NAME=kind`).
+
+```bash
+cd substrate
+
+./hack/create-kind-cluster.sh
+./hack/install-ate-kind.sh --deploy-ate-system
+```
+
+`--deploy-ate-system` installs the **control plane only** (ate-api, ate-controller, atelet, atenet, …). Your registry catalog will show `ateapi-*`, `atelet-*`, etc., but **not** ateom until you build it.
+
+Build and push **ateom-gvisor** (required for the WorkerPool `ateomImage`):
+
+```bash
+# build the ateom-gvisor image from the substrate repo root
+export KO_DOCKER_REPO=localhost:5001
+export KO_DEFAULTPLATFORMS=linux/$(go env GOARCH)
+./hack/run-tool.sh ko build -B ./cmd/ateom-gvisor
+```
+
+## kagent AgentHarness with substrate runtime
+
+kagent generates a per-harness `ActorTemplate` and uses an existing `WorkerPool`.
+
+Install kagent (Substrate must already be running in the cluster):
+
+```bash
+export KIND_CLUSTER_NAME=kind
+make helm-install KAGENT_HELM_EXTRA_ARGS="\
+  --set controller.substrate.enabled=true \
+  --set controller.substrate.ateApiEndpoint=dns:///api.ate-system.svc:443 \
+  --set controller.substrate.ateApiInsecure=true \
+  --set substrateWorkerPool.create=true \
+  --set substrateWorkerPool.ateomImage=localhost:5001/ateom-gvisor:latest"
+```
+
+The generated `ActorTemplate` uses `controller.substrate.pauseImage`, `controller.substrate.runscAMD64URL`, `controller.substrate.runscAMD64SHA256`, `controller.substrate.runscARM64URL`, and `controller.substrate.runscARM64SHA256` from the Helm values Override them with `--set` or a values file when you need to pin a different gVisor build.
+
+Create a harness. If `snapshotsConfig` is omitted, kagent defaults it to `gs://ate-snapshots/<namespace>/<agentharnessname>`.
+
+- **Worker pool** — reference an existing pool (`workerPoolRef`) or configure a controller default WorkerPool
+- **Gateway token** — required per harness with either `gatewayToken` or `gatewayTokenSecretRef`
+
+```yaml
+apiVersion: kagent.dev/v1alpha2
+kind: AgentHarness
+metadata:
+  name: peterj-claw
+  namespace: kagent
+spec:
+  runtime: substrate
+  backend: openclaw
+  description: OpenClaw on Agent Substrate
+  modelConfigRef: default-model-config
+  substrate:
+    # Optional: defaults to gs://ate-snapshots/kagent/peterj-claw
+    # snapshotsConfig:
+    #   location: gs://ate-snapshots/kagent/peterj-claw
+
+    # Required unless the controller has a default WorkerPool configured.
+    workerPoolRef:
+      name: kagent-default
+
+    # Required: configure the OpenClaw gateway token for this harness.
+    # Use either gatewayToken or gatewayTokenSecretRef. The Secret must contain key "token".
+    gatewayToken: test-token
+
+    # gatewayTokenSecretRef:
+    #   name: openclaw-gateway-token
+
+    # Optional: override the sandbox image used in the ActorTemplate (must be digest-pinned).
+    # workloadImage: ghcr.io/kagent-dev/nemoclaw/sandbox-base@sha256:d52bee415dc4c0dba7164f9eabe727574c056d4f211781f20af249707883a3b4
+```
+
+kagent creates an `ActorTemplate` that looks roughly like this:
+
+```yaml
+apiVersion: ate.dev/v1alpha1
+kind: ActorTemplate
+metadata:
+  name: peterj-claw
+  namespace: kagent
+  labels:
+    app.kubernetes.io/managed-by: kagent
+    kagent.dev/agent-harness: peterj-claw
+spec:
+  pauseImage: gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da
+  runsc:
+    amd64:
+      url: gs://gvisor/releases/nightly/2026-05-19/x86_64/runsc
+      sha256Hash: a397be1abc2420d26bce6c70e6e2ff96c73aaaab929756c56f5e2089ea842b63
+    arm64:
+      url: gs://gvisor/releases/nightly/2026-05-19/aarch64/runsc
+      sha256Hash: 1ba2366ae2efceba166046f51a4104f9261c9cb72c6db8f5b3fe2dc57dea86b9
+  workerPoolRef:
+    name: peterj-claw-wp
+    namespace: kagent
+  snapshotsConfig:
+    location: gs://ate-snapshots/kagent/peterj-claw
+  containers:
+  - name: openclaw
+    image: ghcr.io/kagent-dev/nemoclaw/sandbox-base@sha256:d52bee415dc4c0dba7164f9eabe727574c056d4f211781f20af249707883a3b4
+    ports:
+    - containerPort: 80
+    command:
+    - /bin/sh
+    - -c
+    - |
+      # Generated by kagent:
+      # 1. writes ~/.openclaw/openclaw.json from modelConfigRef/channels/gateway token
+      # 2. configures gateway.controlUi.basePath for the kagent proxy path
+      # 3. starts `openclaw gateway run --port 80 --allow-unconfigured`
+      # 4. waits for the gateway and tails the log
+    env:
+    - name: HOME
+      value: /root
+```
+
+The generated `command` contains a base64-encoded `openclaw.json`, so the live object will be more verbose than the abbreviated example above. `pauseImage`, runsc URLs and hashes, and the default workload image come from controller/Helm configuration unless overridden on the `AgentHarness`; the gateway token comes from `spec.substrate.gatewayToken` or `gatewayTokenSecretRef`. kagent also sets `gateway.controlUi.basePath` to `/api/agentharnesses/<namespace>/<name>/gateway` so OpenClaw serves the Control UI under the same path kagent proxies.
+
+When `modelConfigRef` or `spec.channels` are set, credentials are **not** copied into the ActorTemplate or `openclaw.json` as plaintext. kagent writes `valueFrom.secretKeyRef` (or inline `value` for harness inline tokens) on the ActorTemplate container env; Substrate `ate-api` resolves those refs at actor resume. In `openclaw.json`, kagent uses OpenClaw [env SecretRefs](https://docs.openclaw.ai/gateway/secrets) (`{source:"env",provider:"default",id:"<VAR>"}`) for `models.providers.*.apiKey`, `channels.telegram.accounts.*.botToken`, and `channels.slack.accounts.*.botToken` / `appToken`. Rotate a Secret and recreate the ActorTemplate golden snapshot when keys change.
+
+With `controller.substrate.enabled=true`, the kagent Helm chart installs a namespace-scoped Role and RoleBinding so `ate-api-server` (in `ate-system` by default) can `get` Secrets and ConfigMaps referenced by generated ActorTemplates. Harnesses in other namespaces need that namespace listed in `rbac.namespaces` (or a matching RoleBinding applied manually).
+
+Port-forward the UI:
+
+```bash
+kubectl port-forward -n kagent svc/kagent-ui 8001:8080
+```
+
+Navigate to the deployed agent harness. If the OpenClaw Control UI asks for a gateway connection, use:
+
+- Gateway URL: `http://localhost:8001/api/agentharnesses/kagent/peterj-claw/gateway/`
+- Gateway token: `test-token`
+
+The gateway URL must include the trailing slash. The token is the value configured in `spec.substrate.gatewayToken`, or the Secret value referenced by `spec.substrate.gatewayTokenSecretRef`; enter it in the token/credentials field rather than relying on a `token` query parameter.
+
+kagent proxies UI traffic to the actor OpenClaw gateway through Substrate's **atenet-router** (Envoy) using the actor `Host` header (`<actor-id>.actors.resources.substrate.ate.dev`). The default router URL is `http://atenet-router.ate-system.svc:80`; override with `controller.substrate.atenetRouterURL` when needed.

go/.dockerignore

@@ -1,6 +1,8 @@
 # Build artifacts
 ./bin/
 bin/
+.cache/
+**/.cache/
 
 # Test files
 *_test.go
@@ -45,4 +47,4 @@ PROJECT
 hack/
 
 # Makefiles
-Makefile
+Makefile

go/Makefile

@@ -177,6 +177,10 @@ setup-envtest: envtest ## Download the binaries required for ENVTEST in the loca
 		exit 1; \
 	}
 
+.PHONY: envtest-path
+envtest-path: envtest ## Print the path to the envtest binaries (downloads them if absent).
+	@$(ENVTEST) use $(ENVTEST_K8S_VERSION) --bin-dir $(LOCALBIN) -p path
+
 .PHONY: envtest
 envtest: $(ENVTEST) ## Download setup-envtest locally if necessary.
 $(ENVTEST): $(LOCALBIN)