Background Agent hangs indefinitely during authentication in headless environments

[ehedlund]

Summary

The CLI auth logic has a dependency on interactive stdin when a browser cannot be launched. When the agent is run as a background process (specifically for GCA) in headless environments like Cloud Shell or Cloud Workstations, it encounters a "silent hang," preventing the server from ever successfully starting.

Root Cause

1. Forced Interactive Fallback: In packages/core/src/code_assist/oauth2.ts, if the library detects that a browser cannot be opened (isBrowserLaunchSuppressed()), it automatically falls back to authWithUserCode.
2. The Blocking Call: authWithUserCode creates a readline interface and executes rl.question('Enter the authorization code: ', ... ).
3. The Hang: In the VS Code extension context, the Agent (a2a-server) is a background process. Its stdin is a pipe, not a TTY. It waits indefinitely for user input that can never be provided, causing the process to hang before it can log its port or start serving requests.
4. Identity Mismatch: Currently, the agent forces a user-based OAuth login even when running in environments (like Cloud Workstations) where a machine identity (Metadata Server) is available and should be used as a fallback.

Proposed Solution

We need to make the below 3 changes.

1. Prevent the Hang (packages/core)

Modify the OAuth client initialization to respect the interactivity of the session:

• In oauth2.ts, before calling authWithUserCode, check config.isInteractive().
• If the session is non-interactive and a browser cannot be opened, throw a FatalAuthenticationError immediately. This turns a silent hang into a catchable exception.

2. Dynamic Interactivity (packages/a2a-server)

Update the A2A server configuration to detect its environment:

• In src/config/config.ts, set the interactive flag dynamically using !isHeadlessMode().
• This ensures the core library knows whether it's safe to prompt for input based on the presence of a TTY.

3. Implement Automated Fallback (packages/a2a-server)

Align the Agent's authentication behavior with the GCA Language Server:

• In the server's refreshAuthentication logic, wrap the LOGIN_WITH_GOOGLE attempt in a try-catch block.
• If it fails with a FatalAuthenticationError (indicating a headless environment with no saved credentials) and the environment is detected as Cloud Shell or Cloud Workstations, automatically fall back to AuthType.COMPUTE_ADC.
• This allows the agent to transparently use the workstation's built-in identity when user credentials are unavailable.