feat(tools/terminal): add hard_timeout mode to terminate timed-out command processes and surface actionable timeout errors
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 45/100
Research direction
Start with TerminalSession._handle_hard_timeout_command in openhands-tools/openhands/tools/terminal/terminal/terminal_session.py, then trace TerminalAction and TerminalObservation through the tool schema and serialization. Read the timeout tests and Unix and Windows terminal tool descriptions to find the relevant entry points. Done when hard timeouts terminate the command, return the specified error fields and suffix, and existing soft-timeout behavior remains unchanged.
Written by the indexing model from the issue text.
Description
Motivation
In TerminalTool, TerminalAction.timeout currently acts strictly as a soft observation pause: when action.timeout expires (TerminalSession._handle_hard_timeout_command in openhands-tools/openhands/tools/terminal/terminal/terminal_session.py), the session captures the screen buffer and returns exit_code=-1, is_error=False while leaving the child process running in the background inside the terminal / pooled tmux pane until a future independent command happens to reuse that same pane.
While soft pause is useful for interactive commands where the agent wants to inspect progress or send C-c, automated pipelines, test runners, firmware flashes, and bounded-deadline probes frequently require a strict hard deadline where:
- A runaway command must not continue mutating workspace files in the background after its deadline expires (especially in pooled tmux mode where the next command may check out a different pane while the timed-out pane keeps writing);
- Post-tool observers, hooks, and agents need
is_error=True,timeout=True, and an explicit machine-readableprocess_terminated=Trueindicator distinguishing a terminated hard deadline from an interactive soft pause.
In containerized TraceTrial-Bench evaluation across 95 tasks, this gap directly caused failures across both E3 (timeout boundary & orphan process convergence: E3-firmware-timeout-001, E3-longrun-timeout-002, E3-pipeline-timeout-003) and E6 (E6-timeout-error-channel-003).
Proposed Solution
Keep hard_timeout: bool = False as the default (preserving 100% backward compatibility for interactive soft-timeout workflows) and add opt-in strict deadline enforcement:
- Add
hard_timeout: bool = FalsetoTerminalAction. - Add
process_terminated: bool = FalsetoTerminalObservation. - When
action.hard_timeout=Trueandaction.timeoutexpires before completion:- Immediately interrupt the running command (
terminal.interrupt()) and wait boundedly for prompt recovery (closing/marking the session for automatic self-healing if the process ignoresSIGINT); - Reset
prev_statuscleanly when the prompt recovers so subsequent commands start from a clean prompt; - Return
TerminalObservationwithtimeout=True,is_error=True,process_terminated=True, and a clear[The command timed out after X seconds and was terminated.]suffix.
- Immediately interrupt the running command (
OpenHands AI triage
The following comments and acceptance criteria were added by the OpenHands AI agent.
Triage
Verified against main: TerminalSession._handle_hard_timeout_command (openhands-tools/openhands/tools/terminal/terminal/terminal_session.py) returns exit_code=-1 with neither timeout=True nor is_error=True and leaves the child process running; cleanup happens only later at the next pooled-pane checkout (TerminalExecutor._prepare_pooled_session interrupts and polls at most ~2s). The problem statement is accurate.
Bounded scope:
- Add
hard_timeout: bool = FalsetoTerminalActionandprocess_terminated: bool = FalsetoTerminalObservation— both additive withFalsedefaults, preserving backward compatibility. - Enforce termination only when
hard_timeout=Trueandaction.timeoutexpires: interrupt via the existingTerminalInterface.interrupt()(implemented on subprocess, tmux, and Windows backends), bound the prompt-recovery wait, and fall back to the repository's existing self-healing paths (session close with SIGTERM→SIGKILL escalation insubprocess_terminal.py,TmuxPanePool.replace()) when the prompt does not recover; reporttimeout=True,is_error=True,process_terminated=True, and a terminated-timeout suffix. - Trace the new fields through the tool schema/serialization surface and document the mode in the terminal tool descriptions (Unix and Windows).
Non-goals:
- No change to default soft-timeout behavior, the no-change-timeout path, or
max_observation_wait_secondshandling. - No new process-kill API on
TerminalInterfacebeyond the existinginterrupt()and close/replace self-healing; no PID-tracking surface. - No changes to other tools; does not address #6651 (pool Ctrl+C delivery to a still-running command).
Acceptance Criteria
- With
hard_timeout=Trueandtimeout=Non a command still running at the deadline, the returnedTerminalObservationhastimeout=True,is_error=True,process_terminated=True,exit_code=-1, and its text includes a suffix stating the command timed out after N seconds and was terminated. - The observation includes the output the command produced before the deadline (subject to the existing
MAX_CMD_OUTPUT_SIZEtruncation). - After the observation returns, the timed-out process is no longer running on that pane/session (the backend reports no running command and a recovered prompt), so it cannot keep mutating workspace files in the background.
- When the timed-out process ignores SIGINT, the tool still returns the timeout error observation and the session recovers via the existing close/replace self-healing path within a bounded wait, so the next command runs from a clean prompt instead of hanging.
- In pooled tmux mode, an independent follow-up command on the same executor after a hard timeout executes as a new command (not as a follow-up interaction with the timed-out command), with session prompt/
prev_statusstate clean. - Default behavior is unchanged: actions with
hard_timeout=False(or the field absent) keep the current soft-timeout result — no interrupt or termination,is_error=False,process_terminated=False, existing timeout suffix — and existing serialized actions/observations without the new fields still parse with the defaults. -
hard_timeout=Truewithout atimeoutdeadline is inert: no termination occurs and behavior matches the current soft flow. -
hard_timeout=Truedoes not bypass the foreground timeout cap: whenOH_RUNTIME_IDLE_TIMEOUT_SECONDSis configured and the requestedtimeoutexceeds the cap, the existing foreground-timeout rejection observation is returned before execution. - The new fields appear in the terminal tool schema with defaults of
False, and the Unix and Windows tool descriptions document the hard-timeout mode's terminate-on-deadline semantics versus the soft pause. - Automated tests against real sessions (tmux and subprocess backends) demonstrate that a long-running command with
hard_timeout=Truereturns the terminated-error observation and its process is gone afterwards; the existing timeout tests pass unchanged.
- 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