Document credential access in execute_bash tool

[xingyaoww]

Summary

This PR enhances the execute_bash tool to help agents understand and use the secret manager system effectively.

Changes

1. Documentation (Initial Commit)

Added a new "Credential Access" section to the TOOL_DESCRIPTION in openhands-tools/openhands/tools/execute_bash/definition.py that documents:

• Automatic secret injection: How secrets are automatically exported as environment variables when referenced in bash commands
• How to use secrets: Clear examples showing agents how to reference secret keys in their commands (e.g., $GITHUB_TOKEN, $API_KEY)
• Secret detection: Explanation of the case-insensitive matching mechanism that detects secret keys in command text
• Security: Information about automatic output masking to prevent accidental secret exposure

2. Available Secrets in Metadata (New Feature)

Enhanced ExecuteBashObservation to show agents which secrets are available:

• Added available_secrets field to CmdOutputMetadata to store list of available secret names
• Populate available secrets from conversation.state.secret_registry.secret_sources.keys() in the executor
• Display in LLM output via ExecuteBashObservation.to_llm_content() showing format: [Available secrets: $SECRET1, $SECRET2, $SECRET3]
• Added test coverage in test_bash_executor_metadata_available_secrets() to verify the functionality

This helps agents discover what credentials they can access without having to guess or try different secret names.

Implementation Details

The implementation reflects the actual secret manager behavior in openhands-tools/openhands/tools/execute_bash/impl.py:

1. Before executing a bash command, the _export_envs() method calls secret_registry.get_secrets_as_env_vars(action.command)
2. The secret registry searches the command text for registered secret keys (case-insensitive)
3. Found secrets are exported as environment variables using export KEY="value" before the actual command runs
4. Secret values are automatically masked in output, showing <secret-hidden> instead
5. Available secret names are now shown in the observation metadata and LLM-facing output

Testing

• ✅ All pre-commit checks pass (ruff format, ruff lint, pycodestyle, pyright)
• ✅ All secret masking tests pass: tests/tools/execute_bash/test_secrets_masking.py (3 tests)
• ✅ New test added: test_bash_executor_metadata_available_secrets() verifies:
  • Available secrets are correctly populated in metadata.available_secrets
  • Secrets are displayed in LLM-facing content with $ prefix
  • Multiple secrets are properly listed

Example Output

When an agent executes a bash command with secrets available, they'll now see:

[Command: echo "test"]
test
[Current working directory: /workspace]
[Python interpreter: /usr/bin/python3]
[Available secrets: $GITHUB_TOKEN, $API_KEY, $DATABASE_URL]
[Command finished with exit code 0]

Why This Matters

This enhancement helps agents:

1. Understand the correct way to access credentials in bash commands
2. Discover which credentials are available without trial and error
3. Use credentials correctly for tasks involving:
   • API interactions requiring authentication
   • Git operations needing tokens
   • Database access
   • External service integrations
   • Any authenticated operations

Co-authored-by: openhands [email protected]

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:588f72f-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-588f72f-python \
  ghcr.io/openhands/agent-server:588f72f-python

All tags pushed for this build

ghcr.io/openhands/agent-server:588f72f-golang-amd64
ghcr.io/openhands/agent-server:v1.0.0a5_golang_tag_1.21-bookworm_binary-amd64
ghcr.io/openhands/agent-server:588f72f-golang-arm64
ghcr.io/openhands/agent-server:v1.0.0a5_golang_tag_1.21-bookworm_binary-arm64
ghcr.io/openhands/agent-server:588f72f-java-amd64
ghcr.io/openhands/agent-server:v1.0.0a5_eclipse-temurin_tag_17-jdk_binary-amd64
ghcr.io/openhands/agent-server:588f72f-java-arm64
ghcr.io/openhands/agent-server:v1.0.0a5_eclipse-temurin_tag_17-jdk_binary-arm64
ghcr.io/openhands/agent-server:588f72f-python-amd64
ghcr.io/openhands/agent-server:v1.0.0a5_nikolaik_s_python-nodejs_tag_python3.12-nodejs22_binary-amd64
ghcr.io/openhands/agent-server:588f72f-python-arm64
ghcr.io/openhands/agent-server:v1.0.0a5_nikolaik_s_python-nodejs_tag_python3.12-nodejs22_binary-arm64
ghcr.io/openhands/agent-server:588f72f-golang
ghcr.io/openhands/agent-server:588f72f-java
ghcr.io/openhands/agent-server:588f72f-python

About Multi-Architecture Support

• Each variant tag (e.g., 588f72f-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 588f72f-python-amd64) are also available if needed

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-tools/openhands/tools/execute_bash
definition.py	104	63	39%	54, 57, 60–61, 63, 66–68, 70–72, 74–76, 78, 108, 112–124, 129, 132–134, 137, 139–141, 143, 147–148, 151–153, 155–156, 159–162, 166–168, 173, 177–179, 182–184, 188–189, 191, 262
impl.py	72	23	68%	58, 61, 69–70, 97–99, 101–102, 108, 110, 114, 130, 133, 136–137, 142–144, 154, 177–178, 180
metadata.py	51	6	88%	78–79, 83, 101–102, 106
TOTAL	11678	5388	53%