[Bug]: TerminalSession never sets timeout=True on TerminalObservation when commands time out

Open
#6,991 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@zsicheng0214 is already working on this.

Since Nov 19, 2026.

  • #6987 by @zsicheng0214 — open

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
25/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
python
Domain
backend, testing

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

priority:low ready-for-dev
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_command sets timeout=True on TerminalObservation
  • _handle_nochange_timeout_command sets timeout=True on TerminalObservation
  • 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_command returns a TerminalObservation with timeout is True (e.g. calling it with command="sleep 10", terminal_content="", ps1_matches=[], timeout=2.0).
  • TerminalSession._handle_nochange_timeout_command returns a TerminalObservation with timeout is True (e.g. calling it with command="sleep 10", terminal_content="waiting...", ps1_matches=[]).
  • Both timeout handlers' observation text, exit code, and is_error behavior 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, and is_error is False.
  • An observation produced by TerminalSession.execute outside the two timeout handlers has timeout is False: e.g. TerminalExecutor(...).execute(TerminalAction(command="echo ready", timeout=2)) returns an observation with timeout is False.
  • uv run pytest tests/tools/terminal/test_terminal_timeout_flag.py passes, and the existing uv 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

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.