Pre-flight validation for `agents-cli deploy` (e.g. detect lockfiles pinned to package indexes unreachable from the remote build)

Start by tracing the agents-cli deploy command and its existing check for an ignored Dockerfile; the issue does not name that command's file or tests. Compare dev/cmd_install.py and scaffold/utils/generate_locks.py to understand how install and scaffold handle lockfiles and index configuration. Define the pre-flight checks and their error-versus-warning behavior before implementing; done means deploy reports actionable findings before upload, with skip and dry-run behavior as described.

What is your feature suggestion?

Add a fast, offline pre-flight validation step to agents-cli deploy that runs before source is uploaded for a remote build (Agent Runtime, Cloud Run source builds, GKE via Cloud Build). It catches configuration problems that are certain to make the remote build fail, and reports each one with an actionable fix.

Headline check: lockfile references a package index the remote builder can't reach.

Many enterprises configure Python package managers machine-wide (for example a system-level uv.toml or pip.conf) to resolve packages through an internal mirror or security proxy. uv records the index URL of every package in uv.lock. The scaffolded Dockerfile runs uv sync --frozen, which downloads from exactly those URLs. The managed build environment has no route to the internal mirror, so the build fails.

The CLI currently surfaces only:

❌ Error: Deployment failed: {'code': 3, 'message': 'Build failed. The issue might be caused by
incorrect code, requirements.txt file or other dependencies. ...'}

The real cause (Failed to download <package> ... Connection refused) is only visible by querying Cloud Logging for the reasoning_engine_build log, which most users won't know exists. Because the failure doesn't depend on the code, it reproduces with an unmodified scaffolded template, in every region.

Proposed behavior:

❌ Pre-flight: uv.lock pins 175 packages to a package index that remote builds may not be able to reach:
     http://<internal-mirror-host>/simple/
   This usually comes from a machine-wide package manager config (e.g. a system uv.toml).
   Fix (any one):
     • Re-lock against the public index:  uv lock --no-config --default-index https://pypi.org/simple
     • Pin the public index in pyproject.toml so future locks stay deployable:
         [[tool.uv.index]]
         name = "pypi"
         url = "https://pypi.org/simple"
         default = true
   Skip with --skip-preflight if this index is reachable from your build environment.

Other checks that fit the same step (all offline, all cases where the remote build is certain to fail or the deployed agent to break):

1. Lockfile missing or out of sync with pyproject.toml. uv sync --frozen fails without a lockfile, and with a stale one it silently installs an outdated set of dependencies.
2. Build inputs excluded from the upload. Files the Dockerfile COPYs (e.g. uv.lock, README.md, the agent directory) are matched by .gcloudignore/.gitignore, or local path dependencies (path = "../shared-lib") live outside the upload. This generalises the existing check that the Dockerfile isn't ignored.
3. Python version mismatch. The Dockerfile base image's Python version (e.g. FROM python:3.12-slim) doesn't satisfy requires-python in pyproject.toml.

Suggested controls: errors block the deploy; warnings don't (e.g. a private index that may be legitimately reachable); --skip-preflight bypasses the checks; --dry-run runs them, reports the results, and exits non-zero if any error is found, so it can gate CI or a coding agent's deploy step.

Related inconsistency: agents-cli install undoes the scaffold's public lockfile. The scaffold deliberately generates uv.lock against the public index (scaffold/utils/generate_locks.py runs uv lock --no-config --default-index https://pypi.org/simple, "to ensure consistent lock files"). agents-cli install (dev/cmd_install.py) then runs plain uv sync, which honours the machine-wide config. On a workstation with a mirror configured, that re-resolves the lock against the mirror and turns a deployable template into one that can't be deployed. Suggestion: agents-cli install (and anything else agents-cli runs to lock or sync) should follow the same index policy as the scaffold without overriding an index the project pins itself. Where forcing the public index isn't appropriate (some networks only allow the mirror), it should at least warn when the resulting lock references a non-public index.

What will this enable you to do?

• Fail in about a second, locally, instead of waiting for a remote build to fail (about a minute per attempt in our case, longer for larger dependency sets), with a message naming the cause and the fix, instead of a generic "Build failed" that sends people searching through Cloud Logging.
• Deploy reliably from enterprise-managed workstations. Machine-wide package mirrors are common in regulated and security-conscious organisations. Today these users hit an opaque failure even with an unmodified template, and the usual workarounds (dropping the lockfile, removing --frozen) give up reproducible builds.
• Help coding agents too. Agents driving agents-cli deploy get a clear, machine-readable failure they can fix themselves, instead of guessing at dependencies, regions or permissions.
• Keep the CLI consistent. It already catches one problem of this kind before uploading (a Dockerfile excluded by ignore rules "instead of failing opaquely in Agent Engine"). A small pre-flight framework would let more of these checks be added the same way.

Additional context

Related issues:

• #17, #36, #42: three different root causes (missing lockfile, Python version mismatch, dependency that wouldn't resolve), all showing up as the same opaque code: 3 Build failed. Pre-flight checks and showing the build log would have saved time in each.
• #48: deployment-readiness contract. This proposal could be one concrete piece of it.

Reproduction (no internal infrastructure needed):

1. agents-cli scaffold create demo --agent adk --deployment-target agent_runtime --prototype, then agents-cli install.
2. Simulate a lock produced behind a machine-wide mirror by pointing its URLs at a host the remote builder can't reach:

   sed -i.bak -e 's#https://pypi.org/simple#http://10.0.0.1:3141/simple#' \
              -e 's#https://files.pythonhosted.org#http://10.0.0.1:3141#g' uv.lock
   

   In real life a machine-wide uv.toml pointing at an internal mirror produces the same kind of lock with plain uv lock.
3. agents-cli deploy → Build failed (code 3) after the remote build starts.
4. The real error is only in Cloud Logging, under logName=".../logs/aiplatform.googleapis.com%2Freasoning_engine_build":

   RUN uv sync --frozen
   × Failed to download `attrs==26.1.0`
     ├─▶ Failed to fetch: `http://<internal-mirror-host>/.../attrs-26.1.0-py3-none-any.whl`
     ╰─▶ Connection refused
   

5. Re-locking against the public index (uv lock --no-config --default-index https://pypi.org/simple) gives an identical set of package versions (only the URLs change) and the deploy succeeds.

Observations:

• gcloud builds list in the user's project shows nothing, because the build runs in a Google-managed project. The forwarded log under aiplatform.googleapis.com/reasoning_engine_build is the only place the cause appears. A related improvement would be for agents-cli deploy to print the tail of that log when the operation fails with Build failed.
• Verified with uv 0.12: adding [[tool.uv.index]] … default = true to pyproject.toml overrides a machine-wide index for uv lock/uv add. A project-level uv.toml with default-index = … is rejected as an unknown field.

Environment: agents-cli 1.8.0, google-adk 2.10.0, uv 0.12.x, macOS (managed workstation), deployment target agent_runtime (reproduced in us-west1 and us-central1).

I'm happy to contribute an implementation if the approach is acceptable.