fix(tools): Gracefully handle missing PS1 metadata instead of crashing by VascoSch92 · Pull Request #2742 · OpenHands/software-agent-sdk

VascoSch92 · 2026-04-07T14:13:17Z

Summary

Replaces the hard assert in _handle_completed_command with a graceful fallback when no PS1 metadata markers are found in the terminal output
Returns a valid TerminalObservation with exit_code=-1 and a warning suffix instead of crashing the session
This happens when commands produce complex output (TUI rendering from libraries like ratatui, ANSI escape sequences, very large output) that corrupts or scrolls the ###PS1JSON###...###PS1END### markers off the screen buffer

Fixes #2416

Test plan

New test: test_issue_2416_missing_ps1_metadata_graceful_fallback
All 13 PS1 metadata tests pass
Manual: run cargo test in a Rust project with TUI components inside OpenHands

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.13-nodejs22-slim`	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:76ef39b-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:76ef39b-golang-amd64
ghcr.io/openhands/agent-server:76ef39b-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:76ef39b-golang-arm64
ghcr.io/openhands/agent-server:76ef39b-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:76ef39b-java-amd64
ghcr.io/openhands/agent-server:76ef39b-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:76ef39b-java-arm64
ghcr.io/openhands/agent-server:76ef39b-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:76ef39b-python-amd64
ghcr.io/openhands/agent-server:76ef39b-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:76ef39b-python-arm64
ghcr.io/openhands/agent-server:76ef39b-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:76ef39b-golang
ghcr.io/openhands/agent-server:76ef39b-java
ghcr.io/openhands/agent-server:76ef39b-python

About Multi-Architecture Support

Each variant tag (e.g., 76ef39b-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., 76ef39b-python-amd64) are also available if needed

When commands produce complex output (TUI rendering, ANSI escape sequences, large output), the PS1 metadata markers can be corrupted or scrolled off the terminal screen buffer. Previously this caused a hard assert crash. Now the session returns a valid observation with exit_code=-1 and a warning suffix, allowing the agent to continue. Fixes #2416 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-07T14:13:44Z

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-07T14:13:56Z

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

all-hands-bot

Pragmatic fix for a real crash. The fallback logic is sound and properly handles the edge case when PS1 metadata goes missing. Minor code duplication is acceptable given the simplicity trade-off.

openhands-tools/openhands/tools/terminal/terminal/terminal_session.py

tests/tools/terminal/test_terminal_ps1_metadata.py

VascoSch92 · 2026-04-07T14:19:42Z

@OpenHands fix the pre-commit check and follow the suggestion here #2742 (comment). Then push into this branch the changes.

openhands-ai · 2026-04-07T14:20:07Z

I'm on it! VascoSch92 can track my progress at all-hands.dev

- Fix ruff format issues in terminal_session.py and test_terminal_ps1_metadata.py - Update test_ps1_corruption.py tests to verify graceful fallback behavior instead of expecting AssertionError (matches new graceful handling logic) Co-authored-by: openhands <openhands@all-hands.dev>

VascoSch92 · 2026-04-07T14:23:09Z

Fixed the pre-commit check and updated the tests in commit 8485fa5:

Pre-commit formatting fixes:
- Fixed ruff format issue in terminal_session.py (line 179) - CmdOutputMetadata call on single line
- Fixed ruff format issue in test_terminal_ps1_metadata.py (line 382-384) - string concatenation on single line
Test updates:
- Updated test_handle_completed_command_fails_with_corrupted_output → test_handle_completed_command_graceful_fallback_with_corrupted_output
- Updated test_terminal_session_handles_corrupted_output_gracefully
- Both tests now verify the graceful fallback behavior (returning a valid TerminalObservation with exit_code=-1) instead of expecting an AssertionError

The review comment at discussion r3045624320 suggested documenting the exit_code=-1 sentinel but concluded it was "acceptable as-is" since the suffix message explains the situation to users.

This comment was created by an AI assistant (OpenHands) on behalf of @VascoSch92.

openhands-ai · 2026-04-07T14:23:34Z

Summary of Work Completed

Request Checklist

Request	Status
Fix the pre-commit check	✅ Complete
Follow the suggestion at discussion r3045624320	✅ Complete (the suggestion concluded "acceptable as-is")
Push changes to the branch	✅ Complete

Changes Made (commit `8485fa5`)

1. Pre-commit formatting fixes:

terminal_session.py: Single-line format for CmdOutputMetadata call
test_terminal_ps1_metadata.py: Single-line format for string concatenation

2. Test updates in test_ps1_corruption.py:

Updated 2 tests that were failing because they expected AssertionError to be raised
Tests now verify the graceful fallback behavior (exit_code=-1, valid TerminalObservation)

Conciseness Check

✅ All changes are directly related to fixing the CI failures - no extraneous changes were made.

Notes

The review comment (r3045624320) suggested documenting the exit_code=-1 sentinel but concluded it was "acceptable as-is" since the suffix message explains the situation to users. No additional code changes were needed for that suggestion.
All 24 PS1-related tests pass locally
CI checks are now running on the pushed commit

github-actions · 2026-04-07T14:29:56Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-tools/openhands/tools/terminal/terminal
terminal_session.py	203	76	62%	95, 101, 105–107, 143–144, 174, 179–180, 185, 191, 194–198, 213, 228–229, 270–272, 277, 280–281, 285, 291, 294, 309–311, 316, 319–320, 324, 330, 333, 353, 355, 358, 360, 376, 391, 397, 406, 409, 443, 447, 450, 453–454, 460–461, 467, 470, 477–478, 484–485, 544–546, 550, 555, 560–561, 565–566, 569–572, 578–579, 582
TOTAL	22050	11097	49%

all-hands-bot · 2026-04-12T12:25:19Z

[Automatic Post]: This PR seems to be currently waiting for review. @enyst, @xingyaoww, could you please take a look when you have a chance?

VascoSch92 requested a review from all-hands-bot April 7, 2026 14:14

VascoSch92 changed the title ~~Gracefully handle missing PS1 metadata instead of crashing~~ fix(tools): Gracefully handle missing PS1 metadata instead of crashing Apr 7, 2026

all-hands-bot approved these changes Apr 7, 2026

View reviewed changes

openhands-tools/openhands/tools/terminal/terminal/terminal_session.py Show resolved Hide resolved

openhands-tools/openhands/tools/terminal/terminal/terminal_session.py Show resolved Hide resolved

tests/tools/terminal/test_terminal_ps1_metadata.py Show resolved Hide resolved

VascoSch92 requested review from enyst and xingyaoww April 7, 2026 14:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(tools): Gracefully handle missing PS1 metadata instead of crashing#2742

fix(tools): Gracefully handle missing PS1 metadata instead of crashing#2742
VascoSch92 wants to merge 2 commits intomainfrom
fix/ps1-metadata-graceful-fallback

VascoSch92 commented Apr 7, 2026 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

all-hands-bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VascoSch92 commented Apr 7, 2026

Uh oh!

openhands-ai bot commented Apr 7, 2026

Uh oh!

VascoSch92 commented Apr 7, 2026

Uh oh!

openhands-ai bot commented Apr 7, 2026

Uh oh!

github-actions bot commented Apr 7, 2026

Uh oh!

all-hands-bot commented Apr 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

VascoSch92 commented Apr 7, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python API breakage checks — ✅ PASSED

Uh oh!

github-actions bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

REST API breakage checks (OpenAPI) — ✅ PASSED

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VascoSch92 commented Apr 7, 2026

Uh oh!

openhands-ai bot commented Apr 7, 2026

Uh oh!

VascoSch92 commented Apr 7, 2026

Uh oh!

openhands-ai bot commented Apr 7, 2026

Summary of Work Completed

Request Checklist

Changes Made (commit 8485fa5)

Conciseness Check

Notes

Uh oh!

github-actions bot commented Apr 7, 2026

Uh oh!

all-hands-bot commented Apr 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

VascoSch92 commented Apr 7, 2026 •

edited by github-actions bot

Loading

github-actions bot commented Apr 7, 2026 •

edited

Loading

github-actions bot commented Apr 7, 2026 •

edited

Loading

Changes Made (commit `8485fa5`)