[Feature]: Machine-readable truncation metadata and line-range continuation on Observations
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
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
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:
- Hooks, UI clients, and post-tool verifiers inspecting
ObservationEventcannot tell programmatically whether an observation was clipped, how many characters/bytes were omitted, or which line range was elided without regex-scraping<response clipped>. - When
full_output_save_diris 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
- Add optional structured reduction metadata fields (or a typed
TruncationInfosub-model) onObservation/TerminalObservation:truncated: bool = Falseoriginal_chars: int | None = Noneomitted_chars: int | None = Noneelided_line_range: tuple[int, int] | None = Nonepersisted_output_path: str | None = None
- Populate these fields deterministically via a structured helper (e.g.
truncate_with_metadata(...)wrappingmaybe_truncate) so bothObservationEventconsumers andto_llm_contentshare a single source of truth. - Ensure
TerminalTooldefaultsfull_output_save_dirto 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 baseObservation) exposes machine-readable truncation status, original/omitted character counts, elided line range, and persisted path when output is clipped - Unclipped observations serialize with
truncated=Falseand 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
- 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