[QueryPlanner]

What

Add a private, one-time Agent Browser takeover flow for sensitive human login steps in Telegram.

Why

Let the authenticated Telegram user enter passwords, OTPs, or CAPTCHA responses directly in the existing session browser without exposing those values to the model or ADK history.

How

• Register start_browser_takeover only for the private Telegram root agent.
• Send a protected, user-bound Telegram link with a single-use fragment token.
• Redeem the token into an HttpOnly, SameSite cookie and proxy the browser stream same-origin.
• Keep sandbox routing details server-side and clean up streams on completion, expiry, disconnect, and startup failure.
• Normalize configured public URL origins so default ports match browser origin serialization.
• Report when the user returns control without claiming that login succeeded.
• Document HTTPS, Tailscale, reverse-proxy, and environment configuration.

Tests

• uv run ruff format --check
• uv run ruff check --output-format=github
• uv run mypy .
• uv run pytest --cov=src --cov-report=xml --cov-report=term-missing (2,332 passed, 1 skipped, 100% coverage)
• uv run python -m compileall -q src
• git diff --check
• Manual disposable-account Telegram/OpenSandbox smoke test in the configured deployment environment

Related Issues

• None identified.

[QueryPlanner]

I found one blocking correctness issue in the takeover lifecycle. CI is green, but the current tests explicitly encode the problematic behavior: a WebSocket disconnect or upstream connection failure is treated the same as the user clicking Done. That can resume the agent with a false success signal before authentication is complete. I’d fix that before merging.

[QueryPlanner]

Reviewed at a61d12b. The branch now includes current main, GitHub reports it mergeable, and both required workflows pass. I found no remaining code blockers after fixing the disconnect completion behavior and default-port origin normalization. Local format, lint, type checks, full tests (2,332 passed, 1 skipped, 100% coverage), compileall, and diff checks pass. The disposable-account Telegram/OpenSandbox smoke test remains unchecked in the PR body and should be completed in the configured deployment environment.