Makefile

# Load local overrides (gitignored) — e.g. HELM_ARGS=--set ui.replicas=0
-include .env

# Image configuration
DOCKER_REGISTRY ?= localhost:5001
BASE_IMAGE_REGISTRY ?= cgr.dev
DOCKER_REPO ?= kagent-dev/kagent
HELM_REPO ?= oci://ghcr.io/kagent-dev
HELM_DIST_FOLDER ?= dist
HELM_SOURCE_DIR ?= helm
RUNTIME_IMAGE_REPOSITORY ?= ghcr.io/kagent-dev/kagent
# Release packaging requires an explicit metadata directory; local builds have a default.
RUNTIME_BUILD_METADATA_DIR = $(or $(RUNTIME_IMAGE_METADATA_DIR),$(CURDIR)/build/runtime-images)
RUNTIME_IMAGE_METADATA_FILE = $(RUNTIME_BUILD_METADATA_DIR)/$(patsubst build-%,%,$@).json

BUILD_DATE := $(shell date -u '+%Y-%m-%d')
GIT_COMMIT := $(shell git rev-parse --short HEAD || echo "unknown")
VERSION ?= $(shell git describe --tags --always 2>/dev/null | grep v || echo "v0.0.0-$(GIT_COMMIT)")

# Local architecture detection to build for the current platform
LOCALARCH ?= $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
LOCALOS ?= $(shell uname -s | tr '[:upper:]' '[:lower:]')

KUBECONFIG_PERM ?= $(shell \
  if [ "$$(uname -s | tr '[:upper:]' '[:lower:]')" = "darwin" ]; then \
    stat -f "%Lp" ~/.kube/config; \
  else \
    stat -c "%a" ~/.kube/config; \
  fi)


# Container runtime: "docker" (default) or "podman".
# Set CONTAINER_RUNTIME=podman to use Podman for all container operations.
CONTAINER_RUNTIME ?= docker

# Buildx configuration
BUILDKIT_VERSION = v0.23.0
BUILDX_NO_DEFAULT_ATTESTATIONS=1
BUILDX_BUILDER_NAME ?= kagent-builder-$(BUILDKIT_VERSION)

ifeq ($(CONTAINER_RUNTIME),podman)
  DOCKER_BUILDER ?= $(CONTAINER_RUNTIME) build
  DOCKER_BUILD_ARGS ?= --platform linux/$(LOCALARCH)
  # Podman needs a separate push step (no --push on build).
  # --tls-verify=false is needed for local insecure registries (e.g. kind-registry).
  # Override PODMAN_TLS_VERIFY=true when pushing to a remote TLS registry.
  PODMAN_TLS_VERIFY ?= false
  DOCKER_PUSH = $(CONTAINER_RUNTIME) push --tls-verify=$(PODMAN_TLS_VERIFY)
  define push-runtime-image
	$(DOCKER_PUSH) --digestfile "$(RUNTIME_IMAGE_METADATA_FILE).digest" $(1)
	jq -n --arg digest "$$(cat "$(RUNTIME_IMAGE_METADATA_FILE).digest")" '{"containerimage.digest": $$digest}' > "$(RUNTIME_IMAGE_METADATA_FILE)"
  endef
else
  DOCKER_BUILDER ?= $(CONTAINER_RUNTIME) buildx build
  DOCKER_BUILD_ARGS ?= --push --platform linux/$(LOCALARCH)
  # Docker buildx --push handles push inline; no separate push step needed.
  DOCKER_PUSH = @true
  RUNTIME_METADATA_BUILD_ARGS = --metadata-file "$(RUNTIME_IMAGE_METADATA_FILE)"
  define push-runtime-image
	$(DOCKER_PUSH) $(1)
  endef
endif

KIND_CLUSTER_NAME ?= kagent
KIND_IMAGE_VERSION ?= 1.35.0
# Written by use-kind-cluster. CLI installs use it so they always target the Kind
# cluster, whatever the current kubectl context is.
KIND_KUBECONFIG ?= /tmp/kind-config
# Substrate settings for Kind: workers pull localhost:5001 images through the
# registry container, and templates reconcile at the minimum interval.
KIND_SUBSTRATE_HELM_ARGS = --set atelet.extraArgs[0]=--localhost-registry-replacement=kind-registry:5000 --set ateApi.extraArgs[0]=--template-resync-interval=250ms
# A file only releases whose `kagent install` deploys the database contain.
CLI_DATABASE_SENTINEL = go/core/cli/internal/commands/bundled_postgres.yaml
KAGENT_POSTGRES_OWNER_SECRET ?= kagent-postgres-owner
KAGENT_POSTGRES_READWRITE_SECRET ?= kagent-postgres-readwrite

CONTROLLER_IMAGE_NAME ?= controller
UI_IMAGE_NAME ?= ui
GOLANG_ADK_IMAGE_NAME ?= golang-adk

CLAUDE_HARNESS_IMAGE_NAME ?= claude-harness
CODEX_HARNESS_IMAGE_NAME ?= codex-harness
SANDBOX_GUEST_IMAGE_NAME ?= sandbox-guest
CONTROLLER_IMAGE_TAG ?= $(VERSION)
UI_IMAGE_TAG ?= $(VERSION)
GOLANG_ADK_IMAGE_TAG ?= $(VERSION)
CLAUDE_HARNESS_IMAGE_TAG ?= $(VERSION)
CODEX_HARNESS_IMAGE_TAG ?= $(VERSION)
SANDBOX_GUEST_IMAGE_TAG ?= $(VERSION)
CONTROLLER_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(CONTROLLER_IMAGE_NAME):$(CONTROLLER_IMAGE_TAG)
UI_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(UI_IMAGE_NAME):$(UI_IMAGE_TAG)
GOLANG_ADK_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(GOLANG_ADK_IMAGE_NAME):$(GOLANG_ADK_IMAGE_TAG)
CLAUDE_HARNESS_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(CLAUDE_HARNESS_IMAGE_NAME):$(CLAUDE_HARNESS_IMAGE_TAG)
CODEX_HARNESS_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(CODEX_HARNESS_IMAGE_NAME):$(CODEX_HARNESS_IMAGE_TAG)
SANDBOX_GUEST_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(SANDBOX_GUEST_IMAGE_NAME):$(SANDBOX_GUEST_IMAGE_TAG)

#take from go/go.mod
AWK ?= $(shell command -v gawk || command -v awk)
TOOLS_GO_VERSION ?= $(shell $(AWK) '/^go / { print $$2 }' go/go.mod)
export GOTOOLCHAIN=go$(TOOLS_GO_VERSION)
SUBSTRATE_VERSION ?= $(shell $(AWK) '/github\.com\/kagent-dev\/substrate/ { print substr($$5, 2) }' go/go.mod)

# Version information for the build
LDFLAGS := -X github.com/$(DOCKER_REPO)/go/core/internal/version.Version=$(VERSION) \
           -X github.com/$(DOCKER_REPO)/go/core/internal/version.GitCommit=$(GIT_COMMIT) \
           -X github.com/$(DOCKER_REPO)/go/core/internal/version.BuildDate=$(BUILD_DATE) \
           -X github.com/$(DOCKER_REPO)/go/core/internal/version.SubstrateVersion=$(SUBSTRATE_VERSION)

#tools versions
TOOLS_UV_VERSION ?= 0.10.4
TOOLS_NODE_VERSION ?= 24
TOOLS_PYTHON_VERSION ?= 3.13
BUF_VERSION ?= v1.72.0
BUF := go run github.com/bufbuild/buf/cmd/buf@$(BUF_VERSION)

# build args
TOOLS_IMAGE_BUILD_ARGS =  --build-arg VERSION=$(VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg LDFLAGS="$(LDFLAGS)"
TOOLS_IMAGE_BUILD_ARGS += --build-arg DOCKER_REPO=$(DOCKER_REPO)
TOOLS_IMAGE_BUILD_ARGS += --build-arg DOCKER_REGISTRY=$(DOCKER_REGISTRY)
TOOLS_IMAGE_BUILD_ARGS += --build-arg BASE_IMAGE_REGISTRY=$(BASE_IMAGE_REGISTRY)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_GO_VERSION=$(TOOLS_GO_VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_UV_VERSION=$(TOOLS_UV_VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_PYTHON_VERSION=$(TOOLS_PYTHON_VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_NODE_VERSION=$(TOOLS_NODE_VERSION)


##@ General

# The help target prints out all targets with their descriptions organized
# beneath their categories. The categories are represented by '##@' and the
# target descriptions by '##'. The awk command is responsible for reading the
# entire set of makefiles included in this invocation, looking for lines of the
# file as xyz: ## something, and then pretty-format the target and help. Then,
# if there's a line with ##@ something, that gets pretty-printed as a category.
# More info on the usage of ANSI control characters for terminal formatting:
# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
# More info on the awk command:
# http://linuxcommand.org/lc3_adv_awk.php

.PHONY: help
help: ## Display this help.
	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-24s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

.PHONY: print-tools-versions
print-tools-versions: ## Print tools versions
	@echo "VERSION      : $(VERSION)"
	@echo "Tools Go     : $(TOOLS_GO_VERSION)"
	@echo "Tools UV     : $(TOOLS_UV_VERSION)"
	@echo "Tools Node   : $(TOOLS_NODE_VERSION)"
	@echo "Tools Weaver : $(WEAVER_VERSION)"
	@echo "Tools Istio  : $(TOOLS_ISTIO_VERSION)"
	@echo "Tools Argo CD: $(TOOLS_ARGO_CD_VERSION)"

##@ Protobuf

# Builds regenerate protobuf code so local proto edits take effect. CI builds use
# the committed output instead: proto-check verifies it, and every regeneration
# spends Buf Schema Registry remote-plugin requests, which are rate limited.
BUILD_PROTO_GENERATE := $(if $(filter true,$(CI)),,proto-generate)

.PHONY: proto-generate
proto-generate: ## Generate Go, TypeScript, and Python protobuf clients and servers
	cd proto && $(BUF) generate
	cd proto && $(BUF) generate --template buf.gen.typescript.yaml
	cd proto && $(BUF) generate --template buf.gen.python-validation.yaml

.PHONY: proto-lint
proto-lint: ## Lint repository-owned protobuf schemas
	cd proto && $(BUF) lint

.PHONY: proto-breaking
proto-breaking: ## Check protobuf compatibility against the target branch (default: main)
	@if git cat-file -e "$(PROTO_BREAKING_BRANCH):proto/buf.yaml" 2>/dev/null; then \
		$(BUF) breaking proto --against ".git#branch=$(PROTO_BREAKING_BRANCH),subdir=proto"; \
	else \
		echo "No protobuf module on $(PROTO_BREAKING_BRANCH); skipping first-release breaking check"; \
	fi

PROTO_BREAKING_BRANCH ?= main
PROTO_GENERATED_PATHS := go/api/gen ui/src/generated python/packages/kagent-proto/src/kagent python/packages/kagent-proto/src/buf

.PHONY: proto-check
proto-check: proto-lint proto-generate ## Regenerate protobuf artifacts and fail when committed output drifts
	@if test -n "$$(git status --porcelain -- $(PROTO_GENERATED_PATHS))"; then \
		echo "Generated protobuf files are out of date:"; \
		git status --short -- $(PROTO_GENERATED_PATHS); \
		exit 1; \
	fi

##@ Environment documentation

ENV_DOCS_COMMAND = cd go && go run ./core/cli/cmd/kagent env --format markdown

.PHONY: env-docs
env-docs: ## Generate docs/env.md from the environment variable registry
	@set -eu; generated=$$(mktemp); trap 'rm -f "$$generated"' EXIT; \
		($(ENV_DOCS_COMMAND)) > "$$generated"; \
		cp "$$generated" docs/env.md

.PHONY: env-docs-check
env-docs-check: ## Check docs/env.md matches the environment variable registry
	@set -eu; generated=$$(mktemp); trap 'rm -f "$$generated"' EXIT; \
		($(ENV_DOCS_COMMAND)) > "$$generated"; \
		if ! diff -u docs/env.md "$$generated"; then \
			echo "Environment documentation is out of date. Run 'make env-docs' and commit docs/env.md."; \
			exit 1; \
		fi

##@ Telemetry contract

include telemetry/versions.env

WEAVER := telemetry/weaver.sh
SEMCONV_REGISTRY := telemetry/registry
SEMCONV_GENERATE := $(WEAVER) registry generate -r $(SEMCONV_REGISTRY) --v2 -t telemetry/templates
SEMCONV_GENERATED_PATHS := go/pkg/telemetry/conv python/packages/kagent-core/src/kagent/core/telemetry/_conv.py docs/architecture/telemetry-contract.md telemetry/resolved.yaml

.PHONY: semconv-check
semconv-check: ## Validate the telemetry registry with Weaver and the kagent policies
	$(WEAVER) registry check -r $(SEMCONV_REGISTRY) --v2 \
		--policy '$(WEAVER_PACKAGES)[policies/check/naming_conventions]' \
		--policy '$(WEAVER_PACKAGES)[policies/check/stability]' \
		--policy telemetry/policies

.PHONY: semconv-policies-test
semconv-policies-test: ## Check that each kagent telemetry policy rejects its fixture
	telemetry/policies/test.sh

.PHONY: semconv-generate
semconv-generate: ## Generate the telemetry conventions, the contract reference, and the resolved snapshot
	$(SEMCONV_GENERATE) go go/pkg/telemetry/conv
	$(SEMCONV_GENERATE) python python/packages/kagent-core/src/kagent/core/telemetry
	$(SEMCONV_GENERATE) markdown docs/architecture
	$(SEMCONV_GENERATE) yaml telemetry
	gofmt -w go/pkg/telemetry/conv

.PHONY: semconv-verify
semconv-verify: semconv-check semconv-policies-test semconv-generate ## Check the telemetry registry and fail when generated output drifts
	@if test -n "$$(git status --porcelain -- $(SEMCONV_GENERATED_PATHS))"; then \
		echo "Generated telemetry conventions are out of date. Run 'make semconv-generate' and commit the result:"; \
		git status --short -- $(SEMCONV_GENERATED_PATHS); \
		exit 1; \
	fi

##@ Git

.PHONY: init-git-hooks
init-git-hooks:  ## Use the tracked version of Git hooks from this repo
	git config core.hooksPath .githooks
	echo "Git hooks initialized"

# Substrate
# Override for local development with locally published charts.
SUBSTRATE_REPO ?= oci://ghcr.io/kagent-dev/substrate/helm
SUBSTRATE_PODCERT_REPO ?= $(SUBSTRATE_REPO)
SUBSTRATE_PODCERT_VERSION ?= $(SUBSTRATE_VERSION)

HELM_ACTION=upgrade --install

# Helm chart variables
MODEL_PROVIDER ?= openAI


##@ Build

.PHONY: check-api-key
check-api-key: ## Validate required API key for the configured model provider
	@if [ "$(MODEL_PROVIDER)" = "openAI" ]; then \
		if [ -z "$(OPENAI_API_KEY)" ]; then \
			echo "Error: OPENAI_API_KEY environment variable is not set for OpenAI provider"; \
			echo "Please set it with: export OPENAI_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(MODEL_PROVIDER)" = "anthropic" ]; then \
		if [ -z "$(ANTHROPIC_API_KEY)" ]; then \
			echo "Error: ANTHROPIC_API_KEY environment variable is not set for Anthropic provider"; \
			echo "Please set it with: export ANTHROPIC_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(MODEL_PROVIDER)" = "azureOpenAI" ]; then \
		if [ -z "$(AZURE_OPENAI_API_KEY)" ]; then \
			echo "Error: AZURE_OPENAI_API_KEY environment variable is not set for Azure OpenAI provider"; \
			echo "Please set it with: export AZURE_OPENAI_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(MODEL_PROVIDER)" = "gemini" ]; then \
		if [ -z "$(GOOGLE_API_KEY)" ]; then \
			echo "Error: GOOGLE_API_KEY environment variable is not set for Gemini provider"; \
			echo "Please set it with: export GOOGLE_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(MODEL_PROVIDER)" = "ollama" ]; then \
		if [ -z "$$OLLAMA_API_KEY" ]; then \
			echo "Note: OLLAMA_API_KEY is not set — local Ollama models need no key, and a"; \
			echo "      ':cloud' model will be proxied by the local daemon instead of"; \
			echo "      reaching api.ollama.com directly. Export OLLAMA_API_KEY to use the cloud API."; \
		fi; \
	else \
		echo "Warning: Unknown model provider '$(MODEL_PROVIDER)'. Skipping API key check."; \
	fi

.PHONY: buildx-create
buildx-create: ## Create or reuse the buildx builder instance
ifeq ($(CONTAINER_RUNTIME),podman)
	@echo "Podman detected; skipping buildx builder setup (using built-in buildx)."
else
	$(CONTAINER_RUNTIME) buildx inspect $(BUILDX_BUILDER_NAME) 2>&1 > /dev/null || \
	$(CONTAINER_RUNTIME) buildx create --name $(BUILDX_BUILDER_NAME) --platform linux/amd64,linux/arm64 --driver docker-container --use --driver-opt network=host || true
	$(CONTAINER_RUNTIME) buildx use $(BUILDX_BUILDER_NAME) || true
	# Wait for buildkit to actually be up. `create` returns before its container is
	# serving, so a build starting immediately after can find no socket to talk to:
	# `dial unix /run/buildkit/buildkitd.sock: no such file or directory`, then
	# `failed to list workers`. Bootstrapping here also makes this target safe to run
	# concurrently -- a loser of the create race waits for the winner's builder
	# instead of building against a half-made one.
	$(CONTAINER_RUNTIME) buildx inspect --bootstrap $(BUILDX_BUILDER_NAME) 2>&1 > /dev/null
endif

.PHONY: build-all
build-all: ## Build all images for amd64+arm64 without pushing (outputs to /dev/null for CI validation)
build-all: BUILD_ARGS ?= --progress=plain --builder $(BUILDX_BUILDER_NAME) --platform linux/amd64,linux/arm64 --output type=tar,dest=/dev/null
build-all: $(BUILD_PROTO_GENERATE) buildx-create
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f go/Dockerfile     ./go
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f go/harness/claude/Dockerfile ./go
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f go/harness/codex/Dockerfile ./go
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f go/sandbox/guest/Dockerfile ./go
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f ui/Dockerfile     ./ui

.PHONY: build
build: ## Build and push all component images
build: buildx-create build-ui build-golang-adk build-claude-harness build-codex-harness build-sandbox-guest build-controller
	@echo "Build completed successfully."
	@echo "Controller Image: $(CONTROLLER_IMG)"
	@echo "UI Image: $(UI_IMG)"
	@echo "Golang ADK Image: $(GOLANG_ADK_IMG)"
	@echo "Claude Harness Image: $(CLAUDE_HARNESS_IMG)"
	@echo "Codex Harness Image: $(CODEX_HARNESS_IMG)"
	@echo "Sandbox Guest Image: $(SANDBOX_GUEST_IMG)"

.PHONY: build-monitor
build-monitor: ## Watch BuildKit process list inside the buildx container
build-monitor: buildx-create
ifeq ($(CONTAINER_RUNTIME),podman)
	@echo "build-monitor is not supported with Podman (no external buildkit container)"
else
	watch $(CONTAINER_RUNTIME) exec -t  buildx_buildkit_$(BUILDX_BUILDER_NAME)0  ps
endif

.PHONY: build-cli
build-cli: ## Build the kagent CLI (cross-compiled via go sub-make)
build-cli: $(BUILD_PROTO_GENERATE)
	make -C go build

.PHONY: build-cli-local
build-cli-local: ## Build the kagent CLI binary for the local machine
build-cli-local: $(BUILD_PROTO_GENERATE)
	make -C go clean
	make -C go core/bin/kagent-local

.PHONY: build-img-versions
build-img-versions: ## Print the fully-qualified image tags for all components
	@echo controller=$(CONTROLLER_IMG)
	@echo ui=$(UI_IMG)
	@echo golang-adk=$(GOLANG_ADK_IMG)
	@echo claude-harness=$(CLAUDE_HARNESS_IMG)
	@echo codex-harness=$(CODEX_HARNESS_IMG)
	@echo sandbox-guest=$(SANDBOX_GUEST_IMG)

.PHONY: controller-manifests
controller-manifests: ## Regenerate CRD manifests in the Helm chart
	make -C go manifests

.PHONY: build-controller
build-controller: ## Build and push the controller image
build-controller: buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) \
		--build-arg BUILD_PACKAGE=core/cmd/controller/main.go \
		-t $(CONTROLLER_IMG) -f go/Dockerfile ./go
	$(DOCKER_PUSH) $(CONTROLLER_IMG)

.PHONY: build-ui
build-ui: ## Build and push the UI image
build-ui: $(BUILD_PROTO_GENERATE) buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(UI_IMG) -f ui/Dockerfile ./ui
	$(DOCKER_PUSH) $(UI_IMG)

.PHONY: build-golang-adk
build-golang-adk: ## Build and push the Go ADK image
build-golang-adk: $(BUILD_PROTO_GENERATE) buildx-create
	mkdir -p "$(RUNTIME_BUILD_METADATA_DIR)"
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(RUNTIME_METADATA_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) --build-arg BUILD_PACKAGE=adk/cmd/main.go -t $(GOLANG_ADK_IMG) -f go/Dockerfile ./go
	$(call push-runtime-image,$(GOLANG_ADK_IMG))

.PHONY: build-byo-a2a
build-byo-a2a: ## Build and push the opaque BYO A2A e2e image
build-byo-a2a: buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) --build-arg BUILD_PACKAGE=core/test/byoa2a/main.go -t $(DOCKER_REGISTRY)/$(DOCKER_REPO)/byo-a2a:$(VERSION) -f go/Dockerfile ./go
	$(DOCKER_PUSH) $(DOCKER_REGISTRY)/$(DOCKER_REPO)/byo-a2a:$(VERSION)

.PHONY: build-claude-harness
build-claude-harness: ## Build and push the native Claude Harness image
build-claude-harness: buildx-create
	mkdir -p "$(RUNTIME_BUILD_METADATA_DIR)"
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(RUNTIME_METADATA_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(CLAUDE_HARNESS_IMG) -f go/harness/claude/Dockerfile ./go
	$(call push-runtime-image,$(CLAUDE_HARNESS_IMG))

.PHONY: build-codex-harness
build-codex-harness: ## Build and push the native Codex Harness image
build-codex-harness: buildx-create
	mkdir -p "$(RUNTIME_BUILD_METADATA_DIR)"
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(RUNTIME_METADATA_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(CODEX_HARNESS_IMG) -f go/harness/codex/Dockerfile ./go
	$(call push-runtime-image,$(CODEX_HARNESS_IMG))

.PHONY: build-sandbox-guest
build-sandbox-guest: ## Build and push the standalone sandbox guest image
build-sandbox-guest: buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(SANDBOX_GUEST_IMG) -f go/sandbox/guest/Dockerfile ./go
	$(DOCKER_PUSH) $(SANDBOX_GUEST_IMG)

.PHONY: push
push: ## Push all component images (controller, ui, Go ADK)
push: push-controller push-ui push-golang-adk


##@ Testing

.PHONY: lint
lint: ## Run linters for Go and Python
	make -C go lint
	make -C python lint


##@ Cluster

.PHONY: create-kind-cluster

create-kind-cluster: ## Create a local kind cluster with MetalLB
	CONTAINER_RUNTIME=$(CONTAINER_RUNTIME) KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) KIND_IMAGE_VERSION=$(KIND_IMAGE_VERSION) bash ./scripts/kind/setup-kind.sh
	CONTAINER_RUNTIME=$(CONTAINER_RUNTIME) KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) bash ./scripts/kind/setup-metallb.sh

.PHONY: use-kind-cluster
use-kind-cluster: ## Merge kind kubeconfig and set kagent as the default namespace
	kind get kubeconfig --name $(KIND_CLUSTER_NAME) > $(KIND_KUBECONFIG)
	KUBECONFIG=~/.kube/config:$(KIND_KUBECONFIG) kubectl config view --merge --flatten > ~/.kube/config.tmp && mv ~/.kube/config.tmp ~/.kube/config && chmod $(KUBECONFIG_PERM) ~/.kube/config
	kubectl --context kind-$(KIND_CLUSTER_NAME) create namespace kagent || true
	kubectl config set-context kind-$(KIND_CLUSTER_NAME) --namespace kagent || true

.PHONY: delete-kind-cluster
delete-kind-cluster: ## Delete the local kind cluster
	kind delete cluster --name $(KIND_CLUSTER_NAME)


##@ Helm

.PHONY: helm-cleanup
helm-cleanup: ## Remove packaged Helm charts from the dist folder
	rm -f "$(HELM_DIST_FOLDER)"/*.tgz

.PHONY: helm-test
helm-test: ## Render Helm templates for all providers and run helm unittest
helm-test: helm-version
	mkdir -p tmp
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=ollama																	| tee tmp/ollama.yaml 		| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=openAI       --set providers.openAI.apiKey=your-openai-api-key 			| tee tmp/openAI.yaml 		| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=anthropic    --set providers.anthropic.apiKey=your-anthropic-api-key 	| tee tmp/anthropic.yaml 	| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=azureOpenAI  --set providers.azureOpenAI.apiKey=your-openai-api-key		| tee tmp/azureOpenAI.yaml	| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=gemini       --set providers.gemini.apiKey=your-gemini-api-key 			| tee tmp/gemini.yaml 		| grep ^kind: | wc -l)
	helm plugin ls | grep unittest || helm plugin install https://github.com/helm-unittest/helm-unittest.git
	helm unittest helm/kagent

.PHONY: helm-version
helm-version: ## Stamp chart versions, update dependencies, and package kagent + kagent-crds
helm-version: helm-cleanup
	VERSION=$(VERSION) envsubst < "$(HELM_SOURCE_DIR)/kagent-crds/Chart-template.yaml" > "$(HELM_SOURCE_DIR)/kagent-crds/Chart.yaml"
	VERSION=$(VERSION) envsubst < "$(HELM_SOURCE_DIR)/kagent/Chart-template.yaml" > "$(HELM_SOURCE_DIR)/kagent/Chart.yaml"
	helm dependency update "$(HELM_SOURCE_DIR)/kagent"
	helm dependency update "$(HELM_SOURCE_DIR)/kagent-crds"
	helm package -d "$(HELM_DIST_FOLDER)" "$(HELM_SOURCE_DIR)/kagent-crds"
	helm package -d "$(HELM_DIST_FOLDER)" "$(HELM_SOURCE_DIR)/kagent"

.PHONY: helm-dev
helm-dev: ## Prepare development charts with the images published by local builds
	@test -d "$(RUNTIME_BUILD_METADATA_DIR)" || { echo "Missing runtime image metadata. Run make build before preparing development charts." >&2; exit 1; }
	bash scripts/harness-image-catalog.sh "$(VERSION)" "$(RUNTIME_BUILD_METADATA_DIR)" "$(GOLANG_ADK_IMG)" "$(CLAUDE_HARNESS_IMG)" "$(CODEX_HARNESS_IMG)" > "$(RUNTIME_BUILD_METADATA_DIR)/builtin-harness-images.json"
	mkdir -p "$(HELM_SOURCE_DIR)/kagent/files"
	cp "$(RUNTIME_BUILD_METADATA_DIR)/builtin-harness-images.json" "$(HELM_SOURCE_DIR)/kagent/files/builtin-harness-images.json"
	$(MAKE) helm-version

.PHONY: helm-install-provider
helm-install-provider: ## Install or upgrade with Helm; requires a prepared PostgreSQL Secret
helm-install-provider: helm-dev check-api-key
	@case "$(HELM_ACTION)" in \
		*--dry-run*) ;; \
		*) for secret in $(KAGENT_POSTGRES_OWNER_SECRET) $(KAGENT_POSTGRES_READWRITE_SECRET); do \
			kubectl --context kind-$(KIND_CLUSTER_NAME) --namespace kagent get secret $$secret >/dev/null 2>&1 || { \
				echo "Missing PostgreSQL Secret kagent/$$secret. Use 'make kagent-cli-install' for the bundled development database, or create the owner and read/write Secrets before a direct Helm install." >&2; \
				exit 1; \
			}; \
		done ;; \
	esac
	helm $(HELM_ACTION) kagent-crds "$(HELM_SOURCE_DIR)/kagent-crds" \
		--namespace kagent \
		--create-namespace \
		--history-max 2    \
		--timeout 5m 			\
		--kube-context kind-$(KIND_CLUSTER_NAME) \
		--wait
	helm $(HELM_ACTION) kagent "$(HELM_SOURCE_DIR)/kagent" \
		--namespace kagent \
		--create-namespace \
		--history-max 2    \
		--timeout 5m       \
		--kube-context kind-$(KIND_CLUSTER_NAME) \
		--wait \
		--set ui.service.type=LoadBalancer \
		--set registry=$(DOCKER_REGISTRY) \
		--set imagePullPolicy=Always \
		--set tag=$(VERSION) \
		--set config.logging.level=debug \
		--set controller.image.pullPolicy=Always \
		--set ui.image.pullPolicy=Always \
		--set controller.service.type=LoadBalancer \
		--set providers.openAI.apiKey=$(OPENAI_API_KEY) \
		--set providers.azureOpenAI.apiKey=$(AZURE_OPENAI_API_KEY) \
		--set providers.anthropic.apiKey=$(ANTHROPIC_API_KEY) \
		--set providers.gemini.apiKey=$(GOOGLE_API_KEY) \
		--set providers.default=$(MODEL_PROVIDER) \
		--set database.postgres.ownerConnectionStringSecretRef.name=$(KAGENT_POSTGRES_OWNER_SECRET) \
		--set database.postgres.readWriteConnectionStringSecretRef.name=$(KAGENT_POSTGRES_READWRITE_SECRET) \
		$(HELM_ARGS)

.PHONY: helm-install
helm-install: ## Build all images then install kagent onto the kind cluster
helm-install: build
	$(MAKE) helm-install-provider

.PHONY: helm-test-install
helm-test-install: ## Dry-run helm install to validate chart rendering (pipe to tee for inspection)
helm-test-install: HELM_ACTION+="--dry-run"
helm-test-install: helm-install-provider

.PHONY: helm-uninstall
helm-uninstall: ## Uninstall kagent and kagent-crds Helm releases from the kind cluster
	helm uninstall kagent --namespace kagent --kube-context kind-$(KIND_CLUSTER_NAME) --wait
	helm uninstall kagent-crds --namespace kagent --kube-context kind-$(KIND_CLUSTER_NAME) --wait

# Upgrade tests install a previous release with that release's own `kagent install`,
# exactly as a user would, then upgrade it to the current build with kagent-cli-deploy.
# The tests use a separate cluster because they change the database and deployment.
# UPGRADE_FROM_VERSION selects the previous release; it must install its database with
# `kagent install` (see CLI_DATABASE_SENTINEL); earlier releases are rejected.
#
# Prerequisite (provided by CI as a separate step; run it locally first): a kind
# cluster (make create-kind-cluster).
#
# Lazily evaluated and referenced only by the upgrade targets below, so unrelated
# make invocations never run the resolver; CI passes UPGRADE_FROM_VERSION
# explicitly (per matrix leg), which bypasses the script entirely.
UPGRADE_FROM_VERSION ?= $(shell ./scripts/upgrade-from-version.sh)
UPGRADE_FROM_CLI = /tmp/kagent-$(UPGRADE_FROM_VERSION)-$(LOCALOS)-$(LOCALARCH)

.PHONY: install-previous-release
install-previous-release: use-kind-cluster ## Install the previous release with its own kagent CLI
	# Abort early (rather than let the download fail confusingly) if the upgrade-from
	# version could not be resolved or predates the CLI-managed database.
	[ -n "$(UPGRADE_FROM_VERSION)" ] || { echo "UPGRADE_FROM_VERSION is empty; set it explicitly or ensure git tags are fetched." >&2; exit 1; }
	git cat-file -e "v$(UPGRADE_FROM_VERSION):$(CLI_DATABASE_SENTINEL)" 2>/dev/null || { echo "v$(UPGRADE_FROM_VERSION) predates the database kagent install manages; upgrade tests cannot start from it." >&2; exit 1; }
	@echo "=== Installing previous release: $(UPGRADE_FROM_VERSION) ==="
	curl -fsSL -o $(UPGRADE_FROM_CLI) https://github.com/kagent-dev/kagent/releases/download/v$(UPGRADE_FROM_VERSION)/kagent-$(LOCALOS)-$(LOCALARCH)
	chmod +x $(UPGRADE_FROM_CLI)
	KUBECONFIG=$(KIND_KUBECONFIG) \
	KAGENT_DEFAULT_MODEL_PROVIDER=openAI \
	OPENAI_API_KEY="$${OPENAI_API_KEY:-test}" \
	KAGENT_SUBSTRATE_HELM_EXTRA_ARGS="$(KIND_SUBSTRATE_HELM_ARGS)" \
	KAGENT_HELM_EXTRA_ARGS="--set ui.service.type=LoadBalancer --set controller.service.type=LoadBalancer $(UPGRADE_PREV_EXTRA_ARGS)" \
	$(UPGRADE_FROM_CLI) install

# run-upgrade-tests installs the previous release and upgrades it to the current build.
# It tests previous-release behavior after the target migrations,
# data survival, schema equality, previous/current controller startup, and a
# complete application and schema rollback to the previous release.
# KAGENT_E2E_LOCAL_HOST lets the agent reach the local mock LLM.
# Prerequisite (provided by CI as a separate step; run it locally first): a kind
# cluster (make create-kind-cluster).
.PHONY: announce-upgrade-from
announce-upgrade-from: ## Print the upgrade-from -> to versions (runs before the build so it is clear up front)
	@echo "=== Upgrade test: FROM $(UPGRADE_FROM_VERSION) TO $(VERSION). Building current images next. ==="

.PHONY: run-upgrade-tests
run-upgrade-tests: announce-upgrade-from build install-previous-release ## Test an upgrade between Goose releases
	@echo "=== Upgrade test: $(UPGRADE_FROM_VERSION) -> $(VERSION) (registry=$(DOCKER_REGISTRY)) ==="
	@set -e; \
	kind_gw="$$($(CONTAINER_RUNTIME) network inspect kind -f '{{range .IPAM.Config}}{{if .Gateway}}{{.Gateway}}{{"\n"}}{{end}}{{end}}' | grep -E '^[0-9]+\.' | head -1)"; \
	echo "kind gateway (KAGENT_E2E_LOCAL_HOST): $$kind_gw"; \
	cd go && \
	KAGENT_E2E_RUN_UPGRADE_TESTS=true \
	KAGENT_E2E_REPO_ROOT=$(CURDIR) \
	KAGENT_E2E_LOCAL_HOST="$$kind_gw" \
	KAGENT_E2E_UPGRADE_FROM_VERSION=$(UPGRADE_FROM_VERSION) \
	KAGENT_E2E_VERSION=$(VERSION) \
	KAGENT_E2E_DOCKER_REGISTRY=$(DOCKER_REGISTRY) \
	KAGENT_E2E_KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) \
	OPENAI_API_KEY="$${OPENAI_API_KEY:-test}" \
	go test ./core/test/upgrade -run TestUpgrade -count=1 -timeout=45m -v

# The target-specific UPGRADE_PREV_EXTRA_ARGS propagates to the
# install-previous-release prerequisite, so the previous release comes up with 2
# controller replicas (needed to observe the old-code/new-schema rollout window).
.PHONY: run-rolling-upgrade-tests
run-rolling-upgrade-tests: UPGRADE_PREV_EXTRA_ARGS = --set controller.replicas=2
run-rolling-upgrade-tests: announce-upgrade-from build install-previous-release ## Install the previous release with 2 controller replicas, build the current images, and run the rolling upgrade e2e test
	@echo "=== Rolling upgrade test: $(UPGRADE_FROM_VERSION) -> $(VERSION) (registry=$(DOCKER_REGISTRY)) ==="
	cd go && \
	KAGENT_E2E_RUN_ROLLING_UPGRADE_TESTS=true \
	KAGENT_E2E_REPO_ROOT=$(CURDIR) \
	KAGENT_E2E_UPGRADE_FROM_VERSION=$(UPGRADE_FROM_VERSION) \
	KAGENT_E2E_VERSION=$(VERSION) \
	KAGENT_E2E_DOCKER_REGISTRY=$(DOCKER_REGISTRY) \
	KAGENT_E2E_KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) \
	OPENAI_API_KEY="$${OPENAI_API_KEY:-test}" \
	go test ./core/test/upgrade -run TestRollingUpgradeCompatibility -count=1 -timeout=20m -v

.PHONY: helm-release
helm-release: ## Package release charts from RUNTIME_IMAGE_METADATA_DIR without modifying chart sources
	@test -n "$(RUNTIME_IMAGE_METADATA_DIR)" || { echo "RUNTIME_IMAGE_METADATA_DIR is required for release chart packaging" >&2; exit 1; }
	bash scripts/package-release-charts.sh "$(VERSION)" "$(RUNTIME_IMAGE_METADATA_DIR)" "$(HELM_SOURCE_DIR)" "$(HELM_DIST_FOLDER)" "$(RUNTIME_IMAGE_REPOSITORY)"

.PHONY: helm-publish
helm-publish: ## Package and push all Helm charts to the OCI registry
helm-publish: helm-release
	helm push "$(HELM_DIST_FOLDER)/kagent-crds-$(VERSION).tgz" $(HELM_REPO)/kagent/helm
	helm push "$(HELM_DIST_FOLDER)/kagent-$(VERSION).tgz" $(HELM_REPO)/kagent/helm

##@ Dev

.PHONY: kagent-cli-install
kagent-cli-install: ## Build CLI locally, install kagent, and open the dashboard
kagent-cli-install: kagent-cli-deploy
	KUBECONFIG=$(KIND_KUBECONFIG) ./go/core/bin/kagent-local dashboard

.PHONY: kagent-cli-deploy
kagent-cli-deploy: ## Build CLI locally and install kagent with Substrate and the development database
kagent-cli-deploy: use-kind-cluster build-cli-local helm-dev
	printf '%s\n' 'registry: "$(DOCKER_REGISTRY)"' 'tag: "$(VERSION)"' 'imagePullPolicy: Always' 'controller: {image: {pullPolicy: Always}}' 'ui: {image: {pullPolicy: Always}}' > go/core/bin/local-values.yaml
	printf '%s\n' 'atelet:' '  extraArgs: [--localhost-registry-replacement=kind-registry:5000]' 'ateApi:' '  extraArgs: [--template-resync-interval=250ms]' > go/core/bin/local-substrate-values.yaml
	printf '%s\n' 'install:' '  defaultModelProvider: $(shell printf "%s" "$(MODEL_PROVIDER)" | awk "{print toupper(substr(\$$0,1,1)) substr(\$$0,2)}")' '  kagent:' '    repository: "$(abspath $(HELM_SOURCE_DIR))/"' '    version: "$(VERSION)"' '    valuesFiles: [local-values.yaml]' '  substrate:' '    repository: "$(SUBSTRATE_REPO)/"' '    version: "$(SUBSTRATE_VERSION)"' '    valuesFiles: [local-substrate-values.yaml]' '  podCertificate:' '    repository: "$(SUBSTRATE_PODCERT_REPO)/"' '    version: "$(SUBSTRATE_PODCERT_VERSION)"' > go/core/bin/local-config.yaml
	KUBECONFIG=$(KIND_KUBECONFIG) ./go/core/bin/kagent-local --config go/core/bin/local-config.yaml install

.PHONY: kagent-cli-port-forward
kagent-cli-port-forward: ## Port-forward the kagent controller API to localhost:8083
kagent-cli-port-forward: use-kind-cluster
	@echo "Port forwarding to kagent CLI..."
	kubectl --context kind-$(KIND_CLUSTER_NAME) port-forward -n kagent service/kagent-controller 8083:8083

.PHONY: kagent-ui-port-forward
kagent-ui-port-forward: ## Open the UI in a browser and port-forward to localhost:8082
kagent-ui-port-forward: use-kind-cluster
	open http://localhost:8082/
	kubectl --context kind-$(KIND_CLUSTER_NAME) port-forward -n kagent service/kagent-ui 8082:8080

.PHONY: kagent-addon-install
kagent-addon-install: ## Install Istio, Grafana, Prometheus, and metrics-server addons on the kind cluster
kagent-addon-install: use-kind-cluster
	istioctl install --context kind-$(KIND_CLUSTER_NAME) --set profile=demo -y
	kubectl apply --context kind-$(KIND_CLUSTER_NAME) -f contrib/addons/grafana.yaml
	kubectl apply --context kind-$(KIND_CLUSTER_NAME) -f contrib/addons/prometheus.yaml
	kubectl apply --context kind-$(KIND_CLUSTER_NAME) -f contrib/addons/metrics-server.yaml
	# wait for pods to be ready
	kubectl wait --context kind-$(KIND_CLUSTER_NAME) --for=condition=Ready pod -l app.kubernetes.io/name=grafana    -n kagent --timeout=60s
	kubectl wait --context kind-$(KIND_CLUSTER_NAME) --for=condition=Ready pod -l app.kubernetes.io/name=prometheus -n kagent --timeout=60s

.PHONY: open-dev-container
open-dev-container: ## Build and start the devcontainer
	@echo "Building and starting dev container..."
	devcontainer up --workspace-folder .

.PHONY: otel-local
otel-local: ## Start a local Jaeger container for OpenTelemetry tracing (UI at localhost:16686)
	$(CONTAINER_RUNTIME) rm -f jaeger-desktop || true
	$(CONTAINER_RUNTIME) run -d --name jaeger-desktop --restart=always -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/jaeger:2.7.0
	@echo "Jaeger UI available at http://localhost:16686/"

OTEL_COLLECTOR_CHART_VERSION ?= 0.175.1

.PHONY: otel-collector-kind
otel-collector-kind: ## Install the reference OpenTelemetry Collector into the kind cluster with a debug exporter
	helm upgrade --install kagent-otel opentelemetry-collector --repo https://open-telemetry.github.io/opentelemetry-helm-charts \
		--version $(OTEL_COLLECTOR_CHART_VERSION) --kube-context kind-$(KIND_CLUSTER_NAME) --namespace observability --create-namespace \
		-f examples/observability/collector-values.yaml -f examples/observability/collector-local.yaml
	@echo "Point kagent at it with --set-string config.runtimeDefaults.telemetry.traces.endpoint=http://kagent-otel-opentelemetry-collector.observability.svc.cluster.local:4317"

.PHONY: kind-debug
kind-debug: ## Install btop/htop inside the kind control-plane container and launch btop
	@echo "Debugging the kind cluster..."
	@echo "Enter the kind cluster control plane container..."
	$(CONTAINER_RUNTIME) exec -it $(KIND_CLUSTER_NAME)-control-plane bash -c 'apt-get update && apt-get install -y btop htop'
	$(CONTAINER_RUNTIME) exec -it $(KIND_CLUSTER_NAME)-control-plane bash -c 'btop --utf-force'


##@ Security

.PHONY: audit
audit: ## Run CVE audits for Go, UI, and Python dependencies
	echo "Running CVE audit GO"
	make -C go govulncheck
	echo "Running CVE audit UI"
	make -C ui audit
	echo "Running CVE audit PYTHON"
	make -C python audit

.PHONY: report/image-cve
report/image-cve: ## Scan built images with grype and write CVE CSV reports to reports/
report/image-cve: audit build
	echo "Running CVE scan :: CVE -> CSV ... reports/$(SEMVER)/"
	grype $(CONTAINER_RUNTIME):$(CONTROLLER_IMG) -o template -t reports/cve-report.tmpl --file reports/$(SEMVER)/controller-cve.csv
	grype $(CONTAINER_RUNTIME):$(UI_IMG)         -o template -t reports/cve-report.tmpl --file reports/$(SEMVER)/ui-cve.csv


##@ Cleanup

.PHONY: clean
clean: ## Remove build artifacts, prune images, and delete the buildx builder
clean: prune-kind-cluster
clean: prune-images
ifneq ($(CONTAINER_RUNTIME),podman)
	$(CONTAINER_RUNTIME) buildx rm $(BUILDX_BUILDER_NAME)  -f || true
endif
	rm -rf ./go/core/bin

.PHONY: prune-kind-cluster
prune-kind-cluster: ## Remove dangling container images from the kind node
	echo "Pruning dangling container images from kind  ..."
	$(CONTAINER_RUNTIME) exec $(KIND_CLUSTER_NAME)-control-plane crictl images --no-trunc --quiet | \
	grep '<none>' | awk '{print $$3}' | xargs -r -n1 $(CONTAINER_RUNTIME) exec $(KIND_CLUSTER_NAME)-control-plane crictl rmi || :

.PHONY: prune-images
prune-images: ## Remove old kagent images and dangling images from the local daemon
	echo "Pruning dangling container images ..."
	$(CONTAINER_RUNTIME) images --format '{{.Repository}}:{{.Tag}} {{.ID}}' | \
	grep -v ":$(VERSION) " | grep kagent | grep -v '<none>' | awk '{print $$2}' | xargs -r $(CONTAINER_RUNTIME) rmi || :
	$(CONTAINER_RUNTIME) images --filter dangling=true -q | xargs -r $(CONTAINER_RUNTIME) rmi || :