fix(cli): serve dev UI behind prefix-stripping proxies

[reddynitish]

Link to Issue

Closes #7439.

Problem and Solution

With url_prefix=/adk, a proxy that forwards /adk/dev-ui/ as /dev-ui/ causes ADK 2.11 to return 404. Starlette's static mount includes /adk in its child root_path, but the incoming path lacks it, so the static lookup retains dev-ui/ inside the asset directory.

Use a private StaticFiles subclass that restores a missing application root in a copied scope for file-path lookup. Keep FastAPI's root_path, Swagger URLs, runtime configuration, and other routes unchanged. Already-prefixed paths are recognized at a path boundary.

Testing Plan

• Regression observed before the fix: three stripped-prefix cases failed with 404; retained-prefix and outer-mount cases passed.

• Final API-server module: 229 passed, 5 skipped, 1 xfailed.

• Seven regression configurations cover no prefix, stripped/retained prefixes, an outer mount, a nested prefix, /dev versus /dev-ui, and an absolute backend URL. Checks include HTML, a static asset, missing-file 404, runtime config, /list-apps, Swagger, and OpenAPI.

• All applicable pre-commit checks passed.

• File-level mypy diagnostics match the base revision exactly: 49 existing errors, no new errors.

• Full unit suites executed through tox on Python 3.11–3.14:

  Python	Passed	Failed	Skipped	Xfailed	Xpassed
  3.11	17,919	5	89	25	2
  3.12	17,911	5	90	25	2
  3.13	17,909	7	90	25	2
  3.14	17,909	7	90	25	2

  Baseline failures: The five failures in every version are GKE code-executor tests rejecting a mocked uid as a string. Python 3.13 and 3.14 also fail the agent and runner entry-point package allowlist tests. Each failing test was rerun against the unmodified base source in the same corresponding tox environment and reproduced. The full suites are therefore not green; this draft does not claim otherwise. The changed API-server module and new regression cases passed in every version.

  Ran the initial full tox invocation through completion of py311, then stopped its redundant py312 rerun; py312/py313/py314 completed in a separate tox -e py312,py313,py314 -p auto invocation.

Manual E2E: Started adk web --host 127.0.0.1 --port 8765 --url_prefix /adk with a minimal agent. Put an HTTP proxy on port 8766 that forwards /adk/* to the server after stripping /adk. Opened /adk/dev-ui/ in a browser and verified the UI renders with the agent selected. No model credentials or inference calls are required to reproduce this routing bug.

GET /adk/dev-ui/ -> forwards /dev-ui/ -> 200 text/html
GET /adk/dev-ui/adk_favicon.svg -> forwards /dev-ui/adk_favicon.svg -> 200 image/svg+xml
GET /adk/list-apps -> forwards /list-apps -> 200 application/json
GET /adk/docs -> forwards /docs -> 200 text/html
GET /adk/openapi.json -> forwards /openapi.json -> 200 application/json
GET /adk/dev-ui/assets/config/runtime-config.json -> forwards /dev-ui/assets/config/runtime-config.json -> 200 application/json

Swagger still references /adk/openapi.json, and runtime config still reports /adk as the backend URL.

Checklist

• Read CONTRIBUTING.md.
• Performed a self-review.
• Added regression tests and a comment explaining the scope normalization.
• Manually tested end-to-end through a prefix-stripping proxy.
• Full multi-version unit suites pass.

Codex-assisted contribution. CLA status remains subject to the repository's check; no agreement was signed by the coding assistant.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.