[dotnet-port-fixes] Preserve shelltool UTF-8 head/tail ordering

[michelle-clayton-work]

Summary

Aligned Go's internal tool/shelltool head/tail output buffer with the upstream .NET UTF-8 ordering fix from commit 85c00fc55b6f8cef8b88e83f364b527a0d5cd275.

The Go headTailBuffer now seals the head once a full rune no longer fits, keeps all later runes in the tail, and only evicts tail runes after the total captured output exceeds the configured cap. This preserves output order for mixed ASCII and multibyte UTF-8 content while keeping the existing public Go API unchanged.

Ported .NET PRs

• .NET: Preserve UTF-8 order in HeadTailBuffer agent-framework#7128 - preserve HeadTailBuffer UTF-8 order

Breaking Changes

No.

Tests and Examples

• Ran go test ./tool/shelltool
• Added focused parity tests for exact-cap UTF-8 output ordering
• Added focused parity tests for overflowed UTF-8 output ordering and truncation markers
• No example changes were needed because this is an internal buffering fix

Notes

• Upstream commit ported: 85c00fc55b6f8cef8b88e83f364b527a0d5cd275 (https://github.com/microsoft/agent-framework/commit/85c00fc55b6f8cef8b88e83f364b527a0d5cd275)
• I skipped nearby upstream items such as Fix message ordering in workflow-hosted agents agent-framework#7123 and #7042 because they were already tracked by existing Go porting work, and larger API-shaping changes remained out of scope for this fixes workflow.
• This PR only changes internal shelltool buffering behavior and test coverage.

Generated by .NET to Go Fixes and Test Porting Agent · 431.5 AIC · ⌖ 45.2 AIC · ⊞ 21.7K · ◷

Closes #521

[Copilot]

Pull request overview

This PR updates the internal tool/shelltool bounded output accumulator (headTailBuffer) to preserve correct UTF-8 ordering between head and tail segments, aligning behavior with the referenced upstream .NET fix while keeping the Go public API unchanged.

Changes:

• Seal the head once a full UTF-8 rune no longer fits, ensuring subsequent runes are captured in the tail to preserve output order.
• Adjust tail eviction logic to avoid premature truncation when the total captured output is still within the configured cap.
• Add focused internal tests covering exact-cap and overflow UTF-8 scenarios (including truncation marker expectations).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
tool/shelltool/localshell.go	Updates headTailBuffer write/eviction behavior to preserve UTF-8 ordering across head/tail.
tool/shelltool/localshell_internal_test.go	Adds parity-style tests to validate UTF-8 ordering and truncation marker behavior at/over cap.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Cross-Repo Parity Review — PR #537

Scope determination: In scope (internal behavior change in a public package).

Changed Go contract: No exported identifiers were added, removed, or modified. The only changes are to the private headTailBuffer struct (headSealed bool field + eviction guard) and the internal test file.

Upstream parity check: The PR description cites the upstream .NET commit 85c00fc as the direct source, and the Go change mirrors the same semantic fix — sealing the head once a full rune no longer fits and deferring tail eviction until the total captured output exceeds the configured cap. The Python SDK does not appear to have a HeadTailBuffer analogue (shell tool output buffering is not part of the Python surface), so no Python parity gap exists.

Verdict: ✅ This PR restores cross-repo parity with the .NET implementation. No divergences introduced, no public Go API changes, no sample or example changes required. No parity issues found.

Generated by Go API Consistency Review Agent for issue #537 · 39.2 AIC · ⌖ 11.7 AIC · ⊞ 28.4K · ◷