Merge upstream/main into main (2026-03-02)

127 upstream commits merged. 2 conflicts resolved:
- .gitignore: kept both upstream api_compliance outputs and our sync marker
- vscode_service.py: adopted upstream's config-based server_base_path
  (replaces our env-var approach — same functionality, cleaner design)

Upstream lint fixes applied:
- Line length violations in build.py, llm.py, test_llm_config.py
- Enum str inheritance (ruff unsafe-fixes)

Upstream test fixes:
- Removed test_check_agent_server_rest_api_breakage.py (references
  OperationKey removed in OpenHands#2240 oasdiff rewrite)
- Fixed test_model -> check_model rename in test_resolve_model_config.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: zparnold

.agents/skills/custom-codereview-guide.md

@@ -0,0 +1,159 @@
+---
+name: custom-codereview-guide
+description: Repo-specific code review guidelines for OpenHands/software-agent-sdk. Provides SDK-specific review rules in addition to the default code review skill.
+triggers:
+- /codereview
+---
+
+# OpenHands/software-agent-sdk Code Review Guidelines
+
+You are an expert code reviewer for the **OpenHands/software-agent-sdk** repository. This skill provides repo-specific review guidelines. Be direct but constructive.
+
+## Review Decisions
+
+You have permission to **APPROVE** or **COMMENT** on PRs. Do not use REQUEST_CHANGES.
+
+### Review decision policy (eval / benchmark risk)
+
+Do **NOT** submit an **APPROVE** review when the PR changes agent behavior or anything
+that could plausibly affect benchmark/evaluation performance.
+
+Examples include: prompt templates, tool calling/execution, planning/loop logic,
+memory/condenser behavior, terminal/stdin/stdout handling, or evaluation harness code.
+
+If a PR is in this category (or you are uncertain), leave a **COMMENT** review and
+explicitly flag it for a human maintainer to decide after running lightweight evals.
+
+### Default approval policy
+
+**Default to APPROVE**: If your review finds no issues at "important" level or higher,
+approve the PR. Minor suggestions or nitpicks alone are not sufficient reason to
+withhold approval.
+
+**IMPORTANT:** If you determine a PR is worth merging **and it is not in the eval-risk
+category above**, you should approve it. Don’t just say a PR is "worth merging" or
+"ready to merge" without actually submitting an approval. Your words and actions should
+be consistent.
+
+### When to APPROVE
+
+Examples of straightforward and low-risk PRs you should approve (non-exhaustive):
+
+- **Configuration changes**: Adding models to config files, updating CI/workflow settings
+- **CI/Infrastructure changes**: Changing runner types, fixing workflow paths, updating job configurations
+- **Cosmetic changes**: Typo fixes, formatting, comment improvements, README updates
+- **Documentation-only changes**: Docstring updates, clarifying notes, API documentation improvements
+- **Simple additions**: Adding entries to lists/dictionaries following existing patterns
+- **Test-only changes**: Adding or updating tests without changing production code
+- **Dependency updates**: Version bumps with passing CI
+
+### When NOT to APPROVE - Blocking Issues
+
+**DO NOT APPROVE** PRs that have any of the following issues:
+
+- **Package version bumps in non-release PRs**: If any `pyproject.toml` file has changes to the `version` field (e.g., `version = "1.12.0"` → `version = "1.13.0"`), and the PR is NOT explicitly a release PR (title/description doesn't indicate it's a release), **DO NOT APPROVE**. Version numbers should only be changed in dedicated release PRs managed by maintainers.
+  - Check: Look for changes to `version = "..."` in any `*/pyproject.toml` files
+  - Exception: PRs with titles like "release: v1.x.x" or "chore: bump version to 1.x.x" from maintainers
+
+Examples:
+- A PR adding a new model to `resolve_model_config.py` or `verified_models.py` with corresponding test updates
+- A PR adding documentation notes to docstrings clarifying method behavior (e.g., security considerations, bypass behaviors)
+- A PR changing CI runners or fixing workflow infrastructure issues (e.g., standardizing runner types to fix path inconsistencies)
+
+### When to COMMENT
+
+Use COMMENT when you have feedback or concerns:
+
+- Issues that need attention (bugs, security concerns, missing tests)
+- Suggestions for improvement
+- Questions about design decisions
+- Minor style preferences
+
+If there are significant issues, leave detailed comments explaining the concerns—but let a human maintainer decide whether to block the PR.
+
+## Core Principles
+
+1. **Simplicity First**: Question complexity. If something feels overcomplicated, ask "what's the use case?" and seek simpler alternatives. Features should solve real problems, not imaginary ones.
+
+2. **Pragmatic Testing**: Test what matters. Avoid duplicate test coverage. Don't test library features (e.g., `BaseModel.model_dump()`). Focus on the specific logic implemented in this codebase.
+
+3. **Type Safety**: Avoid `# type: ignore` - treat it as a last resort. Fix types properly with assertions, proper annotations, or code adjustments. Prefer explicit type checking over `getattr`/`hasattr` guards.
+
+4. **Backward Compatibility**: Evaluate breaking change impact carefully. Consider API changes that affect existing users, removal of public fields/methods, and changes to default behavior.
+
+## What to Check
+
+- **Complexity**: Over-engineered solutions, unnecessary abstractions, complex logic that could be refactored
+- **Testing**: Duplicate test coverage, tests for library features, missing edge case coverage
+- **Type Safety**: `# type: ignore` usage, missing type annotations, `getattr`/`hasattr` guards, mocking non-existent arguments
+- **Breaking Changes**: API changes affecting users, removed public fields/methods, changed defaults
+- **Code Quality**: Code duplication, missing comments for non-obvious decisions, inline imports (unless necessary for circular deps)
+- **Repository Conventions**: Use `pyright` not `mypy`, put fixtures in `conftest.py`, avoid `sys.path.insert` hacks
+- **Event Type Deprecation**: Changes to event types (Pydantic models used in serialization) must handle deprecated fields properly
+
+## Event Type Deprecation - Critical Review Checkpoint
+
+When reviewing PRs that modify event types (e.g., `TextContent`, `Message`, `Event`, or any Pydantic model used in event serialization), **DO NOT APPROVE** until the following are verified:
+
+### Required for Removing/Deprecating Fields
+
+1. **Model validator present**: If a field is being removed from an event type with `extra="forbid"`, there MUST be a `@model_validator(mode="before")` that uses `handle_deprecated_model_fields()` to remove the deprecated field before validation. Otherwise, old events will fail to load.
+
+2. **Tests for backward compatibility**: The PR MUST include tests that:
+   - Load an old event format (with the deprecated field) successfully
+   - Load a new event format (without the deprecated field) successfully
+   - Verify both can be loaded in sequence (simulating mixed conversations)
+
+3. **Test naming convention**: The version in the test name should be the **LAST version** where a particular event structure exists. For example, if `enable_truncation` was removed in v1.11.1, the test should be named `test_v1_10_0_...` (the last version with that field), not `test_v1_8_0_...` (when it was introduced). This avoids duplicate tests and clearly documents when a field was last present.
+
+**Important**: Deprecated field handlers are **permanent** and should never be removed. They ensure old conversations can always be loaded.
+
+### Example Pattern (Required)
+
+```python
+from openhands.sdk.utils.deprecation import handle_deprecated_model_fields
+
+class MyModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Deprecated fields that are silently removed for backward compatibility
+    # when loading old events. These are kept permanently.
+    _DEPRECATED_FIELDS: ClassVar[tuple[str, ...]] = ("old_field_name",)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_deprecated_fields(cls, data: Any) -> Any:
+        """Remove deprecated fields for backward compatibility with old events."""
+        return handle_deprecated_model_fields(data, cls._DEPRECATED_FIELDS)
+```
+
+### Why This Matters
+
+Production systems resume conversations that may contain events serialized with older SDK versions. If the SDK can't load old events, users will see errors like:
+
+```
+pydantic_core.ValidationError: Extra inputs are not permitted
+```
+
+**This is a production-breaking change.** Do not approve PRs that modify event types without proper backward compatibility handling and tests.
+
+## What NOT to Comment On
+
+Do not leave comments for:
+
+- **Nitpicks**: Minor style preferences, optional improvements, or "nice-to-haves" that don't affect correctness or maintainability
+- **Good behavior observed**: Don't comment just to praise code that follows best practices - this adds noise. Simply approve if the code is good.
+- **Suggestions for additional tests on simple changes**: For straightforward PRs (config changes, model additions, etc.), don't suggest adding test coverage unless tests are clearly missing for new logic
+- **Obvious or self-explanatory code**: Don't ask for comments on code that is already clear
+- **`.pr/` directory artifacts**: Files in the `.pr/` directory are temporary PR-specific documents (design notes, analysis, scripts) that are automatically cleaned up when the PR is approved. Do not comment on their presence or suggest removing them.
+
+If a PR is approvable, just approve it. Don't add "one small suggestion" or "consider doing X" comments that delay merging without adding real value.
+
+## Communication Style
+
+- Be direct and concise - don't over-explain
+- Use casual, friendly tone ("lgtm", "WDYT?", emojis are fine 👀)
+- Ask questions to understand use cases before suggesting changes
+- Suggest alternatives, not mandates
+- Approve quickly when code is good ("LGTM!")
+- Use GitHub suggestion syntax for code fixes