[Bug]: TerminalSession never sets timeout=True on TerminalObservation when commands time out
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 25/100
Research direction
Read openhands-tools/openhands/tools/terminal/terminal/terminal_session.py and openhands-tools/openhands/tools/terminal/definition.py to trace how the two timeout handlers construct observations. PR #6987 is already open and implements this fix. The issue names tests/tools/terminal/test_terminal_timeout_flag.py and the terminal test suite as verification; done means both handlers report timeout=True while preserving the stated text and other behavior.
Written by the indexing model from the issue text.
Description
Is there an existing issue for the same bug?
- I have searched existing issues and this is not a duplicate.
Bug Description
TerminalObservation (openhands/tools/terminal/definition.py) defines timeout: bool = Field(default=False, description="Whether the command execution timed out."), but neither TerminalSession._handle_hard_timeout_command() nor TerminalSession._handle_nochange_timeout_command() passes timeout=True when constructing TerminalObservation.from_text(...).
Expected Behavior
obs.timeout should be True whenever _handle_hard_timeout_command or _handle_nochange_timeout_command produces a timeout TerminalObservation.
Actual Behavior
Reproducible with uv run python -c: calling session._handle_hard_timeout_command(command="sleep 10", terminal_content="", ps1_matches=[], timeout=2.0) returns an observation whose prose suffix says [The command timed out after 2.0 seconds. ...] while obs.timeout is False. Downstream hooks and post-tool observers inspecting structured ObservationEvent fields never observe timeout=True.
Discovered via TraceTrial-Bench (arXiv:2610.32285, mechanism nodes E3 & E6). Companion fix ready in #6987.
Acceptance Criteria
-
_handle_hard_timeout_commandsetstimeout=TrueonTerminalObservation -
_handle_nochange_timeout_commandsetstimeout=TrueonTerminalObservation - Unit tests pass via
uv run pytest tests/tools/terminal/test_terminal_timeout_flag.py
OpenHands AI triage
The following comments and acceptance criteria were added by the OpenHands AI agent.
Triage
Confirmed on main (1.62.0): TerminalObservation.timeout (openhands-tools/openhands/tools/terminal/definition.py) defaults to False, and TerminalSession._handle_hard_timeout_command() and _handle_nochange_timeout_command() in openhands-tools/openhands/tools/terminal/terminal/terminal_session.py construct TerminalObservation.from_text(...) without passing timeout=True, so serialized ObservationEvents never report a timeout. The two timeout handlers are the authoritative construction sites for these prose-suffixed timeout observations, and PR #6987 already implements exactly this fix with a test file.
Bounded scope: pass timeout=True in only those two handlers in openhands-tools/; add unit coverage under tests/tools/terminal/. Non-goals: changing observation text, is_error, exit codes, or the soft-timeout still-running path; altering the LLM-visible string; touching other TerminalObservation construction sites, timeout policy defaults, event schemas, TypeScript clients, or docs.
Actual Behavior
_handle_hard_timeout_command and _handle_nochange_timeout_command return TerminalObservations whose prose suffix says the command timed out, while obs.timeout remains the default False; structured ObservationEvent fields downstream therefore never show timeout=True.
Steps to Reproduce
With a mocked backend terminal, call session._handle_hard_timeout_command(command="sleep 10", terminal_content="", ps1_matches=[], timeout=2.0) and inspect the returned observation: its text says the command timed out, but obs.timeout is False.
Desired Behavior
Every TerminalObservation produced by _handle_hard_timeout_command or _handle_nochange_timeout_command carries timeout=True and is visible as timeout: true in the serialized ObservationEvent, so hooks and post-tool observers can detect timed-out commands from structured fields.
Acceptance Criteria
-
TerminalSession._handle_hard_timeout_commandreturns aTerminalObservationwithtimeout is True(e.g. calling it withcommand="sleep 10",terminal_content="",ps1_matches=[],timeout=2.0). -
TerminalSession._handle_nochange_timeout_commandreturns aTerminalObservationwithtimeout is True(e.g. calling it withcommand="sleep 10",terminal_content="waiting...",ps1_matches=[]). - Both timeout handlers' observation text, exit code, and
is_errorbehavior are unchanged: for the mocked-backend calls above, the text still contains "The command timed out after 2.0 seconds." / "has no new output",exit_code == -1, andis_error is False. - An observation produced by
TerminalSession.executeoutside the two timeout handlers hastimeout is False: e.g.TerminalExecutor(...).execute(TerminalAction(command="echo ready", timeout=2))returns an observation withtimeout is False. -
uv run pytest tests/tools/terminal/test_terminal_timeout_flag.pypasses, and the existinguv run pytest tests/tools/terminal/suite is green.
- Dominant language
- Python
- Stars
- 1.4k
- Forks
- 797
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 354
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from OpenHands/software-agent-sdk
-
[Bug]: `list_directory` reports a complete listing as truncated when a directory has exactly 500 entriesPossibly taken @balabommablock-cpu claimed this 29 days ago. Openbug priority:low ready-for-dev
Difficulty 2/5 1-3 hours Newbie friendliness 87/100
OpenHands/software-agent-sdk#6133 ·
Maintainers usually reply within 1 day
-
[Bug]: Command hook that exits 1 is treated as blocking when its stdout is a JSON `deny` or `continue: false`Possibly taken A pull request linked to this issue is open or already merged. Openbug priority:low ready-for-dev
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
OpenHands/software-agent-sdk#6116 · 3 comments ·
Maintainers usually reply within 1 day
-
[Bug]: TypeScript GET-with-body requests remain pending after a truncated responsePossibly taken @BlueRaddish claimed this 34 days ago. Openbug priority:low ready-for-dev
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
OpenHands/software-agent-sdk#6059 ·
Maintainers usually reply within 1 day
-
[Bug]: Document whether `prompt_tokens` includes `cache_read_tokens` in accumulated token usagePossibly taken @Jaxon1216 claimed this 36 days ago. Openpriority:low ready-for-dev
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
OpenHands/software-agent-sdk#5975 ·
Maintainers usually reply within 1 day
-
priority:low
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
OpenHands/software-agent-sdk#5708 · 1 comment ·
Maintainers usually reply within 1 day
All issues in OpenHands/software-agent-sdk
Similar issues
-
[Bug]: reme CLI crashes when the running server used a relative config pathPossibly taken @nurlanmnn claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
agentscope-ai/ReMe#770 ·
Maintainers usually reply within 1 day
-
Pi: paused model calls are reported as "not signed in" when the model's provider comes from an extensionPossibly taken @balcsida claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
microsoft/TokenEconomizer#288 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 67/100
sickn33/agentic-awesome-skills#2437 ·
Maintainers usually reply within 1 day
-
site-bug triage
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
ethereum/consensus-specs#5846 ·
Maintainers usually reply within 1 day