WP: fix(tools): evict stale credential and re-request auth on 401 in RestApiTool

[philipp-horstenkamp]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: [Bug]: Unhandled HTTP 401 in RestApiTool traps chat sessions in unrecoverable auth loops #7085

2. Or, if no issue exists, describe the change:

Problem:
When an authenticated RestApiTool (e.g., from OpenAPIToolset using OAuth2 or OpenID Connect) encounters an HTTP 401 Unauthorized response because an access token has expired or was revoked and refresh is unavailable or fails, RestApiTool.call() catches httpx.HTTPStatusError generically and returns a text error string ({"error": "Tool ... execution failed ... Status Code: 401 ..."}) directly to the LLM agent.

Crucially, the stale credential was not evicted from tool_context.state. Because the dead token remains in session state across turns, subsequent user messages continue attempting to reuse the revoked token. The session enters an unrecoverable 401 loop and never re-prompts the user for authorization.

Solution:

1. State Deletion & Delta Tombstoning:

   • Added __delitem__ and pop to google.adk.sessions.state.State.
   • Properly sets a tombstone (None) in _delta so deletions persist across session checkpoints.
   • Raises standard KeyError if key does not exist to prevent phantom delta tombstones.
   • Updated __contains__, __getitem__, and to_dict to recognize deleted entries.

2. Credential Eviction & Re-authentication:

   • Updated ToolContextCredentialStore.remove_credential(key) to safely delete keys from tool_context.state.
   • Added ToolAuthHandler.evict_credential() which evicts only the specific stored credential key associated with the tool's authentication scheme (leaving unrelated session state intact) and triggers _request_credential().

3. HTTP 401 Interception in RestApiTool:

   • In RestApiTool.call(), when an HTTPStatusError with status code 401 occurs on a tool with an active auth_scheme, call tool_auth_handler.evict_credential() and return {"pending": True, "message": "Your authorization has expired. Needs your authorization to access your data."}.
   • This registers the requested authentication action in the ADK runtime, prompting the web UI / CLI dev server to display the re-authorization prompt and breaking the infinite 401 loop.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Summary of test results (pytest):

tests/unittests/sessions/test_state.py .......                           [  8%]
tests/unittests/tools/openapi_tool/openapi_spec_parser/test_tool_auth_handler.py ............. [ 23%]
tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py ................................................................. [100%]

====================== 86 passed, 23 warnings in 50.46s =======================

Added tests cover:

• State.__delitem__, State.pop, and delta tombstoning in tests/unittests/sessions/test_state.py.
• Safe removal of credential keys and re-auth triggering in tests/unittests/tools/openapi_tool/openapi_spec_parser/test_tool_auth_handler.py.
• HTTP 401 eviction + pending re-auth flow, 401 on unauthenticated tools (no eviction), and HTTP 403 non-eviction behavior in tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py.

Manual End-to-End (E2E) Tests:

1. Configured an OpenAPI tool with OAuth 2.0 / OpenID Connect authorization.
2. Simulated upstream token revocation / expiry returning HTTP 401.
3. Verified the stale credential key is removed from tool_context.state.
4. Verified tool_context.request_credential() is dispatched and the tool returns a pending status, prompting the client/user for fresh consent rather than looping on the expired token.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

[philipp-horstenkamp]

Self review is not yet as though as i would like. I plan to continue on this tomorrow.