fix(lib): default 'agentex agents build' to --no-cache so stale layers can't ship stale source

[deepthi-rao-scale]

Problem

The tutorial-agent build/publish pipeline can silently republish a stale image to the moving :latest tag. agentex agents build calls docker.buildx.build(...) with no cache control, so a cached layer can ship source that no longer matches the checkout — and the publish job still reports success, so the staleness is invisible.

Concrete failure: the mcp<2 pin merged for the 020_state_machine agent (2b7649c) never reached …/020_state_machine:latest. The build re-published a byte-identical December 2025 image (pre-pin source). scale-agentex's integration suite pulls :latest, so the 10-async-10-temporal-020-state-machine test runs the months-old image, uvx mcp-server-time resolves mcp==2.0.0, and the McpError→MCPError rename crashes it:

ImportError: cannot import name 'McpError' from 'mcp.shared.exceptions'. Did you mean: 'MCPError'?

This currently reddens that required check on unrelated PRs (e.g. scale-agentex #384, #385).

Fix

Make the build cache-free by default and expose a toggle:

• build_agent() gains cache: bool = False → passed through to docker.buildx.build (cache=False ⇒ docker buildx build --no-cache).
• agentex agents build exposes --cache/--no-cache, defaulting to --no-cache.

So a bare agentex agents build no longer caches — which means the existing build-and-push-tutorial-agent.yml needs no change (it already runs a bare build). A stale cached layer can no longer get published. --cache is available to opt back in for faster local rebuilds when you know the cache is safe.

Effect / rollout

This changes the SDK CLI, and the build workflow installs agentex-sdk from PyPI (pip install agentex-sdk==<latest>), not from the repo checkout. So it takes effect once:

1. this merges and agentex-sdk is released to PyPI with it, then
2. a tutorial-agent build runs (push to main touching examples/tutorials/**, or a rebuild_all dispatch) and pip-installs that version.

That rebuild will produce 020_state_machine:latest from current source (which already has the mcp<2 pin), turning the scale-agentex integration check green. It also prevents this silent-stale-publish class for every tutorial agent.

Related

Build-provenance work (#454, releasing in #475) records a deterministic working-tree hash; if later wired in as a cache key it would be a more surgical fix. This is the immediate, guaranteed prevention and doesn't touch those files.

Testing

• python -m py_compile on both changed modules ✓
• cache=False maps to python-on-whales docker.buildx.build(cache=False) → buildx --no-cache ✓

🤖 Generated with Claude Code

Greptile Summary

This PR fixes a silent stale-layer problem where agentex agents build could republish a byte-identical cached image to a moving tag like :latest without any indication that the source had changed.

• Adds cache: bool = False to build_agent() in agent_handlers.py, passing it directly into docker_build_kwargs["cache"] before both docker.buildx.build() call-sites; the python-on-whales library maps cache=False to docker buildx build --no-cache.
• Exposes --cache/--no-cache on the agentex agents build CLI command (via typer.Option), defaulting to --no-cache, so existing bare invocations in CI workflows immediately benefit without any workflow changes.

Confidence Score: 5/5

Safe to merge — a two-parameter addition with no behavioural regressions on the happy path.

Both changed files are small and self-contained. The cache parameter maps correctly to the python-on-whales docker.buildx.build(cache=False) API (confirmed via docs), the typer option is wired end-to-end without any intermediate transform, the default of False matches the stated intent, and the pre-existing --push/--registry guard is untouched. No edge-case issues were found.

Files Needing Attention: No files require special attention.

Important Files Changed

Filename	Overview
src/agentex/lib/cli/handlers/agent_handlers.py	Adds cache: bool = False to build_agent(), correctly threads it into docker_build_kwargs["cache"] before both docker.buildx.build() calls; python-on-whales API confirms cache=False emits --no-cache.
src/agentex/lib/cli/commands/agents.py	Exposes --cache/--no-cache via a typer.Option defaulting to False; wires the value through to build_agent(). No logic issues.

Sequence Diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as agents.py (build cmd)
    participant Handler as agent_handlers.py (build_agent)
    participant Docker as docker.buildx.build (python-on-whales)

    User->>CLI: "agentex agents build [--cache | --no-cache]"
    Note over CLI: cache: bool = False (default = --no-cache)
    CLI->>Handler: "build_agent(..., cache=cache)"
    Handler->>Handler: "Assemble docker_build_kwargs {cache: cache}"
    alt "cache == False (default)"
        Handler->>Handler: logger.info(Build cache disabled)
        Handler->>Docker: "docker.buildx.build(**kwargs) → --no-cache"
    else "cache == True"
        Handler->>Docker: "docker.buildx.build(**kwargs) → with cache"
    end
    Docker-->>Handler: image built
    Handler-->>CLI: image_name
    CLI-->>User: Successfully built image: ...

Loading

_{Reviews (3): Last reviewed commit: "make no-cache the default and drop the w..." | Re-trigger Greptile}