feat(sdk): add opt-in model-directed context resets

[cbinhan]

HUMAN:

---

AGENT:

Depends on #5555. This branch contains its history commits; the main-based diff includes them until that dependency lands. Review only the reset implementation.

Why

Long-running agents need to choose their own context handoff while retaining a way to recover omitted facts. Add an explicit agent_reset mode: the model writes its handoff, the SDK safely commits a window switch, and conversation_history can read the original EventLog.

Summary

• Add AgentResetCondenser, new_context(handoff=""), and once-per-window 80% reminders. Settings add both required tools without mutating the input settings; direct Agent initialization checks them. Default summarization is unchanged.
• Commit complete tool results before the request/Condensation. Preserve the reset response batch, system input, and users arriving after the actual pre-I/O input boundary; handle no-op, rejection, cancellation, Finish, reopen, and fork. Normal reset has no extra summary call.
• Bound emergency summarization to one outer rescue/retry, retaining existing finite internal retries. Add additive event/settings/client types, real REST/WebSocket tests, ordinary-file notes examples, and a provider-backed behavior-test scenario.

Issue Number

Part of #4916; supersedes the reset portion of unpublished #5312. The old branch and experimental records are preserved.

How to Test

make build
uv run pytest tests/sdk -q -n 4
uv run pytest tests/agent_server tests/cross -q -n 4
uv run python examples/01_standalone_sdk/agent_reset/main.py --offline

Validated source: 20532dd3e5fb88e75e880ce07a6afbdff98df1b3; subsequent changes are review artifacts.

• SDK: 6,982 passed, 9 skipped, 11 xfailed, 1 non-strict xpassed. New Agent lifecycle/capacity cases: 30 passed.
• Agent Server/cross-runtime: 2,992 passed, 9 failed, 1 skipped. All nine failures reproduced on untouched main 8ba966d1d: seven Linux-only Canvas extension fixtures on macOS, missing tmux, and missing Docker. This is not a fully green server matrix.
• TypeScript: 384 tests passed; final type refinements also passed focused tests/strict compilation. Build, lint, format, and public type budget passed.
• Persisted settings: 23 fixtures + 8 published baseline payloads passed. SDK/workspace/tools API compatibility and OpenAPI checks passed; existing weak-schema allowlist unchanged.
• Both offline examples passed. b06_agent_reset_history collected/imported successfully but has not run against a real model because no model credentials were configured.

Detailed commands, versions, and limitations. A maintainer needs to apply integration-test; this contributor account has no upstream label permission.

Video/Screenshots

Canvas recording and verification: real Chrome + Canvas a07364828 + this source backend, with a scripted HTTP provider. One passed workflow verifies file creation, reset, file reread, history search/read, and final visible answer. One reset, zero summary rescues; all five tool results succeeded. This demonstrates harness/UI integration, not autonomous model quality. Ancillary 404 toasts from the minimal development stack are documented.

Design Doc

Self-contained reset design and overall diagram

Companion documentation: OpenHands/docs#906

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

Following the simpler model-managed direction discussed with @enyst, the new mode omits context_notes, HistoryIndexEvent, NotesRetrievalCondenser, storage admission/recovery, fixed head/tail retention, and additional capacity options. These were unpublished experimental additions; released defaults and compatibility surfaces remain intact.

Using handoff and ordinary files instead of fixed keep_first and a dedicated history index is an intentional adjustment to the original issue design, still requiring maintainer acceptance. File notes do not gain note-specific version/fork semantics. One outer rescue may make multiple summarizer/provider calls under existing finite retries.

Keep this draft pending real-model evaluation and current-head CI/maintainer review. Remove temporary .pr/ artifacts before merging this fork PR. No review threads or comments were posted or resolved by this implementation.

[github-actions]

📁 PR Artifacts Notice

This PR contains a .pr/ directory with temporary PR-specific documents. Because this is a fork PR, the workflow will open or update a cleanup PR against main after merge.