[Feature]: Machine-readable truncation metadata and line-range continuation on Observations

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

Maintainers usually reply within 1 day

@zsicheng0214 is already working on this.

Since Nov 20, 2026.

  • #7024 by @zsicheng0214 — open

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
backend, tooling

Research direction

Start by reading TerminalObservation.to_llm_content, maybe_truncate, and the Observation and TerminalObservation models; then trace how terminal output is saved and exposed through ObservationEvent. The acceptance criteria define done: structured truncation details serialize compatibly, and clipped terminal output can be recovered by line range without rerunning the command. Add unit and integration coverage for clipped and unclipped observations.

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

When a tool output exceeds MAX_CMD_OUTPUT_SIZE (30,000 chars in TerminalObservation.to_llm_content) or DEFAULT_TEXT_CONTENT_LIMIT (maybe_truncate), OpenHands splices a prose <response clipped><NOTE>... banner into the middle of the text during to_llm_content rendering, while the TerminalObservation model itself exposes no machine-readable truncation metadata.

In our 95-task evaluation of OpenHands on TraceTrial-Bench (arXiv:2610.32285, mechanism node C1), both C1-escalation-export-001 and C1-log-archive-export-002 failed hu_reduction_metadata_is_machine_readable because:

  1. Hooks, UI clients, and post-tool verifiers inspecting ObservationEvent cannot tell programmatically whether an observation was clipped, how many characters/bytes were omitted, or which line range was elided without regex-scraping <response clipped>.
  2. When full_output_save_dir is unset or outside the workspace, the model has no structured cursor or line-range continuation affordance to inspect the elided middle segment safely without re-running non-idempotent commands.
Desired Behavior
  1. Add optional structured reduction metadata fields (or a typed TruncationInfo sub-model) on Observation / TerminalObservation:
    • truncated: bool = False
    • original_chars: int | None = None
    • omitted_chars: int | None = None
    • elided_line_range: tuple[int, int] | None = None
    • persisted_output_path: str | None = None
  2. Populate these fields deterministically via a structured helper (e.g. truncate_with_metadata(...) wrapping maybe_truncate) so both ObservationEvent consumers and to_llm_content share a single source of truth.
  3. Ensure TerminalTool defaults full_output_save_dir to a conversation-scoped scratch directory (or exposes a read-range helper) so clipped outputs of one-shot/stateful commands remain recoverable without re-executing the command.
Acceptance Criteria
  • TerminalObservation (and/or base Observation) exposes machine-readable truncation status, original/omitted character counts, elided line range, and persisted path when output is clipped
  • Unclipped observations serialize with truncated=False and remain backwards-compatible with persisted conversations
  • Clipped terminal outputs are recoverable by line range without re-executing the original command
  • Unit and integration tests cover clipped vs. unclipped observations
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.