fix(lib): build ':latest' tutorial agents with --no-cache to stop shipping stale source

The tutorial-agent build/publish pipeline could silently republish a stale
image to the moving ':latest' tag. 'agentex agents build' invoked
'docker.buildx.build' with no cache control, so a cached layer could ship
source that no longer matched the checkout -- e.g. the merged 'mcp<2' pin for
the 020_state_machine agent never reached ':latest', leaving integration tests
pulling a months-old image and failing on the mcp 2.0.0 'McpError' rename.

- add a 'cache' param to build_agent() -> passes cache=False (buildx
  --no-cache) through to the build
- expose '--cache/--no-cache' on 'agentex agents build' (default: cache on, so
  local dev and immutable SHA builds stay fast)
- build-and-push-tutorial-agent.yml uses --no-cache only for the ':latest'
  publish path; SHA-tagged validation builds keep the cache

Related: build-provenance work (#454) records a working-tree hash and could
later provide a more surgical cache-key-based fix; this is the immediate,
guaranteed prevention.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: deepthi-rao-scale

.github/workflows/build-and-push-tutorial-agent.yml

@@ -185,10 +185,15 @@ jobs:
           if [ "${{ github.event_name }}" = "push" ] || [ "${{ inputs.rebuild_all }}" = "true" ]; then
             SHOULD_PUSH=true
             VERSION_TAG="latest"
+            # ':latest' is a moving tag, so build without cache: a stale cached layer
+            # must never silently ship source that differs from the checkout.
+            CACHE_FLAG="--no-cache"
             echo "🚀 Building agent (will push after validation): ${{ matrix.agent_path }}"
           else
             SHOULD_PUSH=false
             VERSION_TAG="${{ github.sha }}"
+            # SHA-tagged validation build is immutable, so the cache is safe (and faster).
+            CACHE_FLAG="--cache"
             echo "🔍 Building agent for validation: ${{ matrix.agent_path }}"
             # Set full image name for validation step (local build)
             echo "FULL_IMAGE=${REGISTRY}/${REPOSITORY_NAME}:${VERSION_TAG}" >> $GITHUB_ENV
@@ -197,7 +202,7 @@ jobs:
           fi
 
           # Always build locally first (without push)
-          BUILD_ARGS="--manifest ${{ matrix.agent_path }}/manifest.yaml --registry ${REGISTRY} --tag ${VERSION_TAG} --platforms linux/amd64,linux/arm64 --repository-name ${REPOSITORY_NAME}"
+          BUILD_ARGS="--manifest ${{ matrix.agent_path }}/manifest.yaml --registry ${REGISTRY} --tag ${VERSION_TAG} --platforms linux/amd64,linux/arm64 --repository-name ${REPOSITORY_NAME} ${CACHE_FLAG}"
 
           agentex agents build $BUILD_ARGS
           echo "✅ Successfully built: ${REGISTRY}/${REPOSITORY_NAME}:${VERSION_TAG}"

src/agentex/lib/cli/commands/agents.py

@@ -127,6 +127,12 @@ def build(
         None,
         help="Docker build argument in the format 'KEY=VALUE' (can be used multiple times)",
     ),
+    cache: bool = typer.Option(
+        True,
+        "--cache/--no-cache",
+        help="Use the build cache (default). Pass --no-cache when republishing a moving "
+        "tag like ':latest' so a stale cached layer can't ship outdated source.",
+    ),
 ):
     """
     Build an agent image locally from the given manifest.
@@ -155,6 +161,7 @@ def build(
             secret=secret or "",  # Provide default empty string
             tag=tag or "latest",  # Provide default
             build_args=build_arg or [],  # Provide default empty list
+            cache=cache,
         )
         if image_url:
             typer.echo(f"Successfully built image: {image_url}")

src/agentex/lib/cli/handlers/agent_handlers.py

@@ -39,6 +39,7 @@ def build_agent(
     secret: str | None = None,
     tag: str | None = None,
     build_args: list[str] | None = None,
+    cache: bool = True,
 ) -> str:
     """Build the agent locally and optionally push to registry
 
@@ -49,6 +50,10 @@ def build_agent(
         secret: Docker build secret in format 'id=secret-id,src=path-to-secret-file'
         tag: Image tag to use (defaults to 'latest')
         build_args: List of Docker build arguments in format 'KEY=VALUE'
+        cache: Whether to use the build cache. Defaults to True. Set to False (passes
+            --no-cache to buildx) when republishing a moving tag like ':latest' so a
+            stale cached layer can't silently ship source that no longer matches the
+            checkout.
 
     Returns:
         The image URL
@@ -85,7 +90,10 @@ def build_agent(
                 "file": str(build_context.path / build_context.dockerfile_path),  # type: ignore[operator]
                 "tags": [image_name],
                 "platforms": platforms,
+                "cache": cache,  # cache=False -> `docker buildx build --no-cache`
             }
+            if not cache:
+                logger.info("Build cache disabled (--no-cache)")
 
             # Add Docker build args if provided
             if build_args: