[Feature]: Separated stdout/stderr provenance and termination signal telemetry in TerminalObservation

Open
#6,996 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
backend, cli

Research direction

Start by locating TerminalSession, CmdOutputMetadata, and TerminalObservation, then trace how command output is captured and rendered by to_llm_content. Check the existing terminal tests and run the relevant suite before changing behavior. Done means separated streams are represented and labeled when available, bracketed-paste sequences are removed, and detectable signal termination is distinct from normal exit status 143.

Written by the indexing model from the issue text.

Description

priority:low
Is there an existing feature request for this?
  • I have searched existing issues and feature requests, and this is not a duplicate.
Problem or Use Case

TerminalSession captures command output from a merged PTY/tmux screen buffer and reads exit status solely via shell $?. This creates two observability blind spots for agents diagnosing build/ops pipelines:

  1. Lost stdout vs. stderr provenance: Diagnostic warnings written to stderr are interleaved indistinguishably with structured stdout data (alongside bracketed-paste ANSI sequences like \x1b[?2004l). On TraceTrial-Bench (arXiv:2610.32285, node E2), OpenHands scored 6.7% on E2-shard-stderr-003 because stderr diagnostics could not be distinguished from stdout.
  2. Ambiguous signal death (128 + SIG): When a child process dies from SIGTERM (15), bash reports $? = 143 — identical to a process calling exit(143) normally (E1-drainexit-001, hr_signal_death_is_distinguishable_from_normal_exit=False).
Desired Behavior
  1. Add optional fields on CmdOutputMetadata / TerminalObservation:
    • stdout: str | None = None and stderr: str | None = None (populated when using a non-PTY/subprocess execution mode or sidecar stderr capture)
    • termination_signal: str | int | None = None (when the command was terminated by a signal rather than normal exit())
  2. Strip terminal-injected bracketed-paste control sequences (\x1b[?2004h / \x1b[?2004l) from captured command output so clean stdout payloads are not corrupted.
Acceptance Criteria
  • Subprocess / non-interactive terminal execution (or opt-in stream separation) populates distinct stdout and stderr fields on TerminalObservation and labels stderr clearly in to_llm_content
  • Bracketed-paste ANSI control sequences injected by the shell wrapper are stripped from captured output
  • Signal-terminated commands surface signal identity when detectable, distinguishing SIGTERM death from normal exit 143
Dominant language
Python
Stars
1.4k
Forks
797
Avg merge
1d 17h
Merged PRs (30d)
354

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenHands/software-agent-sdk

All issues in OpenHands/software-agent-sdk

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.