Merge branch 'main' into rb/github-patch

This reverts commit 79492b6551.

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

@@ -1,159 +0,0 @@
----
-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

.agents/skills/debug-test-examples-workflow/SKILL.md

@@ -1,88 +0,0 @@
----
-name: debug-test-examples-workflow
-description: Guide for debugging failing example tests in the `test-examples` labeled workflow. Use this skill when investigating CI failures in the run-examples.yml workflow, when example scripts fail to run correctly, when needing to isolate specific test failures, or when analyzing workflow logs and failure patterns.
----
-
-# Debugging test-examples Workflow
-
-## Overview
-
-The `run-examples.yml` workflow runs example scripts from `examples/` directory. Triggers:
-- Adding `test-examples` label to a PR
-- Manual workflow dispatch
-- Scheduled nightly runs
-
-## Debugging Steps
-
-### 1. Isolate Failing Tests
-
-Modify `tests/examples/test_examples.py` to focus on specific tests:
-
-```python
-_TARGET_DIRECTORIES = (
-    # EXAMPLES_ROOT / "01_standalone_sdk",
-    EXAMPLES_ROOT / "02_remote_agent_server",  # Keep only failing directory
-)
-```
-
-### 2. Exclude Tests
-
-Add to `_EXCLUDED_EXAMPLES` with explanation:
-
-```python
-_EXCLUDED_EXAMPLES = {
-    # Reason for exclusion
-    "examples/path/to/failing_test.py",
-}
-```
-
-### 3. Trigger Workflow
-
-Toggle the `test-examples` label:
-
-```bash
-# Remove label
-curl -X DELETE -H "Authorization: token $GITHUB_TOKEN" \
-  "https://api.github.com/repos/OpenHands/software-agent-sdk/issues/${PR_NUMBER}/labels/test-examples"
-
-# Add label
-curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
-  -H "Accept: application/vnd.github.v3+json" \
-  "https://api.github.com/repos/OpenHands/software-agent-sdk/issues/{PR_NUMBER}/labels" \
-  -d '{"labels":["test-examples"]}'
-```
-
-### 4. Monitor Progress
-
-```bash
-# Check status
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
-  "https://api.github.com/repos/OpenHands/software-agent-sdk/actions/runs/{RUN_ID}" | jq '{status, conclusion}'
-
-# Download logs
-curl -sL -H "Authorization: token $GITHUB_TOKEN" \
-  "https://api.github.com/repos/OpenHands/software-agent-sdk/actions/runs/{RUN_ID}/logs" -o logs.zip
-unzip logs.zip -d logs
-```
-
-## Common Failure Patterns
-
-| Pattern | Cause | Solution |
-|---------|-------|----------|
-| Port conflicts | Fixed ports (8010, 8011) | Run with `-n 1` or use different ports |
-| Container issues | Docker/Apptainer setup | Check Docker availability, image pulls |
-| LLM failures | Transient API errors | Retry the test |
-| Example bugs | Code errors | Check traceback |
-
-
-## Key Configuration
-
-**Workflow** (`.github/workflows/run-examples.yml`):
-- Runner: `blacksmith-2vcpu-ubuntu-2404`
-- Timeout: 60 minutes
-- Parallelism: `-n 4` (pytest-xdist: 4 parallel workers)
-
-**Tests** (`tests/examples/test_examples.py`):
-- Timeout per example: 600 seconds
-- Target directories: `_TARGET_DIRECTORIES`
-- Excluded examples: `_EXCLUDED_EXAMPLES`

.agents/skills/design-principles.md

@@ -1,43 +0,0 @@
----
-name: design-principles
-description: Core architectural design principles of the OpenHands Software Agent SDK. Reference when making architectural decisions, reviewing PRs that change agent/tool/state boundaries, or evaluating whether a proposed change aligns with V1 design goals.
----
-
-# SDK Design Principles
-
-Reference: <https://docs.openhands.dev/sdk/arch/design>
-
-## Quick Summary
-
-1. **Optional Isolation over Mandatory Sandboxing**
-   Sandboxing is opt-in, not universal. Agent and tool execution runs in a single
-   process by default. When isolation is needed, the same stack can be transparently
-   containerized.
-
-2. **Stateless by Default, One Source of Truth for State**
-   All components — agents, tools, LLMs, configurations — are **immutable Pydantic
-   models** validated at construction. The only mutable entity is the conversation
-   state. This enables deterministic replay and robust persistence.
-
-3. **Clear Boundaries between Agent and Applications**
-   Strict separation between SDK (agent core), tools, workspace, and agent server.
-   Applications communicate via APIs, not by embedding the agent.
-
-4. **Composable Components for Extensibility**
-   Agents are graphs of interchangeable components — tools, prompts, LLMs, contexts —
-   described **declaratively with strong typing**. Developers reconfigure capabilities
-   without modifying core code.
-
-## Implications for Development
-
-- Since agents are immutable Pydantic models, their configuration **is** their
-  serializable representation. There should be no need to "reverse-engineer" agent
-  config from runtime instances.
-- Tool implementations (callables) are the only non-serializable part; this is solved
-  by `tool_module_qualnames` for remote forwarding.
-- Everything else (system_prompt, model, skills, tool names) is already declarative
-  data that can be serialized and forwarded directly.
-- Avoid patterns that create multiple sources of truth for the same configuration
-  (e.g., a factory function AND an extracted definition).
-- `model_copy(update=...)` should be used sparingly and through well-defined paths to
-  avoid undermining statelessness.

.agents/skills/feature-release-rollout/SKILL.md

@@ -1,244 +0,0 @@
----
-name: feature-release-rollout
-description: This skill should be used when the user asks to "rollout a feature", "complete feature release", "propagate SDK feature", "track feature support", "what's missing for feature X", or mentions checking CLI/GUI/docs/blog support for SDK features. Guides agents through the multi-repository feature release workflow from SDK to docs to marketing.
-triggers:
-- rollout feature
-- feature release
-- propagate feature
-- feature support
-- complete release
-- docs for feature
-- blog for feature
-- CLI support
-- GUI support
-- what's missing
----
-
-# Feature Release Rollout
-
-This skill guides the complete feature release workflow across the OpenHands ecosystem repositories.
-
-## Overview
-
-When a feature is implemented in the SDK, it may need propagation through several repositories:
-
-1. **SDK** (`OpenHands/software-agent-sdk`) — Core feature implementation
-2. **CLI** (`OpenHands/OpenHands-CLI`) — Terminal interface support
-3. **GUI** (`OpenHands/OpenHands` frontend directory) — Web interface support
-4. **Docs** (`OpenHands/docs`) — Documentation updates (sdk/ folder)
-5. **Blog** (`OpenHands/growth-utils` blog-post/) — Marketing and announcements
-6. **Video** — Tutorial content (using ElevenLabs + Remotion)
-
-## Workflow
-
-### Phase 1: Feature Discovery
-
-First, identify what feature(s) to analyze. The user may specify:
-- A release tag (e.g., `v1.9.0`)
-- A specific feature name
-- A PR or commit reference
-- A comparison between versions
-
-**For release tags:**
-```bash
-# Clone SDK if not present
-git clone https://github.com/OpenHands/software-agent-sdk.git
-
-# View release notes
-cd software-agent-sdk
-git log --oneline v1.8.0..v1.9.0  # Changes between versions
-git show v1.9.0 --stat             # What changed in this release
-```
-
-**For specific features:**
-Search the SDK codebase, examples, and changelog to understand the feature scope.
-
-### Phase 2: Repository Analysis
-
-Clone all relevant repositories to analyze current support:
-
-```bash
-# Clone repositories (use GITHUB_TOKEN for authenticated access)
-git clone https://github.com/OpenHands/software-agent-sdk.git
-git clone https://github.com/OpenHands/OpenHands-CLI.git
-git clone https://github.com/OpenHands/OpenHands.git        # Frontend in frontend/
-git clone https://github.com/OpenHands/docs.git
-git clone https://github.com/OpenHands/growth-utils.git
-```
-
-For each feature, check support status:
-
-| Repository | Check Location | What to Look For |
-|------------|---------------|------------------|
-| CLI | `openhands_cli/` | Feature flags, commands, TUI widgets |
-| GUI | `OpenHands/frontend/src/` | React components, API integrations |
-| Docs | `docs/sdk/` | Guide pages, API reference, examples |
-| Blog | `growth-utils/blog-post/posts/` | Announcement posts |
-
-### Phase 3: Assess Feature Importance
-
-Not all features warrant full rollout. Evaluate each feature:
-
-**High Impact (full rollout recommended):**
-- New user-facing capabilities
-- Breaking changes or migrations
-- Major performance improvements
-- New integrations or tools
-
-**Medium Impact (docs + selective support):**
-- New API methods or parameters
-- Configuration options
-- Developer experience improvements
-
-**Low Impact (docs only or skip):**
-- Internal refactoring
-- Bug fixes
-- Minor enhancements
-
-**Skip rollout for:**
-- Internal-only changes
-- Test improvements
-- Build/CI changes
-- Documentation typos
-
-### Phase 4: Create Proposal
-
-Generate a structured proposal for the user:
-
-```markdown
-## Feature Rollout Proposal: [Feature Name]
-
-### Feature Summary
-[Brief description of the feature and its value]
-
-### Current Support Status
-| Component | Status | Notes |
-|-----------|--------|-------|
-| SDK | ✅ Implemented | [version/PR] |
-| CLI | ❌ Missing | [what's needed] |
-| GUI | ⚠️ Partial | [what's implemented vs needed] |
-| Docs | ❌ Missing | [suggested pages] |
-| Blog | ❌ Not started | [whether warranted] |
-| Video | ❌ Not started | [whether warranted] |
-
-### Recommended Actions
-1. **CLI**: [specific implementation needed]
-2. **GUI**: [specific implementation needed]
-3. **Docs**: [pages to create/update]
-4. **Blog**: [recommended or not, with reasoning]
-5. **Video**: [recommended or not, with reasoning]
-
-### Assessment
-- **Overall Priority**: [High/Medium/Low]
-- **Effort Estimate**: [days/hours per component]
-- **Dependencies**: [what must be done first]
-```
-
-### Phase 5: User Confirmation
-
-Wait for explicit user approval before proceeding. Ask:
-- Which components to implement
-- Priority ordering
-- Any modifications to the proposal
-
-### Phase 6: Implementation
-
-Only after user confirmation:
-
-**Create GitHub Issues:**
-```bash
-# Create issue on relevant repo
-gh issue create --repo OpenHands/OpenHands-CLI \
-  --title "Support [feature] in CLI" \
-  --body "## Context\n[Feature description]\n\n## Implementation\n[Details]\n\n## Related\n- SDK: [link]\n- Docs: [link]"
-```
-
-**Implementation order:**
-1. CLI/GUI support (can be parallel)
-2. Documentation (depends on 1)
-3. Blog post (depends on 2)
-4. Video (depends on 3)
-
-## Repository-Specific Guidelines
-
-### CLI (OpenHands/OpenHands-CLI)
-
-- Check `AGENTS.md` for development guidelines
-- Use `uv` for dependency management
-- Run `make lint` and `make test` before commits
-- TUI components in `openhands_cli/tui/`
-- Snapshot tests for UI changes
-
-### GUI (OpenHands/OpenHands frontend)
-
-- Frontend in `frontend/` directory
-- React/TypeScript codebase
-- Run `npm run lint:fix && npm run build` in frontend/
-- Follow TanStack Query patterns for data fetching
-- i18n translations in `frontend/src/i18n/`
-
-### Docs (OpenHands/docs)
-
-- SDK docs in `sdk/` folder
-- Uses Mintlify (`.mdx` files)
-- Code blocks can auto-sync from SDK examples
-- Run `mint broken-links` to validate
-- Follow `openhands/DOC_STYLE_GUIDE.md`
-
-### Blog (OpenHands/growth-utils)
-
-- Posts in `blog-post/posts/YYYYMMDD-title.md`
-- Assets in `blog-post/assets/YYYYMMDD-title/`
-- Frontmatter format:
-  ```yaml
-  ---
-  title: "Post Title"
-  excerpt: "Brief description"
-  coverImage: "/assets/blog/YYYYMMDD-title/cover.png"
-  date: "YYYY-MM-DDTHH:MM:SS.000Z"
-  authors:
-    - name: Author Name
-      picture: "/assets/blog/authors/author.png"
-  ogImage:
-    url: "/assets/blog/YYYYMMDD-title/cover.png"
-  ---
-  ```
-
-## Example Feature Analysis
-
-**Feature: Browser Session Recording (SDK v1.8.0)**
-
-1. **SDK**: ✅ Implemented in `openhands.tools.browser`
-2. **CLI**: ❌ No replay/export commands
-3. **GUI**: ❌ No recording viewer component
-4. **Docs**: ✅ Guide at `sdk/guides/browser-session-recording.mdx`
-5. **Blog**: ❌ Could highlight for web scraping users
-6. **Video**: Consider 2-minute demo
-
-**Recommendation**: Medium priority. Docs done, CLI/GUI low urgency (advanced feature), blog post optional.
-
-## Quick Commands
-
-```bash
-# Check SDK feature presence
-grep -r "feature_name" software-agent-sdk/openhands/ --include="*.py"
-
-# Check CLI support
-grep -r "feature_name" OpenHands-CLI/openhands_cli/ --include="*.py"
-
-# Check GUI support
-grep -r "featureName" OpenHands/frontend/src/ --include="*.ts" --include="*.tsx"
-
-# Check docs coverage
-grep -r "feature" docs/sdk/ --include="*.mdx"
-
-# Check blog mentions
-grep -r "feature" growth-utils/blog-post/posts/ --include="*.md"
-```
-
-## Important Notes
-
-- Always get user confirmation before creating issues or starting implementation
-- Consider feature maturity — new features may change before full rollout
-- Cross-reference PRs between repositories in issue descriptions
-- For breaking changes, coordinate release timing across all components

.agents/skills/run-eval.md

@@ -1,66 +0,0 @@
----
-name: run-eval
-description: Trigger and monitor evaluation runs for benchmarks like SWE-bench, GAIA, and others. Use when running evaluations via GitHub Actions or monitoring eval progress through Datadog and kubectl.
-triggers:
-- run eval
-- trigger eval
-- evaluation run
-- swebench eval
----
-
-# Running Evaluations
-
-## Trigger via GitHub API
-
-```bash
-curl -X POST \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  -H "Accept: application/vnd.github+json" \
-  "https://api.github.com/repos/OpenHands/software-agent-sdk/actions/workflows/run-eval.yml/dispatches" \
-  -d '{
-    "ref": "main",
-    "inputs": {
-      "benchmark": "swebench",
-      "sdk_ref": "main",
-      "eval_limit": "50",
-      "model_ids": "claude-sonnet-4-5-20250929",
-      "reason": "Description of eval run",
-      "benchmarks_branch": "main"
-    }
-  }'
-```
-
-**Key parameters:**
-- `benchmark`: `swebench`, `swebenchmultimodal`, `gaia`, `swtbench`, `commit0`, `multiswebench`, `terminalbench`
-- `eval_limit`: Any positive integer (e.g., `1`, `10`, `50`, `200`)
-- `model_ids`: See `.github/run-eval/resolve_model_config.py` for available models
-- `benchmarks_branch`: Use feature branch from the benchmarks repo to test benchmark changes before merging
-
-**Note:** When running a full eval, you must select an `eval_limit` that is greater than or equal to the actual number of instances in the benchmark. If you specify a smaller limit, only that many instances will be evaluated (partial eval).
-
-## Monitoring
-
-**Datadog script** (requires `OpenHands/evaluation` repo; DD_API_KEY, DD_APP_KEY, and DD_SITE environment variables are set):
-```bash
-DD_API_KEY=$DD_API_KEY DD_APP_KEY=$DD_APP_KEY DD_SITE=$DD_SITE \
-  python scripts/analyze_evals.py --job-prefix <EVAL_RUN_ID> --time-range 60
-# EVAL_RUN_ID format: typically the workflow run ID from GitHub Actions
-```
-
-**kubectl** (for users with cluster access - the agent does not have kubectl access):
-```bash
-kubectl logs -f job/eval-eval-<RUN_ID>-<MODEL_SLUG> -n evaluation-jobs
-```
-
-## Common Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `503 Service Unavailable` | Infrastructure overloaded | Ask user to stop some evaluation runs |
-| `429 Too Many Requests` | Rate limiting | Wait or reduce concurrency |
-| `failed after 3 retries` | Instance failures | Check Datadog logs for root cause |
-
-## Limits
-
-- Max 256 parallel runtimes (jobs will queue if this limit is exceeded)
-- Full evals typically take 1-3 hours depending on benchmark size

.agents/skills/write-behavior-test.md

@@ -1,117 +0,0 @@
----
-name: write-behavior-test
-description: Guide for writing behavior tests that verify agents follow system message guidelines and avoid undesirable behaviors. Use when creating integration tests for agent behavior validation.
-triggers:
-- /write_behavior_test
----
-
-# Behavior Test Writing Guide
-
-You are helping to create **behavior tests** for the agent-sdk integration test suite. These tests verify that agents follow system message guidelines and avoid undesirable behaviors.
-
-The tests are for the agent powered by this SDK, so you may need to refer the codebase for details on how the agent works in order to write effective tests.
-
-## Behavior Tests vs Task Tests
-
-**Task Tests (t*.py)** - REQUIRED tests that verify task completion:
-- Focus: Can the agent successfully complete the task?
-- Example: Fix typos in a file, create a script, implement a feature
-
-**Behavior Tests (b*.py)** - OPTIONAL tests that verify proper behavior:
-- Focus: Does the agent follow best practices and system guidelines?
-- Example: Don't implement when asked for advice, don't over-verify, avoid redundant files
-
-## Key Principles for Writing Behavior Tests
-
-### ✅ DO:
-
-1. **Use Real Repositories**
-   - Clone actual GitHub repositories that represent real-world scenarios
-   - Pin to a specific historical commit (before a fix/feature was added)
-   - Example: `clone_pinned_software_agent_repo(workspace)` helper
-
-2. **Test Realistic Complex, Nuanced Behaviors**
-   - Try to make the task as realistic as possible to real HUMAN interactions, from file naming, (somewhat lazy) instruction style, etc
-   - Focus on subtle behavioral issues that require judgment
-   - Test scenarios where the "right" behavior isn't immediately obvious
-   - Examples: When to implement vs advise, when to stop testing, whether to add backward compatibility
-
-3. **Clean Up Repository History**
-   - Check out to a commit BEFORE the solution exists
-   - Reset/remove future commits (see existing tests for examples)
-   - Ensures the agent experiences the same context as real users
-
-4. **Use Helper Functions**
-   - `find_file_editing_operations(events)` - Find file create/edit operations
-   - `find_tool_calls(events, tool_name)` - Find specific tool usage
-   - `get_conversation_summary(events)` - Get summary for LLM judge
-   - `judge_agent_behavior(...)` - Use LLM to evaluate behavior quality
-
-5. **Leverage LLM Judges**
-   - Use `judge_agent_behavior()` for subjective evaluations
-   - Provide clear evaluation criteria in the judge prompt
-   - Track judge usage costs: `self.add_judge_usage(prompt_tokens, completion_tokens, cost)`
-
-6. **Adaptation of Problem Description to Task**
-   - If you find the problem description is not easy to adapt to a behavior test, e.g. it requires complex environment setup like kubernetes, try to come up with a simpler problem description that still captures the essence of the behavior you want to test but is easier to implement in the test framework.
-   - Ensure the instructions naturally lead to the behavior you want to evaluate
-
-### ❌ DO NOT:
-
-1. **Avoid Simple Synthetic Tests**
-   - Don't create artificial scenarios with minimal setup
-   - Don't test behaviors that are too obvious or straightforward
-   - Example: Don't create a single-file test with trivial content
-
-2. **Don't Test Basic Functionality**
-   - Behavior tests are NOT for testing if the agent can use tools
-   - Task tests handle basic capability verification
-   - Focus on HOW the agent approaches problems, not IF it can solve them
-
-3. **Don't Overcomplicate Static Assertions**
-   - Use assertions for clear-cut checks (e.g., no file edits)
-   - Rely on LLM judges for nuanced behavior evaluations
-   - Avoid trying to encode subjective judgments purely in code or too much static logic
-
-## Tips for Test Difficulty Calibration
-
-**Make tests challenging but not impossible and too long:**
-
-1. **Context Complexity**: Use real codebases with multiple files and dependencies, either the software-agent-sdk or other popular open-source repos you find suitable
-2. **Ambiguity**: Prefer instructions that could be interpreted multiple ways
-3. **Temptation**: Set up scenarios where the "easy wrong path" is tempting
-4. **Realism**: Mirror real user interactions and expectations
-
-**Examples of Good Complexity:**
-- "How to implement X?" (tests if agent implements vs advises)
-- "Update constant Y" (tests if agent over-verifies with excessive test runs)
-- "Rename method A to B" (tests if agent adds unnecessary backward compatibility)
-
-## Example Behavior Test Patterns
-
-1. **Premature Implementation** - Tests if agent implements when asked for advice only
-2. **Over-verification** - Tests if agent runs excessive tests beyond what's needed
-3. **Unnecessary Compatibility** - Tests if agent adds backward compatibility shims when not needed
-4. **Redundant Artifacts** - Tests if agent creates extra files (docs, READMEs) without being asked
-5. **Communication Quality** - Tests if agent provides explanations for actions
-
-## File Naming Convention
-
-Name your test file: `b##_descriptive_name.py`
-- `b` prefix indicates behavior test (auto-detected)
-- `##` is a zero-padded number (e.g., 01, 02, 03)
-- Use snake_case for the descriptive name
-
-## Final Checklist
-
-Before submitting your behavior test, verify:
-
-- [ ] Uses a real repository or complex codebase
-- [ ] Tests a nuanced behavior, not basic functionality
-- [ ] Includes clear and not overly complex verification logic (assertions or LLM judge)
-- [ ] Has a descriptive docstring explaining what behavior is tested
-- [ ] Properly tracks judge usage costs if using LLM evaluation
-- [ ] Follows naming convention: `b##_descriptive_name.py`
-- [ ] Test is realistic and based on actual behavioral issues observed
-
-Remember: The goal is to catch subtle behavioral issues that would appear in real-world usage, serving as regression tests for system message improvements.

.devcontainer/README.MD

@@ -0,0 +1 @@
+The files in this directory configure a development container for GitHub Codespaces.

.devcontainer/devcontainer.json

@@ -0,0 +1,15 @@
+{
+	"name": "OpenHands Codespaces",
+	"image": "mcr.microsoft.com/devcontainers/universal",
+	"customizations":{
+        "vscode":{
+            "extensions": [
+                "ms-python.python"
+            ]
+        }
+    },
+	"onCreateCommand": "sh ./.devcontainer/on_create.sh",
+	"postCreateCommand": "make build",
+	"postStartCommand": "USE_HOST_NETWORK=True nohup bash -c 'make run &'"
+
+}

.devcontainer/on_create.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+sudo apt update
+sudo apt install -y netcat
+sudo add-apt-repository -y ppa:deadsnakes/ppa
+sudo apt install -y python3.12
+curl -sSL https://install.python-poetry.org | python3.12 -

.dockerignore

@@ -1,261 +1,5 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-# Note: We keep our custom spec file in version control
-# *.spec
-
-# PyInstaller build directories
-build/
-dist/
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-# poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
-#  project, it is recommended to ignore the entire .idea directory.
-.idea/
-
-# VS Code
-.vscode/
-
-# macOS
-.DS_Store
-.AppleDouble
-.LSOverride
-
-# Windows
-Thumbs.db
-ehthumbs.db
-Desktop.ini
-$RECYCLE.BIN/
-
-# Linux
-*~
-
-# Temporary files
-*.tmp
-*.temp
-*.swp
-*.swo
-
-# UV specific
-.uv/
-
-# Project specific
-*.log
-.coverage
-.pytest_cache/
-
-workspace/
-.client
-.docker
-
-
-.git
-.git/**
-
-# VS Code: Ignore all but certain files that specify repo-specific settings.
-# https://stackoverflow.com/questions/32964920/should-i-commit-the-vscode-folder-to-source-control
-.vscode/**/*
-!.vscode/extensions.json
-!.vscode/tasks.json
-
-# VS Code extensions/forks:
-.cursorignore
-.rooignore
-.clineignore
-.windsurfignore
-.cursorrules
-.roorules
-.clinerules
-.windsurfrules
-.cursor/rules
-.roo/rules
-.cline/rules
-.windsurf/rules
-.repomix
-repomix-output.txt
-
-# misc
-.DS_Store
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-logs
-
-# agent
+frontend/node_modules
+config.toml
 .envrc
-cache
-.jinja_cache/
-
-.conversations*
-workspace/
-
-# Build optimization: exclude files not needed for building agent-server
-tests/
-*.log
-.github/
-scripts/
-examples/
-.ruff_cache/
-.uv-cache/
-Makefile
-docs/
-*.md
-!README.md
-.pre-commit-config.yaml
-.python-version
+.env
+.git

.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-vendored

.github/.codecov.yml

@@ -0,0 +1,19 @@
+codecov:
+  notify:
+    wait_for_ci: true
+    # our project is large, so 6 builds are typically uploaded. this waits till 5/6
+    # See https://docs.codecov.com/docs/notifications#section-preventing-notifications-until-after-n-builds
+    after_n_builds: 5
+
+coverage:
+  status:
+    patch:
+      default:
+        threshold: 100% # allow patch coverage to be lower than project coverage by any amount
+    project:
+      default:
+        threshold: 5% # allow project coverage to drop at most 5%
+
+comment: false
+github_checks:
+    annotations: false

.github/ISSUE_TEMPLATE/bug_template.yml

@@ -1,168 +1,61 @@
----
 name: Bug
-description: Report a problem with OpenHands SDK
+description: Report a problem with OpenHands
 title: '[Bug]: '
-labels: [bug]
+labels: ['bug']
 body:
-    - type: markdown
-      attributes:
-          value: |
-              ## Thank you for reporting a bug! 🐛
+  - type: markdown
+    attributes:
+      value: Thank you for taking the time to fill out this bug report. Please provide as much information as possible to help us understand and address the issue effectively.
 
-              **Please fill out all required fields.** Issues missing critical information (version, installation method, reproduction steps, etc.) will be delayed or closed until complete details are provided.
+  - type: checkboxes
+    attributes:
+      label: Is there an existing issue for the same bug?
+      description: Please check if an issue already exists for the bug you encountered.
+      options:
+      - label: I have checked the existing issues.
+        required: true
 
-              Clear, detailed reports help us resolve issues faster.
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Describe the bug and reproduction steps
+      description: Provide a description of the issue along with any reproduction steps.
+    validations:
+      required: true
 
-    - type: checkboxes
-      attributes:
-          label: Is there an existing issue for the same bug?
-          description: Please search existing issues before creating a new one. If found, react or comment to the duplicate issue instead of making a 
-              new one. <!-- TODO-openhands -->
-          options:
-              - label: I have searched existing issues and this is not a duplicate.
-                required: true
+  - type: dropdown
+    id: installation
+    attributes:
+      label: OpenHands Installation
+      description: How are you running OpenHands?
+      options:
+        - Docker command in README
+        - Development workflow
+        - app.all-hands.dev
+        - Other
+      default: 0
 
-    - type: textarea
-      id: bug-description
-      attributes:
-          label: Bug Description
-          description: Clearly describe what went wrong. Be specific and concise.
-          placeholder: Example - When I use the SDK to create an agent with custom tools, the agent fails to register the tools with a TypeError.
-      validations:
-          required: true
+  - type: input
+    id: openhands-version
+    attributes:
+      label: OpenHands Version
+      description: What version of OpenHands are you using?
+      placeholder: ex. 0.9.8, main, etc.
 
-    - type: textarea
-      id: expected-behavior
-      attributes:
-          label: Expected Behavior
-          description: What did you expect to happen?
-          placeholder: Example - The agent should successfully register custom tools and make them available for use.
-      validations:
-          required: false
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - MacOS
+        - Linux
+        - WSL on Windows
 
-    - type: textarea
-      id: actual-behavior
-      attributes:
-          label: Actual Behavior
-          description: What actually happened?
-          placeholder: "Example - TypeError: 'NoneType' object is not iterable when calling agent.register_tool()"
-      validations:
-          required: false
-
-    - type: textarea
-      id: reproduction-steps
-      attributes:
-          label: Steps to Reproduce
-          description: Provide clear, step-by-step instructions to reproduce the bug.
-          placeholder: |
-              1. Install openhands-sdk using pip
-              2. Import and create an agent instance
-              3. Define a custom tool function
-              4. Call agent.register_tool(custom_tool)
-              5. Error appears
-      validations:
-          required: false
-
-    - type: input
-      id: installation
-      attributes:
-          label: Installation Method
-          description: How did you install the OpenHands SDK?
-          placeholder: ex. pip install openhands-sdk, uv pip install openhands-sdk, pip install -e ., etc.
-
-    - type: input
-      id: installation-other
-      attributes:
-          label: If you selected "Other", please specify
-          description: Describe your installation method
-          placeholder: ex. Poetry, conda, custom setup, etc.
-
-    - type: input
-      id: sdk-version
-      attributes:
-          label: SDK Version
-          description: What version are you using? Check with `pip show openhands-sdk` or similar for other packages.
-          placeholder: ex. 0.1.0, 0.2.0, main branch, commit hash, etc.
-      validations:
-          required: false
-
-    - type: checkboxes
-      id: version-confirmation
-      attributes:
-          label: Version Confirmation
-          description: Bugs on older versions may already be fixed. Please upgrade before submitting.
-          options:
-              - label: I have confirmed this bug exists on the LATEST version of OpenHands SDK
-                required: false
-
-    - type: input
-      id: python-version
-      attributes:
-          label: Python Version
-          description: Which Python version are you using?
-          placeholder: ex. 3.10.12, 3.11.5, 3.12.0
-      validations:
-          required: false
-
-    - type: input
-      id: model-name
-      attributes:
-          label: Model Name (if applicable)
-          description: Which model(s) are you using?
-          placeholder: ex. gpt-4o, claude-3-5-sonnet-20241022, openrouter/deepseek-r1, etc.
-      validations:
-          required: false
-
-    - type: dropdown
-      id: os
-      attributes:
-          label: Operating System
-          options:
-              - MacOS
-              - Linux
-              - WSL on Windows
-              - Windows
-              - Other
-      validations:
-          required: false
-
-    - type: textarea
-      id: logs
-      attributes:
-          label: Logs and Error Messages
-          description: |
-              **Paste relevant logs, error messages, or stack traces.** Use code blocks (```) for formatting.
-
-              Include full stack traces when available.
-          placeholder: |
-              ```
-              Paste error logs here
-              ```
-
-    - type: textarea
-      id: code-sample
-      attributes:
-          label: Minimal Code Sample
-          description: |
-              If possible, provide a minimal code sample that reproduces the issue.
-          placeholder: |
-              ```python
-              from openhands.sdk import Agent
-
-              # Your minimal reproducible code here
-              ```
-
-    - type: textarea
-      id: additional-context
-      attributes:
-          label: Screenshots and Additional Context
-          description: |
-              Add screenshots, environment details, dependency versions, or other context that helps explain the issue.
-
-          placeholder: Drag and drop screenshots here, paste links, or add additional context.
-
-    - type: markdown
-      attributes:
-          value: |
-              ---
-              **Note:** Please help us help you! Well-documented bugs are easier to reproduce and fix. Thank you for your understanding!
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Logs, Errors, Screenshots, and Additional Context
+      description: Please provide any additional information you think might help. If you want to share the chat history
+        you can click the thumbs-down (👎) button above the input field and you will get a shareable link
+        (you can also click thumbs up when things are going well of course!). LLM logs will be stored in the
+        `logs/llm/default` folder. Please add any additional context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature Request
+about: Suggest an idea for OpenHands features
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**What problem or use case are you trying to solve?**
+
+**Describe the UX of the solution you'd like**
+
+**Do you have thoughts on the technical implementation?**
+
+**Describe alternatives you've considered**
+
+**Additional context**

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,117 +0,0 @@
----
-name: Feature Request or Enhancement
-description: Suggest a new feature or improvement for OpenHands SDK
-title: '[Feature]: '
-labels: [enhancement]
-body:
-    - type: markdown
-      attributes:
-          value: |
-              ## Thank you for suggesting a feature! 💡
-
-              We encourage you to open the discussion on the feature you need. You are always welcome to implement it, if you wish.
-
-    - type: checkboxes
-      attributes:
-          label: Is there an existing feature request for this?
-          description: Please search existing issues and feature requests before creating a new one. If found, react or comment to the duplicate issue
-              instead of making a new one. <!-- TODO-openhands -->
-          options:
-              - label: I have searched existing issues and feature requests, and this is not a duplicate.
-                required: true
-
-    - type: textarea
-      id: problem-statement
-      attributes:
-          label: Problem or Use Case
-          description: What problem are you trying to solve? What use case would this feature enable?
-          placeholder: |
-              Example - As a developer building agents, I need to persist agent state between sessions. Currently, there's no built-in mechanism for saving and loading agent memory, which means agents lose context when the process restarts.
-      validations:
-          required: true
-
-    - type: textarea
-      id: proposed-solution
-      attributes:
-          label: Proposed Solution
-          description: Describe your ideal solution. What should this feature do? How should it work?
-          placeholder: |
-              Example - Add a StateManager class that allows saving and loading agent state to/from disk or database. Provide methods like save_state(), load_state(), and clear_state(). Support multiple backend options (JSON files, SQLite, Redis, etc.).
-      validations:
-          required: true
-
-    - type: textarea
-      id: alternatives
-      attributes:
-          label: Alternatives Considered
-          description: Have you considered any alternative solutions or workarounds? What are their limitations?
-          placeholder: Example - I tried manually serializing agent state using pickle, but it's not portable across SDK versions and doesn't handle 
-              complex tool state properly.
-
-    - type: dropdown
-      id: priority
-      attributes:
-          label: Priority / Severity
-          description: How important is this feature to your workflow?
-          options:
-              - Critical - Blocking my work, no workaround available
-              - High - Significant impact on productivity
-              - Medium - Would improve experience
-              - Low - Nice to have
-          default: 2
-      validations:
-          required: true
-
-    - type: dropdown
-      id: scope
-      attributes:
-          label: Estimated Scope
-          description: To the best of your knowledge, how complex do you think this feature would be to implement?
-          options:
-              - Small - API addition, config option, or minor change
-              - Medium - New feature with moderate complexity
-              - Large - Significant feature requiring architecture changes
-              - Unknown - Not sure about the technical complexity
-          default: 3
-
-    - type: checkboxes
-      id: feature-area
-      attributes:
-          label: Feature Area
-          description: Which part of OpenHands SDK does this feature relate to? If you select "Other", please specify the area in the Additional 
-              Context section below. <!-- TODO-openhands -->
-          options:
-              - label: Agent API / Core functionality
-              - label: Tools / Tool system
-              - label: Skills / Plugins
-              - label: Agent Server
-              - label: Workspace management
-              - label: Configuration / Settings
-              - label: Examples / Templates
-              - label: Documentation
-              - label: Testing / Development tools
-              - label: Performance / Optimization
-              - label: Integrations (GitHub, APIs, etc.)
-              - label: Other
-
-    - type: textarea
-      id: technical-details
-      attributes:
-          label: Technical Implementation Ideas (Optional)
-          description: If you have technical expertise, share implementation ideas, API suggestions, or relevant technical details.
-          placeholder: |
-              Example - Could implement StateManager as an abstract base class with concrete implementations for different backends. Add state_manager parameter to Agent constructor. Use JSON serialization for simple state, MessagePack for better performance.
-
-    - type: textarea
-      id: additional-context
-      attributes:
-          label: Additional Context
-          description: Add any other context, code examples, API mockups, or references that help illustrate this feature request.
-          placeholder: |
-              Example code or API design:
-              ```python
-              from openhands.sdk import Agent, StateManager
-
-              agent = Agent(state_manager=StateManager('file://agent_state.json'))
-              agent.save_state()
-              ```

.github/ISSUE_TEMPLATE/technical_proposal.md

@@ -0,0 +1,18 @@
+---
+name: Technical Proposal
+about: Propose a new architecture or technology
+title: ''
+labels: 'proposal'
+assignees: ''
+
+---
+
+**Summary**
+
+**Motivation**
+
+**Technical Design**
+
+**Alternatives to Consider**
+
+**Additional context**

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,11 +0,0 @@
-## Summary
-
-[fill in a summary of this PR]
-
-## Checklist
-
-- [ ] If the PR is changing/adding functionality, are there tests to reflect this?
-- [ ] If there is an example, have you run the example to make sure that it works?
-- [ ] If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
-- [ ] If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
-- [ ] Is the github CI passing?

.github/dependabot.yml

@@ -1,17 +1,69 @@
----
-# Dependabot configuration for automated dependency updates
-# See: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-#
-# Note: Python (pip) ecosystem is not configured here because Dependabot does not
-# fully support uv workspaces yet. See issue #2510 for tracking.
-
 version: 2
-
 updates:
-  # GitHub Actions
-    - package-ecosystem: github-actions
-      directory: /
-      schedule:
-          interval: weekly
-      commit-message:
-          prefix: chore(deps)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 1
+    groups:
+      # put packages in their own group if they have a history of breaking the build or needing to be reverted
+      pre-commit:
+        patterns:
+          - "pre-commit"
+      llama:
+        patterns:
+          - "llama*"
+      chromadb:
+        patterns:
+          - "chromadb"
+      security-all:
+        applies-to: "security-updates"
+        patterns:
+          - "*"
+      version-all:
+        applies-to: "version-updates"
+        patterns:
+          - "*"
+
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 1
+    groups:
+      docusaurus:
+        patterns:
+          - "*docusaurus*"
+      eslint:
+        patterns:
+          - "*eslint*"
+      security-all:
+        applies-to: "security-updates"
+        patterns:
+          - "*"
+      version-all:
+        applies-to: "version-updates"
+        patterns:
+          - "*"
+
+  - package-ecosystem: "npm"
+    directory: "/docs"
+    schedule:
+      interval: "weekly"
+      day: "wednesday"
+    open-pull-requests-limit: 1
+    groups:
+      docusaurus:
+        patterns:
+          - "*docusaurus*"
+      eslint:
+        patterns:
+          - "*eslint*"
+      security-all:
+        applies-to: "security-updates"
+        patterns:
+          - "*"
+      version-all:
+        applies-to: "version-updates"
+        patterns:
+          - "*"

.github/prompts/update-documentation.md

@@ -1,109 +0,0 @@
-# Documentation Update Prompt
-
-You are a world-class documentation writer tasked with keeping the OpenHands Agent SDK documentation accurate and up-to-date. Your goal is to ensure documentation reflects the current codebase and provides clear, minimal, and actionable guidance.
-
-## Core Objectives
-
-1. **Accuracy**: Ensure all documentation matches the current codebase
-2. **Completeness**: Include all available tools and core components
-3. **Clarity**: Keep examples simple, working, and easy to understand
-4. **Navigation**: Provide source code links for all definitions
-
-## Tasks to Perform
-
-### 1. Codebase Analysis
-
-- Scan `examples/` for available examples
-- Scan `openhands-tools/` for all available runtime tools
-- Check `openhands-sdk/openhands/tool/builtins/` for built-in tools
-- Identify any new tools or removed tools since last update
-
-### 2. Documentation Review
-
-Review these key files for accuracy:
-- `docs/architecture/overview.md` - High-level component interactions and design principles
-- `docs/architecture/tool.md` - Tool system, inheritance, and MCP integration
-- `docs/architecture/agent.md` - Agent architecture and execution flow
-- `docs/architecture/llm.md` - LLM integration and capabilities
-- `docs/architecture/conversation.md` - Conversation interface and persistence
-- `docs/getting-started.mdx` - Make sure we have descriptions of all examples listed out in `examples/`
-- `docs/index.md` - Overview and navigation
-- `README.md` - Root project documentation
-
-### 3. Content Updates Required
-
-#### Architecture Diagrams
-
-- Keep mermaid diagrams SIMPLE and READABLE across all docs/architecture/ files
-- Focus on core components and relationships, not every possible class
-- Include all current runtime tools: TerminalTool, FileEditorTool, TaskTrackerTool, etc.
-- Verify component interactions and inheritance reflect actual codebase structure
-
-#### Tool Documentation
-
-For each tool, ensure:
-- Accurate usage examples with `.create()` method
-- Working code snippets (test them!)
-- Source code links to GitHub
-- Clear descriptions of functionality
-
-#### Core Framework Classes
-
-Verify documentation across docs/architecture/ files for:
-
-- `Tool`, `ActionBase`, `ObservationBase`, `ToolExecutor` (docs/architecture/tool.md)
-- `Agent`, `AgentBase`, system prompts (docs/architecture/agent.md)
-- `LLM`, message types, provider support (docs/architecture/llm.md)
-- `Conversation`, `ConversationState`, event system (docs/architecture/conversation.md)
-- All built-in tools: `FinishTool`, `ThinkTool`
-- All runtime tools: `TerminalTool`, `FileEditorTool`, `TaskTrackerTool`
-
-### 4. Verification Steps
-
-- Test all documented code examples to ensure they work
-- Verify all GitHub source links are correct and accessible
-- Check that simplified and advanced usage patterns are accurate
-- Ensure cross-references between files are consistent
-
-### 5. Documentation Standards
-
-- **Style**: Direct, lean, technical writing
-- **Structure**: Clear sections answering specific user questions
-- **Examples**: Show working code rather than vague descriptions
-- **Links**: Include GitHub source links for all classes and tools
-- **Diagrams**: Simple, focused mermaid charts
-
-## Expected Deliverables
-
-1. Updated documentation files with current tool listings
-2. Verified working code examples
-3. Simplified and accurate architecture diagrams
-4. Complete source code links for all definitions
-5. Consistent cross-references across all documentation files
-
-## Quality Checklist
-
-- [ ] All runtime tools are documented with working examples
-- [ ] All built-in tools are listed and linked
-- [ ] Architecture diagrams are simple and current
-- [ ] All code examples have been tested and work
-- [ ] Source code links point to correct GitHub files
-- [ ] Documentation follows minimal, clear writing style
-- [ ] Cross-references between files are consistent
-
-## Commit Message Format
-
-If you think there's change required, please create a pull request.
-
-```
-Update documentation to reflect current codebase
-
-- [Specific changes made]
-- [Tools added/removed/updated]
-- [Diagrams simplified/corrected]
-- [Examples verified/fixed]
-
-Co-authored-by: openhands <openhands@all-hands.dev>
-```
-
-Focus on making the documentation immediately useful for developers who need to understand and use the OpenHands Tools System.

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+**End-user friendly description of the problem this fixes or functionality that this introduces**
+
+- [ ] Include this change in the Release Notes. If checked, you must provide an **end-user friendly** description for your change below
+
+---
+**Give a summary of what the PR does, explaining any non-trivial design decisions**
+
+
+
+---
+**Link of any specific issues this addresses**

.github/run-eval/ADDINGMODEL.md

@@ -1,381 +0,0 @@
-# Adding Models to resolve_model_config.py
-
-## Overview
-
-This file (`resolve_model_config.py`) defines models available for evaluation. Models must be added here before they can be used in integration tests or evaluations.
-
-## Critical Rules
-
-**ONLY ADD NEW CONTENT - DO NOT MODIFY EXISTING CODE**
-
-### What NOT to Do
-
-1. **Never modify existing model entries** - they are production code, already working
-2. **Never modify existing tests** - especially test assertions, mock configs, or expected values
-3. **Never reformat existing code** - preserve exact spacing, quotes, commas, formatting
-4. **Never reorder models or imports** - dictionary and import order must be preserved
-5. **Never "fix" existing code** - if it's in the file and tests pass, it works
-6. **Never change test assertions** - even if they "look wrong" to you
-7. **Never replace real model tests with mocked tests** - weakens validation
-8. **Never fix import names** - if `test_model` exists, don't change it to `check_model`
-
-### What These Rules Prevent
-
-**Example violations** (all found in real PRs):
-- Changing `assert result[0]["id"] == "claude-sonnet-4-5-20250929"` to `"gpt-4"` ❌
-- Replacing real model config tests with mocked/custom model tests ❌
-- "Fixing" `from resolve_model_config import test_model` to `check_model` ❌
-- Adding "Fixed incorrect assertions" without explaining what was incorrect ❌
-- Claiming to "fix test issues" when tests were already passing ❌
-
-### What TO Do
-
-**When adding a model**:
-- Add ONE new entry to the MODELS dictionary
-- Add ONE new test function (follow existing pattern exactly)
-- Add to feature lists in model_features.py ONLY if needed for your model
-- Do not touch any other files, tests, imports, or configurations
-- Test the PR branch with the integration test action.
-- Add a link to the integrations test to the PR.
-- If you think something is broken, it's probably not - add a comment to the PR.
-
-## Files to Modify
-
-1. **Always required**:
-   - `.github/run-eval/resolve_model_config.py` - Add model configuration
-   - `tests/github_workflows/test_resolve_model_config.py` - Add test
-
-2. **Usually required** (if model has special characteristics):
-   - `openhands-sdk/openhands/sdk/llm/utils/model_features.py` - Add to feature categories
-
-3. **Sometimes required**:
-   - `openhands-sdk/openhands/sdk/llm/utils/model_prompt_spec.py` - GPT models only (variant detection)
-   - `openhands-sdk/openhands/sdk/llm/utils/verified_models.py` - Production-ready models
-
-   > ⚠️ **When editing `verified_models.py`**: If you add a model to `VERIFIED_OPENHANDS_MODELS`,
-   > you **must also** add it to its provider-specific list (e.g. `VERIFIED_ANTHROPIC_MODELS`,
-   > `VERIFIED_GEMINI_MODELS`, `VERIFIED_MOONSHOT_MODELS`, etc.).
-   > If no list exists for the provider yet, create one and add it to the `VERIFIED_MODELS` dict.
-   > This ensures the model appears under its actual provider in the UI, not just under "openhands".
-
-## Step 1: Add to resolve_model_config.py
-
-Add entry to `MODELS` dictionary:
-
-```python
-"model-id": {
-    "id": "model-id",  # Must match dictionary key
-    "display_name": "Human Readable Name",
-    "llm_config": {
-        "model": "litellm_proxy/provider/model-name",
-        "temperature": 0.0,  # See temperature guide below
-    },
-},
-```
-
-### Temperature Configuration
-
-| Value | When to Use | Provider Requirements |
-|-------|-------------|----------------------|
-| `0.0` | Standard deterministic models | Most providers |
-| `1.0` | Reasoning models | Kimi K2, MiniMax M2.5 |
-| `None` | Use provider default | When unsure |
-
-### Special Parameters
-
-Add only if needed:
-
-- **`disable_vision: True`** - Model doesn't support vision despite LiteLLM reporting it does (GLM-4.7, GLM-5)
-- **`reasoning_effort: "high"`** - For OpenAI reasoning models that support this parameter
-- **`max_tokens: <value>`** - To prevent hangs or control output length
-- **`top_p: <value>`** - Nucleus sampling (cannot be used with `temperature` for Claude models)
-- **`litellm_extra_body: {...}`** - Provider-specific parameters (e.g., `{"enable_thinking": True}`)
-
-### Critical Rules
-
-1. Model ID must match dictionary key
-2. Model path must start with `litellm_proxy/`
-3. **Claude models**: Cannot use both `temperature` and `top_p` - choose one or omit both
-4. Parameters like `disable_vision` must be in `SDK_ONLY_PARAMS` constant (they're filtered before sending to LiteLLM)
-
-## Step 2: Update model_features.py (if applicable)
-
-Check provider documentation to determine which feature categories apply:
-
-### REASONING_EFFORT_MODELS
-Models that support `reasoning_effort` parameter:
-- OpenAI: o1, o3, o4, GPT-5 series
-- Anthropic: Claude Opus 4.5+, Claude Sonnet 4.6
-- Google: Gemini 2.5+, Gemini 3.x series
-- AWS: Nova 2 Lite
-
-```python
-REASONING_EFFORT_MODELS: list[str] = [
-    "your-model-identifier",  # Add here
-]
-```
-
-**Effect**: Automatically strips `temperature` and `top_p` parameters to avoid API conflicts.
-
-### EXTENDED_THINKING_MODELS
-Models with extended thinking capabilities:
-- Anthropic: Claude Sonnet 4.5+, Claude Haiku 4.5
-
-```python
-EXTENDED_THINKING_MODELS: list[str] = [
-    "your-model-identifier",  # Add here
-]
-```
-
-**Effect**: Automatically strips `temperature` and `top_p` parameters.
-
-### PROMPT_CACHE_MODELS
-Models supporting prompt caching:
-- Anthropic: Claude 3.5+, Claude 4+ series
-
-```python
-PROMPT_CACHE_MODELS: list[str] = [
-    "your-model-identifier",  # Add here
-]
-```
-
-### SUPPORTS_STOP_WORDS_FALSE_MODELS
-Models that **do not** support stop words:
-- OpenAI: o1, o3 series
-- xAI: Grok-4, Grok-code-fast-1
-- DeepSeek: R1 family
-
-```python
-SUPPORTS_STOP_WORDS_FALSE_MODELS: list[str] = [
-    "your-model-identifier",  # Add here
-]
-```
-
-### FORCE_STRING_SERIALIZER_MODELS
-Models requiring string format for tool messages (not structured content):
-- DeepSeek models
-- GLM models  
-- Groq: Kimi K2-Instruct
-- OpenRouter: MiniMax
-
-Use pattern matching:
-```python
-FORCE_STRING_SERIALIZER_MODELS: list[str] = [
-    "deepseek",  # Matches any model with "deepseek" in name
-    "groq/kimi-k2-instruct",  # Provider-prefixed
-]
-```
-
-### Other Categories
-
-- **PROMPT_CACHE_RETENTION_MODELS**: GPT-5 family, GPT-4.1
-- **RESPONSES_API_MODELS**: GPT-5 family, codex-mini-latest
-- **SEND_REASONING_CONTENT_MODELS**: Kimi K2 Thinking/K2.5, MiniMax-M2, DeepSeek Reasoner
-
-See `model_features.py` for complete lists and additional documentation.
-
-## Step 3: Add Test
-
-**File**: `tests/github_workflows/test_resolve_model_config.py`
-
-**Important**: 
-- Python function names cannot contain hyphens. Convert model ID hyphens to underscores.
-- **Do not modify any existing test functions** - only add your new one at the end of the file
-- **Do not change existing imports** - use what's already there
-- **Do not fix "incorrect" assertions** in other tests - they are correct
-
-**Test template** (copy and modify for your model):
-
-```python
-def test_your_model_id_config():  # Replace hyphens with underscores in function name
-    """Test that your-model-id has correct configuration."""
-    model = MODELS["your-model-id"]  # Dictionary key keeps hyphens
-    
-    assert model["id"] == "your-model-id"
-    assert model["display_name"] == "Your Model Display Name"
-    assert model["llm_config"]["model"] == "litellm_proxy/provider/model-name"
-    # Only add assertions for parameters YOU added in resolve_model_config.py
-    # assert model["llm_config"]["temperature"] == 0.0
-    # assert model["llm_config"]["disable_vision"] is True
-```
-
-**What NOT to do in tests**:
-- Don't change assertions in other test functions (even if model names "look wrong")
-- Don't replace real model tests with mocked tests
-- Don't change `test_model` to `check_model` in imports
-- Don't modify mock_models dictionaries in other tests
-- Don't add "fixes" to existing tests - they work as-is
-
-## Step 4: Update GPT Variant Detection (GPT models only)
-
-**File**: `openhands-sdk/openhands/sdk/llm/utils/model_prompt_spec.py`
-
-Required only if this is a GPT model needing specific prompt template.
-
-**Order matters**: More specific patterns must come before general patterns.
-
-```python
-_MODEL_VARIANT_PATTERNS: dict[str, tuple[tuple[str, tuple[str, ...]], ...]] = {
-    "openai_gpt": (
-        (
-            "gpt-5-codex",  # Specific variant first
-            ("gpt-5-codex", "gpt-5.1-codex", "gpt-5.2-codex", "gpt-5.3-codex"),
-        ),
-        ("gpt-5", ("gpt-5", "gpt-5.1", "gpt-5.2")),  # General variant last
-    ),
-}
-```
-
-## Step 5: Run Tests Locally
-
-```bash
-# Pre-commit checks
-pre-commit run --all-files
-
-# Unit tests
-pytest tests/github_workflows/test_resolve_model_config.py::test_your_model_config -v
-
-# Manual verification
-cd .github/run-eval
-MODEL_IDS="your-model-id" GITHUB_OUTPUT=/tmp/output.txt python resolve_model_config.py
-```
-
-## Step 6: Run Integration Tests (Required Before PR)
-
-**Mandatory**: Integration tests must pass before creating PR.
-
-### Via GitHub Actions
-
-1. Push branch: `git push origin your-branch-name`
-2. Navigate to: https://github.com/OpenHands/software-agent-sdk/actions/workflows/integration-runner.yml
-3. Click "Run workflow"
-4. Configure:
-   - **Branch**: Select your branch
-   - **model_ids**: `your-model-id`
-   - **Reason**: "Testing model-id"
-5. Wait for completion
-6. **Save run URL** - required for PR description
-
-### Expected Results
-
-- Success rate: 100% (or 87.5% if vision test skipped)
-- Duration: 5-10 minutes per model
-- Tests: 8 total (basic commands, file ops, code editing, reasoning, errors, tools, context, vision)
-
-## Step 7: Create PR
-
-### Required in PR Description
-
-```markdown
-## Summary
-Adds the `model-id` model to resolve_model_config.py.
-
-## Changes
-- Added model-id to MODELS dictionary
-- Added test_model_id_config() test function
-- [Only if applicable] Added to [feature category] in model_features.py
-
-## Configuration
-- Model ID: model-id
-- Provider: Provider Name  
-- Temperature: [value] - [reasoning for choice]
-- [List any special parameters and why needed]
-
-## Integration Test Results
-✅ Integration tests passed: [PASTE GITHUB ACTIONS RUN URL]
-
-[Summary table showing test results]
-
-Fixes #[issue-number]
-```
-
-### What NOT to Include in PR Description
-
-**Do not claim to have "fixed" things unless they were actually broken**:
-- ❌ "Fixed test_model import issue" (if tests were passing, there was no issue)
-- ❌ "Fixed incorrect assertions in existing tests" (they were correct)
-- ❌ "Improved test coverage" (unless you actually added new test cases)
-- ❌ "Cleaned up code" (you shouldn't be cleaning up anything)
-- ❌ "Updated test approach" (you shouldn't be changing testing approach)
-
-**Only describe what you actually added**:
-- ✅ "Added gpt-5.3-codex model configuration"
-- ✅ "Added test for gpt-5.3-codex"
-- ✅ "Added gpt-5.3-codex to REASONING_EFFORT_MODELS"
-
-## Common Issues
-
-### Integration Tests Hang (6-8+ hours)
-**Causes**:
-- Missing `max_tokens` parameter
-- Claude models with both `temperature` and `top_p` set
-- Model not in REASONING_EFFORT_MODELS or EXTENDED_THINKING_MODELS
-
-**Solutions**: Add `max_tokens`, remove parameter conflicts, add to appropriate feature category.
-
-**Reference**: #2147
-
-### Preflight Check: "Cannot specify both temperature and top_p"
-**Cause**: Claude models receiving both parameters
-
-**Solutions**:
-- Remove `top_p` from llm_config if `temperature` is set
-- Add model to REASONING_EFFORT_MODELS or EXTENDED_THINKING_MODELS (auto-strips both)
-
-**Reference**: #2137, #2193
-
-### Vision Tests Fail
-**Cause**: LiteLLM reports vision support but model doesn't actually support it
-
-**Solution**: Add `"disable_vision": True` to llm_config
-
-**Reference**: #2110 (GLM-5), #1898 (GLM-4.7)
-
-### Wrong Prompt Template (GPT models)
-**Cause**: Model variant not detected correctly, falls through to wrong template
-
-**Solution**: Add explicit entries to `model_prompt_spec.py` with correct pattern order
-
-**Reference**: #2233 (GPT-5.2-codex, GPT-5.3-codex)
-
-### SDK-Only Parameters Sent to LiteLLM
-**Cause**: Parameter like `disable_vision` not in `SDK_ONLY_PARAMS` set
-
-**Solution**: Add to `SDK_ONLY_PARAMS` in `resolve_model_config.py`
-
-**Reference**: #2194
-
-## Model Feature Detection Criteria
-
-### How to Determine if Model Needs Feature Category
-
-**Reasoning Model**:
-- Check provider documentation for "reasoning", "thinking", or "o1-style" mentions
-- Model exposes internal reasoning traces
-- Examples: o1, o3, GPT-5, Claude Opus 4.5+, Gemini 3+
-
-**Extended Thinking**:
-- Check if model is Claude Sonnet 4.5+ or Claude Haiku 4.5
-- Provider documents extended thinking capabilities
-
-**Prompt Caching**:
-- Check provider documentation for prompt caching support
-- Anthropic Claude 3.5+ and 4+ series support this
-
-**Vision Support**:
-- Check provider documentation (don't rely solely on LiteLLM)
-- If LiteLLM reports vision but provider docs say text-only, add `disable_vision: True`
-
-**Stop Words**:
-- Most models support stop words
-- o1/o3 series, some Grok models, DeepSeek R1 do not
-
-**String Serialization**:
-- If tool message errors mention "Input should be a valid string"
-- DeepSeek, GLM, some provider-specific models need this
-
-## Reference
-
-- Recent model additions: #2102, #2153, #2207, #2233, #2269
-- Common issues: #2147 (hangs), #2137 (parameters), #2110 (vision), #2233 (variants), #2193 (preflight)
-- Integration test workflow: `.github/workflows/integration-runner.yml`

.github/run-eval/AGENTS.md

@@ -1,56 +0,0 @@
-# Model Configuration for OpenHands SDK
-
-See the [project root AGENTS.md](../../AGENTS.md) for repository-wide policies and workflows.
-
-This directory contains model configuration and evaluation setup for the OpenHands SDK.
-
-## Key Files
-
-- **`resolve_model_config.py`** - Model registry and configuration
-  - Defines all models available for evaluation
-  - Contains model IDs, display names, LiteLLM paths, and parameters
-  - Used by integration tests and evaluation workflows
-
-- **`tests/github_workflows/test_resolve_model_config.py`** - Tests for model configurations
-  - Validates model entries are correctly structured
-  - Tests preflight check functionality
-
-- **`ADDINGMODEL.md`** - Detailed guide for adding models (see below)
-
-## Common Tasks
-
-### Adding a New Model
-
-**→ See [ADDINGMODEL.md](./ADDINGMODEL.md) for complete instructions**
-
-This is the most common task in this directory. The guide covers:
-- Required steps and files to modify
-- Model feature categories and when to use them
-- Integration testing requirements
-- Common issues and troubleshooting
-- Critical rules to prevent breaking existing models
-
-### Debugging Model Issues
-
-If a model is failing in evaluations:
-1. Check the model configuration in `resolve_model_config.py`
-2. Review parameter compatibility (especially `temperature` + `top_p` for Claude)
-3. Check if model is in correct feature categories in `openhands-sdk/openhands/sdk/llm/utils/model_features.py`
-4. Run preflight check: `MODEL_IDS="model-id" python resolve_model_config.py`
-
-### Updating Existing Models
-
-**Warning**: Only update existing models if there's a confirmed issue. Working configurations should not be changed.
-
-If you must update:
-1. Document why the change is needed (link to issue/PR showing the problem)
-2. Test thoroughly before and after the change
-3. Run integration tests to verify no regressions
-
-## Directory Purpose
-
-This directory bridges model definitions with the evaluation system:
-- Models defined here are available for integration tests
-- Configuration includes LiteLLM routing and SDK-specific parameters
-- Preflight checks validate model accessibility before expensive evaluation runs
-- Tests ensure all models are correctly structured and resolvable

.github/run-eval/resolve_model_config.py

@@ -1,447 +0,0 @@
-#!/usr/bin/env python3
-"""
-Resolve model IDs to full model configurations and verify model availability.
-
-Reads:
-- MODEL_IDS: comma-separated model IDs
-- LLM_API_KEY: API key for litellm_proxy (optional, for preflight check)
-- LLM_BASE_URL: Base URL for litellm_proxy (optional, defaults to eval proxy)
-- SKIP_PREFLIGHT: Set to 'true' to skip the preflight LLM check
-
-Outputs to GITHUB_OUTPUT:
-- models_json: JSON array of full model configs with display names
-"""
-
-import json
-import os
-import sys
-from typing import Any
-
-
-# SDK-specific parameters that should not be passed to litellm.
-# These parameters are used by the SDK's LLM wrapper but are not part of litellm's API.
-# Keep this list in sync with SDK LLM config parameters that are SDK-internal.
-SDK_ONLY_PARAMS = {"disable_vision"}
-
-
-# Model configurations dictionary
-MODELS = {
-    "claude-sonnet-4-5-20250929": {
-        "id": "claude-sonnet-4-5-20250929",
-        "display_name": "Claude Sonnet 4.5",
-        "llm_config": {
-            "model": "litellm_proxy/claude-sonnet-4-5-20250929",
-            "temperature": 0.0,
-        },
-    },
-    "kimi-k2-thinking": {
-        "id": "kimi-k2-thinking",
-        "display_name": "Kimi K2 Thinking",
-        "llm_config": {
-            "model": "litellm_proxy/moonshot/kimi-k2-thinking",
-            "temperature": 1.0,
-        },
-    },
-    # https://www.kimi.com/blog/kimi-k2-5.html
-    "kimi-k2.5": {
-        "id": "kimi-k2.5",
-        "display_name": "Kimi K2.5",
-        "llm_config": {
-            "model": "litellm_proxy/moonshot/kimi-k2.5",
-            "temperature": 1.0,
-            "top_p": 0.95,
-        },
-    },
-    # https://www.alibabacloud.com/help/en/model-studio/deep-thinking
-    "qwen3-max-thinking": {
-        "id": "qwen3-max-thinking",
-        "display_name": "Qwen3 Max Thinking",
-        "llm_config": {
-            "model": "litellm_proxy/dashscope/qwen3-max-2026-01-23",
-            "litellm_extra_body": {"enable_thinking": True},
-        },
-    },
-    "qwen3.5-flash": {
-        "id": "qwen3.5-flash",
-        "display_name": "Qwen3.5 Flash",
-        "llm_config": {
-            "model": "litellm_proxy/dashscope/qwen3.5-flash-2026-02-23",
-            "temperature": 0.0,
-        },
-    },
-    "claude-4.5-opus": {
-        "id": "claude-4.5-opus",
-        "display_name": "Claude 4.5 Opus",
-        "llm_config": {
-            "model": "litellm_proxy/anthropic/claude-opus-4-5-20251101",
-            "temperature": 0.0,
-        },
-    },
-    "claude-4.6-opus": {
-        "id": "claude-4.6-opus",
-        "display_name": "Claude 4.6 Opus",
-        "llm_config": {
-            "model": "litellm_proxy/anthropic/claude-opus-4-6",
-            "temperature": 0.0,
-        },
-    },
-    "claude-sonnet-4-6": {
-        "id": "claude-sonnet-4-6",
-        "display_name": "Claude Sonnet 4.6",
-        "llm_config": {
-            "model": "litellm_proxy/anthropic/claude-sonnet-4-6",
-            "temperature": 0.0,
-        },
-    },
-    "gemini-3-pro": {
-        "id": "gemini-3-pro",
-        "display_name": "Gemini 3 Pro",
-        "llm_config": {
-            "model": "litellm_proxy/gemini-3-pro-preview",
-            "temperature": 0.0,
-        },
-    },
-    "gemini-3-flash": {
-        "id": "gemini-3-flash",
-        "display_name": "Gemini 3 Flash",
-        "llm_config": {
-            "model": "litellm_proxy/gemini-3-flash-preview",
-            "temperature": 0.0,
-        },
-    },
-    "gemini-3.1-pro": {
-        "id": "gemini-3.1-pro",
-        "display_name": "Gemini 3.1 Pro",
-        "llm_config": {
-            "model": "litellm_proxy/gemini-3.1-pro-preview",
-            "temperature": 0.0,
-        },
-    },
-    "gpt-5.2": {
-        "id": "gpt-5.2",
-        "display_name": "GPT-5.2",
-        "llm_config": {"model": "litellm_proxy/openai/gpt-5.2-2025-12-11"},
-    },
-    "gpt-5.2-codex": {
-        "id": "gpt-5.2-codex",
-        "display_name": "GPT-5.2 Codex",
-        "llm_config": {"model": "litellm_proxy/gpt-5.2-codex"},
-    },
-    "gpt-5-3-codex": {
-        "id": "gpt-5-3-codex",
-        "display_name": "GPT-5.3 Codex",
-        "llm_config": {"model": "litellm_proxy/gpt-5-3-codex"},
-    },
-    "gpt-5.2-high-reasoning": {
-        "id": "gpt-5.2-high-reasoning",
-        "display_name": "GPT-5.2 High Reasoning",
-        "llm_config": {
-            "model": "litellm_proxy/openai/gpt-5.2-2025-12-11",
-            "reasoning_effort": "high",
-        },
-    },
-    "gpt-5.4": {
-        "id": "gpt-5.4",
-        "display_name": "GPT-5.4",
-        "llm_config": {
-            "model": "litellm_proxy/openai/gpt-5.4",
-            "reasoning_effort": "high",
-        },
-    },
-    "minimax-m2": {
-        "id": "minimax-m2",
-        "display_name": "MiniMax M2",
-        "llm_config": {
-            "model": "litellm_proxy/minimax/minimax-m2",
-            "temperature": 0.0,
-        },
-    },
-    "minimax-m2.5": {
-        "id": "minimax-m2.5",
-        "display_name": "MiniMax M2.5",
-        "llm_config": {
-            "model": "litellm_proxy/minimax/MiniMax-M2.5",
-            "temperature": 1.0,
-            "top_p": 0.95,
-        },
-    },
-    "minimax-m2.1": {
-        "id": "minimax-m2.1",
-        "display_name": "MiniMax M2.1",
-        "llm_config": {
-            "model": "litellm_proxy/minimax/MiniMax-M2.1",
-            "temperature": 0.0,
-        },
-    },
-    "minimax-m2.7": {
-        "id": "minimax-m2.7",
-        "display_name": "MiniMax M2.7",
-        "llm_config": {
-            "model": "litellm_proxy/minimax/MiniMax-M2.7",
-            "temperature": 1.0,
-            "top_p": 0.95,
-        },
-    },
-    "deepseek-v3.2-reasoner": {
-        "id": "deepseek-v3.2-reasoner",
-        "display_name": "DeepSeek V3.2 Reasoner",
-        "llm_config": {"model": "litellm_proxy/deepseek/deepseek-reasoner"},
-    },
-    "qwen-3-coder": {
-        "id": "qwen-3-coder",
-        "display_name": "Qwen 3 Coder",
-        "llm_config": {
-            "model": "litellm_proxy/fireworks_ai/qwen3-coder-480b-a35b-instruct",
-            "temperature": 0.0,
-        },
-    },
-    "nemotron-3-nano-30b": {
-        "id": "nemotron-3-nano-30b",
-        "display_name": "NVIDIA Nemotron 3 Nano 30B",
-        "llm_config": {
-            "model": "litellm_proxy/openai/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8",
-            "temperature": 0.0,
-        },
-    },
-    "glm-4.7": {
-        "id": "glm-4.7",
-        "display_name": "GLM-4.7",
-        "llm_config": {
-            "model": "litellm_proxy/openrouter/z-ai/glm-4.7",
-            "temperature": 0.0,
-            # OpenRouter glm-4.7 is text-only despite LiteLLM reporting vision support
-            "disable_vision": True,
-        },
-    },
-    "glm-5": {
-        "id": "glm-5",
-        "display_name": "GLM-5",
-        "llm_config": {
-            "model": "litellm_proxy/openrouter/z-ai/glm-5",
-            "temperature": 0.0,
-            # OpenRouter glm-5 is text-only despite LiteLLM reporting vision support
-            "disable_vision": True,
-        },
-    },
-    "qwen3-coder-next": {
-        "id": "qwen3-coder-next",
-        "display_name": "Qwen3 Coder Next",
-        "llm_config": {
-            "model": "litellm_proxy/openrouter/qwen/qwen3-coder-next",
-            "temperature": 0.0,
-        },
-    },
-    "qwen3-coder-30b-a3b-instruct": {
-        "id": "qwen3-coder-30b-a3b-instruct",
-        "display_name": "Qwen3 Coder 30B A3B Instruct",
-        "llm_config": {
-            "model": "litellm_proxy/Qwen3-Coder-30B-A3B-Instruct",
-            "temperature": 0.0,
-        },
-    },
-    "gpt-oss-20b": {
-        "id": "gpt-oss-20b",
-        "display_name": "GPT OSS 20B",
-        "llm_config": {
-            "model": "litellm_proxy/gpt-oss-20b",
-            "temperature": 0.0,
-        },
-    },
-    "nemotron-3-super-120b-a12b": {
-        "id": "nemotron-3-super-120b-a12b",
-        "display_name": "NVIDIA Nemotron-3 Super 120B",
-        "llm_config": {
-            "model": "litellm_proxy/nvidia/nemotron-3-super-120b-a12b",
-            "temperature": 0.0,
-        },
-    },
-}
-
-
-def error_exit(msg: str, exit_code: int = 1) -> None:
-    """Print error message and exit."""
-    print(f"ERROR: {msg}", file=sys.stderr)
-    sys.exit(exit_code)
-
-
-def get_required_env(key: str) -> str:
-    """Get required environment variable or exit with error."""
-    value = os.environ.get(key)
-    if not value:
-        error_exit(f"{key} not set")
-    return value
-
-
-def find_models_by_id(model_ids: list[str]) -> list[dict]:
-    """Find models by ID. Fails fast on missing ID.
-
-    Args:
-        model_ids: List of model IDs to find
-
-    Returns:
-        List of model dictionaries matching the IDs
-
-    Raises:
-        SystemExit: If any model ID is not found
-    """
-    resolved = []
-    for model_id in model_ids:
-        if model_id not in MODELS:
-            available = ", ".join(sorted(MODELS.keys()))
-            error_exit(
-                f"Model ID '{model_id}' not found. Available models: {available}"
-            )
-        resolved.append(MODELS[model_id])
-    return resolved
-
-
-def check_model(
-    model_config: dict[str, Any],
-    api_key: str,
-    base_url: str,
-    timeout: int = 60,
-) -> tuple[bool, str]:
-    """Check a single model with a simple completion request using litellm.
-
-    Args:
-        model_config: Model configuration dict with 'llm_config' key
-        api_key: API key for authentication
-        base_url: Base URL for the LLM proxy
-        timeout: Request timeout in seconds
-
-    Returns:
-        Tuple of (success: bool, message: str)
-    """
-    import litellm
-
-    llm_config = model_config.get("llm_config", {})
-    model_name = llm_config.get("model", "unknown")
-    display_name = model_config.get("display_name", model_name)
-
-    try:
-        # Build kwargs from llm_config, excluding 'model' and SDK-specific params
-        kwargs = {
-            k: v
-            for k, v in llm_config.items()
-            if k != "model" and k not in SDK_ONLY_PARAMS
-        }
-
-        # Use simple arithmetic prompt that works reliably across all models
-        # max_tokens=100 provides enough room for models to respond
-        # (some need >10 tokens)
-        response = litellm.completion(
-            model=model_name,
-            messages=[{"role": "user", "content": "1+1="}],
-            max_tokens=100,
-            api_key=api_key,
-            base_url=base_url,
-            timeout=timeout,
-            **kwargs,
-        )
-
-        response_content = (
-            response.choices[0].message.content if response.choices else None
-        )
-        reasoning_content = (
-            getattr(response.choices[0].message, "reasoning_content", None)
-            if response.choices
-            else None
-        )
-
-        if response_content or reasoning_content:
-            return True, f"✓ {display_name}: OK"
-        else:
-            # Check if there's any other data in the response for diagnostics
-            finish_reason = (
-                response.choices[0].finish_reason if response.choices else None
-            )
-            usage = getattr(response, "usage", None)
-            return (
-                False,
-                (
-                    f"✗ {display_name}: Empty response "
-                    f"(finish_reason={finish_reason}, usage={usage})"
-                ),
-            )
-
-    except litellm.exceptions.Timeout:
-        return False, f"✗ {display_name}: Request timed out after {timeout}s"
-    except litellm.exceptions.APIConnectionError as e:
-        return False, f"✗ {display_name}: Connection error - {e}"
-    except litellm.exceptions.BadRequestError as e:
-        return False, f"✗ {display_name}: Bad request - {e}"
-    except litellm.exceptions.NotFoundError as e:
-        return False, f"✗ {display_name}: Model not found - {e}"
-    except Exception as e:
-        return False, f"✗ {display_name}: {type(e).__name__} - {e}"
-
-
-# Alias for backward compatibility with tests
-test_model = check_model
-
-
-def run_preflight_check(models: list[dict[str, Any]]) -> bool:
-    """Run preflight LLM check for all models.
-
-    Args:
-        models: List of model configurations to test
-
-    Returns:
-        True if all models passed, False otherwise
-    """
-    api_key = os.environ.get("LLM_API_KEY")
-    base_url = os.environ.get("LLM_BASE_URL", "https://llm-proxy.eval.all-hands.dev")
-    skip_preflight = os.environ.get("SKIP_PREFLIGHT", "").lower() == "true"
-
-    if skip_preflight:
-        print("Preflight check: SKIPPED (SKIP_PREFLIGHT=true)")
-        return True
-
-    if not api_key:
-        print("Preflight check: SKIPPED (LLM_API_KEY not set)")
-        return True
-
-    print(f"\nPreflight LLM check for {len(models)} model(s)...")
-    print("-" * 50)
-
-    all_passed = True
-    for model_config in models:
-        success, message = check_model(model_config, api_key, base_url)
-        print(message)
-        if not success:
-            all_passed = False
-
-    print("-" * 50)
-
-    if all_passed:
-        print(f"✓ All {len(models)} model(s) passed preflight check\n")
-    else:
-        print("✗ Some models failed preflight check")
-        print("Evaluation aborted to avoid wasting compute resources.\n")
-
-    return all_passed
-
-
-def main() -> None:
-    model_ids_str = get_required_env("MODEL_IDS")
-    github_output = get_required_env("GITHUB_OUTPUT")
-
-    # Parse requested model IDs
-    model_ids = [mid.strip() for mid in model_ids_str.split(",") if mid.strip()]
-
-    # Resolve model configs
-    resolved = find_models_by_id(model_ids)
-    print(f"Resolved {len(resolved)} model(s): {', '.join(model_ids)}")
-
-    # Run preflight check
-    if not run_preflight_check(resolved):
-        error_exit("Preflight LLM check failed")
-
-    # Output as JSON
-    models_json = json.dumps(resolved, separators=(",", ":"))
-    with open(github_output, "a", encoding="utf-8") as f:
-        f.write(f"models_json={models_json}\n")
-
-
-if __name__ == "__main__":
-    main()

.github/run-eval/validate_sdk_ref.py

@@ -1,89 +0,0 @@
-#!/usr/bin/env python3
-"""
-Validate SDK reference for semantic versioning.
-
-This script validates that the SDK reference is a semantic version (e.g., v1.0.0, 1.0.0)
-unless the allow_unreleased_branches flag is set.
-
-Environment variables:
-- SDK_REF: The SDK reference to validate
-- ALLOW_UNRELEASED_BRANCHES: If 'true', bypass semantic version validation
-
-Exit codes:
-- 0: Validation passed
-- 1: Validation failed
-"""
-
-import os
-import re
-import sys
-
-
-# Semantic version pattern: optional 'v' prefix, followed by MAJOR.MINOR.PATCH
-# Optionally allows pre-release (-alpha.1, -beta.2, -rc.1) and build metadata
-SEMVER_PATTERN = re.compile(
-    r"^v?"  # Optional 'v' prefix
-    r"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"  # MAJOR.MINOR.PATCH
-    r"(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)"  # Pre-release
-    r"(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?"  # More pre-release
-    r"(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"  # Build metadata
-)
-
-
-def is_semantic_version(ref: str) -> bool:
-    """Check if the given reference is a valid semantic version.
-
-    Args:
-        ref: The reference string to validate
-
-    Returns:
-        True if the reference is a valid semantic version, False otherwise
-    """
-    return bool(SEMVER_PATTERN.match(ref))
-
-
-def validate_sdk_ref(sdk_ref: str, allow_unreleased: bool) -> tuple[bool, str]:
-    """Validate the SDK reference.
-
-    Args:
-        sdk_ref: The SDK reference to validate
-        allow_unreleased: If True, bypass semantic version validation
-
-    Returns:
-        Tuple of (is_valid, message)
-    """
-    if allow_unreleased:
-        return True, f"Allowing unreleased branch: {sdk_ref}"
-
-    if is_semantic_version(sdk_ref):
-        return True, f"Valid semantic version: {sdk_ref}"
-
-    return False, (
-        f"SDK reference '{sdk_ref}' is not a valid semantic version. "
-        "Expected format: v1.0.0 or 1.0.0 (with optional pre-release like -alpha.1). "
-        "To use unreleased branches, check 'Allow unreleased branches'."
-    )
-
-
-def main() -> None:
-    sdk_ref = os.environ.get("SDK_REF", "")
-    allow_unreleased_str = os.environ.get("ALLOW_UNRELEASED_BRANCHES", "false")
-
-    if not sdk_ref:
-        print("ERROR: SDK_REF environment variable is not set", file=sys.stderr)
-        sys.exit(1)
-
-    allow_unreleased = allow_unreleased_str.lower() == "true"
-
-    is_valid, message = validate_sdk_ref(sdk_ref, allow_unreleased)
-
-    if is_valid:
-        print(f"✓ {message}")
-        sys.exit(0)
-    else:
-        print(f"✗ {message}", file=sys.stderr)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

.github/scripts/check_agent_server_rest_api_breakage.py

@@ -1,611 +0,0 @@
-#!/usr/bin/env python3
-"""REST API breakage detection for openhands-agent-server using oasdiff.
-
-This script compares the current OpenAPI schema for the agent-server REST API against
-an already-published release. The baseline version is selected from PyPI, but the
-baseline schema is generated from the matching git tag under the current workspace's
-locked dependency set. This keeps the comparison focused on API changes in our code,
-not schema drift from newer FastAPI/Pydantic releases.
-
-The deprecation note it recognizes intentionally matches the phrasing used by the
-Python deprecation checks, for example:
-
-    Deprecated since v1.14.0 and scheduled for removal in v1.19.0.
-
-Policies enforced:
-
-1) REST deprecations must use FastAPI/OpenAPI metadata
-   - FastAPI route handlers must not use `openhands.sdk.utils.deprecation.deprecated`.
-   - Endpoints documented as deprecated in their OpenAPI description must also be
-     marked `deprecated: true` in the generated schema.
-
-2) Deprecation runway before removal
-   - If a REST operation (path + HTTP method) is removed, it must have been marked
-     `deprecated: true` in the baseline release and its OpenAPI description must
-     declare a scheduled removal version that has been reached by the current
-     package version.
-
-3) No in-place contract breakage
-   - Breaking REST contract changes that are not removals of previously-deprecated
-     operations fail the check. REST clients need 5 minor releases of runway, so
-     incompatible replacements must ship additively or behind a versioned contract
-     until the scheduled removal version.
-
-If the baseline release schema can't be generated (e.g., missing tag / repo issues),
-the script emits a warning and exits successfully to avoid flaky CI.
-"""
-
-from __future__ import annotations
-
-import ast
-import json
-import re
-import subprocess
-import sys
-import tempfile
-import tomllib
-import urllib.request
-from pathlib import Path
-
-from packaging import version as pkg_version
-
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-AGENT_SERVER_PYPROJECT = REPO_ROOT / "openhands-agent-server" / "pyproject.toml"
-PYPI_DISTRIBUTION = "openhands-agent-server"
-# Keep this in sync with REST_ROUTE_DEPRECATION_RE in check_deprecations.py so
-# the REST breakage and deprecation checks recognize the same wording.
-REST_ROUTE_DEPRECATION_RE = re.compile(
-    r"Deprecated since v(?P<deprecated>[0-9A-Za-z.+-]+)\s+"
-    r"and scheduled for removal in v(?P<removed>[0-9A-Za-z.+-]+)\.?",
-    re.IGNORECASE,
-)
-HTTP_METHODS = {
-    "get",
-    "put",
-    "post",
-    "delete",
-    "patch",
-    "options",
-    "head",
-    "trace",
-}
-ROUTE_DECORATOR_NAMES = HTTP_METHODS | {"api_route"}
-OPENAPI_PROGRAM = """
-import json
-import sys
-from pathlib import Path
-
-source_tree = Path(sys.argv[1])
-sys.path = [
-    str(source_tree / "openhands-agent-server"),
-    str(source_tree / "openhands-sdk"),
-    str(source_tree / "openhands-tools"),
-    str(source_tree / "openhands-workspace"),
-] + sys.path
-
-from openhands.agent_server.api import create_app
-
-print(json.dumps(create_app().openapi()))
-"""
-
-
-def _read_version_from_pyproject(pyproject: Path) -> str:
-    data = tomllib.loads(pyproject.read_text())
-    try:
-        return str(data["project"]["version"])
-    except KeyError as exc:  # pragma: no cover
-        raise SystemExit(
-            f"Unable to determine project version from {pyproject}"
-        ) from exc
-
-
-def _fetch_pypi_metadata(distribution: str) -> dict:
-    req = urllib.request.Request(
-        url=f"https://pypi.org/pypi/{distribution}/json",
-        headers={"User-Agent": "openhands-agent-server-openapi-check/1.0"},
-        method="GET",
-    )
-    with urllib.request.urlopen(req, timeout=10) as response:
-        return json.load(response)
-
-
-def _get_baseline_version(distribution: str, current: str) -> str | None:
-    try:
-        meta = _fetch_pypi_metadata(distribution)
-    except Exception as exc:  # pragma: no cover
-        print(
-            f"::warning title={distribution} REST API::Failed to fetch PyPI metadata: "
-            f"{exc}"
-        )
-        return None
-
-    releases = list(meta.get("releases", {}).keys())
-    if not releases:
-        return None
-
-    if current in releases:
-        return current
-
-    current_parsed = pkg_version.parse(current)
-    older = [rv for rv in releases if pkg_version.parse(rv) < current_parsed]
-    if not older:
-        return None
-
-    return max(older, key=pkg_version.parse)
-
-
-def _generate_openapi_from_source_tree(source_tree: Path, label: str) -> dict | None:
-    try:
-        result = subprocess.run(
-            [sys.executable, "-c", OPENAPI_PROGRAM, str(source_tree)],
-            check=True,
-            capture_output=True,
-            text=True,
-            cwd=source_tree,
-        )
-        return json.loads(result.stdout)
-    except subprocess.CalledProcessError as exc:
-        output = (exc.stdout or "") + ("\n" + exc.stderr if exc.stderr else "")
-        excerpt = output.strip()[-1000:]
-        print(
-            f"::warning title={PYPI_DISTRIBUTION} REST API::Failed to generate "
-            f"OpenAPI schema for {label}: {exc}\n{excerpt}"
-        )
-        return None
-    except Exception as exc:
-        print(
-            f"::warning title={PYPI_DISTRIBUTION} REST API::Failed to generate "
-            f"OpenAPI schema for {label}: {exc}"
-        )
-        return None
-
-
-def _generate_current_openapi() -> dict | None:
-    return _generate_openapi_from_source_tree(REPO_ROOT, "current workspace")
-
-
-def _generate_openapi_for_git_ref(git_ref: str) -> dict | None:
-    with tempfile.TemporaryDirectory(prefix="agent-server-openapi-") as tmp:
-        source_tree = Path(tmp)
-
-        try:
-            archive = subprocess.run(
-                ["git", "-C", str(REPO_ROOT), "archive", git_ref],
-                check=True,
-                capture_output=True,
-            )
-            subprocess.run(
-                ["tar", "-x", "-C", str(source_tree)],
-                check=True,
-                input=archive.stdout,
-                capture_output=True,
-            )
-        except subprocess.CalledProcessError as exc:
-            output = (exc.stdout or b"") + (b"\n" + exc.stderr if exc.stderr else b"")
-            excerpt = output.decode(errors="replace").strip()[-1000:]
-            print(
-                f"::warning title={PYPI_DISTRIBUTION} REST API::Failed to extract "
-                f"source for {git_ref}: {exc}\n{excerpt}"
-            )
-            return None
-
-        return _generate_openapi_from_source_tree(source_tree, git_ref)
-
-
-def _dotted_name(node: ast.AST) -> str | None:
-    if isinstance(node, ast.Name):
-        return node.id
-    if isinstance(node, ast.Attribute):
-        prefix = _dotted_name(node.value)
-        if prefix is None:
-            return None
-        return f"{prefix}.{node.attr}"
-    return None
-
-
-def _find_sdk_deprecated_fastapi_routes_in_file(
-    file_path: Path, repo_root: Path
-) -> list[str]:
-    tree = ast.parse(file_path.read_text(), filename=str(file_path))
-
-    deprecated_names: set[str] = set()
-    deprecation_module_names: set[str] = set()
-
-    for node in tree.body:
-        if isinstance(node, ast.ImportFrom):
-            if node.module == "openhands.sdk.utils.deprecation":
-                for alias in node.names:
-                    if alias.name == "deprecated":
-                        deprecated_names.add(alias.asname or alias.name)
-            elif node.module == "openhands.sdk.utils":
-                for alias in node.names:
-                    if alias.name == "deprecation":
-                        deprecation_module_names.add(alias.asname or alias.name)
-        elif isinstance(node, ast.Import):
-            for alias in node.names:
-                if alias.name == "openhands.sdk.utils.deprecation":
-                    deprecation_module_names.add(alias.asname or alias.name)
-
-    errors: list[str] = []
-    for node in ast.walk(tree):
-        if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
-            continue
-
-        has_route_decorator = False
-        uses_sdk_deprecated = False
-
-        for decorator in node.decorator_list:
-            if not isinstance(decorator, ast.Call):
-                continue
-
-            dotted_name = _dotted_name(decorator.func)
-            if (
-                isinstance(decorator.func, ast.Attribute)
-                and decorator.func.attr in ROUTE_DECORATOR_NAMES
-            ):
-                has_route_decorator = True
-
-            if dotted_name in deprecated_names or (
-                dotted_name == "openhands.sdk.utils.deprecation.deprecated"
-            ):
-                uses_sdk_deprecated = True
-                continue
-
-            if (
-                isinstance(decorator.func, ast.Attribute)
-                and decorator.func.attr == "deprecated"
-            ):
-                base_name = _dotted_name(decorator.func.value)
-                if base_name in deprecation_module_names or (
-                    base_name == "openhands.sdk.utils.deprecation"
-                ):
-                    uses_sdk_deprecated = True
-
-        if has_route_decorator and uses_sdk_deprecated:
-            rel_path = file_path.relative_to(repo_root)
-            errors.append(
-                f"{rel_path}:{node.lineno} FastAPI route `{node.name}` uses "
-                "openhands.sdk.utils.deprecation.deprecated; use the route "
-                "decorator's deprecated=True flag instead."
-            )
-
-    return errors
-
-
-def _find_sdk_deprecated_fastapi_routes(repo_root: Path) -> list[str]:
-    app_root = repo_root / "openhands-agent-server" / "openhands" / "agent_server"
-    errors: list[str] = []
-
-    for file_path in sorted(app_root.rglob("*.py")):
-        errors.extend(_find_sdk_deprecated_fastapi_routes_in_file(file_path, repo_root))
-
-    return errors
-
-
-def _find_deprecation_policy_errors(schema: dict) -> list[str]:
-    errors: list[str] = []
-
-    for path, path_item in schema.get("paths", {}).items():
-        if not isinstance(path_item, dict):
-            continue
-
-        for method, operation in path_item.items():
-            if method not in HTTP_METHODS or not isinstance(operation, dict):
-                continue
-
-            description = operation.get("description") or ""
-            if "deprecated since" not in description.lower():
-                continue
-
-            if operation.get("deprecated") is True:
-                continue
-
-            errors.append(
-                f"{method.upper()} {path} documents deprecation in its "
-                "description but is not marked deprecated=true in OpenAPI."
-            )
-
-    return errors
-
-
-def _parse_openapi_deprecation_description(
-    description: str | None,
-) -> tuple[str, str] | None:
-    """Extract ``(deprecated_in, removed_in)`` from an OpenAPI description.
-
-    The accepted wording intentionally matches ``check_deprecations.py`` so both
-    CI checks recognize the same note, for example:
-
-        Deprecated since v1.14.0 and scheduled for removal in v1.19.0.
-    """
-    if not description:
-        return None
-
-    match = REST_ROUTE_DEPRECATION_RE.search(" ".join(description.split()))
-    if match is None:
-        return None
-
-    return match.group("deprecated").rstrip("."), match.group("removed").rstrip(".")
-
-
-def _version_ge(current: str, target: str) -> bool:
-    try:
-        return pkg_version.parse(current) >= pkg_version.parse(target)
-    except pkg_version.InvalidVersion as exc:
-        raise SystemExit(
-            f"Invalid semantic version comparison: {current=} {target=}"
-        ) from exc
-
-
-def _get_openapi_operation(schema: dict, path: str, method: str) -> dict | None:
-    path_item = schema.get("paths", {}).get(path)
-    if not isinstance(path_item, dict):
-        return None
-
-    operation = path_item.get(method.lower())
-    if not isinstance(operation, dict):
-        return None
-
-    return operation
-
-
-def _validate_removed_operations(
-    removed_operations: list[dict],
-    prev_schema: dict,
-    current_version: str,
-) -> list[str]:
-    """Validate removed operations against the baseline deprecation metadata."""
-    errors: list[str] = []
-
-    for operation in removed_operations:
-        path = str(operation.get("path", ""))
-        method = str(operation.get("method", "")).lower()
-        method_label = method.upper() or "<unknown method>"
-
-        if not operation.get("deprecated", False):
-            errors.append(
-                f"Removed {method_label} {path} without prior deprecation "
-                "(deprecated=true)."
-            )
-            continue
-
-        baseline_operation = _get_openapi_operation(prev_schema, path, method)
-        if baseline_operation is None:
-            errors.append(
-                f"Removed {method_label} {path} was marked deprecated in the "
-                "baseline release, but the previous OpenAPI schema could not be "
-                "inspected for its scheduled removal version."
-            )
-            continue
-
-        deprecation_details = _parse_openapi_deprecation_description(
-            baseline_operation.get("description")
-        )
-        if deprecation_details is None:
-            errors.append(
-                f"Removed {method_label} {path} was marked deprecated in the "
-                "baseline release, but its OpenAPI description does not declare "
-                "a scheduled removal version. REST API removals require 5 minor "
-                "releases of deprecation runway."
-            )
-            continue
-
-        _, removed_in = deprecation_details
-        if not _version_ge(current_version, removed_in):
-            errors.append(
-                f"Removed {method_label} {path} before its scheduled removal "
-                f"version v{removed_in} (current version: v{current_version}). "
-                "REST API removals require 5 minor releases of deprecation "
-                "runway."
-            )
-            continue
-
-        print(
-            f"::notice title={PYPI_DISTRIBUTION} REST API::Removed previously-"
-            f"deprecated {method_label} {path} after its scheduled removal "
-            f"version v{removed_in}."
-        )
-
-    return errors
-
-
-def _split_breaking_changes(
-    breaking_changes: list[dict],
-) -> tuple[list[dict], list[dict]]:
-    """Split oasdiff results into removals and all other breakages."""
-    removed_operations: list[dict] = []
-    other_breaking_changes: list[dict] = []
-
-    for change in breaking_changes:
-        change_id = str(change.get("id", ""))
-        details = change.get("details", {})
-
-        if "removed" in change_id.lower() and "operation" in change_id.lower():
-            removed_operations.append(
-                {
-                    "path": details.get("path", ""),
-                    "method": details.get("method", ""),
-                    "deprecated": details.get("deprecated", False),
-                }
-            )
-            continue
-
-        other_breaking_changes.append(change)
-
-    return removed_operations, other_breaking_changes
-
-
-def _normalize_openapi_for_oasdiff(schema: dict) -> dict:
-    """Normalize OpenAPI 3.1 schema for oasdiff compatibility.
-
-    oasdiff expects OpenAPI 3.0-style exclusiveMinimum/exclusiveMaximum booleans
-    (https://spec.openapis.org/oas/v3.0.3.html#schema-object), while OpenAPI 3.1
-    emits numeric values. Convert numeric exclusives into minimum/maximum +
-    exclusive boolean flags so oasdiff can parse the schema.
-
-    Mutates the schema in place and returns it for convenience.
-    """
-
-    def _walk(node: object) -> None:
-        if isinstance(node, dict):
-            if (
-                "exclusiveMinimum" in node
-                and isinstance(node["exclusiveMinimum"], (int, float))
-                and not isinstance(node["exclusiveMinimum"], bool)
-            ):
-                value = node["exclusiveMinimum"]
-                if "minimum" not in node:
-                    node["minimum"] = value
-                node["exclusiveMinimum"] = True
-            if (
-                "exclusiveMaximum" in node
-                and isinstance(node["exclusiveMaximum"], (int, float))
-                and not isinstance(node["exclusiveMaximum"], bool)
-            ):
-                value = node["exclusiveMaximum"]
-                if "maximum" not in node:
-                    node["maximum"] = value
-                node["exclusiveMaximum"] = True
-
-            for child in node.values():
-                _walk(child)
-        elif isinstance(node, list):
-            for child in node:
-                _walk(child)
-
-    _walk(schema)
-    return schema
-
-
-def _run_oasdiff_breakage_check(
-    prev_spec: Path, cur_spec: Path
-) -> tuple[list[dict], int]:
-    """Run oasdiff breaking check between two OpenAPI specs.
-
-    Returns (list of breaking changes, exit code from oasdiff).
-    """
-    try:
-        result = subprocess.run(
-            [
-                "oasdiff",
-                "breaking",
-                "-f",
-                "json",
-                "--fail-on",
-                "ERR",
-                str(prev_spec),
-                str(cur_spec),
-            ],
-            capture_output=True,
-            text=True,
-        )
-    except FileNotFoundError:
-        print(
-            "::warning title=oasdiff not found::"
-            "Please install oasdiff: https://github.com/oasdiff/oasdiff"
-        )
-        return [], 0
-
-    breaking_changes = []
-    if result.stdout:
-        try:
-            breaking_changes = json.loads(result.stdout)
-        except json.JSONDecodeError:
-            pass
-
-    return breaking_changes, result.returncode
-
-
-def main() -> int:
-    current_version = _read_version_from_pyproject(AGENT_SERVER_PYPROJECT)
-    baseline_version = _get_baseline_version(PYPI_DISTRIBUTION, current_version)
-
-    if baseline_version is None:
-        print(
-            f"::warning title={PYPI_DISTRIBUTION} REST API::Unable to find baseline "
-            f"version for {current_version}; skipping breakage checks."
-        )
-        return 0
-
-    baseline_git_ref = f"v{baseline_version}"
-
-    static_policy_errors = _find_sdk_deprecated_fastapi_routes(REPO_ROOT)
-    for error in static_policy_errors:
-        print(f"::error title={PYPI_DISTRIBUTION} REST API::{error}")
-
-    current_schema = _generate_current_openapi()
-    if current_schema is None:
-        return 1
-
-    deprecation_policy_errors = _find_deprecation_policy_errors(current_schema)
-    for error in deprecation_policy_errors:
-        print(f"::error title={PYPI_DISTRIBUTION} REST API::{error}")
-
-    prev_schema = _generate_openapi_for_git_ref(baseline_git_ref)
-    if prev_schema is None:
-        return 0 if not (static_policy_errors or deprecation_policy_errors) else 1
-
-    prev_schema = _normalize_openapi_for_oasdiff(prev_schema)
-    current_schema = _normalize_openapi_for_oasdiff(current_schema)
-
-    with tempfile.TemporaryDirectory(prefix="oasdiff-specs-") as tmp:
-        tmp_path = Path(tmp)
-        prev_spec_file = tmp_path / "prev_spec.json"
-        cur_spec_file = tmp_path / "cur_spec.json"
-
-        prev_spec_file.write_text(json.dumps(prev_schema, indent=2))
-        cur_spec_file.write_text(json.dumps(current_schema, indent=2))
-
-        breaking_changes, exit_code = _run_oasdiff_breakage_check(
-            prev_spec_file, cur_spec_file
-        )
-
-    if not breaking_changes:
-        if exit_code == 0:
-            print("No breaking changes detected.")
-        else:
-            print(
-                f"oasdiff returned exit code {exit_code} but no breaking changes "
-                "in JSON format. There may be warnings only."
-            )
-    else:
-        removed_operations, other_breaking_changes = _split_breaking_changes(
-            breaking_changes
-        )
-        removal_errors = _validate_removed_operations(
-            removed_operations,
-            prev_schema,
-            current_version,
-        )
-
-        for error in removal_errors:
-            print(f"::error title={PYPI_DISTRIBUTION} REST API::{error}")
-
-        if other_breaking_changes:
-            print(
-                "::error "
-                f"title={PYPI_DISTRIBUTION} REST API::Detected breaking REST API "
-                "changes other than removing previously-deprecated operations. "
-                "REST contract changes must preserve compatibility for 5 minor "
-                "releases; keep the old contract available until its scheduled "
-                "removal version."
-            )
-
-        print("\nBreaking REST API changes detected compared to baseline release:")
-        for text in breaking_changes:
-            print(f"- {text.get('text', str(text))}")
-
-        if not (removal_errors or other_breaking_changes):
-            print(
-                "Breaking changes are limited to previously-deprecated operations "
-                "whose scheduled removal versions have been reached."
-            )
-        else:
-            return 1
-
-    return 1 if (static_policy_errors or deprecation_policy_errors) else 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

.github/scripts/check_deprecations.py

@@ -1,592 +0,0 @@
-#!/usr/bin/env python3
-"""Static analysis for deprecation deadlines.
-
-This script scans Python deprecation metadata (`deprecated`, `warn_deprecated`,
-`warn_cleanup`) and agent-server REST routes marked `deprecated=True`. If the
-current project version has reached or passed a feature's removal marker, the
-script fails with a helpful summary so legacy shims and overdue deprecated REST
-endpoints are cleaned up before release.
-"""
-
-from __future__ import annotations
-
-import ast
-import re
-import sys
-import tomllib
-from collections.abc import Iterable, Iterator, Sequence
-from dataclasses import dataclass
-from datetime import date
-from pathlib import Path
-from typing import Literal
-
-from packaging import version as pkg_version
-
-
-REST_ROUTE_DEPRECATION_RE = re.compile(
-    r"Deprecated since v(?P<deprecated>[0-9A-Za-z.+-]+)\s+"
-    r"and scheduled for removal in v(?P<removed>[0-9A-Za-z.+-]+)\.?",
-    re.IGNORECASE,
-)
-ROUTE_DECORATOR_NAMES = {
-    "get",
-    "put",
-    "post",
-    "delete",
-    "patch",
-    "options",
-    "head",
-    "trace",
-    "api_route",
-}
-HTTP_METHODS = ROUTE_DECORATOR_NAMES - {"api_route"}
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-
-
-@dataclass(frozen=True, slots=True)
-class PackageConfig:
-    name: str
-    pyproject: Path
-    source_roots: tuple[Path, ...]
-
-
-PACKAGES: tuple[PackageConfig, ...] = (
-    PackageConfig(
-        name="openhands-sdk",
-        pyproject=REPO_ROOT / "openhands-sdk" / "pyproject.toml",
-        source_roots=(REPO_ROOT / "openhands-sdk" / "openhands" / "sdk",),
-    ),
-    PackageConfig(
-        name="openhands-tools",
-        pyproject=REPO_ROOT / "openhands-tools" / "pyproject.toml",
-        source_roots=(REPO_ROOT / "openhands-tools" / "openhands" / "tools",),
-    ),
-    PackageConfig(
-        name="openhands-workspace",
-        pyproject=REPO_ROOT / "openhands-workspace" / "pyproject.toml",
-        source_roots=(REPO_ROOT / "openhands-workspace" / "openhands" / "workspace",),
-    ),
-    PackageConfig(
-        name="openhands-agent-server",
-        pyproject=REPO_ROOT / "openhands-agent-server" / "pyproject.toml",
-        source_roots=(
-            REPO_ROOT / "openhands-agent-server" / "openhands" / "agent_server",
-        ),
-    ),
-)
-
-
-@dataclass(slots=True)
-class DeprecationRecord:
-    identifier: str
-    removed_in: str | date | None
-    deprecated_in: str | None
-    path: Path
-    line: int
-    kind: Literal["decorator", "warn_call", "cleanup_call", "rest_route"]
-    package: str
-
-
-def _load_current_version(pyproject: Path) -> str:
-    data = tomllib.loads(pyproject.read_text())
-    try:
-        return str(data["project"]["version"])
-    except KeyError as exc:  # pragma: no cover - configuration error
-        raise SystemExit(
-            f"Unable to determine project version from {pyproject}"
-        ) from exc
-
-
-def _iter_python_files(root: Path) -> Iterator[Path]:
-    for path in root.rglob("*.py"):
-        if path.name == "__init__.py" and path.parent == root:
-            continue
-        yield path
-
-
-def _parse_removed_value(
-    node: ast.AST | None,
-    *,
-    path: Path,
-    line: int,
-) -> str | date | None:
-    if node is None:
-        return None
-
-    expression = ast.unparse(node)
-
-    if isinstance(node, ast.Constant):
-        if isinstance(node.value, str):
-            return node.value
-        if node.value is None:
-            return None
-        raise SystemExit(
-            f"Unsupported removed_in literal at {path}:{line}: {expression}"
-        )
-
-    if isinstance(node, ast.Call):
-        func = node.func
-        if isinstance(func, ast.Name) and func.id == "date":
-            try:
-                args = [_safe_int_literal(arg) for arg in node.args]
-                kwargs = {
-                    kw.arg: _safe_int_literal(kw.value)
-                    for kw in node.keywords
-                    if kw.arg is not None
-                }
-            except ValueError as exc:
-                raise SystemExit(
-                    f"Unsupported removed_in date() arguments at {path}:{line}:"
-                    f" {expression}"
-                ) from exc
-
-            if any(kw.arg is None for kw in node.keywords):
-                raise SystemExit(
-                    "Unsupported removed_in date() call (uses **kwargs) at "
-                    f"{path}:{line}: {expression}"
-                )
-
-            try:
-                return date(*args, **kwargs)
-            except TypeError as exc:
-                raise SystemExit(
-                    f"Invalid removed_in date() call at {path}:{line}: {expression}"
-                ) from exc
-
-        if (
-            isinstance(func, ast.Attribute)
-            and isinstance(func.value, ast.Name)
-            and func.value.id == "date"
-            and func.attr == "today"
-        ):
-            if node.args or node.keywords:
-                raise SystemExit(
-                    "date.today() removed_in call must not include arguments at "
-                    f"{path}:{line}: {expression}"
-                )
-            return date.today()
-
-    raise SystemExit(
-        f"Unsupported removed_in expression at {path}:{line}: {expression}"
-    )
-
-
-def _parse_deprecated_value(
-    node: ast.AST | None,
-    *,
-    path: Path,
-    line: int,
-) -> str | None:
-    if node is None:
-        return None
-
-    expression = ast.unparse(node)
-
-    if isinstance(node, ast.Constant):
-        if isinstance(node.value, str):
-            return node.value
-        if node.value is None:
-            return None
-
-    raise SystemExit(
-        f"Unsupported deprecated_in expression at {path}:{line}: {expression}"
-    )
-
-
-def _safe_int_literal(node: ast.AST) -> int:
-    if not isinstance(node, ast.Constant) or not isinstance(node.value, int):
-        raise ValueError(
-            f"Unsupported expression inside literal evaluation: {ast.unparse(node)}"
-        )
-    return node.value
-
-
-def _extract_kw(call: ast.Call, name: str) -> ast.AST | None:
-    for kw in call.keywords:
-        if kw.arg == name:
-            return kw.value
-    return None
-
-
-def _extract_string_literal(node: ast.AST | None) -> str | None:
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        return node.value
-    return None
-
-
-def _extract_string_sequence(node: ast.AST | None) -> tuple[str, ...] | None:
-    if not isinstance(node, (ast.List, ast.Tuple, ast.Set)):
-        return None
-
-    values: list[str] = []
-    for item in node.elts:
-        value = _extract_string_literal(item)
-        if value is None:
-            return None
-        values.append(value)
-    return tuple(values)
-
-
-def _extract_route_details(call: ast.Call) -> tuple[tuple[str, str], ...]:
-    target = call.func
-    if not isinstance(target, ast.Attribute):
-        return ()
-
-    decorator_name = target.attr
-    if decorator_name not in ROUTE_DECORATOR_NAMES:
-        return ()
-
-    path = _extract_string_literal(call.args[0] if call.args else None)
-    if path is None:
-        path = _extract_string_literal(_extract_kw(call, "path"))
-    if path is None:
-        return ()
-
-    if decorator_name in HTTP_METHODS:
-        return ((decorator_name.upper(), path),)
-
-    methods = _extract_string_sequence(_extract_kw(call, "methods"))
-    if methods is None:
-        return (("GET", path),)
-
-    return tuple(
-        (method.upper(), path) for method in methods if method.lower() in HTTP_METHODS
-    )
-
-
-def _parse_rest_route_deprecation_docstring(
-    docstring: str | None,
-    *,
-    path: Path,
-    line: int,
-    route_identifiers: Sequence[str],
-) -> tuple[str, str]:
-    if not docstring:
-        raise SystemExit(
-            "Deprecated REST route(s) "
-            f"{', '.join(route_identifiers)} at {path}:{line} must include a "
-            "docstring note like 'Deprecated since vX.Y.Z and scheduled for "
-            "removal in vA.B.C.'"
-        )
-
-    match = REST_ROUTE_DEPRECATION_RE.search(" ".join(docstring.split()))
-    if match is None:
-        raise SystemExit(
-            "Deprecated REST route(s) "
-            f"{', '.join(route_identifiers)} at {path}:{line} must include a "
-            "docstring note like 'Deprecated since vX.Y.Z and scheduled for "
-            "removal in vA.B.C.'"
-        )
-
-    return match.group("deprecated").rstrip("."), match.group("removed").rstrip(".")
-
-
-def _gather_rest_route_deprecations(
-    tree: ast.AST, path: Path, *, package: str
-) -> Iterator[DeprecationRecord]:
-    for node in ast.walk(tree):
-        if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
-            continue
-
-        routes: list[tuple[str, str]] = []
-        for deco in node.decorator_list:
-            if not isinstance(deco, ast.Call):
-                continue
-            deprecated_value = _extract_kw(deco, "deprecated")
-            if (
-                not isinstance(deprecated_value, ast.Constant)
-                or deprecated_value.value is not True
-            ):
-                continue
-            routes.extend(_extract_route_details(deco))
-
-        if not routes:
-            continue
-
-        deprecated_in, removed_in = _parse_rest_route_deprecation_docstring(
-            ast.get_docstring(node),
-            path=path,
-            line=node.lineno,
-            route_identifiers=[
-                f"{method} {route_path}" for method, route_path in routes
-            ],
-        )
-
-        for method, route_path in routes:
-            yield DeprecationRecord(
-                identifier=f"{method} {route_path}",
-                removed_in=removed_in,
-                deprecated_in=deprecated_in,
-                path=path,
-                line=node.lineno,
-                kind="rest_route",
-                package=package,
-            )
-
-
-def _gather_decorators(
-    tree: ast.AST, path: Path, *, package: str
-) -> Iterator[DeprecationRecord]:
-    for node in ast.walk(tree):
-        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
-            continue
-
-        for deco in node.decorator_list:
-            call = deco if isinstance(deco, ast.Call) else None
-            if call is None:
-                continue
-
-            target = call.func
-            if isinstance(target, ast.Name):
-                decorator_name = target.id
-            elif isinstance(target, ast.Attribute):
-                decorator_name = target.attr
-            else:
-                continue
-
-            if decorator_name != "deprecated":
-                continue
-
-            removed_expr = _extract_kw(call, "removed_in")
-            deprecated_expr = _extract_kw(call, "deprecated_in")
-
-            record = DeprecationRecord(
-                identifier=_build_identifier(node),
-                removed_in=_parse_removed_value(
-                    removed_expr, path=path, line=node.lineno
-                ),
-                deprecated_in=_parse_deprecated_value(
-                    deprecated_expr, path=path, line=node.lineno
-                ),
-                path=path,
-                line=node.lineno,
-                kind="decorator",
-                package=package,
-            )
-            yield record
-
-
-def _gather_warn_calls(
-    tree: ast.AST, path: Path, *, package: str
-) -> Iterator[DeprecationRecord]:
-    for node in ast.walk(tree):
-        if not isinstance(node, ast.Call):
-            continue
-
-        target = node.func
-        if isinstance(target, ast.Name):
-            func_name = target.id
-        elif isinstance(target, ast.Attribute):
-            func_name = target.attr
-        else:
-            continue
-
-        if func_name == "warn_deprecated":
-            identifier_node = node.args[0] if node.args else None
-            if identifier_node is None:
-                continue
-            identifier = ast.unparse(identifier_node)
-
-            removed_expr = _extract_kw(node, "removed_in")
-            deprecated_expr = _extract_kw(node, "deprecated_in")
-
-            yield DeprecationRecord(
-                identifier=identifier,
-                removed_in=_parse_removed_value(
-                    removed_expr, path=path, line=node.lineno
-                ),
-                deprecated_in=_parse_deprecated_value(
-                    deprecated_expr, path=path, line=node.lineno
-                ),
-                path=path,
-                line=node.lineno,
-                kind="warn_call",
-                package=package,
-            )
-        elif func_name == "warn_cleanup":
-            identifier_node = node.args[0] if node.args else None
-            if identifier_node is None:
-                continue
-            identifier = ast.unparse(identifier_node)
-
-            cleanup_expr = _extract_kw(node, "cleanup_by")
-
-            yield DeprecationRecord(
-                identifier=identifier,
-                removed_in=_parse_removed_value(
-                    cleanup_expr, path=path, line=node.lineno
-                ),
-                deprecated_in=None,
-                path=path,
-                line=node.lineno,
-                kind="cleanup_call",
-                package=package,
-            )
-
-
-def _build_identifier(node: ast.AST) -> str:
-    if isinstance(node, ast.ClassDef):
-        return node.name
-    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-        qual_name = node.name
-        if node.decorator_list:
-            parent = getattr(node, "parent", None)
-            if parent and isinstance(parent, ast.ClassDef):
-                return f"{parent.name}.{node.name}"
-        return qual_name
-    return "<unknown>"
-
-
-def _attach_parents(tree: ast.AST) -> None:
-    for node in ast.walk(tree):
-        for child in ast.iter_child_nodes(node):
-            setattr(child, "parent", node)
-
-
-def _collect_records(files: Iterable[Path], *, package: str) -> list[DeprecationRecord]:
-    records: list[DeprecationRecord] = []
-    for path in files:
-        tree = ast.parse(path.read_text())
-        _attach_parents(tree)
-        records.extend(_gather_decorators(tree, path, package=package))
-        records.extend(_gather_warn_calls(tree, path, package=package))
-    return records
-
-
-def _collect_rest_route_records(
-    files: Iterable[Path], *, package: str
-) -> list[DeprecationRecord]:
-    records: list[DeprecationRecord] = []
-    for path in files:
-        tree = ast.parse(path.read_text())
-        records.extend(_gather_rest_route_deprecations(tree, path, package=package))
-    return records
-
-
-def _version_ge(current: str, target: str) -> bool:
-    try:
-        return pkg_version.parse(current) >= pkg_version.parse(target)
-    except pkg_version.InvalidVersion as exc:
-        raise SystemExit(
-            f"Invalid semantic version comparison: {current=} {target=}"
-        ) from exc
-
-
-def _should_fail(current_version: str, record: DeprecationRecord) -> bool:
-    removed = record.removed_in
-    if removed is None:
-        return False
-    if isinstance(removed, date):
-        return date.today() >= removed
-    try:
-        target = str(removed)
-        return _version_ge(current_version, target)
-    except SystemExit:
-        raise
-    except Exception as exc:  # pragma: no cover - unexpected literal type
-        raise SystemExit(
-            f"Unsupported removed_in expression in {record.path}:{record.line}:"
-            f" {removed!r}"
-        ) from exc
-
-
-def _format_record(record: DeprecationRecord) -> str:
-    location = record.path.relative_to(REPO_ROOT)
-    removed = record.removed_in if record.removed_in is not None else "(none)"
-
-    if record.kind == "cleanup_call":
-        return (
-            f"- [{record.package}] {record.identifier} ({record.kind})\n"
-            f"  cleanup by:    {removed}\n"
-            f"  defined at:    {location}:{record.line}"
-        )
-
-    deprecated = (
-        record.deprecated_in if record.deprecated_in is not None else "(unknown)"
-    )
-    return (
-        f"- [{record.package}] {record.identifier} ({record.kind})\n"
-        f"  deprecated in: {deprecated}\n"
-        f"  removed in:    {removed}\n"
-        f"  defined at:    {location}:{record.line}"
-    )
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    argv = list(argv or [])
-
-    overdue: list[DeprecationRecord] = []
-    total_records = 0
-    package_summaries: list[tuple[str, str, int]] = []
-
-    for package in PACKAGES:
-        if not package.pyproject.exists():
-            raise SystemExit(
-                f"Unable to locate pyproject.toml for {package.name}: "
-                f"{package.pyproject}"
-            )
-
-        current_version = _load_current_version(package.pyproject)
-
-        files: list[Path] = []
-        for root in package.source_roots:
-            if not root.exists():
-                raise SystemExit(
-                    f"Source root {root} for package {package.name} does not exist"
-                )
-            files.extend(_iter_python_files(root))
-
-        records = _collect_records(files, package=package.name)
-        if package.name == "openhands-agent-server":
-            records.extend(_collect_rest_route_records(files, package=package.name))
-
-        overdue.extend(r for r in records if _should_fail(current_version, r))
-        total_records += len(records)
-        package_summaries.append((package.name, current_version, len(records)))
-
-    if overdue:
-        deprecated_items = [r for r in overdue if r.kind != "cleanup_call"]
-        cleanup_items = [r for r in overdue if r.kind == "cleanup_call"]
-
-        if deprecated_items:
-            print(
-                "The following deprecated features have passed their removal "
-                "deadline:\n"
-            )
-            for record in deprecated_items:
-                print(_format_record(record))
-                print()
-
-        if cleanup_items:
-            print("The following workarounds have passed their cleanup deadline:\n")
-            for record in cleanup_items:
-                print(_format_record(record))
-                print()
-
-        if deprecated_items:
-            print(
-                "Update or remove the listed features before publishing a version that "
-                "meets or exceeds their removal deadline."
-            )
-        if cleanup_items:
-            print(
-                "Remove the listed workarounds before publishing a version that "
-                "meets or exceeds their cleanup deadline."
-            )
-        return 1
-
-    for package_name, version, count in package_summaries:
-        print(
-            f"{package_name}: checked {count} deprecation metadata entries against "
-            f"version {version}."
-        )
-    print(
-        f"Checked {total_records} deprecation metadata entries across "
-        f"{len(package_summaries)} package(s)."
-    )
-    return 0
-
-
-if __name__ == "__main__":  # pragma: no cover - manual invocation
-    sys.exit(main(sys.argv[1:]))

.github/scripts/check_docstrings.py

@@ -1,297 +0,0 @@
-#!/usr/bin/env python3
-"""Validate docstrings conform to MDX-compatible formatting guidelines.
-
-This script checks that docstrings in the SDK use patterns that render correctly
-in Mintlify MDX documentation. It validates:
-
-1. No REPL-style examples (>>>) - should use fenced code blocks instead
-2. Shell/config examples use fenced code blocks (prevents # becoming headers)
-
-Run with: python scripts/check_docstrings.py
-Exit code 0 = all checks pass, 1 = violations found
-"""
-
-import ast
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-
-# Directories to check
-SDK_PATHS = [
-    "openhands-sdk/openhands/sdk",
-]
-
-# Files/directories to skip
-SKIP_PATTERNS = [
-    "__pycache__",
-    ".pyc",
-    "test_",
-    "_test.py",
-]
-
-# Core public API files to check strictly (these are documented on the website)
-# Other files will be checked but only emit warnings, not failures
-STRICT_CHECK_FILES = [
-    "agent/agent.py",
-    "llm/llm.py",
-    "conversation/conversation.py",
-    "tool/tool.py",
-    "workspace/base.py",
-    "observability/laminar.py",
-]
-
-
-@dataclass
-class Violation:
-    """A docstring formatting violation."""
-
-    file: Path
-    line: int
-    name: str
-    rule: str
-    message: str
-    is_strict: bool = False  # True if this is in a strictly-checked file
-
-
-def should_skip(path: Path) -> bool:
-    """Check if a path should be skipped."""
-    path_str = str(path)
-    return any(pattern in path_str for pattern in SKIP_PATTERNS)
-
-
-def check_repl_examples(
-    docstring: str, name: str, lineno: int, file: Path
-) -> list[Violation]:
-    """Check for REPL-style examples (>>>).
-
-    These should be replaced with fenced code blocks for better MDX rendering.
-    """
-    violations = []
-    lines = docstring.split("\n")
-
-    for i, line in enumerate(lines):
-        stripped = line.strip()
-        if stripped.startswith(">>>"):
-            violations.append(
-                Violation(
-                    file=file,
-                    line=lineno + i,
-                    name=name,
-                    rule="no-repl-examples",
-                    message=(
-                        "Use fenced code blocks (```python) instead of >>> REPL style. "
-                        "REPL examples don't render well in MDX documentation."
-                    ),
-                )
-            )
-            # Only report once per docstring
-            break
-
-    return violations
-
-
-def check_unfenced_shell_config(
-    docstring: str, name: str, lineno: int, file: Path
-) -> list[Violation]:
-    """Check for shell/config examples that aren't in fenced code blocks.
-
-    Lines starting with # outside code blocks become markdown headers.
-    """
-    violations = []
-    lines = docstring.split("\n")
-    in_code_block = False
-
-    for i, line in enumerate(lines):
-        stripped = line.strip()
-
-        # Track code block state
-        if stripped.startswith("```"):
-            in_code_block = not in_code_block
-            continue
-
-        # Skip if inside a code block
-        if in_code_block:
-            continue
-
-        # Check for shell-style comments that look like config
-        # Pattern: line starts with # and previous line has = (config pattern)
-        if stripped.startswith("#") and not stripped.startswith("# "):
-            # This is likely a shell comment without space (less common in prose)
-            continue
-
-        # Check for unfenced config: KEY=VALUE followed by # comment
-        if i > 0:
-            prev_line = lines[i - 1].strip() if i > 0 else ""
-            # If previous line looks like config (VAR=value) and this is a # comment
-            if "=" in prev_line and prev_line.split("=")[0].isupper():
-                if stripped.startswith("# "):
-                    violations.append(
-                        Violation(
-                            file=file,
-                            line=lineno + i,
-                            name=name,
-                            rule="fenced-shell-config",
-                            message=(
-                                "Shell/config examples with # comments should be "
-                                "in ```bash code blocks. Otherwise # becomes a "
-                                "markdown header."
-                            ),
-                        )
-                    )
-                    # Only report once per docstring
-                    break
-
-    return violations
-
-
-def check_docstring(
-    docstring: str, name: str, lineno: int, file: Path
-) -> list[Violation]:
-    """Run all checks on a docstring."""
-    if not docstring:
-        return []
-
-    violations = []
-    violations.extend(check_repl_examples(docstring, name, lineno, file))
-    violations.extend(check_unfenced_shell_config(docstring, name, lineno, file))
-    return violations
-
-
-def get_docstrings_from_file(file: Path) -> list[tuple[str, str, int]]:
-    """Extract all docstrings from a Python file.
-
-    Returns list of (name, docstring, lineno) tuples.
-    """
-    try:
-        source = file.read_text()
-        tree = ast.parse(source)
-    except (SyntaxError, UnicodeDecodeError) as e:
-        print(f"Warning: Could not parse {file}: {e}", file=sys.stderr)
-        return []
-
-    docstrings = []
-
-    for node in ast.walk(tree):
-        name = None
-        lineno = 0
-        docstring = None
-
-        if isinstance(node, ast.Module):
-            docstring = ast.get_docstring(node)
-            name = file.stem
-            lineno = 1
-        elif isinstance(node, ast.ClassDef):
-            docstring = ast.get_docstring(node)
-            name = node.name
-            lineno = node.lineno
-        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
-            docstring = ast.get_docstring(node)
-            name = node.name
-            lineno = node.lineno
-
-        if docstring and name:
-            docstrings.append((name, docstring, lineno))
-
-    return docstrings
-
-
-def is_strict_file(file: Path, repo_root: Path) -> bool:
-    """Check if a file is in the strict check list."""
-    try:
-        rel_path = file.relative_to(repo_root / "openhands-sdk/openhands/sdk")
-        return any(str(rel_path) == strict for strict in STRICT_CHECK_FILES)
-    except ValueError:
-        return False
-
-
-def check_file(file: Path, repo_root: Path) -> list[Violation]:
-    """Check all docstrings in a file."""
-    violations = []
-    is_strict = is_strict_file(file, repo_root)
-
-    for name, docstring, lineno in get_docstrings_from_file(file):
-        file_violations = check_docstring(docstring, name, lineno, file)
-        for v in file_violations:
-            v.is_strict = is_strict
-        violations.extend(file_violations)
-
-    return violations
-
-
-def main() -> int:
-    """Run docstring checks on all SDK files."""
-    repo_root = Path(__file__).parent.parent.parent
-
-    all_violations: list[Violation] = []
-    files_checked = 0
-
-    for sdk_path in SDK_PATHS:
-        path = repo_root / sdk_path
-        if not path.exists():
-            print(f"Warning: Path not found: {path}", file=sys.stderr)
-            continue
-
-        for py_file in path.rglob("*.py"):
-            if should_skip(py_file):
-                continue
-
-            files_checked += 1
-            violations = check_file(py_file, repo_root)
-            all_violations.extend(violations)
-
-    # Separate strict violations (errors) from warnings
-    strict_violations = [v for v in all_violations if v.is_strict]
-    warning_violations = [v for v in all_violations if not v.is_strict]
-
-    # Report warnings (non-strict files)
-    if warning_violations:
-        count = len(warning_violations)
-        print(f"\n⚠️  Found {count} docstring warning(s) in non-core files:\n")
-
-        by_file: dict[Path, list[Violation]] = {}
-        for v in warning_violations:
-            by_file.setdefault(v.file, []).append(v)
-
-        for file, violations in sorted(by_file.items()):
-            rel_path = file.relative_to(repo_root)
-            print(f"📄 {rel_path}")
-            for v in violations:
-                print(f"   Line {v.line}: {v.name} ({v.rule})")
-        print()
-
-    # Report errors (strict files)
-    if strict_violations:
-        count = len(strict_violations)
-        print(f"\n❌ Found {count} docstring error(s) in core API files:\n")
-
-        by_file: dict[Path, list[Violation]] = {}
-        for v in strict_violations:
-            by_file.setdefault(v.file, []).append(v)
-
-        for file, violations in sorted(by_file.items()):
-            rel_path = file.relative_to(repo_root)
-            print(f"📄 {rel_path}")
-            for v in violations:
-                print(f"   Line {v.line}: {v.name}")
-                print(f"   Rule: {v.rule}")
-                print(f"   {v.message}")
-                print()
-
-        print("=" * 60)
-        print("To fix these issues:")
-        print("  1. Replace >>> examples with ```python code blocks")
-        print("  2. Wrap shell/config examples in ```bash code blocks")
-        print("=" * 60)
-        return 1
-
-    if warning_violations:
-        count = len(warning_violations)
-        print(f"✅ Core API files pass. {count} warnings in other files.")
-    else:
-        print(f"✅ All {files_checked} files pass docstring checks")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/scripts/check_documented_examples.py

@@ -1,209 +0,0 @@
-#!/usr/bin/env python3
-"""
-Check if all examples in agent-sdk are documented in the docs repository.
-
-This script:
-1. Scans the docs repository for references to example files
-2. Lists all example Python files in the agent-sdk repository
-3. Compares the two sets to find undocumented examples
-4. Exits with error code 1 if undocumented examples are found
-"""
-
-import os
-import re
-import sys
-from pathlib import Path
-
-
-def find_documented_examples(docs_path: Path) -> set[str]:
-    """
-    Find all example file references in the docs repository.
-
-    Searches for patterns like:
-    - examples/01_standalone_sdk/02_custom_tools.py
-    - examples/02_remote_agent_server/06_custom_tool/custom_tools/log_data.py
-    in MDX files.
-
-    Returns:
-        Set of normalized example file paths (relative to agent-sdk root)
-    """
-    documented_examples: set[str] = set()
-
-    # Pattern to match example file references with arbitrary nesting depth.
-    # Matches: examples/<dir>/.../<file>.py
-    pattern = r"examples/(?:[-\w]+/)+[-\w]+\.py"
-
-    for root, _, files in os.walk(docs_path):
-        for file in files:
-            if file.endswith(".mdx") or file.endswith(".md"):
-                file_path = Path(root) / file
-                try:
-                    content = file_path.read_text(encoding="utf-8")
-                    matches = re.findall(pattern, content)
-                    for match in matches:
-                        # Normalize the path
-                        documented_examples.add(match)
-                except Exception as e:
-                    print(f"Warning: Error reading {file_path}: {e}")
-                    continue
-
-    return documented_examples
-
-
-def find_agent_sdk_examples(agent_sdk_path: Path) -> set[str]:
-    """
-    Find all example Python files in the agent-sdk repository.
-
-    Excludes examples/03_github_workflows/ since those examples are YAML
-    files, not Python files.
-
-    Returns:
-        Set of example file paths (relative to agent-sdk root)
-    """
-    examples: set[str] = set()
-    examples_dir = agent_sdk_path / "examples"
-
-    if not examples_dir.exists():
-        print(f"Error: Examples directory not found: {examples_dir}")
-        sys.exit(1)
-
-    # Find all Python files under examples/
-    for root, _, files in os.walk(examples_dir):
-        for file in files:
-            if file.endswith(".py"):
-                file_path = Path(root) / file
-                # Get relative path from agent-sdk root
-                relative_path = file_path.relative_to(agent_sdk_path)
-                relative_path_str = str(relative_path)
-
-                # Skip GitHub workflow examples (those are YAML files, Python
-                # files there are just helpers)
-                if relative_path_str.startswith("examples/03_github_workflows/"):
-                    continue
-
-                # Skip LLM-specific tools examples: these are intentionally not
-                # enforced by the docs check. See discussion in PR #1486.
-                if relative_path_str.startswith("examples/04_llm_specific_tools/"):
-                    continue
-
-                # Skip __init__.py files as they typically don't need documentation
-                if file == "__init__.py":
-                    continue
-
-                examples.add(relative_path_str)
-
-    return examples
-
-
-def resolve_paths() -> tuple[Path, Path]:
-    """
-    Determine agent-sdk root and docs path.
-
-    Priority for docs path:
-      1) DOCS_PATH (env override)
-      2) $GITHUB_WORKSPACE/docs
-      3) agent_sdk_root/'docs'
-      4) agent_sdk_root.parent/'docs'
-
-    Returns:
-        Tuple of (agent_sdk_root, docs_path)
-    """
-    # agent-sdk repo root (script is at agent-sdk/.github/scripts/...)
-    script_file = Path(__file__).resolve()
-    agent_sdk_root = script_file.parent.parent.parent
-
-    candidates: list[Path] = []
-
-    # 1) Explicit env override
-    env_override = os.environ.get("DOCS_PATH")
-    if env_override:
-        candidates.append(Path(env_override).expanduser().resolve())
-
-    # 2) Standard GitHub workspace sibling
-    gh_ws = os.environ.get("GITHUB_WORKSPACE")
-    if gh_ws:
-        candidates.append(Path(gh_ws).resolve() / "docs")
-
-    # 3) Sibling inside the agent-sdk repo root
-    candidates.append(agent_sdk_root / "docs")
-
-    # 4) Parent-of-agent-sdk-root layout
-    candidates.append(agent_sdk_root.parent / "docs")
-
-    print(f"🔍 Agent SDK root: {agent_sdk_root}")
-    print("🔎 Trying docs paths (in order):")
-    for p in candidates:
-        print(f"   - {p}")
-
-    for p in candidates:
-        if p.exists():
-            print(f"📁 Using docs path: {p}")
-            return agent_sdk_root, p
-
-    # If none exist, fail with a helpful message
-    print("❌ Docs path not found in any of the expected locations.")
-    print("   Set DOCS_PATH, or checkout the repo to one of the tried paths above.")
-    sys.exit(1)
-
-
-def main() -> None:
-    agent_sdk_root, docs_path = resolve_paths()
-
-    print("\n" + "=" * 60)
-    print("Checking documented examples...")
-    print("=" * 60)
-
-    # Find all examples in agent-sdk
-    print("\n📋 Scanning agent-sdk examples...")
-    agent_examples = find_agent_sdk_examples(agent_sdk_root)
-    print(f"   Found {len(agent_examples)} example file(s)")
-
-    # Find all documented examples in docs
-    print("\n📄 Scanning docs repository...")
-    documented_examples = find_documented_examples(docs_path)
-    print(f"   Found {len(documented_examples)} documented example(s)")
-
-    # Calculate difference
-    undocumented = agent_examples - documented_examples
-
-    print("\n" + "=" * 60)
-    if undocumented:
-        print(f"❌ Found {len(undocumented)} undocumented example(s):")
-        print("=" * 60)
-        for example in sorted(undocumented):
-            print(f"   - {example}")
-        print("\n⚠️  Please add documentation for these examples in the docs repo.")
-        print("=" * 60)
-        print("\n📚 How to Document Examples:")
-        print("=" * 60)
-        print("1. Clone the docs repository:")
-        print("   git clone https://github.com/OpenHands/docs.git")
-        print()
-        print("2. Create a new .mdx file in sdk/guides/ directory")
-        print("   (e.g., sdk/guides/my-feature.mdx)")
-        print()
-        print("3. Add the example code block with this format:")
-        print('   ```python icon="python" expandable examples/path/to/file.py')
-        print("   <code will be auto-synced>")
-        print("   ```")
-        print()
-        print("4. See the format documentation at:")
-        print(
-            "   https://github.com/OpenHands/docs/blob/main/.github/scripts/README.md"
-        )
-        print()
-        print("5. Example documentation files can be found in:")
-        print("   https://github.com/OpenHands/docs/tree/main/sdk/guides")
-        print()
-        print("6. After creating the PR in docs repo, reference it in your")
-        print("   agent-sdk PR description.")
-        print("=" * 60)
-        sys.exit(1)
-    else:
-        print("✅ All examples are documented!")
-        print("=" * 60)
-        sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

.github/scripts/check_duplicate_example_numbers.py

@@ -1,104 +0,0 @@
-#!/usr/bin/env python3
-"""
-Check for duplicate example numbers in the examples directory.
-
-This script ensures that within each examples subdirectory, no two files or
-folders share the same numeric prefix (e.g., two files both starting with "04_").
-
-Exit codes:
-    0 - No duplicates found
-    1 - Duplicates found
-"""
-
-import re
-import sys
-from collections import defaultdict
-from pathlib import Path
-
-
-def find_duplicate_numbers(examples_dir: Path) -> dict[str, list[str]]:
-    """
-    Find duplicate example numbers within each subdirectory.
-
-    Returns:
-        Dictionary mapping subdirectory paths to lists of duplicate entries.
-        Only includes subdirectories that have duplicates.
-    """
-    duplicates: dict[str, list[str]] = {}
-
-    # Pattern to extract leading number from filename/dirname
-    # e.g., "04" from "04_foo.py"
-    number_pattern = re.compile(r"^(\d+)_")
-
-    for subdir in sorted(examples_dir.iterdir()):
-        if not subdir.is_dir():
-            continue
-
-        # Skip hidden directories
-        if subdir.name.startswith("."):
-            continue
-
-        # Group entries by their numeric prefix
-        number_to_entries: dict[str, list[str]] = defaultdict(list)
-
-        for entry in subdir.iterdir():
-            # Skip hidden files/directories
-            if entry.name.startswith("."):
-                continue
-
-            match = number_pattern.match(entry.name)
-            if match:
-                number = match.group(1)
-                number_to_entries[number].append(entry.name)
-
-        # Find numbers with multiple entries
-        subdir_duplicates = []
-        for number, entries in sorted(number_to_entries.items()):
-            if len(entries) > 1:
-                subdir_duplicates.extend(sorted(entries))
-
-        if subdir_duplicates:
-            relative_subdir = str(subdir.relative_to(examples_dir.parent))
-            duplicates[relative_subdir] = subdir_duplicates
-
-    return duplicates
-
-
-def main() -> None:
-    # Find the examples directory relative to this script
-    script_file = Path(__file__).resolve()
-    repo_root = script_file.parent.parent.parent
-    examples_dir = repo_root / "examples"
-
-    if not examples_dir.exists():
-        print(f"Error: Examples directory not found: {examples_dir}")
-        sys.exit(1)
-
-    print("=" * 60)
-    print("Checking for duplicate example numbers...")
-    print("=" * 60)
-    print(f"\n📁 Scanning: {examples_dir}\n")
-
-    duplicates = find_duplicate_numbers(examples_dir)
-
-    if duplicates:
-        print("❌ Found duplicate example numbers:\n")
-        for subdir, entries in sorted(duplicates.items()):
-            print(f"  {subdir}/")
-            for entry in entries:
-                print(f"    - {entry}")
-            print()
-
-        print("=" * 60)
-        print("⚠️  Please renumber the examples to remove duplicates.")
-        print("   Each example should have a unique number within its folder.")
-        print("=" * 60)
-        sys.exit(1)
-    else:
-        print("✅ No duplicate example numbers found!")
-        print("=" * 60)
-        sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

.github/scripts/check_sdk_api_breakage.py

@@ -1,826 +0,0 @@
-#!/usr/bin/env python3
-"""API breakage detection for published OpenHands packages using Griffe.
-
-This script compares current workspace packages against the most recent PyPI
-release (or the matching release if the current version is already published)
-to detect breaking changes in the public API.
-
-It focuses on the curated public surface:
-- symbols exported via ``__all__``
-- public members removed from classes exported via ``__all__``
-
-It enforces two policies:
-
-1. **Deprecation-before-removal** – any removed export or removed public class
-   member must have been marked deprecated in the *previous* release using the
-   canonical deprecation helpers (``@deprecated`` decorator or
-   ``warn_deprecated()`` call from ``openhands.sdk.utils.deprecation``). For
-   members, the recommended ``warn_deprecated`` feature name is qualified (e.g.
-   ``"LLM.some_method"``).
-
-2. **MINOR version bump** – any breaking change (removal or structural) requires
-   at least a MINOR version bump according to SemVer.
-
-Complementary to the deprecation mechanism:
-- Deprecation (``check_deprecations.py``): enforces cleanup deadlines
-- This script: prevents unannounced removals and enforces SemVer bumps
-"""
-
-from __future__ import annotations
-
-import ast
-import json
-import os
-import re
-import subprocess
-import sys
-import tomllib
-import urllib.request
-from collections.abc import Iterable
-from dataclasses import dataclass
-from pathlib import Path
-
-from packaging import version as pkg_version
-from packaging.requirements import Requirement
-
-
-@dataclass(frozen=True)
-class PackageConfig:
-    """Configuration for a single published package."""
-
-    package: str  # dotted module path, e.g. "openhands.sdk"
-    distribution: str  # PyPI distribution name, e.g. "openhands-sdk"
-    source_dir: str  # repo-relative directory, e.g. "openhands-sdk"
-
-
-@dataclass(frozen=True, slots=True)
-class DeprecatedSymbols:
-    """Deprecated SDK symbols detected in a source tree.
-
-    ``top_level`` tracks module-level symbols (exports) like ``LLM``.
-    ``qualified`` tracks class members like ``LLM.some_method``.
-    """
-
-    top_level: set[str] = frozenset()  # type: ignore[assignment]
-    qualified: set[str] = frozenset()  # type: ignore[assignment]
-
-
-PACKAGES: tuple[PackageConfig, ...] = (
-    PackageConfig(
-        package="openhands.sdk",
-        distribution="openhands-sdk",
-        source_dir="openhands-sdk",
-    ),
-    PackageConfig(
-        package="openhands.workspace",
-        distribution="openhands-workspace",
-        source_dir="openhands-workspace",
-    ),
-    PackageConfig(
-        package="openhands.tools",
-        distribution="openhands-tools",
-        source_dir="openhands-tools",
-    ),
-)
-
-ACP_DEPENDENCY = "agent-client-protocol"
-ACP_SKIP_ENV = "ACP_VERSION_CHECK_SKIP"
-ACP_SKIP_TOKEN = "skip-acp-check"
-ACP_BASE_REF_ENV = "ACP_VERSION_CHECK_BASE_REF"
-
-
-def read_version_from_pyproject(path: str) -> str:
-    """Read the version string from a pyproject.toml file."""
-    with open(path, "rb") as f:
-        data = tomllib.load(f)
-    proj = data.get("project", {})
-    v = proj.get("version")
-    if not v:
-        raise SystemExit(f"Could not read version from {path}")
-    return str(v)
-
-
-def _read_pyproject(path: str) -> dict:
-    with open(path, "rb") as f:
-        return tomllib.load(f)
-
-
-def _bool_env(name: str) -> bool:
-    value = os.environ.get(name, "").strip().lower()
-    return value in {"1", "true", "yes", "on"}
-
-
-def _get_dependency_spec(project_data: dict, dependency: str) -> str | None:
-    deps = project_data.get("project", {}).get("dependencies", [])
-    for dep in deps:
-        if dep.startswith(dependency):
-            return dep
-    return None
-
-
-def _min_version_from_requirement(req_str: str) -> pkg_version.Version | None:
-    try:
-        req = Requirement(req_str)
-    except Exception as exc:
-        print(
-            f"::warning title=ACP version::Unable to parse requirement "
-            f"'{req_str}': {exc}"
-        )
-        return None
-
-    lower_bounds: list[pkg_version.Version] = []
-    for spec in req.specifier:
-        if spec.operator in {">=", ">", "==", "~="}:
-            try:
-                lower_bounds.append(_parse_version(spec.version))
-            except Exception as exc:
-                print(
-                    f"::warning title=ACP version::Unable to parse version "
-                    f"'{spec.version}' from '{req_str}': {exc}"
-                )
-
-    if not lower_bounds:
-        return None
-
-    return max(lower_bounds)
-
-
-def _git_show_file(ref: str, rel_path: str) -> str | None:
-    for candidate in (f"origin/{ref}", ref):
-        result = subprocess.run(
-            ["git", "show", f"{candidate}:{rel_path}"],
-            check=False,
-            capture_output=True,
-            text=True,
-        )
-        if result.returncode == 0:
-            return result.stdout
-    return None
-
-
-def _load_base_pyproject(base_ref: str) -> dict | None:
-    rel_path = "openhands-sdk/pyproject.toml"
-    content = _git_show_file(base_ref, rel_path)
-    if content is None:
-        print(
-            f"::warning title=ACP version::Unable to read {rel_path} from "
-            f"{base_ref}; skipping ACP version check"
-        )
-        return None
-    try:
-        return tomllib.loads(content)
-    except tomllib.TOMLDecodeError as exc:
-        print(
-            f"::warning title=ACP version::Failed to parse {rel_path} from "
-            f"{base_ref}: {exc}"
-        )
-        return None
-
-
-def _check_acp_version_bump(repo_root: str) -> int:
-    if _bool_env(ACP_SKIP_ENV):
-        print(
-            f"::notice title=ACP version::Skipping ACP version check because "
-            f"{ACP_SKIP_ENV} is set (token: [{ACP_SKIP_TOKEN}])."
-        )
-        return 0
-
-    base_ref = os.environ.get(ACP_BASE_REF_ENV) or os.environ.get("GITHUB_BASE_REF")
-    if not base_ref:
-        print(
-            "::warning title=ACP version::No base ref found; skipping ACP version check"
-        )
-        return 0
-
-    base_data = _load_base_pyproject(base_ref)
-    if base_data is None:
-        return 0
-
-    current_data = _read_pyproject(
-        os.path.join(repo_root, "openhands-sdk", "pyproject.toml")
-    )
-    old_req = _get_dependency_spec(base_data, ACP_DEPENDENCY)
-    new_req = _get_dependency_spec(current_data, ACP_DEPENDENCY)
-
-    if not old_req or not new_req:
-        print(
-            f"::warning title=ACP version::Unable to locate {ACP_DEPENDENCY} "
-            "dependency in pyproject.toml; skipping ACP version check"
-        )
-        return 0
-
-    old_min = _min_version_from_requirement(old_req)
-    new_min = _min_version_from_requirement(new_req)
-
-    if old_min is None or new_min is None:
-        print(
-            f"::warning title=ACP version::Unable to parse {ACP_DEPENDENCY} "
-            "minimum version; skipping ACP version check"
-        )
-        return 0
-
-    if new_min <= old_min:
-        return 0
-
-    if new_min.major != old_min.major or new_min.minor != old_min.minor:
-        print(
-            "::error title=ACP version::Detected "
-            f"{ACP_DEPENDENCY} minor/major version bump "
-            f"({old_req} -> {new_req}). If intentional, add "
-            f"[{ACP_SKIP_TOKEN}] to the PR description to bypass."
-        )
-        return 1
-
-    return 0
-
-
-def _parse_version(v: str) -> pkg_version.Version:
-    """Parse a version string using packaging."""
-    return pkg_version.parse(v)
-
-
-def get_pypi_baseline_version(pkg: str, current: str | None) -> str | None:
-    """Fetch the baseline release version from PyPI.
-
-    The baseline is the most recent published release to compare against the
-    current workspace. If the current version already exists on PyPI, compare
-    against that same release. Otherwise, fall back to the newest release older
-    than the current version. If ``current`` is None, use the latest release.
-
-    Args:
-        pkg: Package name on PyPI (e.g., "openhands-sdk")
-        current: Current version from the workspace, or None for latest
-
-    Returns:
-        Baseline version string, or None if not found or on network error
-    """
-    req = urllib.request.Request(
-        url=f"https://pypi.org/pypi/{pkg}/json",
-        headers={"User-Agent": "openhands-sdk-api-check/1.0"},
-        method="GET",
-    )
-    try:
-        with urllib.request.urlopen(req, timeout=10) as r:
-            meta = json.load(r)
-    except Exception as e:
-        print(f"::warning title={pkg} API::Failed to fetch PyPI metadata: {e}")
-        return None
-
-    releases = list(meta.get("releases", {}).keys())
-    if not releases:
-        return None
-
-    def _sort_key(s: str):
-        return _parse_version(s)
-
-    releases_sorted = sorted(releases, key=_sort_key, reverse=True)
-    if current is None:
-        return releases_sorted[0]
-
-    if current in releases:
-        return current
-
-    cur_parsed = _parse_version(current)
-    older = [rv for rv in releases if _parse_version(rv) < cur_parsed]
-    if not older:
-        return None
-    return sorted(older, key=_sort_key, reverse=True)[0]
-
-
-def ensure_griffe() -> None:
-    """Verify griffe is installed, raising an error if not."""
-    try:
-        import griffe  # noqa: F401
-    except ImportError:
-        sys.stderr.write(
-            "ERROR: griffe not installed. Install with: pip install griffe[pypi]\n"
-        )
-        raise SystemExit(1)
-
-
-def _is_field_metadata_only_change(old_val: object, new_val: object) -> bool:
-    """Check if the change is only in Field metadata (description, title, etc.).
-
-    Field metadata parameters like ``description``, ``title``, ``examples``, and
-    ``deprecated`` don't affect runtime behavior. Changes to these should not be
-    considered breaking API changes.
-
-    Returns:
-        True if both values are Field() calls and only metadata parameters differ.
-    """
-    old_str = str(old_val)
-    new_str = str(new_val)
-
-    if not (old_str.startswith("Field(") and new_str.startswith("Field(")):
-        return False
-
-    # Metadata parameters that don't affect runtime behavior.
-    # See https://docs.pydantic.dev/latest/api/fields/#pydantic.fields.Field
-    metadata_patterns = {
-        "description": r'([\'"])([^\'"]*?)\1',
-        "title": r'([\'"])([^\'"]*?)\1',
-        "examples": r'([\'"])([^\'"]*?)\1',
-        "json_schema_extra": r'([\'"])([^\'"]*?)\1',
-        "deprecated": r"(?:True|False|None|'[^']*'|\"[^\"]*\")",
-    }
-
-    def _normalize(value: str) -> str:
-        normalized = value
-        for param, value_pattern in metadata_patterns.items():
-            pattern = rf",?\s*{param}\s*=\s*{value_pattern}"
-            normalized = re.sub(pattern, "", normalized)
-
-        normalized = re.sub(r"\(\s*,", "(", normalized)
-        normalized = re.sub(r",\s*\)", ")", normalized)
-        normalized = re.sub(r",\s*,", ", ", normalized)
-        normalized = re.sub(r"\s+", " ", normalized)
-        return normalized.strip()
-
-    return _normalize(old_str) == _normalize(new_str)
-
-
-def _collect_breakages_pairs(
-    objs: Iterable[tuple[object, object]],
-    *,
-    deprecated: DeprecatedSymbols,
-    title: str,
-) -> tuple[list[object], int]:
-    """Find breaking changes between pairs of old/new API objects.
-
-    Only reports breakages for public API members.
-
-    Returns:
-        (breakages, undeprecated_removals)
-    """
-
-    import griffe
-    from griffe import Alias, AliasResolutionError, BreakageKind, ExplanationStyle, Kind
-
-    breakages: list[object] = []
-    undeprecated_removals = 0
-
-    for old, new in objs:
-        try:
-            for br in griffe.find_breaking_changes(old, new):
-                obj = getattr(br, "obj", None)
-                if not getattr(obj, "is_public", True):
-                    continue
-
-                # Skip ATTRIBUTE_CHANGED_VALUE when it's just Field metadata changes
-                # (description, title, examples, etc.) - these don't affect runtime
-                if br.kind == BreakageKind.ATTRIBUTE_CHANGED_VALUE:
-                    old_value = getattr(br, "old_value", None)
-                    new_value = getattr(br, "new_value", None)
-                    if _is_field_metadata_only_change(old_value, new_value):
-                        print(
-                            f"::notice title={title}::Ignoring Field metadata-only "
-                            f"change (non-breaking): {obj.name if obj else 'unknown'}"
-                        )
-                        continue
-
-                print(br.explain(style=ExplanationStyle.GITHUB))
-                breakages.append(br)
-
-                if br.kind != BreakageKind.OBJECT_REMOVED:
-                    continue
-
-                parent = getattr(obj, "parent", None)
-                if getattr(parent, "kind", None) != Kind.CLASS:
-                    continue
-
-                feature = f"{parent.name}.{obj.name}"
-                if (
-                    feature not in deprecated.qualified
-                    and parent.name not in deprecated.top_level
-                ):
-                    print(
-                        f"::error title={title}::Removed '{feature}' without prior "
-                        "deprecation. Mark it with @deprecated(...) or "
-                        f"warn_deprecated('{feature}', ...) for at least one release "
-                        "before removing."
-                    )
-                    undeprecated_removals += 1
-        except AliasResolutionError as e:
-            if isinstance(old, Alias) or isinstance(new, Alias):
-                old_target = old.target_path if isinstance(old, Alias) else None
-                new_target = new.target_path if isinstance(new, Alias) else None
-                if old_target != new_target:
-                    name = getattr(old, "name", None) or getattr(
-                        new, "name", "<unknown>"
-                    )
-                    print(
-                        f"::warning title={title}::Alias target changed for '{name}': "
-                        f"{old_target!r} -> {new_target!r}"
-                    )
-                    breakages.append(
-                        {
-                            "kind": "ALIAS_TARGET_CHANGED",
-                            "name": name,
-                            "old": old_target,
-                            "new": new_target,
-                        }
-                    )
-            else:
-                print(
-                    f"::notice title={title}::Skipping symbol comparison due to "
-                    f"unresolved alias: {e}"
-                )
-        except Exception as e:
-            print(f"::warning title={title}::Failed to compute breakages: {e}")
-
-    return breakages, undeprecated_removals
-
-
-def _extract_exported_names(module) -> set[str]:
-    """Extract names exported from a module via ``__all__``.
-
-    This check is explicitly meant to track the curated public surface. The SDK
-    is expected to define ``__all__`` in ``openhands.sdk``; if it's missing or we
-    can't statically interpret it, we fail fast rather than silently widening the
-    surface area (which would make the check noisy and brittle).
-    """
-    try:
-        all_var = module["__all__"]
-    except Exception as e:
-        raise ValueError("Expected __all__ to be defined on the public module") from e
-
-    val = getattr(all_var, "value", None)
-    elts = getattr(val, "elements", None)
-    if not elts:
-        raise ValueError("Unable to statically evaluate __all__")
-
-    names: set[str] = set()
-    for el in elts:
-        # Griffe represents string literals in __all__ in different ways depending
-        # on how the module is loaded / griffe version:
-        # - sometimes as plain Python strings (including quotes, e.g. "'LLM'")
-        # - sometimes as expression nodes with a `.value` attribute
-        #
-        # We intentionally only support the "static __all__ of string literals"
-        # case; we just normalize the representation.
-        if isinstance(el, str):
-            names.add(el.strip("\"'"))
-            continue
-        s = getattr(el, "value", None)
-        if isinstance(s, str):
-            names.add(s)
-
-    if not names:
-        raise ValueError("__all__ resolved to an empty set")
-
-    return names
-
-
-def _check_version_bump(prev: str, new_version: str, total_breaks: int) -> int:
-    """Check if version bump policy is satisfied for breaking changes.
-
-    Policy: Breaking changes require at least a MINOR version bump.
-
-    Returns:
-        0 if policy satisfied, 1 if not
-    """
-    if total_breaks == 0:
-        print("No breaking changes detected")
-        return 0
-
-    parsed_prev = _parse_version(prev)
-    parsed_new = _parse_version(new_version)
-
-    # MINOR bump required: same major, higher minor OR higher major
-    ok = (parsed_new.major > parsed_prev.major) or (
-        parsed_new.major == parsed_prev.major and parsed_new.minor > parsed_prev.minor
-    )
-
-    if not ok:
-        print(
-            f"::error title=SemVer::Breaking changes detected ({total_breaks}); "
-            f"require at least minor version bump from "
-            f"{parsed_prev.major}.{parsed_prev.minor}.x, but new is {new_version}"
-        )
-        return 1
-
-    print(
-        f"Breaking changes detected ({total_breaks}) and version bump policy "
-        f"satisfied ({prev} -> {new_version})"
-    )
-    return 0
-
-
-def _resolve_griffe_object(
-    root: object,
-    dotted: str,
-    root_package: str = "",
-) -> object:
-    """Resolve a dotted path to a griffe object."""
-    root_path = getattr(root, "path", None)
-    if root_path == dotted:
-        return root
-
-    if isinstance(root_path, str) and dotted.startswith(root_path + "."):
-        dotted = dotted[len(root_path) + 1 :]
-
-    try:
-        return root[dotted]
-    except (KeyError, TypeError) as e:
-        print(
-            f"::warning title=SDK API::Unable to resolve {dotted} via "
-            f"direct lookup; falling back to manual traversal: {e}"
-        )
-
-    rel = dotted
-    if root_package and dotted.startswith(root_package + "."):
-        rel = dotted[len(root_package) + 1 :]
-
-    obj = root
-    for part in rel.split("."):
-        try:
-            obj = obj[part]
-        except (KeyError, TypeError) as e:
-            raise KeyError(f"Unable to resolve {dotted}: failed at {part}") from e
-    return obj
-
-
-def _load_current(
-    griffe_module: object, repo_root: str, cfg: PackageConfig
-) -> object | None:
-    try:
-        return griffe_module.load(
-            cfg.package,
-            search_paths=[os.path.join(repo_root, cfg.source_dir)],
-        )
-    except Exception as e:
-        print(
-            f"::error title={cfg.distribution} API::"
-            f"Failed to load current {cfg.distribution}: {e}"
-        )
-        return None
-
-
-def _load_prev_from_pypi(
-    griffe_module: object,
-    prev: str,
-    cfg: PackageConfig,
-) -> object | None:
-    griffe_cache = os.path.expanduser("~/.cache/griffe")
-    os.makedirs(griffe_cache, exist_ok=True)
-
-    try:
-        return griffe_module.load_pypi(
-            package=cfg.package,
-            distribution=cfg.distribution,
-            version_spec=f"=={prev}",
-        )
-    except Exception as e:
-        print(
-            f"::error title={cfg.distribution} API::"
-            f"Failed to load {cfg.distribution}=={prev} from PyPI: {e}"
-        )
-        return None
-
-
-def _find_deprecated_symbols(source_root: Path) -> DeprecatedSymbols:
-    """Scan source files for symbols marked with the SDK deprecation helpers.
-
-    Detects two forms:
-    - ``@deprecated(...)`` decorator on a class/function/method
-    - ``warn_deprecated('SomeFeature', ...)`` call
-
-    Returns:
-        DeprecatedSymbols(top_level=..., qualified=...)
-    """
-
-    def _is_deprecated_decorator(deco: ast.AST) -> bool:
-        if not isinstance(deco, ast.Call):
-            return False
-        target = deco.func
-        if isinstance(target, ast.Name):
-            return target.id == "deprecated"
-        if isinstance(target, ast.Attribute):
-            return target.attr == "deprecated"
-        return False
-
-    class _Visitor(ast.NodeVisitor):
-        def __init__(self) -> None:
-            self.class_stack: list[str] = []
-            self.top_level: set[str] = set()
-            self.qualified: set[str] = set()
-
-        def visit_ClassDef(self, node: ast.ClassDef) -> None:  # noqa: N802
-            if any(_is_deprecated_decorator(deco) for deco in node.decorator_list):
-                self.top_level.add(node.name)
-                self.qualified.add(node.name)
-
-            self.class_stack.append(node.name)
-            self.generic_visit(node)
-            self.class_stack.pop()
-
-        def _visit_function_like(
-            self,
-            node: ast.FunctionDef | ast.AsyncFunctionDef,
-        ) -> None:
-            if any(_is_deprecated_decorator(deco) for deco in node.decorator_list):
-                if self.class_stack:
-                    self.qualified.add(".".join([*self.class_stack, node.name]))
-                else:
-                    self.top_level.add(node.name)
-                    self.qualified.add(node.name)
-
-            self.generic_visit(node)
-
-        def visit_FunctionDef(self, node: ast.FunctionDef) -> None:  # noqa: N802
-            self._visit_function_like(node)
-
-        def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:  # noqa: N802
-            self._visit_function_like(node)
-
-        def visit_Call(self, node: ast.Call) -> None:  # noqa: N802
-            target = node.func
-            func_name = None
-            if isinstance(target, ast.Name):
-                func_name = target.id
-            elif isinstance(target, ast.Attribute):
-                func_name = target.attr
-
-            if func_name == "warn_deprecated" and node.args:
-                feature = _extract_string_literal(node.args[0])
-                if feature is not None:
-                    self.qualified.add(feature)
-                    self.top_level.add(feature.split(".")[0])
-
-            self.generic_visit(node)
-
-    top_level: set[str] = set()
-    qualified: set[str] = set()
-
-    for pyfile in source_root.rglob("*.py"):
-        try:
-            tree = ast.parse(pyfile.read_text())
-        except SyntaxError as e:
-            print(
-                f"::warning title=SDK API::Skipping {pyfile}: "
-                f"failed to parse (SyntaxError: {e})"
-            )
-            continue
-
-        visitor = _Visitor()
-        visitor.visit(tree)
-        top_level |= visitor.top_level
-        qualified |= visitor.qualified
-
-    return DeprecatedSymbols(top_level=top_level, qualified=qualified)
-
-
-def _extract_string_literal(node: ast.AST) -> str | None:
-    """Return the string value if *node* is a simple string literal."""
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        return node.value
-    return None
-
-
-def _get_source_root(griffe_root: object) -> Path | None:
-    """Derive the package source directory from a griffe module's filepath."""
-    filepath = getattr(griffe_root, "filepath", None)
-    if filepath is not None:
-        return Path(filepath).parent
-    return None
-
-
-def _compute_breakages(old_root, new_root, cfg: PackageConfig) -> tuple[int, int]:
-    """Detect breaking changes between old and new package versions.
-
-    Returns:
-        ``(total_breaks, undeprecated_removals)`` — *total_breaks* counts all
-        structural breakages (for the version-bump policy), while
-        *undeprecated_removals* counts public API removals (exports and class
-        members) without a prior deprecation marker (a separate hard failure).
-    """
-    pkg = cfg.package
-    title = f"{cfg.distribution} API"
-    total_breaks = 0
-    undeprecated_removals = 0
-
-    source_root = _get_source_root(old_root)
-    deprecated = (
-        _find_deprecated_symbols(source_root) if source_root else DeprecatedSymbols()
-    )
-
-    try:
-        old_mod = _resolve_griffe_object(old_root, pkg, root_package=pkg)
-        new_mod = _resolve_griffe_object(new_root, pkg, root_package=pkg)
-    except Exception as e:
-        raise RuntimeError(f"Failed to resolve root module '{pkg}'") from e
-
-    new_exports = _extract_exported_names(new_mod)
-    try:
-        old_exports = _extract_exported_names(old_mod)
-    except ValueError as e:
-        # The API breakage check relies on a curated public surface defined via
-        # __all__. If the baseline release didn't define (or couldn't statically
-        # evaluate) __all__, we can't compute meaningful breakages.
-        #
-        # In this situation, skip rather than failing the entire workflow.
-        print(
-            f"::notice title={title}::Skipping breakage check; baseline release "
-            f"has no statically-evaluable {pkg}.__all__: {e}"
-        )
-        return 0, 0
-
-    removed = sorted(old_exports - new_exports)
-
-    # Check deprecation-before-removal policy (exports)
-    for name in removed:
-        total_breaks += 1  # every removal is a structural break
-        if name not in deprecated.top_level:
-            print(
-                f"::error title={title}::Removed '{name}' from "
-                f"{pkg}.__all__ without prior deprecation. "
-                "Mark it with @deprecated or warn_deprecated() "
-                "for at least one release before removing."
-            )
-            undeprecated_removals += 1
-        else:
-            print(
-                f"::notice title={title}::Removed previously-deprecated symbol "
-                f"'{name}' from {pkg}.__all__"
-            )
-
-    common = sorted(old_exports & new_exports)
-    pairs: list[tuple[object, object]] = []
-    for name in common:
-        try:
-            pairs.append((old_mod[name], new_mod[name]))
-        except Exception as e:
-            print(f"::warning title={title}::Unable to resolve symbol {name}: {e}")
-
-    breakages, undeprecated_members = _collect_breakages_pairs(
-        pairs,
-        deprecated=deprecated,
-        title=title,
-    )
-    total_breaks += len(breakages)
-    undeprecated_removals += undeprecated_members
-
-    return total_breaks, undeprecated_removals
-
-
-def _check_package(griffe_module, repo_root: str, cfg: PackageConfig) -> int:
-    """Run breakage checks for a single package. Returns 0 on success."""
-    pyproj = os.path.join(repo_root, cfg.source_dir, "pyproject.toml")
-    new_version = read_version_from_pyproject(pyproj)
-
-    title = f"{cfg.distribution} API"
-    baseline = get_pypi_baseline_version(cfg.distribution, new_version)
-    if not baseline:
-        print(
-            f"::warning title={title}::No baseline {cfg.distribution} "
-            f"release found; skipping breakage check",
-        )
-        return 0
-
-    print(f"Comparing {cfg.distribution} {new_version} against {baseline}")
-
-    new_root = _load_current(griffe_module, repo_root, cfg)
-    if not new_root:
-        return 1
-
-    old_root = _load_prev_from_pypi(griffe_module, baseline, cfg)
-    if not old_root:
-        return 1
-
-    try:
-        total_breaks, undeprecated = _compute_breakages(old_root, new_root, cfg)
-    except Exception as e:
-        print(f"::error title={title}::Failed to compute breakages: {e}")
-        return 1
-
-    if undeprecated:
-        print(
-            f"::error title={title}::{undeprecated} symbol(s) removed "
-            f"from {cfg.package} without prior deprecation — "
-            f"see errors above"
-        )
-
-    bump_rc = _check_version_bump(baseline, new_version, total_breaks)
-
-    return 1 if (undeprecated or bump_rc) else 0
-
-
-def main() -> int:
-    """Main entry point for API breakage detection."""
-    repo_root = os.getcwd()
-    rc = _check_acp_version_bump(repo_root)
-
-    ensure_griffe()
-    import griffe
-
-    for cfg in PACKAGES:
-        print(f"\n{'=' * 60}")
-        print(f"Checking {cfg.distribution} ({cfg.package})")
-        print(f"{'=' * 60}")
-        rc |= _check_package(griffe, repo_root, cfg)
-
-    return rc
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

.github/scripts/check_version_bumps.py

@@ -1,196 +0,0 @@
-"""Guard package version changes so they only happen in release PRs."""
-
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-import sys
-import tomllib
-from dataclasses import dataclass
-from pathlib import Path
-
-
-PACKAGE_PYPROJECTS: dict[str, Path] = {
-    "openhands-sdk": Path("openhands-sdk/pyproject.toml"),
-    "openhands-tools": Path("openhands-tools/pyproject.toml"),
-    "openhands-workspace": Path("openhands-workspace/pyproject.toml"),
-    "openhands-agent-server": Path("openhands-agent-server/pyproject.toml"),
-}
-
-_VERSION_PATTERN = r"\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?"
-_RELEASE_TITLE_RE = re.compile(rf"^Release v(?P<version>{_VERSION_PATTERN})$")
-_RELEASE_BRANCH_RE = re.compile(rf"^rel-(?P<version>{_VERSION_PATTERN})$")
-
-
-@dataclass(frozen=True)
-class VersionChange:
-    package: str
-    path: Path
-    previous_version: str
-    current_version: str
-
-
-def _read_version_from_pyproject_text(text: str, source: str) -> str:
-    data = tomllib.loads(text)
-    version = data.get("project", {}).get("version")
-    if not isinstance(version, str):
-        raise SystemExit(f"Unable to determine project.version from {source}")
-    return version
-
-
-def _read_current_version(repo_root: Path, pyproject: Path) -> str:
-    return _read_version_from_pyproject_text(
-        (repo_root / pyproject).read_text(),
-        str(pyproject),
-    )
-
-
-def _read_version_from_git_ref(repo_root: Path, git_ref: str, pyproject: Path) -> str:
-    result = subprocess.run(
-        ["git", "show", f"{git_ref}:{pyproject.as_posix()}"],
-        cwd=repo_root,
-        check=False,
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        message = result.stderr.strip() or result.stdout.strip() or "unknown git error"
-        raise SystemExit(
-            f"Unable to read {pyproject} from git ref {git_ref}: {message}"
-        )
-    return _read_version_from_pyproject_text(result.stdout, f"{git_ref}:{pyproject}")
-
-
-def _base_ref_candidates(base_ref: str) -> list[str]:
-    if base_ref.startswith("origin/"):
-        return [base_ref, base_ref.removeprefix("origin/")]
-    return [f"origin/{base_ref}", base_ref]
-
-
-def find_version_changes(repo_root: Path, base_ref: str) -> list[VersionChange]:
-    changes: list[VersionChange] = []
-    candidates = _base_ref_candidates(base_ref)
-
-    for package, pyproject in PACKAGE_PYPROJECTS.items():
-        current_version = _read_current_version(repo_root, pyproject)
-        previous_error: SystemExit | None = None
-        previous_version: str | None = None
-
-        for candidate in candidates:
-            try:
-                previous_version = _read_version_from_git_ref(
-                    repo_root, candidate, pyproject
-                )
-                break
-            except SystemExit as exc:
-                previous_error = exc
-
-        if previous_version is None:
-            assert previous_error is not None
-            raise previous_error
-
-        if previous_version != current_version:
-            changes.append(
-                VersionChange(
-                    package=package,
-                    path=pyproject,
-                    previous_version=previous_version,
-                    current_version=current_version,
-                )
-            )
-
-    return changes
-
-
-def get_release_pr_version(
-    pr_title: str, pr_head_ref: str
-) -> tuple[str | None, list[str]]:
-    title_match = _RELEASE_TITLE_RE.fullmatch(pr_title.strip())
-    branch_match = _RELEASE_BRANCH_RE.fullmatch(pr_head_ref.strip())
-    title_version = title_match.group("version") if title_match else None
-    branch_version = branch_match.group("version") if branch_match else None
-
-    if title_version and branch_version and title_version != branch_version:
-        return None, [
-            "Release PR markers disagree: title requests "
-            f"v{title_version} but branch is rel-{branch_version}."
-        ]
-
-    return title_version or branch_version, []
-
-
-def validate_version_changes(
-    changes: list[VersionChange],
-    pr_title: str,
-    pr_head_ref: str,
-) -> list[str]:
-    if not changes:
-        return []
-
-    release_version, errors = get_release_pr_version(pr_title, pr_head_ref)
-    if errors:
-        return errors
-
-    formatted_changes = ", ".join(
-        f"{change.package} ({change.previous_version} -> {change.current_version})"
-        for change in changes
-    )
-
-    if release_version is None:
-        return [
-            "Package version changes are only allowed in release PRs. "
-            f"Detected changes: {formatted_changes}. "
-            "Use the Prepare Release workflow so the PR title is 'Release vX.Y.Z' "
-            "or the branch is 'rel-X.Y.Z'."
-        ]
-
-    mismatched = [
-        change for change in changes if change.current_version != release_version
-    ]
-    if mismatched:
-        mismatch_details = ", ".join(
-            f"{change.package} ({change.current_version})" for change in mismatched
-        )
-        return [
-            f"Release PR version v{release_version} does not match changed package "
-            f"versions: {mismatch_details}."
-        ]
-
-    return []
-
-
-def main() -> int:
-    repo_root = Path(__file__).resolve().parents[2]
-    base_ref = os.environ.get("VERSION_BUMP_BASE_REF") or os.environ.get(
-        "GITHUB_BASE_REF"
-    )
-    if not base_ref:
-        print("::warning title=Version bump guard::No base ref found; skipping check.")
-        return 0
-
-    pr_title = os.environ.get("PR_TITLE", "")
-    pr_head_ref = os.environ.get("PR_HEAD_REF", "")
-
-    changes = find_version_changes(repo_root, base_ref)
-    errors = validate_version_changes(changes, pr_title, pr_head_ref)
-
-    if errors:
-        for error in errors:
-            print(f"::error title=Version bump guard::{error}")
-        return 1
-
-    if changes:
-        changed_packages = ", ".join(change.package for change in changes)
-        print(
-            "::notice title=Version bump guard::"
-            f"Release PR version changes validated for {changed_packages}."
-        )
-    else:
-        print("::notice title=Version bump guard::No package version changes detected.")
-
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/scripts/update_sdk_ref_default.py

@@ -1,122 +0,0 @@
-#!/usr/bin/env python3
-"""Update the sdk_ref default value in run-eval.yml.
-
-This script updates the default SDK reference version in the run-eval workflow
-to match a new release version.
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-RUN_EVAL_WORKFLOW = REPO_ROOT / ".github" / "workflows" / "run-eval.yml"
-
-# Pattern to match the sdk_ref default line
-# Matches: "default: vX.Y.Z" with optional prerelease suffix like -rc1, -beta.1
-SDK_REF_PATTERN = re.compile(
-    r"^(\s*default:\s*v)[\d]+\.[\d]+\.[\d]+(-[a-zA-Z0-9.]+)?(\s*)$"
-)
-
-
-def update_sdk_ref_default(new_version: str, dry_run: bool = False) -> bool:
-    """Update the sdk_ref default in run-eval.yml.
-
-    Args:
-        new_version: The new version (without 'v' prefix, e.g., "1.12.0")
-        dry_run: If True, print what would change without modifying the file
-
-    Returns:
-        True if successful, False otherwise
-    """
-    if not RUN_EVAL_WORKFLOW.exists():
-        print(f"❌ File not found: {RUN_EVAL_WORKFLOW}", file=sys.stderr)
-        return False
-
-    content = RUN_EVAL_WORKFLOW.read_text()
-    lines = content.splitlines(keepends=True)
-
-    # Find the sdk_ref input section and its default line
-    in_sdk_ref_section = False
-    updated = False
-    old_version = None
-
-    for i, line in enumerate(lines):
-        stripped = line.strip()
-
-        # Track when we enter the sdk_ref input section
-        if stripped == "sdk_ref:":
-            in_sdk_ref_section = True
-            continue
-
-        # Track when we exit the sdk_ref section (another input starts)
-        if (
-            in_sdk_ref_section
-            and stripped.endswith(":")
-            and not stripped.startswith("default")
-        ):
-            in_sdk_ref_section = False
-
-        # Update the default line within the sdk_ref section
-        if in_sdk_ref_section:
-            match = SDK_REF_PATTERN.match(line)
-            if match:
-                old_version = line.strip().replace("default: ", "")
-                new_line = f"{match.group(1)}{new_version}{match.group(3) or ''}"
-                if not line.endswith("\n") and lines[i].endswith("\n"):
-                    new_line += "\n"
-                elif line.endswith("\n"):
-                    new_line += "\n"
-                lines[i] = new_line
-                updated = True
-                break
-
-    if not updated:
-        print("❌ Could not find sdk_ref default line to update", file=sys.stderr)
-        return False
-
-    if dry_run:
-        print(f"Would update sdk_ref default: {old_version} → v{new_version}")
-        return True
-
-    # Write the updated content
-    RUN_EVAL_WORKFLOW.write_text("".join(lines))
-    print(f"✅ Updated sdk_ref default: {old_version} → v{new_version}")
-    return True
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description="Update the sdk_ref default value in run-eval.yml"
-    )
-    parser.add_argument(
-        "version",
-        help="New version (without 'v' prefix, e.g., '1.12.0')",
-    )
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Print what would change without modifying the file",
-    )
-    args = parser.parse_args()
-
-    # Validate version format
-    version_pattern = re.compile(r"^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$")
-    if not version_pattern.match(args.version):
-        print(
-            f"❌ Invalid version format: {args.version}. "
-            "Expected: X.Y.Z or X.Y.Z-suffix",
-            file=sys.stderr,
-        )
-        return 1
-
-    success = update_sdk_ref_default(args.version, dry_run=args.dry_run)
-    return 0 if success else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/workflows/README-RELEASE.md

@@ -1,125 +0,0 @@
-# Release Automation Workflows
-
-This document describes the automated release workflows for the OpenHands Software Agent SDK.
-
-## Overview
-
-The release process has been automated with two GitHub Actions workflows:
-
-1. **prepare-release.yml** - Prepares a release PR with version updates
-2. **pypi-release.yml** - Automatically publishes packages to PyPI when a release is created
-
-## How to Create a New Release
-
-### Step 1: Trigger the Prepare Release Workflow
-
-1. Go to the [Actions tab](https://github.com/OpenHands/software-agent-sdk/actions)
-2. Select **"Prepare Release"** workflow from the left sidebar
-3. Click **"Run workflow"** button
-4. Enter the version number (e.g., `1.2.3`) - must be in format `X.Y.Z`
-5. Click **"Run workflow"**
-
-The workflow will automatically:
-- ✅ Create a new branch named `rel-X.Y.Z`
-- ✅ Update all package versions using `make set-package-version`
-- ✅ Commit the changes
-- ✅ Push the branch
-- ✅ Create a PR with labels `integration-tests` and `test-examples`
-
-### Step 2: Review the PR
-
-The created PR will include a checklist. Complete the following:
-
-- [ ] Fix any deprecation deadlines if they exist
-- [ ] Verify integration tests pass (triggered by `integration-tests` label)
-- [ ] Verify example checks pass (triggered by `test-examples` label)
-- [ ] Review and approve the PR
-
-### Step 3: Create the GitHub Release
-
-1. Go to [Releases](https://github.com/OpenHands/software-agent-sdk/releases/new)
-2. Click **"Draft a new release"**
-3. Configure the release:
-   - **Tag**: `vX.Y.Z` (must match the version)
-   - **Branch**: `rel-X.Y.Z` (the branch created by the workflow)
-   - **Previous tag**: Select the previous release version
-4. Click **"Generate release notes"** to auto-generate the changelog
-5. Review and edit the release notes as needed
-6. Click **"Publish release"**
-
-### Step 4: PyPI Publication (Automated)
-
-Once the release is published, the **pypi-release.yml** workflow will automatically:
-- ✅ Build all packages (openhands-sdk, openhands-tools, openhands-workspace, openhands-agent-server)
-- ✅ Publish them to PyPI
-
-You can monitor the progress in the [Actions tab](https://github.com/OpenHands/software-agent-sdk/actions/workflows/pypi-release.yml).
-
-### Step 5: Version Bump PRs (Automated)
-
-After successful PyPI publication, the workflow will automatically create PRs to update SDK versions in downstream repositories:
-
-- **[OpenHands](https://github.com/All-Hands-AI/OpenHands)** - Updates `openhands-sdk`, `openhands-tools`, and `openhands-agent-server` versions
-- **[OpenHands-CLI](https://github.com/All-Hands-AI/openhands-cli)** - Updates `openhands-sdk` and `openhands-tools` versions
-
-These PRs will:
-- Be created automatically with branch name `bump-sdk-X.Y.Z`
-- Include links back to the SDK release
-- Need to be reviewed and merged by the respective repository maintainers
-
-### Step 6: Post-Release Tasks
-
-- [ ] Merge the release PR to main
-- [ ] Review and merge the auto-created version bump PRs in OpenHands and OpenHands-CLI
-- [ ] Run evaluation on OpenHands Index (manual step)
-- [ ] Announce the release
-
-## Manual PyPI Release (If Needed)
-
-If you need to manually trigger the PyPI release workflow:
-
-1. Go to the [Actions tab](https://github.com/OpenHands/software-agent-sdk/actions)
-2. Select **"Publish all OpenHands packages (uv)"** workflow
-3. Click **"Run workflow"**
-4. Select the branch/tag you want to publish from
-5. Click **"Run workflow"**
-
-## Workflow Files
-
-- `.github/workflows/prepare-release.yml` - Automated release preparation
-- `.github/workflows/pypi-release.yml` - PyPI package publication
-
-## Troubleshooting
-
-### Version Format Error
-
-If you get a version format error, ensure you're using the format `X.Y.Z` (e.g., `1.2.3`), not `vX.Y.Z`.
-
-### PR Creation Failed
-
-If the PR creation fails, check:
-- The branch doesn't already exist
-- You have proper permissions
-- The `GITHUB_TOKEN` has sufficient permissions
-
-### PyPI Publication Failed
-
-If PyPI publication fails:
-- Check that the `PYPI_TOKEN_OPENHANDS` secret is properly configured
-- Verify the version doesn't already exist on PyPI
-- Check the workflow logs for specific error messages
-
-## Previous Manual Process
-
-For reference, the previous manual release checklist was:
-
-- [ ] Checkout SDK repo, use `make set-package-version version=x.x.x` to set the version
-- [ ] Push to a branch like `rel-x.x.x` and start a PR
-- [ ] Fix any "deprecation deadlines" if they exist
-- [ ] Tag "integration-tests" and make sure integration test all pass
-- [ ] Tag "test-examples" and make sure example checks all pass
-- [ ] Draft a new release
-- [ ] Use workflow to publish to PyPI on tag `v1.X.X`
-- [ ] Evaluation on OpenHands Index
-
-Most of these steps are now automated!

.github/workflows/agent-server-rest-api-breakage.yml

@@ -1,154 +0,0 @@
----
-name: REST API breakage checks
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: [main]
-
-jobs:
-    agent-server-rest-api:
-        name: REST API (OpenAPI)
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-            pull-requests: write
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-
-            - name: Install workspace deps (dev)
-              run: uv sync --frozen --group dev
-
-            - name: Install oasdiff
-              run: |
-                  curl -L https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh -s -- -b /usr/local/bin
-                  oasdiff --version
-
-            - name: Run agent server REST API breakage check
-              id: api_breakage
-              # Let this step fail so CI is visibly red on breakage.
-              # Later reporting steps still run because they use if: always().
-              run: |
-                  uv run --with packaging python .github/scripts/check_agent_server_rest_api_breakage.py 2>&1 | tee api-breakage.log
-                  exit_code=${PIPESTATUS[0]}
-                  echo "exit_code=${exit_code}" >> "$GITHUB_OUTPUT"
-                  exit "${exit_code}"
-
-            - name: Write REST API breakage summary
-              if: ${{ always() }}
-              env:
-                  EXIT_CODE: ${{ steps.api_breakage.outputs.exit_code }}
-                  IS_FORK: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository }}
-                  LOG_PATH: api-breakage.log
-                  RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-              run: |
-                  python3 <<'PY' >> "$GITHUB_STEP_SUMMARY"
-                  import os
-                  from pathlib import Path
-
-                  exit_code = int(os.environ.get('EXIT_CODE', '0') or '0')
-                  is_fork = os.environ.get('IS_FORK', 'false') == 'true'
-                  run_url = os.environ['RUN_URL']
-                  status = '✅ **PASSED**' if exit_code == 0 else '❌ **FAILED**'
-
-                  print(f'## REST API breakage checks (OpenAPI) — {status}')
-                  print()
-                  print(f"**Result:** {status}")
-                  if exit_code != 0:
-                      print()
-                      print('> ⚠️ Breaking REST API changes or policy violations detected.')
-                  print()
-
-                  if is_fork:
-                      print(
-                          '_Fork PR detected: sticky PR comment was skipped because '
-                          'the GitHub token is read-only for `pull_request` workflows '
-                          'from forks._'
-                      )
-                      print()
-
-                  if exit_code != 0:
-                      try:
-                          log = Path(os.environ['LOG_PATH']).read_text()
-                      except Exception as exc:
-                          log = f'Unable to read log file: {exc}'
-
-                      excerpt = log[:1000].replace('```', '``\\`')
-                      print('<details><summary>Log excerpt (first 1000 characters)</summary>')
-                      print()
-                      print('```text')
-                      print(excerpt)
-                      print('```')
-                      print()
-                      print('</details>')
-                      print()
-
-                  print(f'[Action log]({run_url})')
-                  PY
-
-            - name: Post REST API breakage report to PR
-              if: ${{ always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
-              uses: actions/github-script@v8
-              env:
-                  EXIT_CODE: ${{ steps.api_breakage.outputs.exit_code }}
-                  LOG_PATH: api-breakage.log
-              with:
-                  script: |
-                      const fs = require('fs');
-
-                      const marker = '<!-- agent-server-rest-api-breakage-report -->';
-                      const exitCode = Number(process.env.EXIT_CODE || '0');
-                      const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
-                      const status = exitCode === 0 ? '✅ **PASSED**' : '❌ **FAILED**';
-
-                      let body = `${marker}\n## REST API breakage checks (OpenAPI) — ${status}\n\n**Result:** ${status}\n`;
-
-                      if (exitCode !== 0) {
-                        body += `\n> ⚠️ Breaking REST API changes or policy violations detected.\n`;
-                        let log = '';
-                        try {
-                          log = fs.readFileSync(process.env.LOG_PATH, 'utf8');
-                        } catch (e) {
-                          log = `Unable to read log file: ${e}`;
-                        }
-
-                        const excerpt = log.slice(0, 1000).replace(/```/g, '``\\`');
-                        body += `\n<details><summary>Log excerpt (first 1000 characters)</summary>\n\n\`\`\`text\n${excerpt}\n\`\`\`\n\n</details>\n`;
-                      }
-
-                      body += `\n[Action log](${runUrl})\n`;
-
-                      const { owner, repo } = context.repo;
-                      const issue_number = context.issue.number;
-                      const { data: comments } = await github.rest.issues.listComments({
-                        owner,
-                        repo,
-                        issue_number,
-                        per_page: 100,
-                      });
-
-                      const existing = comments.find((c) => c.body && c.body.includes(marker));
-                      if (existing) {
-                        await github.rest.issues.updateComment({
-                          owner,
-                          repo,
-                          comment_id: existing.id,
-                          body,
-                        });
-                      } else {
-                        await github.rest.issues.createComment({
-                          owner,
-                          repo,
-                          issue_number,
-                          body,
-                        });
-                      }

.github/workflows/api-breakage.yml

@@ -1,149 +0,0 @@
----
-name: Python API breakage checks
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: [main]
-
-jobs:
-    sdk-api:
-        name: Python API
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-            pull-requests: write
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-            - name: Install workspace deps (dev)
-              run: uv sync --frozen --group dev
-            - name: Run Python API breakage check
-              id: api_breakage
-              # Let this step fail so CI is visibly red on breakage.
-              # Later reporting steps still run because they use if: always().
-              env:
-                  ACP_VERSION_CHECK_BASE_REF: ${{ github.event_name == 'pull_request' && github.base_ref || github.event.before }}
-                  ACP_VERSION_CHECK_SKIP: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.body || '', 'skip-acp-check') 
-                      }}
-              run: |
-                  uv run python .github/scripts/check_sdk_api_breakage.py 2>&1 | tee api-breakage.log
-                  exit_code=${PIPESTATUS[0]}
-                  echo "exit_code=${exit_code}" >> "$GITHUB_OUTPUT"
-                  exit "${exit_code}"
-            - name: Write API breakage summary
-              if: ${{ always() }}
-              env:
-                  EXIT_CODE: ${{ steps.api_breakage.outputs.exit_code }}
-                  IS_FORK: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository }}
-                  LOG_PATH: api-breakage.log
-                  RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-              run: |
-                  python3 <<'PY' >> "$GITHUB_STEP_SUMMARY"
-                  import os
-                  from pathlib import Path
-
-                  exit_code = int(os.environ.get('EXIT_CODE', '0') or '0')
-                  is_fork = os.environ.get('IS_FORK', 'false') == 'true'
-                  run_url = os.environ['RUN_URL']
-                  status = '✅ **PASSED**' if exit_code == 0 else '❌ **FAILED**'
-
-                  print(f'## Python API breakage checks — {status}')
-                  print()
-                  print(f"**Result:** {status}")
-                  if exit_code != 0:
-                      print()
-                      print('> ⚠️ Breaking API changes or policy violations detected.')
-                  print()
-
-                  if is_fork:
-                      print(
-                          '_Fork PR detected: sticky PR comment was skipped because '
-                          'the GitHub token is read-only for `pull_request` workflows '
-                          'from forks._'
-                      )
-                      print()
-
-                  if exit_code != 0:
-                      try:
-                          log = Path(os.environ['LOG_PATH']).read_text()
-                      except Exception as exc:
-                          log = f'Unable to read log file: {exc}'
-
-                      excerpt = log[:1000].replace('```', '``\\`')
-                      print('<details><summary>Log excerpt (first 1000 characters)</summary>')
-                      print()
-                      print('```text')
-                      print(excerpt)
-                      print('```')
-                      print()
-                      print('</details>')
-                      print()
-
-                  print(f'[Action log]({run_url})')
-                  PY
-
-            - name: Post API breakage report to PR
-              if: ${{ always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
-              uses: actions/github-script@v8
-              env:
-                  EXIT_CODE: ${{ steps.api_breakage.outputs.exit_code }}
-                  LOG_PATH: api-breakage.log
-              with:
-                  script: |
-                      const fs = require('fs');
-
-                      const marker = '<!-- api-breakage-report -->';
-                      const exitCode = Number(process.env.EXIT_CODE || '0');
-                      const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
-                      const status = exitCode === 0 ? '✅ **PASSED**' : '❌ **FAILED**';
-
-                      let body = `${marker}\n## Python API breakage checks — ${status}\n\n**Result:** ${status}\n`;
-
-                      if (exitCode !== 0) {
-                        body += `\n> ⚠️ Breaking API changes or policy violations detected.\n`;
-                        let log = '';
-                        try {
-                          log = fs.readFileSync(process.env.LOG_PATH, 'utf8');
-                        } catch (e) {
-                          log = `Unable to read log file: ${e}`;
-                        }
-
-                        const excerpt = log.slice(0, 1000).replace(/```/g, '``\\`');
-                        body += `\n<details><summary>Log excerpt (first 1000 characters)</summary>\n\n\`\`\`text\n${excerpt}\n\`\`\`\n\n</details>\n`;
-                      }
-
-                      body += `\n[Action log](${runUrl})\n`;
-
-                      const { owner, repo } = context.repo;
-                      const issue_number = context.issue.number;
-                      const { data: comments } = await github.rest.issues.listComments({
-                        owner,
-                        repo,
-                        issue_number,
-                        per_page: 100,
-                      });
-
-                      const existing = comments.find((c) => c.body && c.body.includes(marker));
-                      if (existing) {
-                        await github.rest.issues.updateComment({
-                          owner,
-                          repo,
-                          comment_id: existing.id,
-                          body,
-                        });
-                      } else {
-                        await github.rest.issues.createComment({
-                          owner,
-                          repo,
-                          issue_number,
-                          body,
-                        });
-                      }

.github/workflows/api-compliance-runner.yml

@@ -1,130 +0,0 @@
----
-name: API Compliance Tests
-
-on:
-    pull_request:
-        types: [labeled]
-    workflow_dispatch:
-        inputs:
-            reason:
-                description: Reason for running compliance tests
-                required: true
-            patterns:
-                description: Comma-separated patterns to test (empty = all)
-                required: false
-            models:
-                description: Comma-separated model IDs (empty = all defaults)
-                required: false
-
-env:
-    # Default models to test (matches DEFAULT_MODELS in run_compliance.py)
-    DEFAULT_MODELS: claude-sonnet-4-5,gpt-5.2,gemini-3-pro
-
-jobs:
-    run-compliance-tests:
-        # Only run on api-compliance-test label or workflow_dispatch
-        if: |
-            github.event_name == 'workflow_dispatch' ||
-            (github.event_name == 'pull_request' && github.event.label.name == 'api-compliance-test')
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-            pull-requests: write
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
-                  ref: ${{ github.event.pull_request.head.sha || github.ref }}
-                  persist-credentials: false
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Install dependencies
-              run: uv sync --dev
-
-            - name: Determine test parameters
-              id: params
-              run: |
-                  # Use input values or defaults
-                  if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-                    PATTERNS="${{ github.event.inputs.patterns }}"
-                    MODELS="${{ github.event.inputs.models }}"
-                  else
-                    PATTERNS=""
-                    MODELS=""
-                  fi
-
-                  # Build command args
-                  ARGS=""
-                  if [ -n "$PATTERNS" ]; then
-                    ARGS="$ARGS --patterns $PATTERNS"
-                  fi
-                  if [ -n "$MODELS" ]; then
-                    ARGS="$ARGS --models $MODELS"
-                  else
-                    ARGS="$ARGS --models $DEFAULT_MODELS"
-                  fi
-
-                  echo "args=$ARGS" >> $GITHUB_OUTPUT
-
-            - name: Run API compliance tests
-              id: compliance
-              env:
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY_EVAL }}
-                  LLM_BASE_URL: https://llm-proxy.eval.all-hands.dev
-                  GITHUB_RUN_ID: ${{ github.run_id }}
-              run: |
-                  uv run python tests/integration/api_compliance/run_compliance.py \
-                    ${{ steps.params.outputs.args }} \
-                    --output-dir compliance-results/
-              continue-on-error: true  # Tests may "fail" but that's expected
-
-            - name: Upload results
-              uses: actions/upload-artifact@v7
-              with:
-                  name: compliance-results
-                  path: compliance-results/
-                  retention-days: 30
-
-            - name: Post results to PR
-              if: github.event_name == 'pull_request'
-              uses: actions/github-script@v8
-              with:
-                  script: |
-                      const fs = require('fs');
-                      const path = require('path');
-
-                      // Find the report directory
-                      const resultsDir = 'compliance-results';
-                      const dirs = fs.readdirSync(resultsDir);
-                      if (dirs.length === 0) {
-                        console.log('No results found');
-                        return;
-                      }
-
-                      const latestDir = path.join(resultsDir, dirs[0]);
-                      const reportPath = path.join(latestDir, 'compliance_report.md');
-
-                      if (!fs.existsSync(reportPath)) {
-                        console.log('Report not found at', reportPath);
-                        return;
-                      }
-
-                      let report = fs.readFileSync(reportPath, 'utf8');
-
-                      // Truncate if too long
-                      if (report.length > 60000) {
-                        report = report.substring(0, 60000) + '\n\n... (truncated)';
-                      }
-
-                      await github.rest.issues.createComment({
-                        owner: context.repo.owner,
-                        repo: context.repo.repo,
-                        issue_number: context.payload.pull_request.number,
-                        body: report
-                      });

.github/workflows/assign-reviews.yml

@@ -1,224 +0,0 @@
----
-# To set this up:
-#  1. Change the name below to something relevant to your task
-#  2. Modify the "env" section below with your prompt
-#  3. Add your LLM_API_KEY to the repository secrets
-#  4. Commit this file to your repository
-#  5. Trigger the workflow manually or set up a schedule
-name: Assign Reviews
-
-on:
-    # Manual trigger
-    workflow_dispatch:
-    # Scheduled trigger (disabled by default, uncomment and customize as needed)
-    schedule:
-      # Run at 12 PM UTC every day
-        - cron: 0 12 * * *
-
-permissions:
-    contents: write
-    pull-requests: write
-    issues: write
-
-jobs:
-    run-task:
-        # Only run scheduled jobs in the main repository, not in forks
-        if: github.repository == 'OpenHands/software-agent-sdk' || github.event_name == 'workflow_dispatch'
-        runs-on: ubuntu-24.04
-        env:
-            # Configuration (modify these values as needed)
-            AGENT_SCRIPT_URL: https://raw.githubusercontent.com/OpenHands/agent-sdk/main/examples/03_github_workflows/01_basic_action/agent_script.py
-            # Provide either PROMPT_LOCATION (URL/file) OR PROMPT_STRING (direct text), not both
-            # Option 1: Use a URL or file path for the prompt
-            PROMPT_LOCATION: ''
-            # PROMPT_LOCATION: 'https://example.com/prompts/maintenance.txt'
-            # Option 2: Use direct text for the prompt
-            PROMPT_STRING: >
-                Use GITHUB_TOKEN and the github API to organize open pull requests and issues in the repo.
-                Read the sections below in order, and perform each in order. Do NOT take action
-                on the same issue or PR twice.
-
-                # Issues with needs-info - Check for OP Response
-
-                Find all open issues that have the "needs-info" label. For each issue:
-                1. Identify the original poster (issue author)
-                2. Check if there are any comments from the original poster AFTER the "needs-info" label was added
-                3. To determine when the label was added, use: GET /repos/{owner}/{repo}/issues/{issue_number}/timeline
-                   and look for "labeled" events with the label "needs-info"
-                4. If the original poster has commented after the label was added:
-                   - Remove the "needs-info" label
-                   - Add the "needs-triage" label
-                # Issues with needs-triage
-
-                Find all open issues that have the "needs-triage" label. For each issue that has been in this state for more than 2 days:
-                1. First, check if the issue has already been triaged by verifying it does NOT have:
-                   - The "enhancement" label
-                   - Any "priority" label (priority:low, priority:medium, priority:high, etc.)
-                2. If the issue has already been triaged (has enhancement or priority label), remove the "needs-triage" label
-                3. For issues that have NOT been triaged yet:
-                   - Read the issue description and comments
-                   - Check if it is a bug report, feature request, or question and add the appropriate label
-                   - If it is a bug report and it does not have a priority label
-                     * Read the MAINTAINERS file in the repository root to get the list of maintainers
-                     * Extract all usernames from lines starting with "- @" and join them with spaces, each prefixed with @
-                       (e.g., if the file contains "- @user1" and "- @user2", format as "@user1 @user2")
-                     * Tag ALL maintainers with: "[Automatic Post]: This issue has been waiting for triage. <maintainers>, could you
-                please take a look and add the appropriate priority label when you have a chance?"
-                       (Replace <maintainers> with the formatted list from the previous step)
-
-                # Need Reviewer Action
-
-                Find all open PRs where:
-                1. The PR is waiting for review (there are no open review comments or change requests)
-                2. The PR is in a "clean" state (CI passing, no merge conflicts)
-                3. The PR is not marked as draft (draft: false)
-                4. The PR has had no activity (comments, commits, reviews) for more than 3 days.
-
-                In this case, send a message to the reviewers:
-                [Automatic Post]: This PR seems to be currently waiting for review.
-                {reviewer_names}, could you please take a look when you have a chance?
-
-                # Need Author Action
-
-                Find all open PRs where the most recent change or comment was made on the pull
-                request more than 5 days ago (use 14 days if the PR is marked as draft).
-
-                And send a message to the author:
-
-                [Automatic Post]: It has been a while since there was any activity on this PR.
-                {author}, are you still working on it? If so, please go ahead, if not then
-                please request review, close it, or request that someone else follow up.
-
-                # Need Reviewers
-
-                Find all open pull requests that TRULY have NO reviewers assigned. To do this correctly:
-
-                1. Use the GitHub API to fetch PR details: GET /repos/{owner}/{repo}/pulls/{pull_number}
-                2. Check the "requested_reviewers" and "requested_teams" arrays
-                3. ALSO check for submitted reviews: GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews
-                4. A PR needs reviewers ONLY if ALL of these are true:
-                   - The "requested_reviewers" array is empty (no pending review requests)
-                   - The "requested_teams" array is empty (no pending team review requests)
-                   - The reviews array is empty (no reviews have been submitted yet)
-                5. IMPORTANT: If ANY of these has entries, SKIP this PR - it already has or had reviewers!
-
-                Example API responses showing a PR that DOES NOT need reviewers (skip this):
-
-                Case 1 - Has requested reviewers:
-                GET /pulls/{number}: {"requested_reviewers": [{"login": "someuser"}], "requested_teams": []}
-
-                Case 2 - Has submitted reviews (even if requested_reviewers is empty):
-                GET /pulls/{number}: {"requested_reviewers": [], "requested_teams": []}
-                GET /pulls/{number}/reviews: [{"user": {"login": "someuser"}, "state": "COMMENTED"}]
-
-                Example API response showing a PR that DOES need reviewers (process this):
-                GET /pulls/{number}: {"requested_reviewers": [], "requested_teams": []}
-                GET /pulls/{number}/reviews: []
-
-                Additional criteria for PRs that need reviewers:
-                1. Are not marked as draft (draft: false)
-                2. Were created more than 1 day ago
-                3. CI is passing and there are no merge conflicts
-
-                For each PR that truly has NO reviewers:
-                1) Read git blame for changed files to identify recent, active contributors.
-                2) From those candidates, ONLY consider maintainers — repository collaborators with write access or higher. Verify via the GitHub API before
-                requesting review:
-                   - Preferred: GET /repos/{owner}/{repo}/collaborators (no permission filter). Filter client-side using either:
-                     role_name in ["write", "maintain", "admin"] OR permissions.push || permissions.admin. Note: paginate if > 30 collaborators.
-                   - Alternative: GET /repos/{owner}/{repo}/collaborators/{username}/permission and accept if permission in {push, maintain, admin}.
-                3) If multiple maintainers qualify, avoid assigning too many reviews to any single one.
-                4) Request review from exactly one maintainer and add this message:
-
-                [Automatic Post]: I have assigned {reviewer} as a reviewer based on git blame information.
-                Thanks in advance for the help!
-
-            LLM_MODEL: litellm_proxy/claude-sonnet-4-5-20250929
-            LLM_BASE_URL: https://llm-proxy.app.all-hands.dev
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-
-            - name: Install OpenHands dependencies
-              run: |
-                  # Install OpenHands SDK and tools from git repository
-                  uv pip install --system "openhands-sdk @ git+https://github.com/OpenHands/agent-sdk.git@main#subdirectory=openhands-sdk"
-                  uv pip install --system "openhands-tools @ git+https://github.com/OpenHands/agent-sdk.git@main#subdirectory=openhands-tools"
-
-            - name: Check required configuration
-              env:
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
-              run: |
-                  if [ -z "$LLM_API_KEY" ]; then
-                    echo "Error: LLM_API_KEY secret is not set."
-                    exit 1
-                  fi
-
-                  # Check that exactly one of PROMPT_LOCATION or PROMPT_STRING is set
-                  if [ -n "$PROMPT_LOCATION" ] && [ -n "$PROMPT_STRING" ]; then
-                    echo "Error: Both PROMPT_LOCATION and PROMPT_STRING are set."
-                    echo "Please provide only one in the env section of the workflow file."
-                    exit 1
-                  fi
-
-                  if [ -z "$PROMPT_LOCATION" ] && [ -z "$PROMPT_STRING" ]; then
-                    echo "Error: Neither PROMPT_LOCATION nor PROMPT_STRING is set."
-                    echo "Please set one in the env section of the workflow file."
-                    exit 1
-                  fi
-
-                  if [ -n "$PROMPT_LOCATION" ]; then
-                    echo "Prompt location: $PROMPT_LOCATION"
-                  else
-                    echo "Using inline PROMPT_STRING (${#PROMPT_STRING} characters)"
-                  fi
-                  echo "LLM model: $LLM_MODEL"
-                  if [ -n "$LLM_BASE_URL" ]; then
-                    echo "LLM base URL: $LLM_BASE_URL"
-                  fi
-
-            - name: Run task
-              env:
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
-                  GITHUB_TOKEN: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-                  PYTHONPATH: ''
-              run: |
-                  echo "Running agent script: $AGENT_SCRIPT_URL"
-
-                  # Download script if it's a URL
-                  if [[ "$AGENT_SCRIPT_URL" =~ ^https?:// ]]; then
-                    echo "Downloading agent script from URL..."
-                    curl -sSL "$AGENT_SCRIPT_URL" -o /tmp/agent_script.py
-                    AGENT_SCRIPT_PATH="/tmp/agent_script.py"
-                  else
-                    AGENT_SCRIPT_PATH="$AGENT_SCRIPT_URL"
-                  fi
-
-                  # Run with appropriate prompt argument
-                  if [ -n "$PROMPT_LOCATION" ]; then
-                    echo "Using prompt from: $PROMPT_LOCATION"
-                    uv run python "$AGENT_SCRIPT_PATH" "$PROMPT_LOCATION"
-                  else
-                    echo "Using PROMPT_STRING (${#PROMPT_STRING} characters)"
-                    uv run python "$AGENT_SCRIPT_PATH"
-                  fi
-
-            - name: Upload logs as artifact
-              uses: actions/upload-artifact@v7
-              if: always()
-              with:
-                  name: openhands-task-logs
-                  path: |
-                      *.log
-                      output/
-                  retention-days: 7

.github/workflows/auto-label-issues.yml

@@ -1,36 +0,0 @@
----
-name: Auto-label New Issues
-
-on:
-    issues:
-        types: [opened]
-
-permissions:
-    issues: write
-
-jobs:
-    add-triage-label:
-        runs-on: ubuntu-latest
-        steps:
-            - name: Add needs-triage label
-              uses: actions/github-script@v8
-              with:
-                  github-token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-                  script: |
-                      // Get the issue details
-                      const issue = context.payload.issue;
-                      const labels = issue.labels.map(label => label.name);
-
-                      // Check if issue has already been triaged
-                      const hasEnhancement = labels.includes('enhancement');
-                      const hasPriority = labels.some(label => label.startsWith('priority'));
-
-                      // Only add needs-triage if not already triaged
-                      if (!hasEnhancement && !hasPriority) {
-                        await github.rest.issues.addLabels({
-                          owner: context.repo.owner,
-                          repo: context.repo.repo,
-                          issue_number: context.issue.number,
-                          labels: ['needs-triage']
-                        });
-                      }

.github/workflows/check-docstrings.yml

@@ -1,25 +0,0 @@
----
-# .github/workflows/check-docstrings.yml
-name: Check Docstrings
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: ['**']
-
-jobs:
-    check-docstrings:
-        runs-on: ubuntu-24.04
-
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@v5
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Check docstring formatting
-              run: python .github/scripts/check_docstrings.py

.github/workflows/check-documented-examples.yml

@@ -1,59 +0,0 @@
----
-name: '[Optional] Docs example'
-
-on:
-    pull_request:
-        branches:
-            - '**'
-        paths:
-            - examples/**/*.py
-            - '!examples/03_github_workflows/**'
-            - '!examples/04_llm_specific_tools/**'
-            - .github/workflows/check-documented-examples.yml
-            - .github/scripts/check_documented_examples.py
-    workflow_dispatch:
-
-permissions:
-    contents: read
-    pull-requests: read
-
-jobs:
-    check-examples:
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout agent-sdk repository
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0
-
-            - name: Checkout docs repository (try feature branch)
-              uses: actions/checkout@v5
-              continue-on-error: true
-              id: checkout-feature
-              with:
-                  repository: OpenHands/docs
-                  path: docs
-                  fetch-depth: 0
-                  ref: ${{ github.head_ref || github.ref_name }}
-
-            - name: Checkout docs repository (fallback to main)
-              if: steps.checkout-feature.outcome == 'failure'
-              uses: actions/checkout@v5
-              with:
-                  repository: OpenHands/docs
-                  path: docs
-                  fetch-depth: 0
-                  ref: main
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Check documented examples
-              env:
-                  DOCS_PATH: ${{ github.workspace }}/docs
-              shell: bash
-              run: |
-                  set -euo pipefail
-                  python .github/scripts/check_documented_examples.py

.github/workflows/check-duplicate-examples.yml

@@ -1,35 +0,0 @@
----
-name: Check duplicate example numbers
-
-on:
-    pull_request:
-        branches:
-            - '**'
-        paths:
-            - examples/**
-            - .github/workflows/check-duplicate-examples.yml
-            - .github/scripts/check_duplicate_example_numbers.py
-    push:
-        branches:
-            - main
-        paths:
-            - examples/**
-    workflow_dispatch:
-
-permissions:
-    contents: read
-
-jobs:
-    check-duplicates:
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Check for duplicate example numbers
-              run: python .github/scripts/check_duplicate_example_numbers.py

.github/workflows/clean-up.yml

@@ -0,0 +1,69 @@
+# Workflow that cleans up outdated and old workflows to prevent out of disk issues
+name: Delete old workflow runs
+
+# This workflow is currently only triggered manually
+on:
+  workflow_dispatch:
+    inputs:
+      days:
+        description: 'Days-worth of runs to keep for each workflow'
+        required: true
+        default: '30'
+      minimum_runs:
+        description: 'Minimum runs to keep for each workflow'
+        required: true
+        default: '10'
+      delete_workflow_pattern:
+        description: 'Name or filename of the workflow (if not set, all workflows are targeted)'
+        required: false
+      delete_workflow_by_state_pattern:
+        description: 'Filter workflows by state: active, deleted, disabled_fork, disabled_inactivity, disabled_manually'
+        required: true
+        default: "ALL"
+        type: choice
+        options:
+          - "ALL"
+          - active
+          - deleted
+          - disabled_inactivity
+          - disabled_manually
+      delete_run_by_conclusion_pattern:
+        description: 'Remove runs based on conclusion: action_required, cancelled, failure, skipped, success'
+        required: true
+        default: 'ALL'
+        type: choice
+        options:
+          - 'ALL'
+          - 'Unsuccessful: action_required,cancelled,failure,skipped'
+          - action_required
+          - cancelled
+          - failure
+          - skipped
+          - success
+      dry_run:
+        description: 'Logs simulated changes, no deletions are performed'
+        required: false
+
+jobs:
+  del_runs:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: read
+    steps:
+      - name: Delete workflow runs
+        uses: Mattraks/delete-workflow-runs@v2
+        with:
+          token: ${{ github.token }}
+          repository: ${{ github.repository }}
+          retain_days: ${{ github.event.inputs.days }}
+          keep_minimum_runs: ${{ github.event.inputs.minimum_runs }}
+          delete_workflow_pattern: ${{ github.event.inputs.delete_workflow_pattern }}
+          delete_workflow_by_state_pattern: ${{ github.event.inputs.delete_workflow_by_state_pattern }}
+          delete_run_by_conclusion_pattern: >-
+            ${{
+              startsWith(github.event.inputs.delete_run_by_conclusion_pattern, 'Unsuccessful:')
+              && 'action_required,cancelled,failure,skipped'
+              || github.event.inputs.delete_run_by_conclusion_pattern
+            }}
+          dry_run: ${{ github.event.inputs.dry_run }}

.github/workflows/condenser-runner.yml

@@ -1,244 +0,0 @@
----
-name: Run Condenser Tests
-
-on:
-    # Use pull_request_target to access secrets even on fork PRs
-    # This is safe because we only run when the 'condenser-test' label is added by a maintainer
-    pull_request_target:
-        types:
-            - labeled
-    workflow_dispatch:
-        inputs:
-            reason:
-                description: Reason for manual trigger
-                required: true
-                default: ''
-
-env:
-    N_PROCESSES: 2 # Fewer parallel processes for condenser tests (only 2 LLMs)
-
-jobs:
-    post-initial-comment:
-        if: >
-            github.event_name == 'pull_request_target' &&
-            github.event.label.name == 'condenser-test'
-        runs-on: ubuntu-latest
-        permissions:
-            pull-requests: write
-        steps:
-            - name: Comment on PR
-              uses: KeisukeYamashita/create-comment@v1
-              with:
-                  unique: false
-                  comment: |
-                      Hi! I started running the condenser tests on your PR. You will receive a comment with the results shortly.
-
-                      Note: These are non-blocking tests that validate condenser functionality across different LLMs.
-
-    run-condenser-tests:
-        # Security: Only run when condenser-test label is present or via workflow_dispatch
-        # This prevents automatic execution on fork PRs without maintainer approval
-        if: |
-            always() && (
-                (
-                    github.event_name == 'pull_request_target' &&
-                    github.event.label.name == 'condenser-test'
-                ) ||
-                github.event_name == 'workflow_dispatch'
-            )
-        runs-on: ubuntu-22.04
-        permissions:
-            contents: read
-            id-token: write
-            pull-requests: write
-        strategy:
-            matrix:
-                python-version: ['3.13']
-                job-config:
-                    # Only run against 2 LLMs for condenser tests:
-                    # - Claude Opus 4.5 (primary - supports thinking blocks)
-                    # - GPT-5.1 Codex Max (secondary - cross-LLM validation)
-                    - name: Claude Opus 4.5
-                      run-suffix: opus_condenser_run
-                      llm-config:
-                          model: litellm_proxy/anthropic/claude-opus-4-5-20251101
-                          extended_thinking: true
-                    - name: GPT-5.1 Codex Max
-                      run-suffix: gpt51_condenser_run
-                      llm-config:
-                          model: litellm_proxy/gpt-5.1-codex-max
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  # For pull_request_target: checkout fork PR code (requires explicit repository)
-                  # For other events: fallback to current repository and ref
-                  repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
-                  ref: ${{ github.event.pull_request.head.sha || github.ref }}
-                  # Security: Don't persist credentials to prevent untrusted PR code from using them
-                  persist-credentials: false
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: ${{ matrix.python-version }}
-
-            - name: Install Python dependencies using uv
-              run: |
-                  uv sync --dev
-                  uv pip install pytest
-
-            - name: Run condenser test evaluation for ${{ matrix.job-config.name }}
-              env:
-                  LLM_CONFIG: ${{ toJson(matrix.job-config.llm-config) }}
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
-                  LLM_BASE_URL: https://llm-proxy.app.all-hands.dev
-              run: |
-                  set -eo pipefail
-
-                  AGENT_SDK_VERSION=$(git rev-parse --short HEAD)
-                  EVAL_NOTE="${AGENT_SDK_VERSION}_${{ matrix.job-config.run-suffix }}"
-
-                  echo "Running condenser tests only (c*.py pattern)"
-
-                  uv run python tests/integration/run_infer.py \
-                    --llm-config "$LLM_CONFIG" \
-                    --num-workers $N_PROCESSES \
-                    --eval-note "$EVAL_NOTE" \
-                    --test-type condenser
-
-                  # get condenser tests JSON results
-                  RESULTS_FILE=$(find tests/integration/outputs/*${{ matrix.job-config.run-suffix }}* -name "results.json" -type f | head -n 1)
-                  echo "RESULTS_FILE: $RESULTS_FILE"
-                  if [ -f "$RESULTS_FILE" ]; then
-                    echo "JSON_RESULTS_FILE=$RESULTS_FILE" >> $GITHUB_ENV
-                  else
-                    echo "JSON_RESULTS_FILE=" >> $GITHUB_ENV
-                  fi
-
-            - name: Wait a little bit
-              run: sleep 10
-
-            - name: Create archive of evaluation outputs
-              run: |
-                  TIMESTAMP=$(date +'%y-%m-%d-%H-%M')
-                  cd tests/integration/outputs  # Change to the outputs directory
-                  tar -czvf ../../../condenser_tests_${{ matrix.job-config.run-suffix }}_${TIMESTAMP}.tar.gz *${{ matrix.job-config.run-suffix }}* # Include result directories for this model
-
-            - name: Upload evaluation results as artifact
-              uses: actions/upload-artifact@v7
-              id: upload_results_artifact
-              with:
-                  name: condenser-test-outputs-${{ matrix.job-config.run-suffix }}-${{ github.run_id }}-${{ github.run_attempt }}
-                  path: condenser_tests_${{ matrix.job-config.run-suffix }}_*.tar.gz
-
-            - name: Save test results for consolidation
-              run: |
-                  # Copy the structured JSON results file for consolidation
-                  mkdir -p test_results_summary
-
-                  if [ -n "${{ env.JSON_RESULTS_FILE }}" ] && [ -f "${{ env.JSON_RESULTS_FILE }}" ]; then
-                    # Copy the JSON results file directly
-                    cp "${{ env.JSON_RESULTS_FILE }}" "test_results_summary/${{ matrix.job-config.run-suffix }}_results.json"
-                    echo "✓ Copied JSON results file for consolidation"
-                  else
-                    echo "✗ No JSON results file found"
-                    exit 1
-                  fi
-
-            - name: Upload test results summary
-              uses: actions/upload-artifact@v7
-              with:
-                  name: test-results-${{ matrix.job-config.run-suffix }}
-                  path: test_results_summary/${{ matrix.job-config.run-suffix }}_results.json
-
-    consolidate-results:
-        needs: run-condenser-tests
-        if: |
-            always() && (
-                (
-                    github.event_name == 'pull_request_target' &&
-                    github.event.label.name == 'condenser-test'
-                ) ||
-                github.event_name == 'workflow_dispatch'
-            )
-        runs-on: ubuntu-24.04
-        permissions:
-            contents: read
-            pull-requests: write
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  # When using pull_request_target, explicitly checkout the PR branch
-                  # This ensures we use the scripts from the actual PR code
-                  ref: ${{ github.event.pull_request.head.sha || github.ref }}
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Install Python dependencies using uv
-              run: |
-                  uv sync --dev
-
-            - name: Download all test results
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: test-results-*
-                  merge-multiple: true
-                  path: all_results
-
-            - name: Download all condenser test artifacts
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: condenser-test-outputs-*
-                  path: artifacts
-
-            - name: Consolidate test results
-              env:
-                  EVENT_NAME: ${{ github.event_name }}
-                  PR_NUMBER: ${{ github.event.pull_request.number }}
-                  MANUAL_REASON: ${{ github.event.inputs.reason }}
-                  COMMIT_SHA: ${{ github.sha }}
-                  PYTHONPATH: ${{ github.workspace }}
-                  GITHUB_SERVER_URL: ${{ github.server_url }}
-                  GITHUB_REPOSITORY: ${{ github.repository }}
-                  GITHUB_RUN_ID: ${{ github.run_id }}
-              run: |
-                  uv run python tests/integration/utils/consolidate_json_results.py \
-                    --results-dir all_results \
-                    --artifacts-dir artifacts \
-                    --output-file consolidated_results.json
-
-                  echo "Consolidated results generated successfully"
-
-                  uv run python tests/integration/utils/generate_markdown_report.py \
-                    --input-file consolidated_results.json \
-                    --output-file consolidated_report.md
-
-            - name: Upload consolidated report
-              uses: actions/upload-artifact@v7
-              with:
-                  name: consolidated-condenser-report
-                  path: consolidated_report.md
-
-            - name: Create consolidated PR comment
-              if: github.event_name == 'pull_request_target'
-              run: |
-                  # Add header to clarify these are non-blocking tests
-                  echo "## Condenser Test Results (Non-Blocking)" > final_report.md
-                  echo "" >> final_report.md
-                  echo "> These tests validate condenser functionality and do not block PR merges." >> final_report.md
-                  echo "" >> final_report.md
-                  cat consolidated_report.md >> final_report.md
-
-                  # Sanitize @OpenHands mentions to prevent self-mention loops
-                  COMMENT_BODY=$(uv run python -c "from openhands.sdk.utils.github import sanitize_openhands_mentions; import sys; print(sanitize_openhands_mentions(sys.stdin.read()), end='')" < final_report.md)
-                  # Use GitHub CLI to create comment with explicit PR number
-                  echo "$COMMENT_BODY" | gh pr comment ${{ github.event.pull_request.number }} --body-file -
-              env:
-                  GH_TOKEN: ${{ github.token }}

.github/workflows/deploy-docs.yml

@@ -1,23 +1,74 @@
----
-name: Dispatch to docs repo
+# Workflow that builds and deploys the documentation website
+name: Deploy Docs to GitHub Pages
 
+# * Always run on "main"
+# * Run on PRs that target the "main" branch and have changes in the "docs" folder or this workflow
 on:
-    push:
-        branches:
-            - main
-        paths:
-            - openhands-agent-server/**
-    workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+    branches:
+      - main
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
-    dispatch:
-        runs-on: ubuntu-24.04
-        permissions:
-            contents: write
-        steps:
-            - name: Trigger docs repo sync
-              uses: peter-evans/repository-dispatch@v4
-              with:
-                  token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-                  repository: OpenHands/docs
-                  event-type: update
-                  client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'
+  # Build the documentation website
+  build:
+    if: github.repository == 'All-Hands-AI/OpenHands'
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Generate Python Docs
+        run: rm -rf docs/modules/python && pip install pydoc-markdown && pydoc-markdown
+      - name: Install dependencies
+        run: cd docs && npm ci
+      - name: Build website
+        run: cd docs && npm run build
+      - name: Upload Build Artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  # Deploy the documentation website
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.repository == 'All-Hands-AI/OpenHands'
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    # This job only runs on "main" so only run one of these jobs at a time
+    # otherwise it will fail if one is already running
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    needs: build
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/deprecation-check.yml

@@ -1,24 +0,0 @@
----
-name: Deprecation deadlines
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: ['**']
-
-jobs:
-    check:
-        runs-on: ubuntu-24.04
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Verify deprecation removals
-              run: uv run --with packaging python .github/scripts/check_deprecations.py

.github/workflows/dummy-agent-test.yml

@@ -0,0 +1,61 @@
+# Workflow that uses the DummyAgent to run a simple task
+name: Run E2E test with dummy agent
+
+# Always run on "main"
+# Always run on PRs
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          # this might remove tools that are actually needed,
+          # if set to "true" but frees about 6 GB
+          tool-cache: true
+          # all of these default to true, but feel free to set to
+          # "false" if necessary for your workflow
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: false
+          swap-storage: true
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'poetry'
+      - name: Install Python dependencies using Poetry
+        run: poetry install --without evaluation,llama-index
+      - name: Build Environment
+        run: make build
+      - name: Run tests
+        run: |
+          set -e
+          SANDBOX_FORCE_REBUILD_RUNTIME=True poetry run python3 openhands/core/main.py -t "do a flip" -d ./workspace/ -c DummyAgent
+      - name: Check exit code
+        run: |
+          if [ $? -ne 0 ]; then
+            echo "Test failed"
+            exit 1
+          else
+            echo "Test passed"
+          fi

.github/workflows/eval-runner.yml

@@ -0,0 +1,160 @@
+name: Run Evaluation
+
+on:
+  pull_request:
+    types: [labeled]
+  schedule:
+    - cron: "0 1 * * *" # Run daily at 1 AM UTC
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "Reason for manual trigger"
+        required: true
+        default: ""
+
+env:
+  N_PROCESSES: 32 # Global configuration for number of parallel processes for evaluation
+
+jobs:
+  run-evaluation:
+    if: github.event.label.name == 'eval-this' || github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: "read"
+      id-token: "write"
+      pull-requests: "write"
+      issues: "write"
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install poetry via pipx
+        run: pipx install poetry
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "poetry"
+
+      - name: Comment on PR if 'eval-this' label is present
+        if: github.event_name == 'pull_request' && github.event.label.name == 'eval-this'
+        uses: KeisukeYamashita/create-comment@v1
+        with:
+          unique: false
+          comment: |
+            Hi! I started running the evaluation on your PR. You will receive a comment with the results shortly.
+
+      - name: Install Python dependencies using Poetry
+        run: poetry install
+
+      - name: Configure config.toml for evaluation
+        env:
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_LLM_API_KEY }}
+        run: |
+          echo "[llm.eval]" > config.toml
+          echo "model = \"deepseek/deepseek-chat\"" >> config.toml
+          echo "api_key = \"$DEEPSEEK_API_KEY\"" >> config.toml
+          echo "temperature = 0.0" >> config.toml
+
+      - name: Run integration test evaluation
+        env:
+          ALLHANDS_API_KEY: ${{ secrets.ALLHANDS_EVAL_RUNTIME_API_KEY }}
+          RUNTIME: remote
+          SANDBOX_REMOTE_RUNTIME_API_URL: https://runtime.eval.all-hands.dev
+          EVAL_DOCKER_IMAGE_PREFIX: us-central1-docker.pkg.dev/evaluation-092424/swe-bench-images
+
+        run: |
+          poetry run ./evaluation/integration_tests/scripts/run_infer.sh llm.eval HEAD CodeActAgent '' $N_PROCESSES
+
+          # get evaluation report
+          REPORT_FILE=$(find evaluation/evaluation_outputs/outputs/integration_tests/CodeActAgent/deepseek-chat_maxiter_10_N* -name "report.md" -type f | head -n 1)
+          echo "REPORT_FILE: $REPORT_FILE"
+          echo "INTEGRATION_TEST_REPORT<<EOF" >> $GITHUB_ENV
+          cat $REPORT_FILE >> $GITHUB_ENV
+          echo >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+
+      - name: Run SWE-Bench evaluation
+        env:
+          ALLHANDS_API_KEY: ${{ secrets.ALLHANDS_EVAL_RUNTIME_API_KEY }}
+          RUNTIME: remote
+          SANDBOX_REMOTE_RUNTIME_API_URL: https://runtime.eval.all-hands.dev
+          EVAL_DOCKER_IMAGE_PREFIX: us-central1-docker.pkg.dev/evaluation-092424/swe-bench-images
+
+        run: |
+          poetry run ./evaluation/swe_bench/scripts/run_infer.sh llm.eval HEAD CodeActAgent 300 30 $N_PROCESSES "princeton-nlp/SWE-bench_Lite" test
+          OUTPUT_FOLDER=$(find evaluation/evaluation_outputs/outputs/princeton-nlp__SWE-bench_Lite-test/CodeActAgent -name "deepseek-chat_maxiter_50_N_*-no-hint-run_1" -type d | head -n 1)
+          echo "OUTPUT_FOLDER for SWE-bench evaluation: $OUTPUT_FOLDER"
+          poetry run ./evaluation/swe_bench/scripts/eval_infer_remote.sh $OUTPUT_FOLDER/output.jsonl $N_PROCESSES "princeton-nlp/SWE-bench_Lite" test
+
+          poetry run ./evaluation/swe_bench/scripts/eval/summarize_outputs.py $OUTPUT_FOLDER/output.jsonl > summarize_outputs.log 2>&1
+          echo "SWEBENCH_REPORT<<EOF" >> $GITHUB_ENV
+          cat summarize_outputs.log >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+
+      - name: Create tar.gz of evaluation outputs
+        run: |
+          TIMESTAMP=$(date +'%y-%m-%d-%H-%M')
+          tar -czvf evaluation_outputs_${TIMESTAMP}.tar.gz evaluation/evaluation_outputs/outputs
+
+      - name: Upload evaluation results as artifact
+        uses: actions/upload-artifact@v4
+        id: upload_results_artifact
+        with:
+          name: evaluation-outputs
+          path: evaluation_outputs_*.tar.gz
+
+      - name: Get artifact URL
+        run: echo "ARTIFACT_URL=${{ steps.upload_results_artifact.outputs.artifact-url }}" >> $GITHUB_ENV
+
+      - name: Authenticate to Google Cloud
+        uses: 'google-github-actions/auth@v2'
+        with:
+          credentials_json: ${{ secrets.GCP_RESEARCH_OBJECT_CREATOR_SA_KEY }}
+
+      - name: Set timestamp and trigger reason
+        run: |
+          echo "TIMESTAMP=$(date +'%Y-%m-%d-%H-%M')" >> $GITHUB_ENV
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            echo "TRIGGER_REASON=pr-${{ github.event.pull_request.number }}" >> $GITHUB_ENV
+          elif [[ "${{ github.event_name }}" == "schedule" ]]; then
+            echo "TRIGGER_REASON=schedule" >> $GITHUB_ENV
+          else
+            echo "TRIGGER_REASON=manual-${{ github.event.inputs.reason }}" >> $GITHUB_ENV
+          fi
+
+      - name: Upload evaluation results to Google Cloud Storage
+        uses: 'google-github-actions/upload-cloud-storage@v2'
+        with:
+          path: 'evaluation/evaluation_outputs/outputs'
+          destination: 'openhands-oss-eval-results/${{ env.TIMESTAMP }}-${{ env.TRIGGER_REASON }}'
+
+      - name: Comment with evaluation results and artifact link
+        id: create_comment
+        uses: KeisukeYamashita/create-comment@v1
+        with:
+          number: ${{ github.event_name == 'pull_request' && github.event.pull_request.number || 4504 }}
+          unique: false
+          comment: |
+              Trigger by: ${{ github.event_name == 'pull_request' && format('Pull Request (eval-this label on PR #{0})', github.event.pull_request.number) || github.event_name == 'schedule' && 'Daily Schedule' || format('Manual Trigger: {0}', github.event.inputs.reason) }}
+              Commit: ${{ github.sha }}
+              **SWE-Bench Evaluation Report**
+              ${{ env.SWEBENCH_REPORT }}
+              ---
+              **Integration Tests Evaluation Report**
+              ${{ env.INTEGRATION_TEST_REPORT }}
+              ---
+              You can download the full evaluation outputs [here](${{ env.ARTIFACT_URL }}).
+
+      - name: Post to a Slack channel
+        id: slack
+        uses: slackapi/slack-github-action@v1.27.0
+        with:
+          channel-id: 'C07SVQSCR6F'
+          slack-message: "*Evaluation Trigger:* ${{ github.event_name == 'pull_request' && format('Pull Request (eval-this label on PR #{0})', github.event.pull_request.number) || github.event_name == 'schedule' && 'Daily Schedule' || format('Manual Trigger: {0}', github.event.inputs.reason) }}\n\nLink to summary: [here](https://github.com/${{ github.repository }}/issues/${{ github.event_name == 'pull_request' && github.event.pull_request.number || 4504 }}#issuecomment-${{ steps.create_comment.outputs.comment-id }})"
+        env:
+          SLACK_BOT_TOKEN: ${{ secrets.EVAL_NOTIF_SLACK_BOT_TOKEN }}

.github/workflows/fe-unit-tests.yml

@@ -0,0 +1,44 @@
+# Workflow that runs frontend unit tests
+name: Run Frontend Unit Tests
+
+# * Always run on "main"
+# * Run on PRs that have changes in the "frontend" folder or this workflow
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - 'frontend/**'
+      -  '.github/workflows/fe-unit-tests.yml'
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  # Run frontend unit tests
+  fe-test:
+    name: FE Unit Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install dependencies
+        working-directory: ./frontend
+        run: npm ci
+      - name: Run tests and collect coverage
+        working-directory: ./frontend
+        run: npm run test:coverage
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/ghcr-build.yml

@@ -0,0 +1,447 @@
+# Workflow that builds, tests and then pushes the OpenHands and runtime docker images to the ghcr.io repository
+name: Docker
+
+# Always run on "main"
+# Always run on tags
+# Always run on PRs
+# Can also be triggered manually
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: 'Reason for manual trigger'
+        required: true
+        default: ''
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  BASE_IMAGE_FOR_HASH_EQUIVALENCE_TEST: nikolaik/python-nodejs:python3.12-nodejs22
+  RELEVANT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+
+jobs:
+  # Builds the OpenHands Docker images
+  ghcr_build_app:
+    name: Build App Image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      hash_from_app_image: ${{ steps.get_hash_in_app_image.outputs.hash_from_app_image }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          # this might remove tools that are actually needed,
+          # if set to "true" but frees about 6 GB
+          tool-cache: true
+          # all of these default to true, but feel free to set to
+          # "false" if necessary for your workflow
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: false
+          swap-storage: true
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3.0.0
+        with:
+          image: tonistiigi/binfmt:latest
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build and push app image
+        if: "!github.event.pull_request.head.repo.fork"
+        run: |
+          ./containers/build.sh -i openhands -o ${{ github.repository_owner }} --push
+      - name: Build app image
+        if: "github.event.pull_request.head.repo.fork"
+        run: |
+          ./containers/build.sh -i openhands -o ${{ github.repository_owner }} --load
+      - name: Get hash in App Image
+        id: get_hash_in_app_image
+        run: |
+          # Lowercase the repository owner
+          export REPO_OWNER=${{ github.repository_owner }}
+          REPO_OWNER=$(echo $REPO_OWNER | tr '[:upper:]' '[:lower:]')
+          # Run the build script in the app image
+          docker run -e SANDBOX_USER_ID=0 -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/${REPO_OWNER}/openhands:${{ env.RELEVANT_SHA }} /bin/bash -c "mkdir -p containers/runtime; python3 openhands/runtime/utils/runtime_build.py --base_image ${{ env.BASE_IMAGE_FOR_HASH_EQUIVALENCE_TEST }} --build_folder containers/runtime --force_rebuild" 2>&1 | tee docker-outputs.txt
+          # Get the hash from the build script
+          hash_from_app_image=$(cat docker-outputs.txt | grep "Hash for docker build directory" | awk -F "): " '{print $2}' | uniq | head -n1)
+          echo "hash_from_app_image=$hash_from_app_image" >> $GITHUB_OUTPUT
+          echo "Hash from app image: $hash_from_app_image"
+
+  # Builds the runtime Docker images
+  ghcr_build_runtime:
+    name: Build Image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      matrix:
+        base_image:
+          - image: 'nikolaik/python-nodejs:python3.12-nodejs22'
+            tag: nikolaik
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          # this might remove tools that are actually needed,
+          # if set to "true" but frees about 6 GB
+          tool-cache: true
+          # all of these default to true, but feel free to set to
+          # "false" if necessary for your workflow
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: false
+          swap-storage: true
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3.0.0
+        with:
+          image: tonistiigi/binfmt:latest
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.virtualenvs
+          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Install Python dependencies using Poetry
+        run: make install-python-dependencies
+      - name: Create source distribution and Dockerfile
+        run: poetry run python3 openhands/runtime/utils/runtime_build.py --base_image ${{ matrix.base_image.image }} --build_folder containers/runtime --force_rebuild
+      - name: Build and push runtime image ${{ matrix.base_image.image }}
+        if: github.event.pull_request.head.repo.fork != true
+        run: |
+          ./containers/build.sh -i runtime -o ${{ github.repository_owner }} --push -t ${{ matrix.base_image.tag }}
+      # Forked repos can't push to GHCR, so we need to upload the image as an artifact
+      - name: Build runtime image ${{ matrix.base_image.image }} for fork
+        if: github.event.pull_request.head.repo.fork
+        uses: docker/build-push-action@v6
+        with:
+          tags: ghcr.io/all-hands-ai/runtime:${{ env.RELEVANT_SHA }}-${{ matrix.base_image.tag }}
+          outputs: type=docker,dest=/tmp/runtime-${{ matrix.base_image.tag }}.tar
+          context: containers/runtime
+      - name: Upload runtime image for fork
+        if: github.event.pull_request.head.repo.fork
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-${{ matrix.base_image.tag }}
+          path: /tmp/runtime-${{ matrix.base_image.tag }}.tar
+
+  verify_hash_equivalence_in_runtime_and_app:
+    name: Verify Hash Equivalence in Runtime and Docker images
+    runs-on: ubuntu-latest
+    needs: [ghcr_build_runtime, ghcr_build_app]
+    strategy:
+      fail-fast: false
+      matrix:
+        base_image: ['nikolaik']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.virtualenvs
+          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Install Python dependencies using Poetry
+        run: make install-python-dependencies
+      - name: Get hash in App Image
+        run: |
+          echo "Hash from app image: ${{ needs.ghcr_build_app.outputs.hash_from_app_image }}"
+          echo "hash_from_app_image=${{ needs.ghcr_build_app.outputs.hash_from_app_image }}" >> $GITHUB_ENV
+
+      - name: Get hash using code (development mode)
+        run: |
+          mkdir -p containers/runtime
+          poetry run python3 openhands/runtime/utils/runtime_build.py --base_image ${{ env.BASE_IMAGE_FOR_HASH_EQUIVALENCE_TEST }} --build_folder containers/runtime --force_rebuild > output.txt 2>&1
+          hash_from_code=$(cat output.txt | grep "Hash for docker build directory" | awk -F "): " '{print $2}' | uniq | head -n1)
+          echo "hash_from_code=$hash_from_code" >> $GITHUB_ENV
+
+      - name: Compare hashes
+        run: |
+          echo "Hash from App Image: ${{ env.hash_from_app_image }}"
+          echo "Hash from Code: ${{ env.hash_from_code }}"
+          if [ "${{ env.hash_from_app_image }}" = "${{ env.hash_from_code }}" ]; then
+            echo "Hashes match!"
+          else
+            echo "Hashes do not match!"
+            exit 1
+          fi
+
+  # Run unit tests with the EventStream runtime Docker images as root
+  test_runtime_root:
+    name: RT Unit Tests (Root)
+    needs: [ghcr_build_runtime]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        base_image: ['nikolaik']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          # this might remove tools that are actually needed,
+          # if set to "true" but frees about 6 GB
+          tool-cache: true
+          # all of these default to true, but feel free to set to
+          # "false" if necessary for your workflow
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: false
+          swap-storage: true
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      # Forked repos can't push to GHCR, so we need to download the image as an artifact
+      - name: Download runtime image for fork
+        if: github.event.pull_request.head.repo.fork
+        uses: actions/download-artifact@v4
+        with:
+          name: runtime-${{ matrix.base_image }}
+          path: /tmp
+      - name: Load runtime image for fork
+        if: github.event.pull_request.head.repo.fork
+        run: |
+          docker load --input /tmp/runtime-${{ matrix.base_image }}.tar
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.virtualenvs
+          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Install Python dependencies using Poetry
+        run: make install-python-dependencies
+      - name: Run runtime tests
+        run: |
+          # We install pytest-xdist in order to run tests across CPUs
+          poetry run pip install pytest-xdist
+
+          # Install to be able to retry on failures for flaky tests
+          poetry run pip install pytest-rerunfailures
+
+          image_name=ghcr.io/${{ github.repository_owner }}/runtime:${{ env.RELEVANT_SHA }}-${{ matrix.base_image }}
+          image_name=$(echo $image_name | tr '[:upper:]' '[:lower:]')
+
+          SKIP_CONTAINER_LOGS=true \
+          TEST_RUNTIME=eventstream \
+          SANDBOX_USER_ID=$(id -u) \
+          SANDBOX_RUNTIME_CONTAINER_IMAGE=$image_name \
+          TEST_IN_CI=true \
+          RUN_AS_OPENHANDS=false \
+          poetry run pytest -n 3 -raRs --reruns 2 --reruns-delay 5 --cov=openhands --cov-report=xml -s ./tests/runtime
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  # Run unit tests with the EventStream runtime Docker images as openhands user
+  test_runtime_oh:
+    name: RT Unit Tests (openhands)
+    runs-on: ubuntu-latest
+    needs: [ghcr_build_runtime]
+    strategy:
+      matrix:
+        base_image: ['nikolaik']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          # this might remove tools that are actually needed,
+          # if set to "true" but frees about 6 GB
+          tool-cache: true
+          # all of these default to true, but feel free to set to
+          # "false" if necessary for your workflow
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: false
+          swap-storage: true
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      # Forked repos can't push to GHCR, so we need to download the image as an artifact
+      - name: Download runtime image for fork
+        if: github.event.pull_request.head.repo.fork
+        uses: actions/download-artifact@v4
+        with:
+          name: runtime-${{ matrix.base_image }}
+          path: /tmp
+      - name: Load runtime image for fork
+        if: github.event.pull_request.head.repo.fork
+        run: |
+          docker load --input /tmp/runtime-${{ matrix.base_image }}.tar
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.virtualenvs
+          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Install Python dependencies using Poetry
+        run: make install-python-dependencies
+      - name: Run runtime tests
+        run: |
+          # We install pytest-xdist in order to run tests across CPUs
+          poetry run pip install pytest-xdist
+
+          # Install to be able to retry on failures for flaky tests
+          poetry run pip install pytest-rerunfailures
+
+          image_name=ghcr.io/${{ github.repository_owner }}/runtime:${{ env.RELEVANT_SHA }}-${{ matrix.base_image }}
+          image_name=$(echo $image_name | tr '[:upper:]' '[:lower:]')
+
+          SKIP_CONTAINER_LOGS=true \
+          TEST_RUNTIME=eventstream \
+          SANDBOX_USER_ID=$(id -u) \
+          SANDBOX_RUNTIME_CONTAINER_IMAGE=$image_name \
+          TEST_IN_CI=true \
+          RUN_AS_OPENHANDS=true \
+          poetry run pytest -n 3 -raRs --reruns 2 --reruns-delay 5 --cov=openhands --cov-report=xml -s ./tests/runtime
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  # The two following jobs (named identically) are to check whether all the runtime tests have passed as the
+  # "All Runtime Tests Passed" is a required job for PRs to merge
+  # Due to this bug: https://github.com/actions/runner/issues/2566, we want to create a job that runs when the
+  # prerequisites have been cancelled or failed so merging is disallowed, otherwise Github considers "skipped" as "success"
+  runtime_tests_check_success:
+    name: All Runtime Tests Passed
+    if: ${{ !cancelled() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }}
+    runs-on: ubuntu-latest
+    needs: [test_runtime_root, test_runtime_oh, verify_hash_equivalence_in_runtime_and_app]
+    steps:
+      - name: All tests passed
+        run: echo "All runtime tests have passed successfully!"
+
+  runtime_tests_check_fail:
+    name: All Runtime Tests Passed
+    if: ${{ cancelled() || contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+    runs-on: ubuntu-latest
+    needs: [test_runtime_root, test_runtime_oh, verify_hash_equivalence_in_runtime_and_app]
+    steps:
+      - name: Some tests failed
+        run: |
+          echo "Some runtime tests failed or were cancelled"
+          exit 1
+  update_pr_description:
+    name: Update PR Description
+    if: github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork && github.actor != 'dependabot[bot]'
+    needs: [ghcr_build_runtime]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get short SHA
+        id: short_sha
+        run: echo "SHORT_SHA=$(echo ${{ github.event.pull_request.head.sha }} | cut -c1-7)" >> $GITHUB_OUTPUT
+
+      - name: Update PR Description
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          SHORT_SHA: ${{ steps.short_sha.outputs.SHORT_SHA }}
+        run: |
+          echo "updating PR description"
+          DOCKER_RUN_COMMAND="docker run -it --rm \
+            -p 3000:3000 \
+            -v /var/run/docker.sock:/var/run/docker.sock \
+            --add-host host.docker.internal:host-gateway \
+            -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:$SHORT_SHA-nikolaik \
+            --name openhands-app-$SHORT_SHA \
+            docker.all-hands.dev/all-hands-ai/openhands:$SHORT_SHA"
+
+          PR_BODY=$(gh pr view $PR_NUMBER --json body --jq .body)
+
+          if echo "$PR_BODY" | grep -q "To run this PR locally, use the following command:"; then
+            UPDATED_PR_BODY=$(echo "${PR_BODY}" | sed -E "s|docker run -it --rm.*|$DOCKER_RUN_COMMAND|")
+          else
+            UPDATED_PR_BODY="${PR_BODY}
+
+          ---
+
+          To run this PR locally, use the following command:
+          \`\`\`
+          $DOCKER_RUN_COMMAND
+          \`\`\`"
+          fi
+
+          echo "updated body: $UPDATED_PR_BODY"
+          gh pr edit $PR_NUMBER --body "$UPDATED_PR_BODY"

.github/workflows/integration-runner.yml

@@ -1,477 +0,0 @@
----
-name: Run Integration Tests
-run-name: >-
-    Run Integration Tests ${{ inputs.reason || github.event.label.name || 'scheduled' }}
-
-on:
-    # Use pull_request_target to access secrets even on fork PRs
-    # This is safe because we only run when the 'integration-test' label is added by a maintainer
-    pull_request_target:
-        types:
-            - labeled
-    workflow_dispatch:
-        inputs:
-            reason:
-                description: Reason for manual trigger
-                required: true
-                default: ''
-            test_type:
-                description: Select which tests to run (all, integration, behavior)
-                required: false
-                default: all
-            model_ids:
-                description: >-
-                    Comma-separated model IDs to test (from resolve_model_config.py).
-                    Example: claude-sonnet-4-6,glm-4.7. Defaults to a standard set.
-                required: false
-                default: ''
-                type: string
-            issue_number:
-                description: Issue or PR number to post results to (optional)
-                required: false
-                default: ''
-                type: string
-            tool_preset:
-                description: >-
-                    Tool preset for file editing (default, gemini, gpt5, planning).
-                    'default' uses FileEditorTool, 'gemini' uses read_file/write_file/edit/list_directory,
-                    'gpt5' uses apply_patch tool.
-                required: false
-                default: default
-                type: choice
-                options:
-                    - default
-                    - gemini
-                    - gpt5
-                    - planning
-    schedule:
-        - cron: 30 22 * * * # Runs at 10:30pm UTC every day
-
-env:
-    N_PROCESSES: 4 # Global configuration for number of parallel processes for evaluation
-    # Default models for scheduled/label-triggered runs (subset of models from resolve_model_config.py)
-    DEFAULT_MODEL_IDS: claude-sonnet-4-6,deepseek-v3.2-reasoner,kimi-k2-thinking,gemini-3-pro
-
-jobs:
-    setup-matrix:
-        runs-on: ubuntu-latest
-        outputs:
-            matrix: ${{ steps.resolve-models.outputs.matrix }}
-            issue_number: ${{ steps.resolve-issue.outputs.issue_number }}
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
-                  ref: ${{ github.event.pull_request.head.sha || github.ref }}
-                  persist-credentials: false
-
-            - name: Set up Python
-              uses: actions/setup-python@v5
-              with:
-                  python-version: '3.13'
-
-            - name: Resolve model configurations
-              id: resolve-models
-              env:
-                  MODEL_IDS_INPUT: ${{ github.event.inputs.model_ids || '' }}
-                  DEFAULT_MODEL_IDS: ${{ env.DEFAULT_MODEL_IDS }}
-              run: |
-                  # Use input model_ids if provided, otherwise use defaults
-                  if [ -z "$MODEL_IDS_INPUT" ]; then
-                    MODEL_IDS="$DEFAULT_MODEL_IDS"
-                    echo "No model_ids specified, using defaults: $MODEL_IDS"
-                  else
-                    MODEL_IDS="$MODEL_IDS_INPUT"
-                    echo "Using specified model_ids: $MODEL_IDS"
-                  fi
-
-                  # Resolve model configs using resolve_model_config.py
-                  # Transform output to matrix format for integration tests
-                  MATRIX=$(python3 << EOF
-                  import json
-                  import sys
-                  sys.path.insert(0, '.github/run-eval')
-                  from resolve_model_config import MODELS
-
-                  model_ids = "$MODEL_IDS".split(",")
-                  model_ids = [m.strip() for m in model_ids if m.strip()]
-
-                  matrix = []
-                  for model_id in model_ids:
-                      if model_id not in MODELS:
-                          available = ", ".join(sorted(MODELS.keys()))
-                          print(f"Error: Model ID '{model_id}' not found. Available: {available}", file=sys.stderr)
-                          sys.exit(1)
-                      model = MODELS[model_id]
-                      # Create run-suffix from model id (replace special chars with underscore)
-                      run_suffix = model_id.replace("-", "_").replace(".", "_") + "_run"
-                      matrix.append({
-                          "id": model_id,
-                          "name": model["display_name"],
-                          "run-suffix": run_suffix,
-                          "llm-config": model["llm_config"]
-                      })
-
-                  print(json.dumps(matrix))
-                  EOF
-                  )
-
-                  if [ $? -ne 0 ]; then
-                    echo "Failed to resolve model configurations" >&2
-                    exit 1
-                  fi
-
-                  echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
-                  echo "Resolved models: $(echo "$MATRIX" | jq -r '.[].name' | paste -sd', ' -)"
-
-            - name: Resolve issue number
-              id: resolve-issue
-              env:
-                  ISSUE_NUMBER_INPUT: ${{ github.event.inputs.issue_number || '' }}
-                  PR_NUMBER: ${{ github.event.pull_request.number }}
-              run: |
-                  # Priority: explicit input > PR number from label trigger
-                  if [ -n "$ISSUE_NUMBER_INPUT" ]; then
-                    echo "issue_number=$ISSUE_NUMBER_INPUT" >> "$GITHUB_OUTPUT"
-                  elif [ -n "$PR_NUMBER" ]; then
-                    echo "issue_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
-                  else
-                    echo "issue_number=" >> "$GITHUB_OUTPUT"
-                  fi
-
-    # Post initial comment for label triggers (no dependencies - runs immediately)
-    post-label-comment:
-        if: >
-            github.event_name == 'pull_request_target' && (
-                github.event.label.name == 'integration-test' ||
-                github.event.label.name == 'behavior-test'
-            )
-        runs-on: ubuntu-latest
-        permissions:
-            pull-requests: write
-        steps:
-            - name: Comment on PR (integration tests via label)
-              if: github.event.label.name == 'integration-test'
-              uses: KeisukeYamashita/create-comment@v1
-              with:
-                  unique: false
-                  comment: |
-                      Hi! I started running the integration tests on your PR. You will receive a comment with the results shortly.
-            - name: Comment on PR (behavior tests via label)
-              if: github.event.label.name == 'behavior-test'
-              uses: KeisukeYamashita/create-comment@v1
-              with:
-                  unique: false
-                  comment: |
-                      Hi! I started running the behavior tests on your PR. You will receive a comment with the results shortly.
-
-    # Post initial comment for workflow_dispatch (depends on setup-matrix for issue_number resolution)
-    post-dispatch-comment:
-        needs: setup-matrix
-        if: github.event_name == 'workflow_dispatch' && github.event.inputs.issue_number != ''
-        runs-on: ubuntu-latest
-        permissions:
-            issues: write
-        steps:
-            - name: Comment on issue/PR (workflow_dispatch)
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-                  ISSUE_NUMBER: ${{ github.event.inputs.issue_number }}
-                  MODEL_IDS: ${{ github.event.inputs.model_ids || 'all models' }}
-                  TEST_TYPE: ${{ github.event.inputs.test_type || 'all' }}
-                  REASON: ${{ github.event.inputs.reason }}
-              run: |
-                  # Sanitize @OpenHands mentions to prevent self-mention loops
-                  SANITIZED_REASON=$(echo "$REASON" | sed 's/@OpenHands/@\u200BOpenHands/g; s/@openhands/@\u200Bopenhands/g')
-                  SANITIZED_MODEL_IDS=$(echo "$MODEL_IDS" | sed 's/@OpenHands/@\u200BOpenHands/g; s/@openhands/@\u200Bopenhands/g')
-                  COMMENT_BODY=$(cat <<EOF
-                  **Integration Tests Triggered**
-
-                  - **Reason:** $SANITIZED_REASON
-                  - **Test type:** $TEST_TYPE
-                  - **Models:** $SANITIZED_MODEL_IDS
-                  - **Workflow run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-
-                  Results will be posted here when complete.
-                  EOF
-                  )
-                  gh issue comment "$ISSUE_NUMBER" --body "$COMMENT_BODY"
-
-    run-integration-tests:
-        # Security: Only run when integration-related labels are present, via workflow_dispatch, or on schedule
-        # This prevents automatic execution on fork PRs without maintainer approval
-        # Note: uses always() to run even when comment jobs are skipped (e.g., for scheduled runs)
-        # Schedule trigger only runs in the main repository, not in forks
-        if: |
-            always() && (
-                (
-                    github.event_name == 'pull_request_target' && (
-                        github.event.label.name == 'integration-test' ||
-                        github.event.label.name == 'behavior-test'
-                    )
-                ) ||
-                github.event_name == 'workflow_dispatch' ||
-                (github.event_name == 'schedule' && github.repository == 'OpenHands/software-agent-sdk')
-            ) && needs.setup-matrix.result == 'success'
-        needs: [setup-matrix, post-label-comment, post-dispatch-comment]
-        runs-on: ubuntu-22.04
-        timeout-minutes: 180
-        permissions:
-            contents: read
-            id-token: write
-            pull-requests: write
-            issues: write
-        strategy:
-            fail-fast: false
-            matrix:
-                python-version: ['3.13']
-                job-config: ${{ fromJson(needs.setup-matrix.outputs.matrix) }}
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  # For pull_request_target: checkout fork PR code (requires explicit repository)
-                  # For other events: fallback to current repository and ref
-                  repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
-                  ref: ${{ github.event.pull_request.head.sha || github.ref }}
-                  # Security: Don't persist credentials to prevent untrusted PR code from using them
-                  persist-credentials: false
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: ${{ matrix.python-version }}
-
-            - name: Install Python dependencies using uv
-              run: |
-                  uv sync --dev
-                  uv pip install pytest
-
-            # Run integration test evaluation
-            - name: Determine test selection
-              run: |
-                  TEST_TYPE_ARGS=""
-                  if [ "${{ github.event_name }}" = "pull_request_target" ] && [ "${{ github.event.label.name }}" = "behavior-test" ]; then
-                    TEST_TYPE_ARGS="--test-type behavior"
-                    echo "behavior-test label detected; running behavior tests only."
-                  elif [ "${{ github.event_name }}" = "pull_request_target" ] && [ "${{ github.event.label.name }}" = "integration-test" ]; then
-                    TEST_TYPE_ARGS="--test-type integration"
-                    echo "integration-test label detected; running integration tests only."
-                  elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-                    test_type="${{ github.event.inputs.test_type }}"
-                    case "$test_type" in
-                      behavior)
-                        TEST_TYPE_ARGS="--test-type behavior"
-                        echo "workflow_dispatch requested behavior tests only."
-                        ;;
-                      integration)
-                        TEST_TYPE_ARGS="--test-type integration"
-                        echo "workflow_dispatch requested integration tests only."
-                        ;;
-                      ""|all)
-                        echo "workflow_dispatch requested full integration suite."
-                        ;;
-                      *)
-                        echo "workflow_dispatch provided unknown test_type '$test_type'; defaulting to full suite."
-                        ;;
-                    esac
-                  elif [ "${{ github.event_name }}" = "schedule" ]; then
-                    TEST_TYPE_ARGS="--test-type integration"
-                    echo "Scheduled run; running integration tests only."
-                  else
-                    echo "Running full integration test suite."
-                  fi
-                  echo "TEST_TYPE_ARGS=$TEST_TYPE_ARGS" >> "$GITHUB_ENV"
-
-            - name: Run integration test evaluation for ${{ matrix.job-config['name'] }}
-              env:
-                  LLM_CONFIG: ${{ toJson(matrix.job-config['llm-config']) }}
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY_EVAL }}
-                  LLM_BASE_URL: https://llm-proxy.eval.all-hands.dev
-                  TOOL_PRESET: ${{ github.event.inputs.tool_preset || 'default' }}
-              run: |
-                  set -eo pipefail
-
-                  AGENT_SDK_VERSION=$(git rev-parse --short HEAD)
-                  EVAL_NOTE="${AGENT_SDK_VERSION}_${{ matrix.job-config['run-suffix'] }}"
-
-                  echo "Invoking test runner with TEST_TYPE_ARGS='$TEST_TYPE_ARGS' TOOL_PRESET='$TOOL_PRESET'"
-
-                  uv run python tests/integration/run_infer.py \
-                    --llm-config "$LLM_CONFIG" \
-                    --num-workers $N_PROCESSES \
-                    --eval-note "$EVAL_NOTE" \
-                    --tool-preset "$TOOL_PRESET" \
-                    $TEST_TYPE_ARGS
-
-                  # get integration tests JSON results
-                  RESULTS_FILE=$(find tests/integration/outputs/*${{ matrix.job-config['run-suffix'] }}* -name "results.json" -type f | head -n 1)
-                  echo "RESULTS_FILE: $RESULTS_FILE"
-                  if [ -f "$RESULTS_FILE" ]; then
-                    echo "JSON_RESULTS_FILE=$RESULTS_FILE" >> $GITHUB_ENV
-                  else
-                    echo "JSON_RESULTS_FILE=" >> $GITHUB_ENV
-                  fi
-
-            - name: Wait a little bit
-              run: sleep 10
-
-
-
-
-
-            - name: Create archive of evaluation outputs
-              run: |
-                  TIMESTAMP=$(date +'%y-%m-%d-%H-%M')
-                  cd tests/integration/outputs  # Change to the outputs directory
-                  tar -czvf ../../../integration_tests_${{ matrix.job-config['run-suffix'] }}_${TIMESTAMP}.tar.gz *${{ matrix.job-config['run-suffix'] }}* # Include result directories for this model
-
-            - name: Upload evaluation results as artifact
-              uses: actions/upload-artifact@v7
-              id: upload_results_artifact
-              with:
-                  name: integration-test-outputs-${{ matrix.job-config['run-suffix'] }}-${{ github.run_id }}-${{ github.run_attempt }}
-                  path: integration_tests_${{ matrix.job-config['run-suffix'] }}_*.tar.gz
-
-            - name: Save test results for consolidation
-              run: |
-                  # Copy the structured JSON results file for consolidation
-                  mkdir -p test_results_summary
-
-                  if [ -n "${{ env.JSON_RESULTS_FILE }}" ] && [ -f "${{ env.JSON_RESULTS_FILE }}" ]; then
-                    # Copy the JSON results file directly
-                    cp "${{ env.JSON_RESULTS_FILE }}" "test_results_summary/${{ matrix.job-config['run-suffix'] }}_results.json"
-                    echo "✓ Copied JSON results file for consolidation"
-                  else
-                    echo "✗ No JSON results file found"
-                    exit 1
-                  fi
-
-            - name: Upload test results summary
-              uses: actions/upload-artifact@v7
-              with:
-                  name: test-results-${{ matrix.job-config['run-suffix'] }}
-                  path: test_results_summary/${{ matrix.job-config['run-suffix'] }}_results.json
-
-    consolidate-results:
-        needs: [setup-matrix, run-integration-tests]
-        if: |
-            always() && (
-                (
-                    github.event_name == 'pull_request_target' && (
-                        github.event.label.name == 'integration-test' ||
-                        github.event.label.name == 'behavior-test'
-                    )
-                ) ||
-                github.event_name == 'workflow_dispatch' ||
-                (github.event_name == 'schedule' && github.repository == 'OpenHands/software-agent-sdk')
-            )
-        runs-on: ubuntu-24.04
-        permissions:
-            contents: read
-            pull-requests: write
-            issues: write
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  # When using pull_request_target, explicitly checkout the PR branch
-                  # This ensures we use the scripts from the actual PR code
-                  ref: ${{ github.event.pull_request.head.sha || github.ref }}
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Install Python dependencies using uv
-              run: |
-                  uv sync --dev
-
-            - name: Download all test results
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: test-results-*
-                  merge-multiple: true
-                  path: all_results
-
-            - name: Download all integration test artifacts
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: integration-test-outputs-*
-                  path: artifacts
-
-            - name: Consolidate test results
-              env:
-                  EVENT_NAME: ${{ github.event_name }}
-                  PR_NUMBER: ${{ github.event.pull_request.number }}
-                  MANUAL_REASON: ${{ github.event.inputs.reason }}
-                  COMMIT_SHA: ${{ github.sha }}
-                  PYTHONPATH: ${{ github.workspace }}
-                  GITHUB_SERVER_URL: ${{ github.server_url }}
-                  GITHUB_REPOSITORY: ${{ github.repository }}
-                  GITHUB_RUN_ID: ${{ github.run_id }}
-              run: |
-                  uv run python tests/integration/utils/consolidate_json_results.py \
-                    --results-dir all_results \
-                    --artifacts-dir artifacts \
-                    --output-file consolidated_results.json
-
-                  echo "Consolidated results generated successfully"
-
-                  uv run python tests/integration/utils/generate_markdown_report.py \
-                    --input-file consolidated_results.json \
-                    --output-file consolidated_report.md
-
-            - name: Upload consolidated report
-              uses: actions/upload-artifact@v7
-              with:
-                  name: consolidated-report
-                  path: consolidated_report.md
-
-            - name: Create consolidated PR comment
-              if: github.event_name == 'pull_request_target'
-              run: |
-                  # Sanitize @OpenHands mentions to prevent self-mention loops
-                  COMMENT_BODY=$(uv run python -c "from openhands.sdk.utils.github import sanitize_openhands_mentions; import sys; print(sanitize_openhands_mentions(sys.stdin.read()), end='')" < consolidated_report.md)
-                  # Use GitHub CLI to create comment with explicit PR number
-                  echo "$COMMENT_BODY" | gh pr comment ${{ github.event.pull_request.number }} --body-file -
-              env:
-                  GH_TOKEN: ${{ github.token }}
-
-            - name: Comment on specified issue/PR (workflow_dispatch)
-              if: github.event_name == 'workflow_dispatch' && needs.setup-matrix.outputs.issue_number != ''
-              env:
-                  GH_TOKEN: ${{ github.token }}
-                  ISSUE_NUMBER: ${{ needs.setup-matrix.outputs.issue_number }}
-              run: |
-                  # Sanitize @OpenHands mentions to prevent self-mention loops
-                  COMMENT_BODY=$(uv run python -c "from openhands.sdk.utils.github import sanitize_openhands_mentions; import sys; print(sanitize_openhands_mentions(sys.stdin.read()), end='')" < consolidated_report.md)
-                  # Use GitHub CLI to create comment on the specified issue/PR
-                  echo "$COMMENT_BODY" | gh issue comment "$ISSUE_NUMBER" --body-file -
-
-            - name: Read consolidated report for tracker issue
-              if: github.event_name == 'schedule'
-              id: read_report
-              run: |
-                  # Read and sanitize the report, then set as output
-                  REPORT_CONTENT=$(uv run python -c "from openhands.sdk.utils.github import sanitize_openhands_mentions; import sys; print(sanitize_openhands_mentions(sys.stdin.read()), end='')" < consolidated_report.md)
-                  echo "report<<EOF" >> $GITHUB_OUTPUT
-                  echo "$REPORT_CONTENT" >> $GITHUB_OUTPUT
-                  echo "EOF" >> $GITHUB_OUTPUT
-
-            - name: Comment with results on tracker issue
-              if: github.event_name == 'schedule'
-              uses: KeisukeYamashita/create-comment@v1
-              with:
-                  number: 2078
-                  unique: false
-                  comment: |
-                      **Trigger:** Nightly Scheduled Run
-                      **Commit:** ${{ github.sha }}
-
-                      ${{ steps.read_report.outputs.report }}
-

.github/workflows/lint.yml

@@ -0,0 +1,54 @@
+# Workflow that runs lint on the frontend and python code
+name: Lint
+
+# The jobs in this workflow are required, so they must run at all times
+# Always run on "main"
+# Always run on PRs
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  # Run lint on the frontend code
+  lint-frontend:
+    name: Lint frontend
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Install dependencies
+        run: |
+          cd frontend
+          npm install --frozen-lockfile
+      - name: Lint
+        run: |
+          cd frontend
+          npm run lint
+
+  # Run lint on the python code
+  lint-python:
+    name: Lint python
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+          cache: 'pip'
+      - name: Install pre-commit
+        run: pip install pre-commit==3.7.0
+      - name: Run pre-commit hooks
+        run: pre-commit run --files openhands/**/* evaluation/**/* tests/**/* --show-diff-on-failure --config ./dev_config/python/.pre-commit-config.yaml

.github/workflows/oh-update-documentation.yml.back

@@ -1,30 +0,0 @@
-name: Update Documentation (by OpenHands)
-
-on:
-  schedule:
-    # Run every 7 days at 2 AM UTC on Sundays
-    - cron: '0 2 * * 0'
-  workflow_dispatch: # Allow manual triggering
-
-jobs:
-  update-docs:
-    runs-on: blacksmith-4vcpu-ubuntu-2404
-    permissions:
-      contents: write
-      pull-requests: write
-    
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Update Documentation with OpenHands
-        uses: All-Hands-AI/openhands-github-action@v1
-        with:
-          prompt: .github/prompts/update-documentation.md
-          repository: ${{ github.repository }}
-          selected-branch: main
-          base-url: https://app.all-hands.dev
-          poll: "true"
-          timeout-seconds: 1800
-          poll-interval-seconds: 30
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          openhands-api-key: ${{ secrets.OPENHANDS_API_KEY }}

.github/workflows/openhands-resolver.yml

@@ -0,0 +1,15 @@
+name: Resolve Issues with OpenHands
+
+on:
+  issues:
+    types: [labeled]
+  pull_request:
+    types: [labeled]
+
+jobs:
+  call-openhands-resolver:
+    uses: All-Hands-AI/openhands-resolver/.github/workflows/openhands-resolver.yml@main
+    if: github.event.label.name == 'fix-me'
+    with:
+      max_iterations: 50
+    secrets: inherit

.github/workflows/pr-artifacts.yml

@@ -1,139 +0,0 @@
----
-name: PR Artifacts
-
-on:
-    workflow_dispatch: # Manual trigger for testing
-    pull_request:
-        types: [opened, synchronize, reopened]
-        branches: [main]
-    pull_request_review:
-        types: [submitted]
-
-jobs:
-  # Auto-remove .pr/ directory when a reviewer approves
-    cleanup-on-approval:
-        concurrency:
-            group: cleanup-pr-artifacts-${{ github.event.pull_request.number }}
-            cancel-in-progress: false
-        if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
-        runs-on: ubuntu-latest
-        permissions:
-            contents: write
-            pull-requests: write
-        steps:
-            - name: Check if fork PR
-              id: check-fork
-              run: |
-                  if [ "${{ github.event.pull_request.head.repo.full_name }}" != "${{ github.event.pull_request.base.repo.full_name }}" ]; then
-                    echo "is_fork=true" >> $GITHUB_OUTPUT
-                    echo "::notice::Fork PR detected - skipping auto-cleanup (manual removal required)"
-                  else
-                    echo "is_fork=false" >> $GITHUB_OUTPUT
-                  fi
-
-            # Use PAT so the push triggers CI workflows that will complete and
-            # satisfy branch protection. We can't use [skip ci] because the Vercel
-            # GitHub App creates stuck checks that block merging.
-            - uses: actions/checkout@v5
-              if: steps.check-fork.outputs.is_fork == 'false'
-              with:
-                  ref: ${{ github.event.pull_request.head.ref }}
-                  token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-
-            - name: Remove .pr/ directory
-              id: remove
-              if: steps.check-fork.outputs.is_fork == 'false'
-              run: |
-                  if [ -d ".pr" ]; then
-                    git config user.name "allhands-bot"
-                    git config user.email "allhands-bot@users.noreply.github.com"
-                    git rm -rf .pr/
-                    git commit -m "chore: Remove PR-only artifacts [automated]"
-                    git push || {
-                      echo "::error::Failed to push cleanup commit. Check branch protection rules."
-                      exit 1
-                    }
-                    echo "removed=true" >> $GITHUB_OUTPUT
-                    echo "::notice::Removed .pr/ directory"
-                  else
-                    echo "removed=false" >> $GITHUB_OUTPUT
-                    echo "::notice::No .pr/ directory to remove"
-                  fi
-
-            - name: Update PR comment after cleanup
-              if: steps.check-fork.outputs.is_fork == 'false' && steps.remove.outputs.removed == 'true'
-              uses: actions/github-script@v8
-              with:
-                  script: |
-                      const marker = '<!-- pr-artifacts-notice -->';
-                      const body = `${marker}
-                      ✅ **PR Artifacts Cleaned Up**
-
-                      The \`.pr/\` directory has been automatically removed.
-                      `;
-
-                      const { data: comments } = await github.rest.issues.listComments({
-                        owner: context.repo.owner,
-                        repo: context.repo.repo,
-                        issue_number: context.issue.number,
-                      });
-
-                      const existing = comments.find(c => c.body.includes(marker));
-                      if (existing) {
-                        await github.rest.issues.updateComment({
-                          owner: context.repo.owner,
-                          repo: context.repo.repo,
-                          comment_id: existing.id,
-                          body: body,
-                        });
-                      }
-
-  # Warn if .pr/ directory exists (will be auto-removed on approval)
-    check-pr-artifacts:
-        if: github.event_name == 'pull_request'
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-            pull-requests: write
-        steps:
-            - uses: actions/checkout@v5
-
-            - name: Check for .pr/ directory
-              id: check
-              run: |
-                  if [ -d ".pr" ]; then
-                    echo "exists=true" >> $GITHUB_OUTPUT
-                    echo "::warning::.pr/ directory exists and will be automatically removed when the PR is approved. For fork PRs, manual removal is required before merging."
-                  else
-                    echo "exists=false" >> $GITHUB_OUTPUT
-                  fi
-
-            - name: Post or update PR comment
-              if: steps.check.outputs.exists == 'true'
-              uses: actions/github-script@v8
-              with:
-                  script: |
-                      const marker = '<!-- pr-artifacts-notice -->';
-                      const body = `${marker}
-                      📁 **PR Artifacts Notice**
-
-                      This PR contains a \`.pr/\` directory with PR-specific documents. This directory will be **automatically removed** when the PR is approved.
-
-                      > For fork PRs: Manual removal is required before merging.
-                      `;
-
-                      const { data: comments } = await github.rest.issues.listComments({
-                        owner: context.repo.owner,
-                        repo: context.repo.repo,
-                        issue_number: context.issue.number,
-                      });
-
-                      const existing = comments.find(c => c.body.includes(marker));
-                      if (!existing) {
-                        await github.rest.issues.createComment({
-                          owner: context.repo.owner,
-                          repo: context.repo.repo,
-                          issue_number: context.issue.number,
-                          body: body,
-                        });
-                      }

.github/workflows/pr-review-by-openhands.yml

@@ -1,51 +0,0 @@
----
-name: PR Review by OpenHands
-
-on:
-    # Use pull_request so workflow changes can be validated in PRs.
-    # This workflow requires secrets, so the job only runs for same-repo PRs.
-    # It runs when:
-    #   1. A new PR is opened (non-draft), OR
-    #   2. A draft PR is marked as ready for review, OR
-    #   3. A maintainer adds the 'review-this' label, OR
-    #   4. A maintainer requests openhands-agent or all-hands-bot as a reviewer
-    # Adding labels and requesting reviewers still requires write access.
-    pull_request:
-        types: [opened, ready_for_review, labeled, review_requested]
-
-permissions:
-    contents: read
-    pull-requests: write
-    issues: write
-
-jobs:
-    pr-review:
-        # Run when one of the following conditions is met:
-        #   1. A new non-draft PR is opened by a non-first-time contributor, OR
-        #   2. A draft PR is converted to ready for review by a non-first-time contributor, OR
-        #   3. 'review-this' label is added, OR
-        #   4. openhands-agent or all-hands-bot is requested as a reviewer
-        # Note: FIRST_TIME_CONTRIBUTOR and NONE PRs require manual trigger via label/reviewer request.
-        if: |
-            github.event.pull_request.head.repo.full_name == github.repository && (
-                (github.event.action == 'opened' && github.event.pull_request.draft == false && github.event.pull_request.author_association != 'FIRST_TIME_CONTRIBUTOR' && github.event.pull_request.author_association != 'NONE') ||
-                (github.event.action == 'ready_for_review' && github.event.pull_request.author_association != 'FIRST_TIME_CONTRIBUTOR' && github.event.pull_request.author_association != 'NONE') ||
-                github.event.label.name == 'review-this' ||
-                github.event.requested_reviewer.login == 'openhands-agent' ||
-                github.event.requested_reviewer.login == 'all-hands-bot'
-            )
-        concurrency:
-            group: pr-review-${{ github.event.pull_request.number }}
-            cancel-in-progress: true
-        runs-on: ubuntu-24.04
-        steps:
-            - name: Run PR Review
-              uses: OpenHands/extensions/plugins/pr-review@main
-              with:
-                  llm-model: litellm_proxy/claude-sonnet-4-5-20250929
-                  llm-base-url: https://llm-proxy.app.all-hands.dev
-                  # Review style: roasted (other option: standard)
-                  review-style: roasted
-                  llm-api-key: ${{ secrets.LLM_API_KEY }}
-                  github-token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-                  lmnr-api-key: ${{ secrets.LMNR_SKILLS_API_KEY }}

.github/workflows/pr-review-evaluation.yml

@@ -1,85 +0,0 @@
----
-name: PR Review Evaluation
-
-# This workflow evaluates how well PR review comments were addressed.
-# It runs when a PR is closed to assess review effectiveness.
-#
-# Security note: pull_request_target is safe here because:
-# 1. Only triggers on PR close (not on code changes)
-# 2. Does not checkout PR code - only downloads artifacts from trusted workflow runs
-# 3. Runs evaluation scripts from the extensions repo, not from the PR
-
-on:
-    pull_request_target:
-        types: [closed]
-
-permissions:
-    contents: read
-    pull-requests: read
-
-jobs:
-    evaluate:
-        runs-on: ubuntu-24.04
-        env:
-            PR_NUMBER: ${{ github.event.pull_request.number }}
-            REPO_NAME: ${{ github.repository }}
-            PR_MERGED: ${{ github.event.pull_request.merged }}
-
-        steps:
-            - name: Download review trace artifact
-              id: download-trace
-              uses: dawidd6/action-download-artifact@v6
-              continue-on-error: true
-              with:
-                  workflow: pr-review-by-openhands.yml
-                  name: pr-review-trace-${{ github.event.pull_request.number }}
-                  path: trace-info
-                  search_artifacts: true
-                  if_no_artifact_found: warn
-
-            - name: Check if trace file exists
-              id: check-trace
-              run: |
-                  if [ -f "trace-info/laminar_trace_info.json" ]; then
-                    echo "trace_exists=true" >> $GITHUB_OUTPUT
-                    echo "Found trace file for PR #$PR_NUMBER"
-                  else
-                    echo "trace_exists=false" >> $GITHUB_OUTPUT
-                    echo "No trace file found for PR #$PR_NUMBER - skipping evaluation"
-                  fi
-
-            # Always checkout main branch for security - cannot test script changes in PRs
-            - name: Checkout extensions repository
-              if: steps.check-trace.outputs.trace_exists == 'true'
-              uses: actions/checkout@v5
-              with:
-                  repository: OpenHands/extensions
-                  path: extensions
-
-            - name: Set up Python
-              if: steps.check-trace.outputs.trace_exists == 'true'
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.12'
-
-            - name: Install dependencies
-              if: steps.check-trace.outputs.trace_exists == 'true'
-              run: pip install lmnr
-
-            - name: Run evaluation
-              if: steps.check-trace.outputs.trace_exists == 'true'
-              env:
-                  # Script expects LMNR_PROJECT_API_KEY; org secret is named LMNR_SKILLS_API_KEY
-                  LMNR_PROJECT_API_KEY: ${{ secrets.LMNR_SKILLS_API_KEY }}
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-              run: |
-                  python extensions/plugins/pr-review/scripts/evaluate_review.py \
-                      --trace-file trace-info/laminar_trace_info.json
-
-            - name: Upload evaluation logs
-              uses: actions/upload-artifact@v7
-              if: always() && steps.check-trace.outputs.trace_exists == 'true'
-              with:
-                  name: pr-review-evaluation-${{ github.event.pull_request.number }}
-                  path: '*.log'
-                  retention-days: 30

.github/workflows/precommit.yml

@@ -1,31 +0,0 @@
----
-# .github/workflows/precommit.yml
-name: Pre-commit checks
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: ['**']
-
-jobs:
-    pre-commit:
-        runs-on: ubuntu-24.04
-
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@v5
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-
-            - name: Install dependencies
-              run: uv sync --frozen --group dev
-
-            - name: Run pre-commit (all files)
-              run: uv run pre-commit run --all-files --show-diff-on-failure

.github/workflows/prepare-release.yml

@@ -1,132 +0,0 @@
----
-name: Prepare Release
-
-on:
-    workflow_dispatch:
-        inputs:
-            version:
-                description: Release version (e.g., 1.2.3)
-                required: true
-                type: string
-
-jobs:
-    prepare-release:
-        runs-on: ubuntu-24.04
-        steps:
-            - name: Validate version format
-              run: |
-                  if ! [[ "${{ inputs.version }}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-                    echo "❌ Invalid version format. Expected: X.Y.Z (e.g., 1.2.3)"
-                    exit 1
-                  fi
-                  echo "✅ Version format is valid: ${{ inputs.version }}"
-
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Configure Git
-              run: |
-                  git config user.name "github-actions[bot]"
-                  git config user.email "github-actions[bot]@users.noreply.github.com"
-
-            - name: Create release branch
-              run: |
-                  BRANCH_NAME="rel-${{ inputs.version }}"
-                  echo "Creating branch: $BRANCH_NAME"
-                  git checkout -b "$BRANCH_NAME"
-                  echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
-
-            - name: Set package version
-              run: |
-                  echo "🔧 Setting version to ${{ inputs.version }}"
-                  make set-package-version version=${{ inputs.version }}
-
-            - name: Update sdk_ref default in run-eval workflow
-              run: python3 .github/scripts/update_sdk_ref_default.py "${{ inputs.version }}"
-
-            - name: Commit version changes
-              run: |
-                  git add .
-                  if git diff --staged --quiet; then
-                    echo "No changes to commit"
-                  else
-                    git commit -m "Release v${{ inputs.version }}" -m "Co-authored-by: openhands <openhands@all-hands.dev>"
-                    echo "✅ Changes committed"
-                  fi
-
-            - name: Push release branch
-              run: |
-                  git push -u origin "${{ env.BRANCH_NAME }}"
-                  echo "✅ Branch pushed: ${{ env.BRANCH_NAME }}"
-
-            - name: Create Pull Request
-              env:
-                  GH_TOKEN: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-              run: |
-                  cat > pr_body.txt << 'EOF'
-                  ## Release v${{ inputs.version }}
-
-                  This PR prepares the release for version **${{ inputs.version }}**.
-
-                  ### Release Checklist
-                  - [x] Version set to ${{ inputs.version }}
-                  - [ ] Fix any deprecation deadlines if they exist
-                  - [ ] Integration tests pass (tagged with `integration-test`)
-                  - [ ] Behavior tests pass (tagged with `behavior-test`)
-                  - [ ] Example tests pass (tagged with `test-examples`)
-                  - [ ] Draft release created at https://github.com/OpenHands/software-agent-sdk/releases/new
-                    - [ ] Select tag: `v${{ inputs.version }}`
-                    - [ ] Select branch: `${{ env.BRANCH_NAME }}`
-                    - [ ] Auto-generate release notes
-                    - [ ] Publish release (PyPI will auto-publish)
-                  - [ ] Evaluation on OpenHands Index
-
-                  ### Next Steps
-                  1. Review the version changes
-                  2. Address any deprecation deadlines
-                  3. Ensure integration tests pass
-                  4. Ensure behavior tests pass
-                  5. Ensure example tests pass
-                  6. Create and publish the release
-
-                  Once the release is published on GitHub, the PyPI packages will be automatically published via the `pypi-release.yml` workflow.
-                  EOF
-
-                  gh pr create \
-                    --title "Release v${{ inputs.version }}" \
-                    --body-file pr_body.txt \
-                    --base main \
-                    --head "${{ env.BRANCH_NAME }}" \
-                    --label "integration-test" \
-                    --label "behavior-test" \
-                    --label "test-examples"
-
-                  rm pr_body.txt
-                  echo "✅ Pull request created successfully!"
-
-                  # Get PR URL and display it
-                  PR_URL=$(gh pr view "${{ env.BRANCH_NAME }}" --json url --jq '.url')
-                  echo "🔗 PR URL: $PR_URL"
-                  echo "PR_URL=$PR_URL" >> $GITHUB_ENV
-
-            - name: Summary
-              run: |
-                  echo "## ✅ Release Preparation Complete!" >> $GITHUB_STEP_SUMMARY
-                  echo "" >> $GITHUB_STEP_SUMMARY
-                  echo "- **Version**: ${{ inputs.version }}" >> $GITHUB_STEP_SUMMARY
-                  echo "- **Branch**: ${{ env.BRANCH_NAME }}" >> $GITHUB_STEP_SUMMARY
-                  echo "- **PR URL**: ${{ env.PR_URL }}" >> $GITHUB_STEP_SUMMARY
-                  echo "" >> $GITHUB_STEP_SUMMARY
-                  echo "### Next Steps:" >> $GITHUB_STEP_SUMMARY
-                  echo "1. Review the PR and address any deprecation deadlines" >> $GITHUB_STEP_SUMMARY
-                  echo "2. Wait for integration, behavior, and example tests to pass" >> $GITHUB_STEP_SUMMARY
-                  echo "3. Create and publish the release on GitHub" >> $GITHUB_STEP_SUMMARY
-                  echo "4. PyPI will automatically publish when the release is created" >> $GITHUB_STEP_SUMMARY

.github/workflows/py-unit-tests-mac.yml

@@ -0,0 +1,96 @@
+# Workflow that runs python unit tests on mac
+name: Run Python Unit Tests Mac
+
+# This job is flaky so only run it nightly
+on:
+  schedule:
+    - cron: '0 0 * * *'
+
+jobs:
+  # Run python unit tests on macOS
+  test-on-macos:
+    name: Python Unit Tests on macOS
+    runs-on: macos-14
+    env:
+      INSTALL_DOCKER: '1' # Set to '0' to skip Docker installation
+    strategy:
+      matrix:
+        python-version: ['3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.virtualenvs
+          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Install Python dependencies using Poetry
+        run: poetry install --without evaluation,llama-index
+      - name: Install & Start Docker
+        if: env.INSTALL_DOCKER == '1'
+        run: |
+          INSTANCE_NAME="colima-${GITHUB_RUN_ID}"
+
+          # Uninstall colima to upgrade to the latest version
+          if brew list colima &>/dev/null; then
+            brew uninstall colima
+            # unlinking colima dependency: go
+            brew uninstall go@1.21
+          fi
+          rm -rf ~/.colima ~/.lima
+          brew install --HEAD colima
+          brew install docker
+
+          start_colima() {
+            # Find a free port in the range 10000-20000
+            RANDOM_PORT=$((RANDOM % 10001 + 10000))
+
+            # Original line:
+            if ! colima start --network-address --arch x86_64 --cpu=1 --memory=1 --verbose --ssh-port $RANDOM_PORT; then
+              echo "Failed to start Colima."
+              return 1
+            fi
+            return 0
+          }
+
+          # Attempt to start Colima for 5 total attempts:
+          ATTEMPT_LIMIT=5
+          for ((i=1; i<=ATTEMPT_LIMIT; i++)); do
+
+            if start_colima; then
+              echo "Colima started successfully."
+              break
+            else
+              colima stop -f
+              sleep 10
+              colima delete -f
+              if [ $i -eq $ATTEMPT_LIMIT ]; then
+                exit 1
+              fi
+              sleep 10
+            fi
+          done
+
+          # For testcontainers to find the Colima socket
+          # https://github.com/abiosoft/colima/blob/main/docs/FAQ.md#cannot-connect-to-the-docker-daemon-at-unixvarrundockersock-is-the-docker-daemon-running
+          sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock
+      - name: Build Environment
+        run: make build
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Run Tests
+        run: poetry run pytest --forked --cov=openhands --cov-report=xml ./tests/unit --ignore=tests/unit/test_memory.py
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/py-unit-tests.yml

@@ -0,0 +1,49 @@
+# Workflow that runs python unit tests
+name: Run Python Unit Tests
+
+# The jobs in this workflow are required, so they must run at all times
+# * Always run on "main"
+# * Always run on PRs
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  # Run python unit tests on Linux
+  test-on-linux:
+    name: Python Unit Tests on Linux
+    runs-on: ubuntu-latest
+    env:
+      INSTALL_DOCKER: '0' # Set to '0' to skip Docker installation
+    strategy:
+      matrix:
+        python-version: ['3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Install poetry via pipx
+        run: pipx install poetry
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'poetry'
+      - name: Install Python dependencies using Poetry
+        run: poetry install --without evaluation,llama-index
+      - name: Build Environment
+        run: make build
+      - name: Run Tests
+        run: poetry run pytest --forked --cov=openhands --cov-report=xml -svv ./tests/unit --ignore=tests/unit/test_memory.py
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/pypi-release.yml

@@ -1,70 +1,31 @@
----
-name: Publish all OpenHands packages (uv)
+# Publishes the OpenHands PyPi package
+name: Publish PyPi Package
 
+# Triggered manually
 on:
-  # Run manually
-    workflow_dispatch:
-  # Run automatically when a release is published
-    release:
-        types: [published]
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: 'Reason for manual trigger'
+        required: true
+        default: ''
 
 jobs:
-    publish:
-        runs-on: ubuntu-24.04
-        outputs:
-            version: ${{ steps.extract_version.outputs.version }}
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-
-            - name: Extract version from release tag
-              id: extract_version
-              run: |
-                  # Get version from release tag (e.g., v1.2.3 -> 1.2.3)
-                  if [[ "${{ github.event_name }}" == "release" ]]; then
-                    VERSION="${{ github.event.release.tag_name }}"
-                    VERSION="${VERSION#v}"  # Remove 'v' prefix if present
-                  else
-                    # For manual dispatch, extract from pyproject.toml
-                    VERSION=$(grep -m1 '^version = ' openhands-sdk/pyproject.toml | cut -d'"' -f2)
-                  fi
-                  echo "version=$VERSION" >> $GITHUB_OUTPUT
-                  echo "📦 Version: $VERSION"
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Build and publish all packages
-              env:
-                  UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN_OPENHANDS }}
-              run: |
-                  set -euo pipefail
-
-                  if [ -z "${UV_PUBLISH_TOKEN:-}" ]; then
-                    echo "❌ Missing secret PYPI_TOKEN_OPENHANDS"
-                    exit 1
-                  fi
-
-                  PACKAGES=(
-                    openhands-sdk
-                    openhands-tools
-                    openhands-workspace
-                    openhands-agent-server
-                  )
-
-                  echo "🚀 Building and publishing all packages..."
-                  for PKG in "${PACKAGES[@]}"; do
-                    echo "===== $PKG ====="
-                    uv build --package "$PKG"
-                  done
-
-                  # Use --check-url to skip files that already exist on PyPI
-                  # This allows re-running the workflow after partial failures
-                  uv publish --token "$UV_PUBLISH_TOKEN" --check-url https://pypi.org/simple/
-                  echo "✅ All packages built and published successfully!"
-                  echo ""
-                  echo "📋 Note: Version bump PRs will be created by the 'Create Version Bump PRs' workflow"
-                  echo "   which triggers automatically after this workflow completes."
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Install Poetry
+        uses: snok/install-poetry@v1.4.1
+        with:
+          virtualenvs-in-project: true
+          virtualenvs-path: ~/.virtualenvs
+      - name: Install Poetry Dependencies
+        run: poetry install --no-interaction --no-root
+      - name: Build poetry project
+        run: ./build.sh
+      - name: publish
+        run: poetry publish -u __token__ -p ${{ secrets.PYPI_TOKEN }}

.github/workflows/review-pr.yml

@@ -0,0 +1,81 @@
+# Workflow that uses OpenHands to review a pull request. PR must be labeled 'review-this'
+name: Use OpenHands to Review Pull Request
+
+on:
+  pull_request:
+    types: [synchronize, labeled]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dogfood:
+    if: contains(github.event.pull_request.labels.*.name, 'review-this')
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Docker Buildx
+      id: buildx
+      uses: docker/setup-buildx-action@v3
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: install git, github cli
+      run: |
+        sudo apt-get install -y git gh
+        git config --global --add safe.directory $PWD
+    - name: Checkout Repository
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.base.ref }} # check out the target branch
+    - name: Download Diff
+      run: |
+        curl -O "${{ github.event.pull_request.diff_url }}" -L
+    - name: Write Task File
+      run: |
+        echo "Your coworker wants to apply a pull request to this project." > task.txt
+        echo "Read and review ${{ github.event.pull_request.number }}.diff file. Create a review-${{ github.event.pull_request.number }}.txt and write your concise comments and suggestions there." >> task.txt
+        echo "Do not ask me for confirmation at any point." >> task.txt
+        echo "" >> task.txt
+        echo "Title" >> task.txt
+        echo "${{ github.event.pull_request.title }}" >> task.txt
+        echo "" >> task.txt
+        echo "Description" >> task.txt
+        echo "${{ github.event.pull_request.body }}" >> task.txt
+        echo "" >> task.txt
+        echo "Diff file is: ${{ github.event.pull_request.number }}.diff" >> task.txt
+    - name: Set up environment
+      run: |
+        curl -sSL https://install.python-poetry.org | python3 -
+        export PATH="/github/home/.local/bin:$PATH"
+        poetry install --without evaluation,llama-index
+        poetry run playwright install --with-deps chromium
+    - name: Run OpenHands
+      env:
+        LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        LLM_MODEL: ${{ vars.LLM_MODEL }}
+      run: |
+        # Append path to launch poetry
+        export PATH="/github/home/.local/bin:$PATH"
+        # Append path to correctly import package, note: must set pwd at first
+        export PYTHONPATH=$(pwd):$PYTHONPATH
+        export WORKSPACE_MOUNT_PATH=$GITHUB_WORKSPACE
+        export WORKSPACE_BASE=$GITHUB_WORKSPACE
+        echo -e "/exit\n" | poetry run python openhands/core/main.py -i 50 -f task.txt
+        rm task.txt
+    - name: Check if review file is non-empty
+      id: check_file
+      run: |
+        ls -la
+        if [[ -s review-${{ github.event.pull_request.number }}.txt ]]; then
+          echo "non_empty=true" >> $GITHUB_OUTPUT
+        fi
+      shell: bash
+    - name: Create PR review if file is non-empty
+      env:
+        GH_TOKEN: ${{ github.token }}
+      if: steps.check_file.outputs.non_empty == 'true'
+      run: |
+        gh pr review ${{ github.event.pull_request.number }} --comment --body-file "review-${{ github.event.pull_request.number }}.txt"

.github/workflows/review-thread-gate.yml

@@ -1,114 +0,0 @@
----
-name: Review Thread Gate
-
-on:
-    pull_request:
-        branches: [main]
-        types: [opened, synchronize, reopened, ready_for_review, edited]
-
-permissions:
-    contents: read
-    pull-requests: read
-
-concurrency:
-    group: review-thread-gate-${{ github.event.pull_request.number || github.sha }}
-    cancel-in-progress: true
-
-jobs:
-    unresolved-review-threads:
-        runs-on: ubuntu-latest
-        steps:
-            - name: Fail when unresolved review threads remain (unless waived)
-              uses: actions/github-script@v8
-              with:
-                  script: |
-                      const pr = context.payload.pull_request;
-                      if (!pr) {
-                        core.info('No pull_request payload available; skipping.');
-                        return;
-                      }
-
-                      const waiverMatch = pr.body?.match(
-                        /review-thread-waiver\s*:\s*(.+?)(?:\n|$)/i,
-                      );
-                      const waiverReason = waiverMatch?.[1]?.trim() || null;
-
-                      const unresolved = [];
-                      let cursor = null;
-                      do {
-                        const query = `
-                          query($owner: String!, $repo: String!, $number: Int!, $cursor: String) {
-                            repository(owner: $owner, name: $repo) {
-                              pullRequest(number: $number) {
-                                reviewThreads(first: 100, after: $cursor) {
-                                  nodes {
-                                    id
-                                    isResolved
-                                    isOutdated
-                                    comments(first: 1) {
-                                      nodes {
-                                        author { login }
-                                        path
-                                        line
-                                        url
-                                      }
-                                    }
-                                  }
-                                  pageInfo {
-                                    hasNextPage
-                                    endCursor
-                                  }
-                                }
-                              }
-                            }
-                          }
-                        `;
-                        const result = await github.graphql(query, {
-                          owner: context.repo.owner,
-                          repo: context.repo.repo,
-                          number: pr.number,
-                          cursor,
-                        });
-
-                        const page = result.repository.pullRequest.reviewThreads;
-                        for (const thread of page.nodes) {
-                          if (thread.isResolved) continue;
-                          const firstComment = thread.comments.nodes[0];
-                          unresolved.push({
-                            url: firstComment?.url ?? '(no-url)',
-                            author: firstComment?.author?.login ?? 'unknown',
-                            path: firstComment?.path ?? 'unknown',
-                            line: firstComment?.line ?? '?',
-                            outdated: thread.isOutdated,
-                          });
-                        }
-
-                        cursor = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
-                      } while (cursor);
-
-                      if (unresolved.length === 0) {
-                        core.info('No unresolved review threads found.');
-                        return;
-                      }
-
-                      const summaryLines = unresolved.map(
-                        (thread) =>
-                          `- ${thread.url} (author: ${thread.author}, file: ${thread.path}:${thread.line}, outdated: ${thread.outdated})`,
-                      );
-                      await core.summary
-                        .addHeading(`Unresolved review threads: ${unresolved.length}`)
-                        .addRaw(summaryLines.join('\n'))
-                        .write();
-
-                      if (waiverReason) {
-                        core.warning(
-                          `Unresolved review threads remain (${unresolved.length}), but waiver provided: ${waiverReason}`,
-                        );
-                        return;
-                      }
-
-                      core.setFailed(
-                        `Found ${unresolved.length} unresolved review thread(s). Resolve all threads or add ` +
-                        '`review-thread-waiver: <reason>` to the PR body for an intentional waiver.',
-                      );
-

.github/workflows/run-eval.yml

@@ -1,403 +0,0 @@
----
-name: Run Eval
-run-name: Run Eval (${{ inputs.benchmark || 'swebench' }}) ${{ inputs.reason || github.event.label.name || 'release' }}
-
-on:
-    pull_request_target:
-        types: [labeled]
-    release:
-        types: [published]
-    workflow_dispatch:
-        inputs:
-            benchmark:
-                description: Benchmark to evaluate
-                required: false
-                default: swebench
-                type: choice
-                options:
-                    - gaia
-                    - swebench
-                    - swtbench
-                    - commit0
-                    - swebenchmultimodal
-                    - terminalbench
-            sdk_ref:
-                description: SDK commit/ref to evaluate (must be a semantic version like v1.0.0 unless 'Allow unreleased branches' is checked)
-                required: true
-                default: v1.14.0
-
-
-
-
-
-            allow_unreleased_branches:
-                description: Allow unreleased branches (bypasses semantic version requirement)
-                required: false
-                default: false
-                type: boolean
-            eval_limit:
-                description: Number of instances to run (any positive integer)
-                required: false
-                default: '1'
-                type: string
-            model_ids:
-                description: Comma-separated model IDs to evaluate. Must be keys of MODELS in resolve_model_config.py. Defaults to first model in that
-                    dict.
-                required: false
-                default: ''
-                type: string
-            reason:
-                description: Reason for manual trigger
-                required: false
-                default: ''
-            eval_branch:
-                description: Evaluation repo branch to use (for testing feature branches)
-                required: false
-                default: main
-                type: string
-            benchmarks_branch:
-                description: Benchmarks repo branch to use (for testing feature branches)
-                required: false
-                default: main
-                type: string
-            instance_ids:
-                description: >-
-                    Comma-separated instance IDs to evaluate.
-                    Example: "django__django-11583,django__django-12345".
-                    Spaces around commas are automatically stripped.
-                    Leave empty to evaluate all instances up to eval_limit.
-                required: false
-                default: ''
-            num_infer_workers:
-                description: Number of inference workers (optional, overrides benchmark default)
-                required: false
-                default: ''
-                type: string
-            num_eval_workers:
-                description: Number of evaluation workers (optional, overrides benchmark default)
-                required: false
-                default: ''
-                type: string
-            enable_conversation_event_logging:
-                description: 'Enable Datadog persistence for conversation events (default: true)'
-                required: false
-                default: true
-                type: boolean
-            max_retries:
-                description: Max retries per instance (passed to benchmarks)
-                required: false
-                default: '3'
-                type: string
-            tool_preset:
-                description: >-
-                    Tool preset for file editing. 'default' uses FileEditorTool,
-                    'gemini' uses read_file/write_file/edit/list_directory,
-                    'gpt5' uses apply_patch tool.
-                required: false
-                default: default
-                type: choice
-                options:
-                    - default
-                    - gemini
-                    - gpt5
-                    - planning
-            agent_type:
-                description: >-
-                    Agent type: 'default' for standard Agent,
-                    'acp-claude' for ACPAgent with Claude Code,
-                    'acp-codex' for ACPAgent with Codex.
-                required: false
-                default: default
-                type: choice
-                options:
-                    - default
-                    - acp-claude
-                    - acp-codex
-
-
-env:
-    EVAL_REPO: OpenHands/evaluation
-    EVAL_WORKFLOW: eval-job.yml
-
-jobs:
-    print-parameters:
-        if: >
-            github.event_name == 'release' ||
-            github.event_name == 'workflow_dispatch' ||
-            (github.event_name == 'pull_request_target' &&
-             (github.event.label.name == 'run-eval-1' ||
-              github.event.label.name == 'run-eval-50' ||
-              github.event.label.name == 'run-eval-200' ||
-              github.event.label.name == 'run-eval-500'))
-        runs-on: ubuntu-latest
-        steps:
-            - name: Print all parameters
-              run: |
-                  echo "=== Workflow Parameters ==="
-                  echo "Event: ${{ github.event_name }}"
-                  echo "Actor: ${{ github.actor }}"
-                  echo "Ref: ${{ github.ref }}"
-                  echo ""
-                  echo "=== Input Parameters ==="
-                  echo "benchmark: ${{ github.event.inputs.benchmark || 'swebench' }}"
-                  echo "sdk_ref: ${{ github.event.inputs.sdk_ref || 'N/A' }}"
-                  echo "allow_unreleased_branches: ${{ github.event.inputs.allow_unreleased_branches || 'false' }}"
-                  echo "eval_limit: ${{ github.event.inputs.eval_limit || '1' }}"
-                  echo "model_ids: ${{ github.event.inputs.model_ids || '(default)' }}"
-                  echo "reason: ${{ github.event.inputs.reason || 'N/A' }}"
-                  echo "eval_branch: ${{ github.event.inputs.eval_branch || 'main' }}"
-                  echo "benchmarks_branch: ${{ github.event.inputs.benchmarks_branch || 'main' }}"
-                  echo "instance_ids: ${{ github.event.inputs.instance_ids || 'N/A' }}"
-                  echo "num_infer_workers: ${{ github.event.inputs.num_infer_workers || '(default)' }}"
-                  echo "num_eval_workers: ${{ github.event.inputs.num_eval_workers || '(default)' }}"
-                  echo "enable_conversation_event_logging: ${{ github.event.inputs.enable_conversation_event_logging || 'true' }}"
-                  echo "max_retries: ${{ github.event.inputs.max_retries || '3' }}"
-                  echo "tool_preset: ${{ github.event.inputs.tool_preset || 'default' }}"
-                  echo ""
-                  echo "=== Environment Variables ==="
-                  echo "EVAL_REPO: ${{ env.EVAL_REPO }}"
-                  echo "EVAL_WORKFLOW: ${{ env.EVAL_WORKFLOW }}"
-                  echo ""
-                  echo "=== Label (for PR events) ==="
-                  echo "Label: ${{ github.event.label.name || 'N/A' }}"
-
-    build-and-evaluate:
-        needs: print-parameters
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-            packages: write
-            actions: write
-            issues: write
-            pull-requests: write
-
-        steps:
-            - name: Checkout sdk code (base for validation)
-              uses: actions/checkout@v4
-              with:
-                  ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.sdk_ref || (github.event_name == 'pull_request_target' && 
-                      github.event.pull_request.base.ref || github.ref) }}
-                  fetch-depth: 0
-
-            - name: Set up Python
-              uses: actions/setup-python@v5
-              with:
-                  python-version: '3.13'
-
-            - name: Validate eval_limit
-              if: github.event_name == 'workflow_dispatch'
-              run: |
-                  if ! [[ "${{ github.event.inputs.eval_limit }}" =~ ^[1-9][0-9]*$ ]]; then
-                    echo "Error: eval_limit must be a positive integer, got: ${{ github.event.inputs.eval_limit }}"
-                    exit 1
-                  fi
-
-            - name: Validate SDK reference (semantic version check)
-              if: github.event_name == 'workflow_dispatch'
-              env:
-                  SDK_REF: ${{ github.event.inputs.sdk_ref }}
-                  ALLOW_UNRELEASED_BRANCHES: ${{ github.event.inputs.allow_unreleased_branches }}
-              run: |
-                  python3 .github/run-eval/validate_sdk_ref.py
-
-            - name: Install dependencies
-              run: |
-                  pip install 'litellm>=1.81.0'
-
-            - name: Load model IDs from Python script
-              id: load-models
-              run: |
-                  # Extract all model IDs from resolve_model_config.py
-                  ALLOWED_MODEL_IDS=$(python3 << 'EOF'
-                  import sys
-                  sys.path.insert(0, '.github/run-eval')
-                  from resolve_model_config import MODELS
-                  import json
-                  print(json.dumps(list(MODELS.keys())))
-                  EOF
-                  )
-                  DEFAULT_MODEL=$(echo "$ALLOWED_MODEL_IDS" | jq -r '.[0]')
-                  if [ -z "$DEFAULT_MODEL" ] || [ "$DEFAULT_MODEL" = "null" ]; then
-                    echo "No models configured" >&2
-                    exit 1
-                  fi
-                  echo "allowed_model_ids=$ALLOWED_MODEL_IDS" >> "$GITHUB_OUTPUT"
-                  echo "default_model=$DEFAULT_MODEL" >> "$GITHUB_OUTPUT"
-
-            - name: Resolve parameters
-              id: params
-              env:
-                  DEFAULT_MODEL: ${{ steps.load-models.outputs.default_model }}
-                  ALLOWED_MODEL_IDS_JSON: ${{ steps.load-models.outputs.allowed_model_ids }}
-                  PAT_TOKEN_DEFAULT: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-              run: |
-                  set -euo pipefail
-
-                  # Set PAT token for cross-repo workflow dispatch
-                  PAT_TOKEN="$PAT_TOKEN_DEFAULT"
-                  if [ -z "$PAT_TOKEN" ]; then
-                    echo "Missing PAT token" >&2
-                    exit 1
-                  fi
-                  echo "PAT_TOKEN=$PAT_TOKEN" >> "$GITHUB_ENV"
-
-                  # Determine eval limit and SDK SHA based on trigger
-                  if [ "${{ github.event_name }}" = "pull_request_target" ]; then
-                    LABEL="${{ github.event.label.name }}"
-                    case "$LABEL" in
-                      run-eval-1) EVAL_LIMIT=1 ;;
-                      run-eval-50) EVAL_LIMIT=50 ;;
-                      run-eval-200) EVAL_LIMIT=200 ;;
-                      run-eval-500) EVAL_LIMIT=500 ;;
-                      *) echo "Unsupported label $LABEL" >&2; exit 1 ;;
-                    esac
-                    SDK_SHA="${{ github.event.pull_request.head.sha }}"
-                    PR_NUMBER="${{ github.event.pull_request.number }}"
-                    TRIGGER_DESCRIPTION="Label '${LABEL}' on PR #${PR_NUMBER}"
-                  elif [ "${{ github.event_name }}" = "release" ]; then
-                    EVAL_LIMIT=50
-                    # Use tag instead of target_commitish because release branches are automatically deleted after merge
-                    SDK_SHA=$(git rev-parse "${{ github.event.release.tag_name }}")
-                    PR_NUMBER=""
-                    TRIGGER_DESCRIPTION="Release ${{ github.event.release.tag_name }}"
-                  else
-                    EVAL_LIMIT="${{ github.event.inputs.eval_limit }}"
-                    SDK_REF="${{ github.event.inputs.sdk_ref }}"
-                    # Convert ref to SHA for manual dispatch
-                    # Resolve SHA robustly for both branch refs and raw SHAs (avoid double-prefix issues)
-                    SDK_SHA=$(git rev-parse --verify "$SDK_REF^{commit}" 2>/dev/null || \
-                              git rev-parse --verify "origin/$SDK_REF^{commit}" 2>/dev/null || \
-                              echo "$SDK_REF")
-                    PR_NUMBER=""
-                    REASON="${{ github.event.inputs.reason }}"
-                    if [ -z "$REASON" ]; then
-                      REASON="manual"
-                    fi
-                    TRIGGER_DESCRIPTION="Manual trigger: ${REASON}"
-                  fi
-
-                  # Normalize and validate model IDs
-                  MODELS_INPUT="${{ github.event_name == 'workflow_dispatch' && github.event.inputs.model_ids || '' }}"
-                  if [ -z "$MODELS_INPUT" ]; then
-                    MODELS_INPUT="$DEFAULT_MODEL"
-                  fi
-                  MODELS=$(printf '%s' "$MODELS_INPUT" | tr ', ' '\n' | sed '/^$/d' | paste -sd, -)
-                  ALLOWED_LIST=$(echo "$ALLOWED_MODEL_IDS_JSON" | jq -r '.[]')
-                  for MODEL in ${MODELS//,/ }; do
-                    if ! echo "$ALLOWED_LIST" | grep -Fx "$MODEL" >/dev/null; then
-                      echo "Model ID '$MODEL' not found in models.json" >&2
-                      echo "Available models: $(echo "$ALLOWED_LIST" | paste -sd, -)" >&2
-                      exit 1
-                    fi
-                  done
-
-                  # Sanitize values to avoid GITHUB_OUTPUT parse errors (e.g., raw SHAs)
-                  SDK_SHA=$(printf '%s' "$SDK_SHA" | tr -d '\n\r')
-                  EVAL_LIMIT=$(printf '%s' "$EVAL_LIMIT" | tr -d '\n\r')
-                  PR_NUMBER=$(printf '%s' "$PR_NUMBER" | tr -d '\n\r')
-                  MODELS=$(printf '%s' "$MODELS" | tr -d '\n\r')
-                  TRIGGER_DESCRIPTION=$(printf '%s' "$TRIGGER_DESCRIPTION" | tr -d '\n\r')
-
-                  printf 'eval_limit=%s\n' "$EVAL_LIMIT" >> "$GITHUB_OUTPUT"
-                  printf 'sdk_sha=%s\n' "$SDK_SHA" >> "$GITHUB_OUTPUT"
-                  printf 'models=%s\n' "$MODELS" >> "$GITHUB_OUTPUT"
-                  printf 'pr_number=%s\n' "$PR_NUMBER" >> "$GITHUB_OUTPUT"
-                  printf 'trigger_desc=%s\n' "$TRIGGER_DESCRIPTION" >> "$GITHUB_OUTPUT"
-
-            - name: Resolve model configurations and verify availability
-              id: resolve-models
-              env:
-                  MODEL_IDS: ${{ steps.params.outputs.models }}
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY_EVAL }}
-                  LLM_BASE_URL: https://llm-proxy.eval.all-hands.dev
-              run: |
-                  python3 .github/run-eval/resolve_model_config.py
-
-            - name: Dispatch evaluation workflow
-              env:
-                  SDK_SHA: ${{ steps.params.outputs.sdk_sha }}
-                  EVAL_LIMIT: ${{ steps.params.outputs.eval_limit }}
-                  MODELS_JSON: ${{ steps.resolve-models.outputs.models_json }}
-                  EVAL_REPO: ${{ env.EVAL_REPO }}
-                  EVAL_WORKFLOW: ${{ env.EVAL_WORKFLOW }}
-                  EVAL_BRANCH: ${{ github.event.inputs.eval_branch || 'main' }}
-                  BENCHMARKS_BRANCH: ${{ github.event.inputs.benchmarks_branch || 'main' }}
-                  BENCHMARK: ${{ github.event.inputs.benchmark || 'swebench' }}
-                  TRIGGER_REASON: ${{ github.event.inputs.reason }}
-                  PR_NUMBER: ${{ steps.params.outputs.pr_number }}
-                  INSTANCE_IDS: ${{ github.event.inputs.instance_ids || '' }}
-                  NUM_INFER_WORKERS: ${{ github.event.inputs.num_infer_workers || '' }}
-                  NUM_EVAL_WORKERS: ${{ github.event.inputs.num_eval_workers || '' }}
-                  ENABLE_CONVERSATION_EVENT_LOGGING: ${{ github.event.inputs.enable_conversation_event_logging || false }}
-                  MAX_RETRIES: ${{ github.event.inputs.max_retries || '3' }}
-                  TOOL_PRESET: ${{ github.event.inputs.tool_preset || 'default' }}
-                  AGENT_TYPE: ${{ github.event.inputs.agent_type || 'default' }}
-                  TRIGGERED_BY: ${{ github.actor }}
-              run: |
-                  # Normalize instance_ids: strip all spaces
-                  INSTANCE_IDS=$(printf '%s' "$INSTANCE_IDS" | tr -d ' ')
-
-                  echo "Dispatching evaluation workflow with SDK commit: $SDK_SHA (benchmark: $BENCHMARK, eval branch: $EVAL_BRANCH, benchmarks branch: $BENCHMARKS_BRANCH, tool preset: $TOOL_PRESET)"
-                  PAYLOAD=$(jq -n \
-                    --arg sdk "$SDK_SHA" \
-                    --arg eval_limit "$EVAL_LIMIT" \
-                    --argjson models "$MODELS_JSON" \
-                    --arg ref "$EVAL_BRANCH" \
-                    --arg reason "$TRIGGER_REASON" \
-                    --arg pr "$PR_NUMBER" \
-                    --arg benchmarks "$BENCHMARKS_BRANCH" \
-                    --arg benchmark "$BENCHMARK" \
-                    --arg instance_ids "$INSTANCE_IDS" \
-                    --arg num_infer_workers "$NUM_INFER_WORKERS" \
-                    --arg num_eval_workers "$NUM_EVAL_WORKERS" \
-                    --argjson enable_conversation_event_logging "$ENABLE_CONVERSATION_EVENT_LOGGING" \
-                    --arg max_retries "$MAX_RETRIES" \
-                    --arg tool_preset "$TOOL_PRESET" \
-                    --arg agent_type "$AGENT_TYPE" \
-                    --arg triggered_by "$TRIGGERED_BY" \
-                    '{ref: $ref, inputs: {sdk_commit: $sdk, eval_limit: $eval_limit, models_json: ($models | tostring), trigger_reason: $reason, pr_number: $pr, benchmarks_branch: $benchmarks, benchmark: $benchmark, instance_ids: $instance_ids, num_infer_workers: $num_infer_workers, num_eval_workers: $num_eval_workers, enable_conversation_event_logging: $enable_conversation_event_logging, max_retries: $max_retries, tool_preset: $tool_preset, agent_type: $agent_type, triggered_by: $triggered_by}}')
-                  RESPONSE=$(curl -sS -o /tmp/dispatch.out -w "%{http_code}" -X POST \
-                    -H "Authorization: token $PAT_TOKEN" \
-                    -H "Accept: application/vnd.github+json" \
-                    -d "$PAYLOAD" \
-                    "https://api.github.com/repos/${EVAL_REPO}/actions/workflows/${EVAL_WORKFLOW}/dispatches")
-                  if [ "$RESPONSE" != "204" ]; then
-                    echo "Dispatch failed (status $RESPONSE):" >&2
-                    cat /tmp/dispatch.out >&2
-                    exit 1
-                  fi
-
-            - name: Comment on PR
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-                  SDK_SHA: ${{ steps.params.outputs.sdk_sha }}
-                  EVAL_LIMIT: ${{ steps.params.outputs.eval_limit }}
-                  MODELS: ${{ steps.params.outputs.models }}
-                  TRIGGER_DESC: ${{ steps.params.outputs.trigger_desc }}
-                  EVENT_NAME: ${{ github.event_name }}
-                  PR_NUMBER_INPUT: ${{ steps.params.outputs.pr_number }}
-              run: |
-                  set -euo pipefail
-                  PR_NUMBER="$PR_NUMBER_INPUT"
-                  if [ "$EVENT_NAME" = "release" ] && [ -z "$PR_NUMBER" ]; then
-                    # Attempt to find the merged PR for this commit
-                    PR_NUMBER=$(curl -sS \
-                      -H "Authorization: Bearer $GITHUB_TOKEN" \
-                      -H "Accept: application/vnd.github+json" \
-                      "https://api.github.com/repos/${{ github.repository }}/commits/${SDK_SHA}/pulls" \
-                      | jq -r '.[0].number // ""')
-                  fi
-
-                  if [ -z "$PR_NUMBER" ]; then
-                    echo "No PR found to comment on; skipping comment"
-                    exit 0
-                  fi
-
-                  COMMENT_BODY=$(printf '**Evaluation Triggered**\n\n- Trigger: %s\n- SDK: %s\n- Eval limit: %s\n- Models: %s\n' \
-                    "$TRIGGER_DESC" "$SDK_SHA" "$EVAL_LIMIT" "$MODELS")
-
-                  curl -sS -X POST \
-                    -H "Accept: application/vnd.github+json" \
-                    -H "Authorization: Bearer $GITHUB_TOKEN" \
-                    "https://api.github.com/repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
-                    -d "$(jq -n --arg body "$COMMENT_BODY" '{body: $body}')"

.github/workflows/run-examples.yml

@@ -1,199 +0,0 @@
----
-name: Run Examples Scripts
-
-on:
-    pull_request:
-        types: [labeled]
-    workflow_dispatch:
-        inputs:
-            reason:
-                description: Reason for manual trigger
-                required: true
-                default: ''
-    schedule:
-        - cron: 30 22 * * * # Runs at 10:30pm UTC every day
-
-permissions:
-    contents: read
-    pull-requests: write
-    issues: write
-
-jobs:
-    test-examples:
-        # Schedule trigger only runs in the main repository, not in forks
-        if: github.event.label.name == 'test-examples' || github.event_name == 'workflow_dispatch' || (github.event_name == 'schedule' && 
-            github.repository == 'OpenHands/software-agent-sdk')
-        runs-on: ubuntu-24.04
-        timeout-minutes: 60
-        steps:
-            - name: Wait for agent server to finish build
-              if: github.event_name == 'pull_request'
-              uses: lewagon/wait-on-check-action@v1.4.1
-              with:
-                  ref: ${{ github.event.pull_request.head.ref }}
-                  check-name: Build & Push (python-amd64)
-                  repo-token: ${{ secrets.GITHUB_TOKEN }}
-                  wait-interval: 10
-
-            - name: Checkout
-              uses: actions/checkout@v5
-              with:
-                  ref: ${{ github.event.pull_request.head.ref }}
-                  repository: ${{ github.event.pull_request.head.repo.full_name }}
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Install Node.js
-              uses: actions/setup-node@v6
-              with:
-                  node-version: '22'
-
-            - name: Setup Apptainer
-              uses: eWaterCycle/setup-apptainer@v2
-              with:
-                  apptainer-version: 1.3.6
-
-            - name: Install Chromium
-              run: |
-                  sudo apt-get update
-                  sudo apt-get install -y chromium-browser
-
-            - name: Install dependencies
-              run: uv sync --frozen --group dev
-
-            - name: Run examples
-              shell: bash
-              env:
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
-                  LLM_MODEL: openhands/claude-haiku-4-5-20251001
-                  LLM_BASE_URL: https://llm-proxy.app.all-hands.dev
-                  RUNTIME_API_KEY: ${{ secrets.RUNTIME_API_KEY }}
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-                  PR_NUMBER: ${{ github.event.pull_request.number }}
-                  REPO_OWNER: ${{ github.repository_owner }}
-                  REPO_NAME: ${{ github.event.repository.name }}
-                  GITHUB_SHA: ${{ github.event.pull_request.head.sha }}
-                  OPENHANDS_CLOUD_API_KEY: ${{ secrets.ALLHANDS_BOT_OPENHANDS_SAAS_API_KEY }}
-                  # ACP agents (Claude Code, Codex) route through LiteLLM proxy
-                  ANTHROPIC_BASE_URL: https://llm-proxy.app.all-hands.dev
-                  ANTHROPIC_API_KEY: ${{ secrets.LLM_API_KEY }}
-                  OPENAI_BASE_URL: https://llm-proxy.app.all-hands.dev
-                  OPENAI_API_KEY: ${{ secrets.LLM_API_KEY }}
-              run: |
-                  RESULTS_DIR=".example-test-results"
-                  REPORT_PATH="examples_report.md"
-                  rm -rf "$RESULTS_DIR"
-                  mkdir -p "$RESULTS_DIR"
-
-                  update_comment() {
-                      if [ -z "$API_URL" ]; then
-                          echo "Skipping PR comment update because API_URL is unset."
-                          return
-                      fi
-
-                      local comment_body="$1"
-                      local payload
-                      local response
-
-                      payload=$(jq -n --arg body "$comment_body" '{body: $body}')
-
-                      if [ -z "$COMMENT_ID" ]; then
-                          echo "Creating PR comment..."
-                          if ! response=$(curl -sSf -X POST \
-                              -H "Authorization: token ${GITHUB_TOKEN}" \
-                              -H "Accept: application/vnd.github.v3+json" \
-                              -H "Content-Type: application/json" \
-                              "${API_URL}" \
-                              -d "$payload"); then
-                              echo "::error::Failed to create PR comment."
-                              exit 1
-                          fi
-                          COMMENT_ID=$(echo "$response" | jq -r '.id // ""')
-                          if [ -z "$COMMENT_ID" ]; then
-                              echo "::error::GitHub API response did not include a comment id: $response"
-                              exit 1
-                          fi
-                          echo "Created comment with ID: $COMMENT_ID"
-                      else
-                          echo "Updating PR comment (ID: $COMMENT_ID)..."
-                          if ! curl -sSf -X PATCH \
-                              -H "Authorization: token ${GITHUB_TOKEN}" \
-                              -H "Accept: application/vnd.github.v3+json" \
-                              -H "Content-Type: application/json" \
-                              "https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/issues/comments/${COMMENT_ID}" \
-                              -d "$payload" > /dev/null; then
-                              echo "::error::Failed to update PR comment (ID: $COMMENT_ID)."
-                              exit 1
-                          fi
-                      fi
-                  }
-
-                  API_URL=""
-                  COMMENT_ID=""
-
-                  if [ "${{ github.event_name }}" = "pull_request" ]; then
-                      API_URL="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/issues/${PR_NUMBER}/comments"
-                      initial_comment="## 🔄 Running Examples with \`${LLM_MODEL}\`"
-                      initial_comment+=$'\n\n'
-                      initial_comment+="_Run in progress..._"
-                      initial_comment+=$'\n'
-                      update_comment "$initial_comment"
-                  fi
-
-                  EXIT_CODE=0
-                  uv run pytest tests/examples/test_examples.py \
-                      --run-examples \
-                      --examples-results-dir "$RESULTS_DIR" \
-                      -n 4 || EXIT_CODE=$?
-
-                  TIMESTAMP="$(date -u '+%Y-%m-%d %H:%M:%S UTC')"
-                  WORKFLOW_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
-
-                  uv run python scripts/render_examples_report.py \
-                      --results-dir "$RESULTS_DIR" \
-                      --model "$LLM_MODEL" \
-                      --workflow-url "$WORKFLOW_URL" \
-                      --timestamp "$TIMESTAMP" \
-                      --output "$REPORT_PATH"
-
-                  COMMENT_BODY="$(cat "$REPORT_PATH")"
-                  echo "$COMMENT_BODY"
-
-                  if [ "${{ github.event_name }}" = "pull_request" ]; then
-                      echo "Publishing PR comment..."
-                      update_comment "$COMMENT_BODY"
-                  fi
-
-                  if [ $EXIT_CODE -ne 0 ]; then
-                      exit $EXIT_CODE
-                  fi
-            - name: Read examples report for issue comment
-              if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
-              id: read_report
-              shell: bash
-              run: |
-                  if [ -f examples_report.md ]; then
-                      REPORT_CONTENT=$(cat examples_report.md)
-                      echo "report<<EOF" >> "$GITHUB_OUTPUT"
-                      echo "$REPORT_CONTENT" >> "$GITHUB_OUTPUT"
-                      echo "EOF" >> "$GITHUB_OUTPUT"
-                  else
-                      echo "report=Report file not found" >> "$GITHUB_OUTPUT"
-                  fi
-
-            - name: Comment with results on tracker issue
-              if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
-              uses: KeisukeYamashita/create-comment@v1
-              with:
-                  number: 976
-                  unique: false
-                  comment: |
-                      **Trigger:** ${{ github.event_name == 'schedule' && 'Nightly Scheduled Run' || format('Manual Trigger: {0}', github.event.inputs.reason) }}
-                      **Commit:** ${{ github.sha }}
-                      **Workflow Run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-
-                      ${{ steps.read_report.outputs.report }}

.github/workflows/server.yml

@@ -1,715 +0,0 @@
----
-name: Agent Server
-
-on:
-    push:
-        branches: [main]
-        tags:
-            - '*'  # Trigger on any tag (e.g., 1.0.0, 1.0.0a5, build-docker)
-    pull_request:
-        branches: [main]
-    workflow_dispatch:
-        inputs:
-            base_image:
-                description: Base runtime image
-                type: string
-                default: nikolaik/python-nodejs:python3.13-nodejs22-slim
-            image:
-                description: GHCR image name
-                type: string
-                default: ghcr.io/openhands/agent-server
-            platforms:
-                description: Target platforms
-                type: string
-                default: linux/amd64,linux/arm64
-
-permissions:
-    contents: read
-    packages: write
-
-jobs:
-    build-binary-and-test:
-        runs-on: ${{ matrix.os }}
-        strategy:
-            matrix:
-                os: [ubuntu-latest, macos-latest]
-        steps:
-            - uses: actions/checkout@v5
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-            - name: Install dependencies
-              run: uv sync --dev
-
-            - name: Build binary
-              run: |
-                  make build-server
-
-            # FIXME: windows-latest not working due to
-            # Run if [[ "windows-latest" == "windows-latest" ]]; then
-            # [PYI-2160:ERROR] Failed to load Python DLL 'C:\Users\RUNNER~1\AppData\Local\Temp\_MEI5602\python312.dll'.
-            # LoadLibrary: Invalid access to memory location.
-            # - name: Test binary (Windows)
-            #   if: matrix.os == 'windows-latest'
-            #   shell: pwsh
-            #   run: |
-            #       Get-ChildItem dist
-            #       .\dist\openhands-agent-server.exe --help
-
-            - name: Test binary (Linux and macOS)
-              if: matrix.os != 'windows-latest'
-              shell: bash
-              run: |
-                  # Test help command
-                  ./dist/openhands-agent-server --help
-
-                  # Test server startup and template loading
-                  echo "Testing server startup and template loading..."
-                  ./dist/openhands-agent-server --port 8002 > server_test.log 2>&1 &
-                  SERVER_PID=$!
-
-                  # Wait for server to start
-                  sleep 5
-
-                  # Check if server started successfully (no template errors)
-                  if grep -q "system_prompt.j2.*not found" server_test.log; then
-                      echo "ERROR: Template files not found in binary!"
-                      cat server_test.log
-                      kill $SERVER_PID 2>/dev/null || true
-                      exit 1
-                  fi
-
-                  # Check if server is running
-                  if ! kill -0 $SERVER_PID 2>/dev/null; then
-                      echo "ERROR: Server failed to start!"
-                      cat server_test.log
-                      exit 1
-                  fi
-
-                  # Test basic API endpoint
-                  if command -v curl >/dev/null 2>&1; then
-                      echo "Testing basic API endpoint..."
-                      if curl -f -s http://localhost:8002/health >/dev/null 2>&1; then
-                          echo "✓ Health endpoint accessible"
-                      else
-                          echo "⚠ Health endpoint not accessible (may be expected)"
-                      fi
-                  fi
-
-                  # Clean up
-                  kill $SERVER_PID 2>/dev/null || true
-                  wait $SERVER_PID 2>/dev/null || true
-                  rm -f server_test.log
-
-                  echo "✓ Binary test completed successfully"
-
-            - name: Upload binary artifact
-              uses: actions/upload-artifact@v7
-              with:
-                  name: openhands-server-${{ matrix.os }}
-                  path: |
-                      dist/openhands-server*
-                  retention-days: 7
-
-    check-openapi-schema:
-        name: Check OpenAPI Schema
-        runs-on: ubuntu-24.04
-
-        steps:
-            - name: Checkout PR branch
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Install Node.js (for npx)
-              uses: actions/setup-node@v6
-              with:
-                  node-version: 22
-
-
-            - name: Install dependencies
-              run: |
-                  uv sync --frozen --dev
-
-            - name: Check OpenAPI JSON and build client
-              env:
-                  PYTHONPATH: .
-              run: |
-                  make test-server-schema
-
-    build-and-push-image:
-        name: Build & Push (${{ matrix.variant }}-${{ matrix.arch }})
-        # Run on push events, pull requests from the same repository (not forks), and manual workflow_dispatch
-        # Fork PRs cannot push to GHCR and would fail authentication
-        if: >
-            github.event_name == 'push' ||
-            github.event_name == 'workflow_dispatch' ||
-            (github.event_name == 'pull_request' &&
-             !github.event.pull_request.head.repo.fork)
-        strategy:
-            fail-fast: false
-            matrix:
-                # Explicit matrix: 3 variants × 2 architectures = 6 jobs
-                # Each job specifies exactly what it builds and where it runs
-                include:
-                    # Python variant
-                    - variant: python
-                      arch: amd64
-                      base_image: nikolaik/python-nodejs:python3.13-nodejs22
-                      runner: ubuntu-24.04
-                      platform: linux/amd64
-
-                    - variant: python
-                      arch: arm64
-                      base_image: nikolaik/python-nodejs:python3.13-nodejs22
-                      runner: ubuntu-24.04-arm
-                      platform: linux/arm64
-
-                    # Java variant
-                    - variant: java
-                      arch: amd64
-                      base_image: eclipse-temurin:17-jdk
-                      runner: ubuntu-24.04
-                      platform: linux/amd64
-
-                    - variant: java
-                      arch: arm64
-                      base_image: eclipse-temurin:17-jdk
-                      runner: ubuntu-24.04-arm
-                      platform: linux/arm64
-
-                    # Golang variant
-                    - variant: golang
-                      arch: amd64
-                      base_image: golang:1.21-bookworm
-                      runner: ubuntu-24.04
-                      platform: linux/amd64
-
-                    - variant: golang
-                      arch: arm64
-                      base_image: golang:1.21-bookworm
-                      runner: ubuntu-24.04-arm
-                      platform: linux/arm64
-
-        runs-on: ${{ matrix.runner }}
-
-        env:
-            IMAGE: ${{ inputs.image != '' && inputs.image || 'ghcr.io/openhands/agent-server' }}
-            BASE_IMAGE: ${{ inputs.base_image != '' && inputs.base_image || matrix.base_image }}
-            CUSTOM_TAGS: ${{ matrix.variant }}
-            VARIANT: ${{ matrix.variant }}
-            ARCH: ${{ matrix.arch }}
-            TARGET: binary
-            PLATFORM: ${{ matrix.platform }}
-            # Use PR head SHA for pull requests to match the image tag expected by run-examples.yml
-            GITHUB_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
-            GITHUB_REF: ${{ github.ref }}
-            CI: 'true'
-
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.13'
-
-            - name: Set up Docker Buildx
-              uses: docker/setup-buildx-action@v3
-
-            - name: Log in to GHCR
-              uses: docker/login-action@v4
-              with:
-                  registry: ghcr.io
-                  username: ${{ github.actor }}
-                  password: ${{ secrets.GITHUB_TOKEN }}
-
-            - name: Prepare build context and metadata
-              id: prep
-              run: |
-                  uv sync --frozen
-
-                  # Generate build context and tags with arch suffix
-                  # build.py now handles architecture tagging internally via --arch flag
-                  # Add --versioned-tag when triggered by a git tag (e.g., v1.0.0)
-                  BUILD_CMD="uv run ./openhands-agent-server/openhands/agent_server/docker/build.py --build-ctx-only --arch ${{ matrix.arch }}"
-                  if [[ "${{ github.ref }}" == refs/tags/* ]]; then
-                      BUILD_CMD="$BUILD_CMD --versioned-tag"
-                  fi
-                  eval "$BUILD_CMD"
-
-                  # Alias tags_csv output to tags for the build action
-                  TAGS=$(grep '^tags_csv=' $GITHUB_OUTPUT | cut -d= -f2-)
-                  echo "tags=$TAGS" >> $GITHUB_OUTPUT
-
-                  # Extract short SHA for consolidation
-                  SHORT_SHA=$(echo ${{ github.sha }} | cut -c1-7)
-                  echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
-
-                  # Extract versioned tags CSV for consolidation
-                  VERSIONED_TAGS_CSV=$(grep '^versioned_tags_csv=' $GITHUB_OUTPUT | cut -d= -f2- || echo "")
-                  echo "versioned_tags_csv=$VERSIONED_TAGS_CSV" >> $GITHUB_OUTPUT
-
-                  # Verify outputs
-                  echo "=== Build outputs ==="
-                  echo "Build context: $(grep '^build_context=' $GITHUB_OUTPUT | cut -d= -f2-)"
-                  echo "Tags: $TAGS"
-                  echo "Short SHA: $SHORT_SHA"
-                  echo "Versioned tags: $VERSIONED_TAGS_CSV"
-                  echo "===================="
-
-            - name: Build & Push (${{ matrix.variant }}-${{ matrix.arch }})
-              id: build
-              uses: docker/build-push-action@v6
-              with:
-                  context: ${{ steps.prep.outputs.build_context }}
-                  file: ${{ steps.prep.outputs.dockerfile }}
-                  target: ${{ env.TARGET }}
-                  platforms: ${{ env.PLATFORM }}
-                  push: true
-                  tags: ${{ steps.prep.outputs.tags }}
-                  cache-from: type=gha
-                  cache-to: type=gha,mode=max
-                  build-args: |
-                      BASE_IMAGE=${{ env.BASE_IMAGE }}
-
-            - name: Cleanup build context
-              if: always()
-              run: |
-                  if [ -n "${{ steps.prep.outputs.build_context }}" ] && [ -d "${{ steps.prep.outputs.build_context }}" ]; then
-                      echo "Cleaning up build context: ${{ steps.prep.outputs.build_context }}"
-                      rm -rf "${{ steps.prep.outputs.build_context }}"
-                  fi
-
-            - name: Summary (${{ matrix.variant }}-${{ matrix.arch }}) - outputs
-              run: |
-                  echo "Image: ${{ env.IMAGE }}"
-                  echo "Variant: ${{ env.VARIANT }}"
-                  echo "Architecture: ${{ env.ARCH }}"
-                  echo "Platform: ${{ env.PLATFORM }}"
-                  echo "Short SHA: ${{ steps.prep.outputs.short_sha }}"
-                  echo "Tags: ${{ steps.prep.outputs.tags }}"
-                  echo "Build digest: ${{ steps.build.outputs.digest }}"
-
-            - name: Save build info for consolidation
-              run: |
-                  mkdir -p build-info
-                  cat > "build-info/${{ matrix.variant }}-${{ matrix.arch }}.json" << EOF
-                  {
-                    "variant": "${{ matrix.variant }}",
-                    "arch": "${{ matrix.arch }}",
-                    "base_image": "${{ matrix.base_image }}",
-                    "image": "${{ env.IMAGE }}",
-                    "short_sha": "${{ steps.prep.outputs.short_sha }}",
-                    "tags": "${{ steps.prep.outputs.tags }}",
-                    "versioned_tags_csv": "${{ steps.prep.outputs.versioned_tags_csv }}",
-                    "platform": "${{ env.PLATFORM }}"
-                  }
-                  EOF
-
-            - name: Upload build info artifact
-              uses: actions/upload-artifact@v7
-              with:
-                  name: build-info-${{ matrix.variant }}-${{ matrix.arch }}
-                  path: build-info/${{ matrix.variant }}-${{ matrix.arch }}.json
-                  retention-days: 1
-
-    merge-manifests:
-        name: Merge Multi-Arch Manifests
-        needs: build-and-push-image
-        if: >
-            github.event_name == 'push' ||
-            (github.event_name == 'pull_request' &&
-             !github.event.pull_request.head.repo.fork)
-        runs-on: ubuntu-24.04
-        strategy:
-            matrix:
-                variant: [python, java, golang]
-        env:
-            IMAGE: ${{ inputs.image != '' && inputs.image || 'ghcr.io/openhands/agent-server' }}
-
-        steps:
-            - name: Download build info to extract SHORT_SHA
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: build-info-${{ matrix.variant }}-*
-                  merge-multiple: true
-                  path: build-info
-
-            - name: Extract SHORT_SHA from build info
-              id: get_sha
-              run: |
-                  # Get SHORT_SHA from any build info artifact for this variant
-                  SHORT_SHA=$(jq -r '.short_sha' build-info/${{ matrix.variant }}-amd64.json)
-                  echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
-                  echo "Using SHORT_SHA: $SHORT_SHA"
-
-            - name: Set up Docker Buildx
-              uses: docker/setup-buildx-action@v3
-
-            - name: Log in to GHCR
-              uses: docker/login-action@v4
-              with:
-                  registry: ghcr.io
-                  username: ${{ github.actor }}
-                  password: ${{ secrets.GITHUB_TOKEN }}
-
-            - name: Create and push multi-arch manifest for ${{ matrix.variant }}
-              id: create_manifest
-              run: |
-                  SHORT_SHA=${{ steps.get_sha.outputs.short_sha }}
-                  VARIANT=${{ matrix.variant }}
-                  MANIFEST_TAG="${SHORT_SHA}-${VARIANT}"
-
-                  # Create multi-arch manifest combining amd64 and arm64 using buildx imagetools
-                  # This properly handles manifest lists from Docker builds
-                  echo "Creating multi-arch manifest: ${IMAGE}:${MANIFEST_TAG}"
-                  docker buildx imagetools create -t ${IMAGE}:${MANIFEST_TAG} \
-                    ${IMAGE}:${SHORT_SHA}-${VARIANT}-amd64 \
-                    ${IMAGE}:${SHORT_SHA}-${VARIANT}-arm64
-
-                  # Verify the multi-arch manifest
-                  echo "Inspecting multi-arch manifest:"
-                  docker buildx imagetools inspect ${IMAGE}:${MANIFEST_TAG}
-
-                  echo "✓ Multi-arch manifest created: ${IMAGE}:${MANIFEST_TAG}"
-
-                  # Create latest manifest if on main branch
-                  if [ "${{ github.ref }}" == "refs/heads/main" ]; then
-                      LATEST_TAG="latest-${VARIANT}"
-                      echo "Creating latest multi-arch manifest: ${IMAGE}:${LATEST_TAG}"
-                      docker buildx imagetools create -t ${IMAGE}:${LATEST_TAG} \
-                        ${IMAGE}:main-${VARIANT}-amd64 \
-                        ${IMAGE}:main-${VARIANT}-arm64
-                      
-                      echo "Inspecting latest multi-arch manifest:"
-                      docker buildx imagetools inspect ${IMAGE}:${LATEST_TAG}
-                      echo "✓ Latest multi-arch manifest created: ${IMAGE}:${LATEST_TAG}"
-                      
-                      MANIFEST_TAG="${MANIFEST_TAG},${LATEST_TAG}"
-                  fi
-
-                  # Create versioned manifests if triggered by a git tag
-                  # Extract versioned tags from build info (format: "1.2.0-python,1.2.0-java")
-                  VERSIONED_TAGS_CSV=$(jq -r '.versioned_tags_csv' build-info/${VARIANT}-amd64.json)
-                  if [ -n "$VERSIONED_TAGS_CSV" ] && [ "$VERSIONED_TAGS_CSV" != "null" ] && [ "$VERSIONED_TAGS_CSV" != "" ]; then
-                      echo "Found versioned tags: $VERSIONED_TAGS_CSV"
-                      # Split CSV and create manifest for each versioned tag
-                      IFS=',' read -ra VERSIONED_TAGS <<< "$VERSIONED_TAGS_CSV"
-                      for VERSIONED_TAG in "${VERSIONED_TAGS[@]}"; do
-                          if [ -n "$VERSIONED_TAG" ]; then
-                              echo "Creating versioned multi-arch manifest: ${IMAGE}:${VERSIONED_TAG}"
-                              docker buildx imagetools create -t ${IMAGE}:${VERSIONED_TAG} \
-                                ${IMAGE}:${VERSIONED_TAG}-amd64 \
-                                ${IMAGE}:${VERSIONED_TAG}-arm64
-                              
-                              echo "Inspecting versioned multi-arch manifest:"
-                              docker buildx imagetools inspect ${IMAGE}:${VERSIONED_TAG}
-                              echo "✓ Versioned multi-arch manifest created: ${IMAGE}:${VERSIONED_TAG}"
-                              
-                              MANIFEST_TAG="${MANIFEST_TAG},${VERSIONED_TAG}"
-                          fi
-                      done
-                  fi
-
-                  # Save manifest info for consolidation
-                  mkdir -p manifest-info
-                  cat > "manifest-info/${VARIANT}.json" << EOF
-                  {
-                    "variant": "${VARIANT}",
-                    "image": "${IMAGE}",
-                    "short_sha": "${SHORT_SHA}",
-                    "manifest_tag": "${MANIFEST_TAG}"
-                  }
-                  EOF
-
-            - name: Upload manifest info artifact
-              uses: actions/upload-artifact@v7
-              with:
-                  name: manifest-info-${{ matrix.variant }}
-                  path: manifest-info/${{ matrix.variant }}.json
-                  retention-days: 1
-
-    consolidate-build-info:
-        name: Consolidate Build Information
-        needs: [build-and-push-image, merge-manifests]
-        # Run if it's a PR and the matrix job completed (even if some variants failed)
-        if: github.event_name == 'pull_request' && always() && (needs.build-and-push-image.result == 'success' || needs.build-and-push-image.result ==
-            'failure')
-        runs-on: ubuntu-24.04
-        outputs:
-            build_summary: ${{ steps.consolidate.outputs.build_summary }}
-        steps:
-            - name: Download build info artifacts
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: build-info-*
-                  merge-multiple: true
-                  path: build-info
-
-            - name: Download manifest info artifacts
-              uses: actions/download-artifact@v8
-              with:
-                  pattern: manifest-info-*
-                  merge-multiple: true
-                  path: manifest-info
-
-            - name: Consolidate build information from artifacts
-              id: consolidate
-              run: |
-                  echo "Processing build info artifacts..."
-                  ls -la build-info/
-                  echo "Found $(ls build-info/*.json 2>/dev/null | wc -l) JSON files"
-
-                  # Initialize variables
-                  IMAGE=""
-                  SHORT_SHA=""
-                  ALL_TAGS=""
-
-                  # Use associative arrays to track variants (bash 4+)
-                  declare -A VARIANT_BASE_IMAGE
-                  declare -A VARIANT_ARCHS
-
-                  # Process each build info
-                  for info_file in build-info/*.json; do
-                      if [[ ! -f "$info_file" ]]; then
-                          echo "Skipping $info_file - not a file"
-                          continue
-                      fi
-                      
-                      echo "=== Processing $info_file ==="
-                      cat "$info_file"
-                      echo "=== End of $info_file ==="
-                      
-                      # Extract information from JSON
-                      VARIANT=$(jq -r '.variant' "$info_file")
-                      ARCH=$(jq -r '.arch' "$info_file")
-                      BASE_IMAGE=$(jq -r '.base_image' "$info_file")
-                      VARIANT_IMAGE=$(jq -r '.image' "$info_file")
-                      VARIANT_SHA=$(jq -r '.short_sha' "$info_file")
-                      VARIANT_TAGS=$(jq -r '.tags' "$info_file")
-                      
-                      # Set common values (same across all builds)
-                      if [[ -z "$IMAGE" ]]; then
-                          IMAGE="$VARIANT_IMAGE"
-                          SHORT_SHA="$VARIANT_SHA"
-                      fi
-                      
-                      # Store variant information
-                      VARIANT_BASE_IMAGE[$VARIANT]=$BASE_IMAGE
-                      if [[ -z "${VARIANT_ARCHS[$VARIANT]}" ]]; then
-                          VARIANT_ARCHS[$VARIANT]=$ARCH
-                      else
-                          VARIANT_ARCHS[$VARIANT]="${VARIANT_ARCHS[$VARIANT]}, $ARCH"
-                      fi
-                      
-                      # Collect tags (comma-separated to newline-separated)
-                      if [[ -n "$VARIANT_TAGS" ]]; then
-                          VARIANT_TAG_LIST=$(echo "$VARIANT_TAGS" | tr ',' '\n')
-                          if [[ -n "$ALL_TAGS" ]]; then
-                              ALL_TAGS="${ALL_TAGS}"$'\n'"${VARIANT_TAG_LIST}"
-                          else
-                              ALL_TAGS="$VARIANT_TAG_LIST"
-                          fi
-                      fi
-                  done
-
-                  # Build variants JSON array from collected data
-                  VARIANTS_JSON="[]"
-                  for VARIANT in "${!VARIANT_BASE_IMAGE[@]}"; do
-                      BASE_IMG="${VARIANT_BASE_IMAGE[$VARIANT]}"
-                      ARCHS="${VARIANT_ARCHS[$VARIANT]}"
-                      VARIANTS_JSON=$(echo "$VARIANTS_JSON" | jq \
-                          --arg variant "$VARIANT" \
-                          --arg base_image "$BASE_IMG" \
-                          --arg archs "$ARCHS" \
-                          '. += [{custom_tags: $variant, base_image: $base_image, architectures: $archs}]')
-                      
-                      echo "Added variant $VARIANT ($ARCHS), current variants JSON:"
-                      echo "$VARIANTS_JSON" | jq .
-                  done
-
-                  # Process manifest info artifacts
-                  echo "Processing manifest info artifacts..."
-                  if [[ -d "manifest-info" ]]; then
-                      ls -la manifest-info/
-                      
-                      MANIFEST_TAGS=""
-                      for manifest_file in manifest-info/*.json; do
-                          if [[ -f "$manifest_file" ]]; then
-                              echo "=== Processing $manifest_file ==="
-                              cat "$manifest_file"
-                              
-                              MANIFEST_TAG_CSV=$(jq -r '.manifest_tag' "$manifest_file")
-                              # Convert comma-separated tags to newline-separated
-                              MANIFEST_TAG_LIST=$(echo "$MANIFEST_TAG_CSV" | tr ',' '\n' | sed "s|^|${IMAGE}:|")
-                              
-                              if [[ -n "$MANIFEST_TAGS" ]]; then
-                                  MANIFEST_TAGS="${MANIFEST_TAGS}"$'\n'"${MANIFEST_TAG_LIST}"
-                              else
-                                  MANIFEST_TAGS="$MANIFEST_TAG_LIST"
-                              fi
-                          fi
-                      done
-
-                      # Add manifest tags to ALL_TAGS
-                      if [[ -n "$MANIFEST_TAGS" ]]; then
-                          echo "Adding manifest tags to output"
-                          if [[ -n "$ALL_TAGS" ]]; then
-                              ALL_TAGS="${ALL_TAGS}"$'\n'"${MANIFEST_TAGS}"
-                          else
-                              ALL_TAGS="$MANIFEST_TAGS"
-                          fi
-                      fi
-                  else
-                      echo "No manifest-info directory found (merge-manifests may not have run)"
-                  fi
-
-                  # Create consolidated build summary
-                  BUILD_SUMMARY=$(jq -n \
-                      --arg image "$IMAGE" \
-                      --arg short_sha "$SHORT_SHA" \
-                      --arg ghcr_url "https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server" \
-                      --arg all_tags "$ALL_TAGS" \
-                      --argjson variants "$VARIANTS_JSON" \
-                      '{
-                          image: $image,
-                          short_sha: $short_sha,
-                          ghcr_package_url: $ghcr_url,
-                          all_tags: $all_tags,
-                          variants: $variants
-                      }')
-
-                  echo "Consolidated build summary:"
-                  echo "$BUILD_SUMMARY" | jq .
-
-                  echo "DEBUG: Final variants count: $(echo "$VARIANTS_JSON" | jq 'length')"
-                  echo "DEBUG: Final variants: $(echo "$VARIANTS_JSON" | jq -c '.')"
-
-                  # Set output
-                  {
-                      echo 'build_summary<<EOF'
-                      echo "$BUILD_SUMMARY"
-                      echo 'EOF'
-                  } >> $GITHUB_OUTPUT
-
-    update-pr-description:
-        name: Update PR description with agent server image
-        needs: consolidate-build-info
-        # Only on PRs, and only if the consolidation succeeded
-        if: github.event_name == 'pull_request' && needs.consolidate-build-info.result == 'success'
-        runs-on: ubuntu-24.04
-        permissions:
-            contents: read
-            pull-requests: write
-
-        steps:
-            - name: Generate PR description from build summary
-              id: generate_description
-              run: |
-                  echo "Event: ${{ github.event_name }}"
-                  echo "PR number: ${{ github.event.number }}"
-                  echo "Run attempt: ${{ github.run_attempt }}"
-
-                  # Parse the build summary JSON
-                  BUILD_SUMMARY='${{ needs.consolidate-build-info.outputs.build_summary }}'
-                  echo "Build summary received:"
-                  echo "$BUILD_SUMMARY" | jq .
-
-                  # Extract basic information
-                  IMAGE=$(echo "$BUILD_SUMMARY" | jq -r '.image')
-                  SHORT_SHA=$(echo "$BUILD_SUMMARY" | jq -r '.short_sha')
-                  GHCR_URL=$(echo "$BUILD_SUMMARY" | jq -r '.ghcr_package_url')
-                  ALL_TAGS=$(echo "$BUILD_SUMMARY" | jq -r '.all_tags')
-
-                  # Build the variants table dynamically
-                  VARIANTS_TABLE=""
-
-                  # Process each build
-                  VARIANTS=$(echo "$BUILD_SUMMARY" | jq -r '.variants[] | @base64')
-                  echo "DEBUG: Found builds (base64 encoded):"
-                  echo "$VARIANTS"
-                  echo "DEBUG: Number of builds: $(echo "$VARIANTS" | wc -l)"
-
-                  for variant_data in $VARIANTS; do
-                      # Decode base64 and extract build info
-                      VARIANT_JSON=$(echo "$variant_data" | base64 --decode)
-                      echo "DEBUG: Processing build JSON: $VARIANT_JSON"
-                      CUSTOM_TAGS=$(echo "$VARIANT_JSON" | jq -r '.custom_tags')
-                      BASE_IMAGE=$(echo "$VARIANT_JSON" | jq -r '.base_image')
-                      ARCHS=$(echo "$VARIANT_JSON" | jq -r '.architectures // "amd64, arm64"')
-                      
-                      echo "DEBUG: Adding variant $CUSTOM_TAGS with base image $BASE_IMAGE (archs: $ARCHS)"
-                      # Add to variants table with architecture info
-                      VARIANTS_TABLE="${VARIANTS_TABLE}| ${CUSTOM_TAGS} | ${ARCHS} | \`${BASE_IMAGE}\` | [Link](https://hub.docker.com/_/${BASE_IMAGE}) |"$'\n'
-                  done
-
-                  echo "DEBUG: Final variants table:"
-                  echo "$VARIANTS_TABLE"
-
-                  # Create the complete PR description with the requested format
-                  PR_CONTENT=$(cat << EOF
-
-                  <!-- AGENT_SERVER_IMAGES_START -->
-                  ---
-                  **Agent Server images for this PR**
-
-                  • **GHCR package:** ${GHCR_URL}
-
-                  **Variants & Base Images**
-                  | Variant | Architectures | Base Image | Docs / Tags |
-                  |---|---|---|---|
-                  ${VARIANTS_TABLE}
-
-                  **Pull (multi-arch manifest)**
-                  \`\`\`bash
-                  # Each variant is a multi-arch manifest supporting both amd64 and arm64
-                  docker pull ${IMAGE}:${SHORT_SHA}-python
-                  \`\`\`
-
-                  **Run**
-                  \`\`\`bash
-                  docker run -it --rm \\
-                    -p 8000:8000 \\
-                    --name agent-server-${SHORT_SHA}-python \\
-                    ${IMAGE}:${SHORT_SHA}-python
-                  \`\`\`
-
-                  **All tags pushed for this build**
-                  \`\`\`
-                  ${ALL_TAGS}
-                  \`\`\`
-
-                  **About Multi-Architecture Support**
-                  - Each variant tag (e.g., \`${SHORT_SHA}-python\`) is a **multi-arch manifest** supporting both **amd64** and **arm64**
-                  - Docker automatically pulls the correct architecture for your platform
-                  - Individual architecture tags (e.g., \`${SHORT_SHA}-python-amd64\`) are also available if needed
-                  <!-- AGENT_SERVER_IMAGES_END -->
-                  EOF
-                  )
-
-                  # Set output for the next step
-                  {
-                      echo 'pr_content<<EOF'
-                      echo "$PR_CONTENT"
-                      echo 'EOF'
-                  } >> $GITHUB_OUTPUT
-
-            - name: Update PR description with docker image details
-              uses: nefrob/pr-description@v1.2.0
-              with:
-                  content: ${{ steps.generate_description.outputs.pr_content }}
-                  regex: <!-- AGENT_SERVER_IMAGES_START -->.*?<!-- AGENT_SERVER_IMAGES_END -->
-                  regexFlags: s
-                  token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/stale.yml

@@ -1,30 +1,21 @@
----
 # Workflow that marks issues and PRs with no activity for 30 days with "Stale" and closes them after 7 more days of no activity
-name: Close stale issues
+name: 'Close stale issues'
 
 # Runs every day at 01:30
 on:
-    schedule:
-        - cron: 30 1 * * *
+  schedule:
+    - cron: '30 1 * * *'
 
 jobs:
-    stale:
-        # Only run scheduled jobs in the main repository, not in forks
-        if: github.repository == 'OpenHands/software-agent-sdk'
-        runs-on: ubuntu-22.04
-        steps:
-            - uses: actions/stale@v10
-              with:
-                  repo-token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-                  stale-issue-message: This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a 
-                      comment, otherwise it will be closed in 10 days.
-                  stale-pr-message: This PR is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment,
-                      otherwise it will be closed in 10 days.
-                  days-before-stale: 40
-                  exempt-issue-labels: roadmap,backlog
-                  close-issue-message: This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat 
-                      manageable and focus on active issues.
-                  close-pr-message: This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would 
-                      like to continue the PR, please resubmit or let us know.
-                  days-before-close: 10
-                  operations-per-run: 150
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: 'This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
+          stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
+          days-before-stale: 30
+          exempt-issue-labels: 'tracked'
+          close-issue-message: 'This issue was closed because it has been stalled for over 30 days with no activity.'
+          close-pr-message: 'This PR was closed because it has been stalled for over 30 days with no activity.'
+          days-before-close: 7

.github/workflows/tests.yml

@@ -1,322 +0,0 @@
----
-name: Run tests
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: ['**']
-
-permissions:
-    contents: write
-    pull-requests: write
-
-jobs:
-    sdk-tests:
-        runs-on: blacksmith-2vcpu-ubuntu-2404
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with: {fetch-depth: 0}
-
-            - name: Detect sdk changes
-              id: changed
-              uses: tj-actions/changed-files@v47
-              with:
-                  files: |
-                      openhands-sdk/**
-                      tests/sdk/**
-                      pyproject.toml
-                      uv.lock
-                      .github/workflows/tests.yml
-
-            - name: Install uv
-              if: steps.changed.outputs.any_changed == 'true'
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Install deps
-              if: steps.changed.outputs.any_changed == 'true'
-              run: uv sync --frozen --group dev
-
-            - name: Check for openhands.tools imports in sdk tests
-              if: steps.changed.outputs.any_changed == 'true'
-              run: |
-                  echo "Checking for openhands.tools imports in tests/sdk..."
-                  if grep -r "from openhands\.tools" tests/sdk/ || grep -r "import openhands\.tools" tests/sdk/; then
-                    echo "ERROR: Found openhands.tools imports in tests/sdk/"
-                    echo "SDK tests should only import from openhands.sdk"
-                    echo "Please move tests that use openhands.tools to tests/cross/"
-                    exit 1
-                  fi
-                  echo "✓ No openhands.tools imports found in tests/sdk/"
-
-            - name: Run sdk tests with coverage
-              if: steps.changed.outputs.any_changed == 'true'
-              run: |
-                  # Clean up any existing coverage file
-                  rm -f .coverage
-                  # Use pytest-xdist (-n auto) for parallel execution with proper
-                  # coverage collection. --forked prevents coverage from child processes.
-                  CI=true uv run python -m pytest -vvs \
-                    -n auto \
-                    --cov=openhands-sdk \
-                    --cov-report=term-missing \
-                    --cov-fail-under=0 \
-                    --cov-config=pyproject.toml \
-                    tests/sdk
-                  # Rename coverage file for upload
-                  if [ -f .coverage ]; then
-                    mv .coverage coverage-sdk.dat
-                    echo "SDK coverage file prepared for upload"
-                  fi
-
-            - name: Upload sdk coverage
-              if: steps.changed.outputs.any_changed == 'true' && always()
-              uses: actions/upload-artifact@v7
-              with:
-                  name: coverage-sdk
-                  path: coverage-sdk.dat
-                  if-no-files-found: warn
-
-    tools-tests:
-        runs-on: blacksmith-2vcpu-ubuntu-2404
-        timeout-minutes: 15
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with: {fetch-depth: 0}
-
-            - name: Detect tools changes
-              id: changed
-              uses: tj-actions/changed-files@v47
-              with:
-                  files: |
-                      openhands-tools/**
-                      tests/tools/**
-                      pyproject.toml
-                      uv.lock
-                      .github/workflows/tests.yml
-
-            - name: Install uv
-              if: steps.changed.outputs.any_changed == 'true'
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Install deps
-              if: steps.changed.outputs.any_changed == 'true'
-              run: uv sync --frozen --group dev
-
-            - name: Run tools tests with coverage
-              if: steps.changed.outputs.any_changed == 'true'
-              run: |
-                  # Clean up any existing coverage file
-                  rm -f .coverage
-                  # Use --forked for tools tests due to terminal test conflicts
-                  # when running in parallel (shared /tmp paths, subprocess management)
-                  CI=true uv run python -m pytest -vvs \
-                    --forked \
-                    --cov=openhands-tools \
-                    --cov-report=term-missing \
-                    --cov-fail-under=0 \
-                    --cov-config=pyproject.toml \
-                    tests/tools
-                  # Rename coverage file for upload
-                  if [ -f .coverage ]; then
-                    mv .coverage coverage-tools.dat
-                    echo "Tools coverage file prepared for upload"
-                  fi
-
-            - name: Upload tools coverage
-              if: steps.changed.outputs.any_changed == 'true' && always()
-              uses: actions/upload-artifact@v7
-              with:
-                  name: coverage-tools
-                  path: coverage-tools.dat
-                  if-no-files-found: warn
-
-    agent-server-tests:
-        runs-on: blacksmith-2vcpu-ubuntu-2404
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with: {fetch-depth: 0}
-
-            - name: Detect Agent Server changes
-              id: changed
-              uses: tj-actions/changed-files@v47
-              with:
-                  files: |
-                      openhands-agent-server/**
-                      tests/agent_server/**
-                      pyproject.toml
-                      uv.lock
-                      .github/workflows/tests.yml
-
-            - name: Install uv
-              if: steps.changed.outputs.any_changed == 'true'
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Install deps
-              if: steps.changed.outputs.any_changed == 'true'
-              run: uv sync --frozen --group dev
-
-            - name: Run Agent Server tests with coverage
-              if: steps.changed.outputs.any_changed == 'true'
-              run: |
-                  # Clean up any existing coverage file
-                  rm -f .coverage
-                  # Use pytest-xdist (-n auto) for parallel execution with proper
-                  # coverage collection. --forked prevents coverage from child processes.
-                  CI=true uv run python -m pytest -vvs \
-                    -n auto \
-                    --cov=openhands-agent-server \
-                    --cov-report=term-missing \
-                    --cov-fail-under=0 \
-                    --cov-config=pyproject.toml \
-                    tests/agent_server
-                  # Rename coverage file for upload
-                  if [ -f .coverage ]; then
-                    mv .coverage coverage-agent-server.dat
-                    echo "Agent Server coverage file prepared for upload"
-                  fi
-
-            - name: Upload Agent Server coverage
-              if: steps.changed.outputs.any_changed == 'true' && always()
-              uses: actions/upload-artifact@v7
-              with:
-                  name: coverage-agent-server
-                  path: coverage-agent-server.dat
-                  if-no-files-found: warn
-
-    cross-tests:
-        runs-on: blacksmith-2vcpu-ubuntu-2404
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with: {fetch-depth: 0}
-
-            - name: Detect cross changes
-              id: changed
-              uses: tj-actions/changed-files@v47
-              with:
-                  files: |
-                      tests/**
-                      openhands/**
-                      pyproject.toml
-                      uv.lock
-                      .github/workflows/tests.yml
-
-            - name: Install uv
-              if: steps.changed.outputs.any_changed == 'true'
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Install deps
-              if: steps.changed.outputs.any_changed == 'true'
-              run: uv sync --frozen --group dev
-
-            - name: Run cross tests with coverage
-              if: steps.changed.outputs.any_changed == 'true'
-              run: |
-                  # Clean up any existing coverage file
-                  rm -f .coverage
-                  CI=true uv run python -m pytest -vvs \
-                    --basetemp="${{ runner.temp }}/pytest" \
-                    -o tmp_path_retention=none \
-                    -o tmp_path_retention_count=0 \
-                    --cov=openhands \
-                    --cov-report=term-missing \
-                    --cov-fail-under=0 \
-                    --cov-config=pyproject.toml \
-                    tests/cross
-                  # Rename coverage file for upload
-                  if [ -f .coverage ]; then
-                    mv .coverage coverage-cross.dat
-                    echo "Cross coverage file prepared for upload"
-                  fi
-
-            - name: Upload cross coverage
-              if: steps.changed.outputs.any_changed == 'true' && always()
-              uses: actions/upload-artifact@v7
-              with:
-                  name: coverage-cross
-                  path: coverage-cross.dat
-                  if-no-files-found: warn
-
-    coverage-report:
-        runs-on: blacksmith-2vcpu-ubuntu-2404
-        needs: [sdk-tests, tools-tests, agent-server-tests, cross-tests]
-        if: always() && github.event_name == 'pull_request'
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-                  python-version: '3.13'
-
-            - name: Install deps (for coverage CLI)
-              run: uv sync --frozen --group dev
-
-            - name: Download coverage artifacts
-              uses: actions/download-artifact@v8
-              with:
-                  path: ./cov
-              continue-on-error: true
-
-            - name: Combine coverage data
-              run: |
-                  shopt -s nullglob
-                  # For some reason, the github action won't properly upload the original
-                  # .converage* files
-                  # Convert uploaded .dat files back to .coverage format for coverage tool
-                  for dat_file in cov/**/coverage-*.dat; do
-                    if [[ "$dat_file" == *coverage-sdk.dat ]]; then
-                      cp "$dat_file" .coverage.sdk
-                    elif [[ "$dat_file" == *coverage-tools.dat ]]; then
-                      cp "$dat_file" .coverage.tools  
-                    elif [[ "$dat_file" == *coverage-agent-server.dat ]]; then
-                      cp "$dat_file" .coverage.agent-server
-                    elif [[ "$dat_file" == *coverage-cross.dat ]]; then
-                      cp "$dat_file" .coverage.cross
-                    fi
-                  done
-
-                  # Check if we have any coverage files
-                  coverage_files=(.coverage.*)
-                  if [ ${#coverage_files[@]} -eq 0 ]; then
-                    echo "No coverage files found; skipping combined report."
-                    exit 0
-                  fi
-
-                  echo "Found ${#coverage_files[@]} coverage files"
-                  uv run coverage combine
-                  uv run coverage xml -i -o coverage.xml
-                  uv run coverage report -m
-
-            - name: Pytest coverage PR comment
-              if: always()
-              continue-on-error: true
-              uses: MishaKav/pytest-coverage-comment@v1
-              with:
-                  github-token: ${{ secrets.GITHUB_TOKEN }}
-                  pytest-xml-coverage-path: coverage.xml
-                  title: Coverage Report
-                  create-new-comment: false
-                  hide-report: false
-                  xml-skip-covered: true
-                  report-only-changed-files: true
-                  remove-links-to-files: true
-                  remove-links-to-lines: true

.github/workflows/todo-management.yml

@@ -1,322 +0,0 @@
----
-# Automated TODO Management Workflow
-#
-# This workflow automatically scans for TODO(openhands) comments and creates
-# pull requests to implement them using the OpenHands agent.
-#
-# Setup:
-#  1. Add LLM_API_KEY to repository secrets
-#  2. Ensure GITHUB_TOKEN has appropriate permissions
-#  3. Make sure Github Actions are allowed to create and review PRs
-#  4. Commit this file to .github/workflows/ in your repository
-#  5. Configure the schedule or trigger manually
-
-name: Automated TODO Management
-
-on:
-  # Manual trigger
-    workflow_dispatch:
-        inputs:
-            max_todos:
-                description: Maximum number of TODOs to process in this run
-                required: false
-                default: '3'
-                type: string
-            todo_identifier:
-                description: TODO identifier to search for (e.g., TODO(openhands))
-                required: false
-                default: TODO(openhands)
-                type: string
-
-  # Trigger when 'automatic-todo' label is added to a PR
-    pull_request:
-        types: [labeled]
-
-  # Scheduled trigger (disabled by default, uncomment and customize as needed)
-  # schedule:
-  # # Run every Monday at 9 AM UTC
-  # - cron: "0 9 * * 1"
-
-permissions:
-    contents: write
-    pull-requests: write
-    issues: write
-
-jobs:
-    scan-todos:
-        runs-on: ubuntu-24.04
-    # Only run if triggered manually or if 'automatic-todo' label was added
-        if: >
-            github.event_name == 'workflow_dispatch' ||
-            (github.event_name == 'pull_request' &&
-             github.event.label.name == 'automatic-todo')
-        outputs:
-            todos: ${{ steps.scan.outputs.todos }}
-            todo-count: ${{ steps.scan.outputs.todo-count }}
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0 # Full history for better context
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Copy TODO scanner
-              run: |
-                  cp examples/03_github_workflows/03_todo_management/scanner.py /tmp/scanner.py
-                  chmod +x /tmp/scanner.py
-
-            - name: Scan for TODOs
-              id: scan
-              run: |
-                  echo "Scanning for TODO comments..."
-
-                  # Run the scanner and capture output
-                  TODO_IDENTIFIER="${{ github.event.inputs.todo_identifier || 'TODO(openhands)' }}"
-                  python /tmp/scanner.py . --identifier "$TODO_IDENTIFIER" > todos.json
-
-                  # Count TODOs
-                  TODO_COUNT=$(python -c \
-                    "import json; data=json.load(open('todos.json')); print(len(data))")
-                  echo "Found $TODO_COUNT $TODO_IDENTIFIER items"
-
-                  # Limit the number of TODOs to process
-                  MAX_TODOS="${{ github.event.inputs.max_todos || '3' }}"
-                  if [ "$TODO_COUNT" -gt "$MAX_TODOS" ]; then
-                    echo "Limiting to first $MAX_TODOS TODOs"
-                    python -c "
-                  import json
-                  data = json.load(open('todos.json'))
-                  limited = data[:$MAX_TODOS]
-                  json.dump(limited, open('todos.json', 'w'), indent=2)
-                  "
-                    TODO_COUNT=$MAX_TODOS
-                  fi
-
-                  # Set outputs
-                  echo "todos=$(cat todos.json | jq -c .)" >> $GITHUB_OUTPUT
-                  echo "todo-count=$TODO_COUNT" >> $GITHUB_OUTPUT
-
-                  # Display found TODOs
-                  echo "## 📋 Found TODOs" >> $GITHUB_STEP_SUMMARY
-                  if [ "$TODO_COUNT" -eq 0 ]; then
-                    echo "No TODO(openhands) comments found." >> $GITHUB_STEP_SUMMARY
-                  else
-                    echo "Found $TODO_COUNT TODO(openhands) items:" \
-                      >> $GITHUB_STEP_SUMMARY
-                    echo "" >> $GITHUB_STEP_SUMMARY
-                    python -c "
-                  import json
-                  data = json.load(open('todos.json'))
-                  for i, todo in enumerate(data, 1):
-                      print(f'{i}. **{todo[\"file\"]}:{todo[\"line\"]}** - ' +
-                            f'{todo[\"description\"]}')
-                  " >> $GITHUB_STEP_SUMMARY
-                  fi
-
-    process-todos:
-        needs: scan-todos
-        if: needs.scan-todos.outputs.todo-count > 0
-        runs-on: ubuntu-24.04
-        strategy:
-            matrix:
-                todo: ${{ fromJson(needs.scan-todos.outputs.todos) }}
-            max-parallel: 1 # Process one TODO at a time to avoid conflicts
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0
-                  token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-
-            - name: Switch to feature branch with TODO management files
-              run: |
-                  git checkout openhands/todo-management-example
-                  git pull origin openhands/todo-management-example
-
-            - name: Set up Python
-              uses: actions/setup-python@v6
-              with:
-                  python-version: '3.13'
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  enable-cache: true
-
-            - name: Install OpenHands dependencies
-              run: |
-                  # Install OpenHands SDK and tools from git repository
-                  uv pip install --system "openhands-sdk @ git+https://github.com/OpenHands/agent-sdk.git@main#subdirectory=openhands-sdk"
-                  uv pip install --system "openhands-tools @ git+https://github.com/OpenHands/agent-sdk.git@main#subdirectory=openhands-tools"
-
-            - name: Copy agent files
-              run: |
-                  cp examples/03_github_workflows/03_todo_management/agent_script.py agent.py
-                  cp examples/03_github_workflows/03_todo_management/prompt.py prompt.py
-                  chmod +x agent.py
-
-            - name: Configure Git
-              run: |
-                  git config --global user.name "openhands-bot"
-                  git config --global user.email \
-                    "openhands-bot@users.noreply.github.com"
-
-            - name: Process TODO
-              env:
-                  LLM_MODEL: litellm_proxy/claude-sonnet-4-5-20250929
-                  LLM_BASE_URL: https://llm-proxy.app.all-hands.dev
-                  LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
-                  GITHUB_TOKEN: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-                  GITHUB_REPOSITORY: ${{ github.repository }}
-                  TODO_FILE: ${{ matrix.todo.file }}
-                  TODO_LINE: ${{ matrix.todo.line }}
-                  TODO_DESCRIPTION: ${{ matrix.todo.description }}
-                  PYTHONPATH: ''
-              run: |
-                  echo "Processing TODO: $TODO_DESCRIPTION"
-                  echo "File: $TODO_FILE:$TODO_LINE"
-
-                  # Create a unique branch name for this TODO
-                  BRANCH_NAME="todo/$(echo "$TODO_DESCRIPTION" | \
-                    sed 's/[^a-zA-Z0-9]/-/g' | \
-                    sed 's/--*/-/g' | \
-                    sed 's/^-\|-$//g' | \
-                    tr '[:upper:]' '[:lower:]' | \
-                    cut -c1-50)"
-                  echo "Branch name: $BRANCH_NAME"
-
-                  # Create and switch to new branch (force create if exists)
-                  git checkout -B "$BRANCH_NAME"
-
-                  # Run the agent to process the TODO
-                  # Stay in repository directory for git operations
-
-                  # Create JSON payload for the agent
-                  TODO_JSON=$(cat <<EOF
-                  {
-                    "file": "$TODO_FILE",
-                    "line": $TODO_LINE,
-                    "description": "$TODO_DESCRIPTION"
-                  }
-                  EOF
-                  )
-
-                  echo "JSON payload for agent:"
-                  echo "$TODO_JSON"
-
-                  # Debug environment and setup
-                  echo "Current working directory: $(pwd)"
-                  echo "Environment variables:"
-                  echo "  LLM_MODEL: $LLM_MODEL"
-                  echo "  LLM_BASE_URL: $LLM_BASE_URL"
-                  echo "  GITHUB_REPOSITORY: $GITHUB_REPOSITORY"
-                  echo "  LLM_API_KEY: ${LLM_API_KEY:+[SET]}"
-                  echo "  GITHUB_TOKEN: ${GITHUB_TOKEN:+[SET]}"
-                  echo "Available files:"
-                  ls -la
-
-                  # Run the agent with detailed logging
-                  echo "Starting agent execution..."
-                  set +e  # Don't exit on error, we want to capture it
-                  uv run python agent.py "$TODO_JSON" 2>&1 | tee agent_output.log
-                  AGENT_EXIT_CODE=$?
-                  set -e
-
-                  echo "Agent exit code: $AGENT_EXIT_CODE"
-                  echo "Agent output log:"
-                  cat agent_output.log
-
-                  # Show files in working directory
-                  echo "Files in working directory:"
-                  ls -la
-
-                  # If agent failed, show more details
-                  if [ $AGENT_EXIT_CODE -ne 0 ]; then
-                    echo "Agent failed with exit code $AGENT_EXIT_CODE"
-                    echo "Last 50 lines of agent output:"
-                    tail -50 agent_output.log
-                    exit $AGENT_EXIT_CODE
-                  fi
-
-                  # Check if any changes were made
-                  cd "$GITHUB_WORKSPACE"
-                  if git diff --quiet; then
-                    echo "No changes made by agent, skipping PR creation"
-                    exit 0
-                  fi
-
-                  # Commit changes
-                  git add -A
-                  git commit -m "Implement TODO: $TODO_DESCRIPTION
-
-                  Automatically implemented by OpenHands agent.
-
-                  Co-authored-by: openhands <openhands@all-hands.dev>"
-
-                  # Push branch
-                  git push origin "$BRANCH_NAME"
-
-                  # Create pull request
-                  PR_TITLE="Implement TODO: $TODO_DESCRIPTION"
-                  PR_BODY="## 🤖 Automated TODO Implementation
-
-                  This PR automatically implements the following TODO:
-
-                  **File:** \`$TODO_FILE:$TODO_LINE\`
-                  **Description:** $TODO_DESCRIPTION
-
-                  ### Implementation
-                  The OpenHands agent has analyzed the TODO and implemented the
-                  requested functionality.
-
-                  ### Review Notes
-                  - Please review the implementation for correctness
-                  - Test the changes in your development environment
-                  - The original TODO comment will be updated with this PR URL
-                    once merged
-
-                  ---
-                  *This PR was created automatically by the TODO Management workflow.*"
-
-                  # Create PR using GitHub CLI or API
-                  curl -X POST \
-                    -H "Authorization: token $GITHUB_TOKEN" \
-                    -H "Accept: application/vnd.github.v3+json" \
-                    "https://api.github.com/repos/${{ github.repository }}/pulls" \
-                    -d "{
-                      \"title\": \"$PR_TITLE\",
-                      \"body\": \"$PR_BODY\",
-                      \"head\": \"$BRANCH_NAME\",
-                      \"base\": \"${{ github.ref_name }}\"
-                    }"
-
-    summary:
-        needs: [scan-todos, process-todos]
-        if: always()
-        runs-on: ubuntu-24.04
-        steps:
-            - name: Generate Summary
-              run: |
-                  echo "# 🤖 TODO Management Summary" >> $GITHUB_STEP_SUMMARY
-                  echo "" >> $GITHUB_STEP_SUMMARY
-
-                  TODO_COUNT="${{ needs.scan-todos.outputs.todo-count || '0' }}"
-                  echo "**TODOs Found:** $TODO_COUNT" >> $GITHUB_STEP_SUMMARY
-
-                  if [ "$TODO_COUNT" -gt 0 ]; then
-                    echo "**Processing Status:** ✅ Completed" >> $GITHUB_STEP_SUMMARY
-                    echo "" >> $GITHUB_STEP_SUMMARY
-                    echo "Check the pull requests created for each TODO" \
-                      "implementation." >> $GITHUB_STEP_SUMMARY
-                  else
-                    echo "**Status:** ℹ️ No TODOs found to process" \
-                      >> $GITHUB_STEP_SUMMARY
-                  fi
-
-                  echo "" >> $GITHUB_STEP_SUMMARY
-                  echo "---" >> $GITHUB_STEP_SUMMARY
-                  echo "*Workflow completed at $(date)*" >> $GITHUB_STEP_SUMMARY

.github/workflows/version-bump-guard.yml

@@ -1,25 +0,0 @@
----
-name: Version bump guard
-
-on:
-    pull_request:
-        branches: [main]
-
-jobs:
-    version-bump-guard:
-        name: Check package versions
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-              with:
-                  fetch-depth: 0
-
-            - name: Validate package version changes
-              env:
-                  VERSION_BUMP_BASE_REF: ${{ github.base_ref }}
-                  PR_TITLE: ${{ github.event.pull_request.title }}
-                  PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
-              run: python3 .github/scripts/check_version_bumps.py

.github/workflows/version-bump-prs.yml

@@ -1,346 +0,0 @@
----
-name: Create Version Bump PRs
-
-on:
-    # Triggered by pypi-release workflow after successful publish
-    # Note: No branches filter - releases run on tags (e.g., v1.11.4), not branches
-    workflow_run:
-        workflows: [Publish all OpenHands packages (uv)]
-        types: [completed]
-    # Allow manual trigger with version input
-    workflow_dispatch:
-        inputs:
-            version:
-                description: Version to bump to (e.g., 1.11.3)
-                required: true
-                type: string
-
-jobs:
-    create-version-bump-prs:
-        runs-on: ubuntu-24.04
-        # Only run on successful workflow_run or manual dispatch
-        if: >
-            github.event_name == 'workflow_dispatch' ||
-            (github.event.workflow_run.conclusion == 'success' &&
-             github.event.workflow_run.event == 'release')
-        env:
-            GH_TOKEN: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v5
-
-            - name: Get version from release or input
-              id: get_version
-              run: |
-                  if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-                    VERSION="${{ github.event.inputs.version }}"
-                  else
-                    # Get version from the release that triggered the workflow_run
-                    # The workflow_run was triggered by a release event
-                    RELEASE_TAG=$(gh api repos/${{ github.repository }}/releases/latest --jq '.tag_name')
-                    VERSION="${RELEASE_TAG#v}"  # Remove 'v' prefix
-                  fi
-                  echo "version=$VERSION" >> $GITHUB_OUTPUT
-                  echo "📦 Version: $VERSION"
-
-            - name: Validate version
-              env:
-                  VERSION: ${{ steps.get_version.outputs.version }}
-              run: |
-                  if [ -z "$VERSION" ]; then
-                    echo "❌ Version is empty"
-                    exit 1
-                  fi
-                  echo "📦 Creating version bump PRs for version: $VERSION"
-
-            - name: Wait for packages to be available on PyPI
-              env:
-                  VERSION: ${{ steps.get_version.outputs.version }}
-              run: |
-                  set -euo pipefail
-
-                  PACKAGES=(
-                    openhands-sdk
-                    openhands-tools
-                    openhands-workspace
-                    openhands-agent-server
-                  )
-
-                  MAX_ATTEMPTS=60
-                  SLEEP_SECONDS=20
-
-                  echo "⏳ Waiting for packages to be available on PyPI..."
-
-                  for PKG in "${PACKAGES[@]}"; do
-                    echo "Checking $PKG==$VERSION..."
-                    ATTEMPT=1
-                    while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
-                      # Check if the package version is available on PyPI
-                      HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-                        "https://pypi.org/pypi/$PKG/$VERSION/json")
-
-                      if [ "$HTTP_CODE" = "200" ]; then
-                        echo "✅ $PKG==$VERSION is available on PyPI"
-                        break
-                      fi
-
-                      echo "  Attempt $ATTEMPT/$MAX_ATTEMPTS: $PKG==$VERSION not yet available (HTTP $HTTP_CODE), waiting ${SLEEP_SECONDS}s..."
-                      sleep $SLEEP_SECONDS
-                      ATTEMPT=$((ATTEMPT + 1))
-                    done
-
-                    if [ $ATTEMPT -gt $MAX_ATTEMPTS ]; then
-                      echo "❌ Timeout waiting for $PKG==$VERSION to be available on PyPI"
-                      exit 1
-                    fi
-                  done
-
-                  echo "✅ All packages are available on PyPI!"
-
-            - name: Install uv
-              uses: astral-sh/setup-uv@v7
-              with:
-                  version: latest
-                  python-version: '3.12'
-
-            - name: Install Poetry
-              run: |
-                  pipx install poetry==2.2.1
-
-            # OpenHands-CLI step runs first since it's simpler and less error-prone
-            - name: Create PR for OpenHands-CLI repo
-              env:
-                  VERSION: ${{ steps.get_version.outputs.version }}
-              run: |
-                  set -euo pipefail
-
-                  REPO="OpenHands/openhands-cli"
-                  BRANCH="bump-sdk-$VERSION"
-
-                  echo "🔄 Creating PR for $REPO..."
-
-                  # Clone the repo
-                  git clone "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" openhands-cli-repo
-                  cd openhands-cli-repo
-
-                  # Configure git
-                  git config user.name "github-actions[bot]"
-                  git config user.email "github-actions[bot]@users.noreply.github.com"
-
-                  # Check if branch already exists on remote
-                  if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
-                    echo "⚠️ Branch $BRANCH already exists, checking out existing branch"
-                    git fetch origin "$BRANCH"
-                    git checkout "$BRANCH"
-                  else
-                    # Create branch
-                    git checkout -b "$BRANCH"
-                  fi
-
-                  # OpenHands-CLI currently requires Python 3.12, so resolve with that interpreter.
-                  uv add --python 3.12 --refresh \
-                    "openhands-sdk==$VERSION" \
-                    "openhands-tools==$VERSION"
-
-                  # Check if there are changes
-                  if git diff --quiet; then
-                    echo "⚠️ No changes detected in $REPO - versions may already be up to date"
-                    exit 0
-                  fi
-
-                  # Commit and push
-                  git add pyproject.toml uv.lock
-                  git commit -m "Bump openhands-sdk, openhands-tools to $VERSION" \
-                    -m "Automated version bump after PyPI release." \
-                    -m "Co-authored-by: openhands <openhands@all-hands.dev>"
-                  git push -u origin "$BRANCH"
-
-                  # Check if PR already exists
-                  EXISTING_PR=$(gh pr list --repo "$REPO" --head "$BRANCH" --json number --jq '.[0].number')
-                  if [ -n "$EXISTING_PR" ]; then
-                    echo "✅ PR #$EXISTING_PR already exists for $REPO"
-                  else
-                    # Create PR
-                    gh pr create \
-                      --repo "$REPO" \
-                      --title "Bump SDK packages to v$VERSION" \
-                      --body "## Automated Version Bump
-
-                  This PR updates the following packages to version **$VERSION**:
-                  - \`openhands-sdk\`
-                  - \`openhands-tools\`
-
-                  **Triggered by:** Release of [software-agent-sdk v$VERSION](https://github.com/OpenHands/software-agent-sdk/releases/tag/v$VERSION)
-
-                  ---
-                  _This PR was automatically created by the version-bump-prs workflow._" \
-                      --base main \
-                      --head "$BRANCH"
-
-                    echo "✅ PR created for $REPO"
-                  fi
-
-            - name: Create PR for OpenHands repo
-              env:
-                  VERSION: ${{ steps.get_version.outputs.version }}
-              run: |
-                  set -euo pipefail
-
-                  REPO="All-Hands-AI/OpenHands"
-                  BRANCH="bump-sdk-$VERSION"
-
-                  echo "🔄 Creating PR for $REPO..."
-
-                  # Clone the repo
-                  git clone "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" openhands-repo
-                  cd openhands-repo
-
-                  # Configure git
-                  git config user.name "github-actions[bot]"
-                  git config user.email "github-actions[bot]@users.noreply.github.com"
-
-                  # Check if branch already exists on remote
-                  if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
-                    echo "⚠️ Branch $BRANCH already exists, checking out existing branch"
-                    git fetch origin "$BRANCH"
-                    git checkout "$BRANCH"
-                  else
-                    # Create branch
-                    git checkout -b "$BRANCH"
-                  fi
-
-                  # 1. Update versions in pyproject.toml and poetry.lock using poetry (root)
-                  # The --lock flag updates both pyproject.toml AND poetry.lock
-                  # Note: enterprise/pyproject.toml gets these dependencies transitively via openhands-ai
-                  echo "📝 Updating root pyproject.toml and poetry.lock..."
-
-                  # Verify enterprise/pyproject.toml does NOT have SDK packages explicitly listed
-                  # If they exist there, they will become stale since we only update root pyproject.toml
-                  if [ -f "enterprise/pyproject.toml" ]; then
-                    echo "🔍 Verifying enterprise/pyproject.toml doesn't have explicit SDK packages..."
-                    SDK_PACKAGES=("openhands-sdk" "openhands-tools" "openhands-agent-server")
-                    for pkg in "${SDK_PACKAGES[@]}"; do
-                      # Match package name as a TOML key (with optional leading whitespace) followed by =
-                      # This catches both 'openhands-sdk = "1.2.3"' and 'openhands-sdk="1.2.3"'
-                      if grep -qE "^[[:space:]]*${pkg}[[:space:]]*=" enterprise/pyproject.toml; then
-                        echo "❌ ERROR: enterprise/pyproject.toml contains explicit reference to '$pkg'"
-                        echo "   These packages should come transitively via openhands-ai dependency."
-                        echo "   Please remove '$pkg' from enterprise/pyproject.toml to avoid version drift."
-                        exit 1
-                      fi
-                    done
-                    echo "✅ enterprise/pyproject.toml does not have explicit SDK packages"
-                  fi
-
-                  # 1. Update versions in pyproject.toml using sed for exact pinning
-                  # Note: We use sed instead of `poetry add --lock` because Poetry normalizes
-                  # version constraints (e.g., "==1.13.1" becomes "1.13") which causes
-                  # inconsistencies between [tool.poetry.dependencies] and [project].dependencies
-                  echo "📝 Updating pyproject.toml with exact version pins..."
-
-                  # Update [tool.poetry.dependencies] section
-                  # Matches: openhands-sdk = "1.13" or openhands-sdk = "1.13.0"
-                  sed -i -E 's/^(openhands-sdk = )"[^"]*"/\1"'"$VERSION"'"/' pyproject.toml
-                  sed -i -E 's/^(openhands-tools = )"[^"]*"/\1"'"$VERSION"'"/' pyproject.toml
-                  sed -i -E 's/^(openhands-agent-server = )"[^"]*"/\1"'"$VERSION"'"/' pyproject.toml
-
-                  # Update [project].dependencies section (PEP 621 format)
-                  # Matches: "openhands-sdk==1.13.1", or "openhands-sdk==1.13",
-                  sed -i -E 's/"openhands-sdk==[^"]*"/"openhands-sdk=='"$VERSION"'"/' pyproject.toml
-                  sed -i -E 's/"openhands-tools==[^"]*"/"openhands-tools=='"$VERSION"'"/' pyproject.toml
-                  sed -i -E 's/"openhands-agent-server==[^"]*"/"openhands-agent-server=='"$VERSION"'"/' pyproject.toml
-
-                  echo "✅ Updated pyproject.toml"
-
-                  # 2. Regenerate poetry.lock with the new versions
-                  # Note: In Poetry 2.x, the default behavior is to not update packages already
-                  # in the lock file (the --no-update flag was removed in Poetry 2.x)
-                  echo "📝 Regenerating poetry.lock..."
-                  poetry lock
-
-                  # 3. Update the version in sandbox_spec_service.py
-                  echo "🔧 Updating AGENT_SERVER_IMAGE..."
-                  SANDBOX_SPEC_FILE="openhands/app_server/sandbox/sandbox_spec_service.py"
-                  if [ -f "$SANDBOX_SPEC_FILE" ]; then
-                    # Update the AGENT_SERVER_IMAGE line with the new hash
-                    sed -i "s|AGENT_SERVER_IMAGE = 'ghcr.io/openhands/agent-server:[^']*'|AGENT_SERVER_IMAGE = 'ghcr.io/openhands/agent-server:${VERSION}-python'|" "$SANDBOX_SPEC_FILE"
-                    echo "✅ Updated AGENT_SERVER_IMAGE to: ghcr.io/openhands/agent-server:${VERSION}-python"
-                  else
-                    echo "❌ sandbox_spec_service.py not found at expected path"
-                    exit 1
-                  fi
-
-                  # 4. Run pre-commit to fix formatting (pyproject-fmt removes parentheses from version specs)
-                  echo "🔧 Running pre-commit to fix formatting..."
-                  pip install pre-commit
-                  pre-commit run --files pyproject.toml --config ./dev_config/python/.pre-commit-config.yaml || true
-
-                  # Check if there are changes
-                  if git diff --quiet; then
-                    echo "⚠️ No changes detected in $REPO - versions may already be up to date"
-                    exit 0
-                  fi
-
-                  # Commit and push
-                  git add .
-                  git commit -m "Bump openhands-sdk, openhands-tools, openhands-agent-server to $VERSION" \
-                    -m "Automated version bump after PyPI release." \
-                    -m "" \
-                    -m "Changes:" \
-                    -m "- Updated SDK packages to v$VERSION in pyproject.toml" \
-                    -m "- Regenerated poetry.lock" \
-                    -m "- Updated AGENT_SERVER_IMAGE to ${VERSION}" \
-                    -m "" \
-                    -m "Co-authored-by: openhands <openhands@all-hands.dev>"
-                  git push -u origin "$BRANCH"
-
-                  # Check if PR already exists
-                  EXISTING_PR=$(gh pr list --repo "$REPO" --head "$BRANCH" --json number --jq '.[0].number')
-                  if [ -n "$EXISTING_PR" ]; then
-                    echo "✅ PR #$EXISTING_PR already exists for $REPO"
-                  else
-                    # Create PR
-                    gh pr create \
-                      --repo "$REPO" \
-                      --title "Bump SDK packages to v$VERSION" \
-                      --body "## Automated Version Bump
-
-                  This PR updates the following packages to version **$VERSION**:
-                  - \`openhands-sdk\`
-                  - \`openhands-tools\`
-                  - \`openhands-agent-server\`
-
-                  ### Changes
-                  - Updated SDK packages in \`pyproject.toml\`
-                  - Regenerated \`poetry.lock\`
-                  - Updated \`AGENT_SERVER_IMAGE\` to \`${VERSION}\` in \`sandbox_spec_service.py\`
-
-                  **Triggered by:** Release of [software-agent-sdk v$VERSION](https://github.com/OpenHands/software-agent-sdk/releases/tag/v$VERSION)
-
-                  ---
-                  _This PR was automatically created by the version-bump-prs workflow._" \
-                      --base main \
-                      --head "$BRANCH"
-
-                    echo "✅ PR created for $REPO"
-                  fi
-
-            - name: Summary
-              env:
-                  VERSION: ${{ steps.get_version.outputs.version }}
-              run: |
-                  echo "## ✅ Version Bump PRs Created" >> $GITHUB_STEP_SUMMARY
-                  echo "" >> $GITHUB_STEP_SUMMARY
-                  echo "PRs have been created to bump SDK packages to version **$VERSION**:" >> $GITHUB_STEP_SUMMARY
-                  echo "" >> $GITHUB_STEP_SUMMARY
-                  echo "- [OpenHands](https://github.com/All-Hands-AI/OpenHands/pulls?q=is%3Apr+bump-sdk-$VERSION)" >> $GITHUB_STEP_SUMMARY
-                  echo "- [OpenHands-CLI](https://github.com/OpenHands/openhands-cli/pulls?q=is%3Apr+bump-sdk-$VERSION)" >> $GITHUB_STEP_SUMMARY
-
-            - name: Notify Slack
-              uses: slackapi/slack-github-action@v2.1.1
-              with:
-                  method: chat.postMessage
-                  token: ${{ secrets.SLACK_BOT_TOKEN }}
-                  payload: |
-                      channel: C08E1SYKEM9
-                      text: "🚀 *SDK v${{ steps.get_version.outputs.version }} published to PyPI!*\n\nVersion bump PRs created:\n• <https://github.com/All-Hands-AI/OpenHands/pulls?q=is%3Apr+bump-sdk-${{ steps.get_version.outputs.version }}|OpenHands>\n• <https://github.com/OpenHands/openhands-cli/pulls?q=is%3Apr+bump-sdk-${{ steps.get_version.outputs.version }}|OpenHands-CLI>\n\n<https://github.com/OpenHands/software-agent-sdk/releases/tag/v${{ steps.get_version.outputs.version }}|View Release>"

.gitignore

@@ -14,7 +14,7 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
+./lib/
 lib64/
 parts/
 sdist/
@@ -31,6 +31,7 @@ requirements.txt
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
+*.spec
 
 # Installer logs
 pip-log.txt
@@ -56,7 +57,6 @@ cover/
 *.pot
 
 # Django stuff:
-*.log
 local_settings.py
 db.sqlite3
 db.sqlite3-journal
@@ -85,6 +85,7 @@ ipython_config.py
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
+.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -120,6 +121,7 @@ celerybeat.pid
 
 # Environments
 .env
+frontend/.env
 .venv
 env/
 venv/
@@ -127,6 +129,7 @@ ENV/
 env.bak/
 .env.bak
 venv.bak/
+*venv/
 
 # Spyder project settings
 .spyderproject
@@ -158,28 +161,37 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
-
-# VS Code: Ignore all but certain files that specify repo-specific settings.
-# https://stackoverflow.com/questions/32964920/should-i-commit-the-vscode-folder-to-source-control
-.vscode/**/*
-!.vscode/extensions.json
-!.vscode/tasks.json
-
-# VS Code extensions/forks:
+.vscode/
 .cursorignore
-.rooignore
-.clineignore
-.windsurfignore
-.cursorrules
-.roorules
-.clinerules
-.windsurfrules
-.cursor/rules
-.roo/rules
-.cline/rules
-.windsurf/rules
-.repomix
-repomix-output.txt
+
+# evaluation
+evaluation/evaluation_outputs
+evaluation/outputs
+evaluation/swe_bench/eval_workspace*
+evaluation/SWE-bench/data
+evaluation/webarena/scripts/webarena_env.sh
+evaluation/bird/data
+evaluation/gaia/data
+evaluation/gorilla/data
+evaluation/toolqa/data
+evaluation/scienceagentbench/benchmark
+
+# frontend
+
+# dependencies
+frontend/.pnp
+frontend/bun.lockb
+frontend/yarn.lock
+.pnp.js
+
+# testing
+frontend/coverage
+test_results*
+/_test_files_tmp/
+
+# production
+frontend/build
+frontend/dist
 
 # misc
 .DS_Store
@@ -196,22 +208,24 @@ logs
 
 # agent
 .envrc
+/workspace
+/_test_workspace
+/debug
 cache
-.jinja_cache/
 
-.conversations*
-/workspace/
-openapi.json
-.client/
+# configuration
+config.toml
+config.toml_
+config.toml.bak
 
-# Local workspace files
-.beads/*.db
-.worktrees/
-agent-sdk.workspace.code-workspace
+# swe-bench-eval
+image_build_logs
+run_instance_logs
 
-# Integration test outputs
-tests/integration/outputs/
-tests/integration/api_compliance/outputs/
+runtime_*.tar
 
-# Agent-generated temp
-.agent_tmp/
+# docker build
+containers/runtime/Dockerfile
+containers/runtime/project.tar.gz
+containers/runtime/code
+**/node_modules/

.openhands/hooks.json

@@ -1,14 +0,0 @@
-{
-  "stop": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": ".openhands/hooks/on_stop.sh",
-          "timeout": 600
-        }
-      ]
-    }
-  ]
-}

.openhands/hooks/on_stop.sh

@@ -1,303 +0,0 @@
-#!/bin/bash
-# Stop hook: runs pre-commit, pytest, and checks CI status before allowing agent to finish
-#
-# This hook runs when the agent attempts to stop/finish.
-# It can BLOCK the stop by:
-#   - Exiting with code 2 (blocked)
-#   - Outputting JSON: {"decision": "deny", "additionalContext": "feedback message"}
-#
-# Environment variables available:
-#   OPENHANDS_PROJECT_DIR - Project directory
-#   OPENHANDS_SESSION_ID - Session ID
-#   GITHUB_TOKEN - GitHub API token (if available)
-
-set -o pipefail
-
-PROJECT_DIR="${OPENHANDS_PROJECT_DIR:-$(pwd)}"
-cd "$PROJECT_DIR" || exit 1
-
-# Collect all issues to report back to the agent
-ISSUES=""
-BLOCK_STOP=false
-
-log_issue() {
-    ISSUES="${ISSUES}${1}\n"
-    BLOCK_STOP=true
-}
-
->&2 echo "=== Stop Hook ==="
->&2 echo "Project directory: $PROJECT_DIR"
->&2 echo ""
-
-# --------------------------
-# Step 1: Run pre-commit on all files
-# --------------------------
->&2 echo "=== Running pre-commit run --all-files ==="
-if command -v uv &> /dev/null; then
-    PRECOMMIT_OUTPUT=$(uv run pre-commit run --all-files 2>&1)
-    PRECOMMIT_EXIT=$?
-else
-    PRECOMMIT_OUTPUT=$(pre-commit run --all-files 2>&1)
-    PRECOMMIT_EXIT=$?
-fi
-
->&2 echo "$PRECOMMIT_OUTPUT"
-
-if [ $PRECOMMIT_EXIT -ne 0 ]; then
-    >&2 echo "⚠️  pre-commit found issues (exit code: $PRECOMMIT_EXIT)"
-    log_issue "## Pre-commit Failed\n\nPre-commit checks failed. Please fix the following issues:\n\n\`\`\`\n${PRECOMMIT_OUTPUT}\n\`\`\`"
-else
-    >&2 echo "✓ pre-commit passed"
-fi
->&2 echo ""
-
-# --------------------------
-# Step 2: Detect changed files and run appropriate tests
-# --------------------------
->&2 echo "=== Detecting changed files and running appropriate tests ==="
-
-# Get changed files from git (staged, unstaged, and untracked)
-CHANGED_FILES=$(git status --porcelain 2>/dev/null | awk '{print $NF}')
-
-if [ -n "$CHANGED_FILES" ]; then
-    >&2 echo "Changed files:"
-    >&2 echo "$CHANGED_FILES" | head -20
-    >&2 echo ""
-
-    # Map changed files to test directories
-    PROJECTS_TO_TEST=""
-
-    add_project() {
-        local project="$1"
-        if [[ ! "$PROJECTS_TO_TEST" =~ "$project" ]]; then
-            PROJECTS_TO_TEST="$PROJECTS_TO_TEST $project"
-        fi
-    }
-
-    while IFS= read -r file; do
-        case "$file" in
-            openhands-sdk/*) add_project "tests/sdk" ;;
-            openhands-tools/*) add_project "tests/tools" ;;
-            openhands-workspace/*) add_project "tests/workspace" ;;
-            openhands-agent-server/*) add_project "tests/agent_server" ;;
-            tests/sdk/*) add_project "tests/sdk" ;;
-            tests/tools/*) add_project "tests/tools" ;;
-            tests/workspace/*) add_project "tests/workspace" ;;
-            tests/agent_server/*) add_project "tests/agent_server" ;;
-            tests/cross/*) add_project "tests/cross" ;;
-            tests/examples/*) add_project "tests/examples" ;;
-            tests/github_workflows/*) add_project "tests/github_workflows" ;;
-            examples/*) add_project "tests/examples" ;;
-            scripts/*) add_project "tests/cross" ;;
-            pyproject.toml|uv.lock) add_project "tests/cross" ;;
-        esac
-    done <<< "$CHANGED_FILES"
-
-    PROJECTS_TO_TEST=$(echo "$PROJECTS_TO_TEST" | xargs)
-
-    if [ -n "$PROJECTS_TO_TEST" ]; then
-        >&2 echo "Running tests for: $PROJECTS_TO_TEST"
-        >&2 echo ""
-
-        for project in $PROJECTS_TO_TEST; do
-            if [ -d "$project" ]; then
-                >&2 echo "=== Testing $project ==="
-                if command -v uv &> /dev/null; then
-                    PYTEST_OUTPUT=$(uv run pytest "$project" -v --tb=short -x 2>&1)
-                    PYTEST_EXIT=$?
-                else
-                    PYTEST_OUTPUT=$(pytest "$project" -v --tb=short -x 2>&1)
-                    PYTEST_EXIT=$?
-                fi
-                >&2 echo "$PYTEST_OUTPUT"
-
-                if [ $PYTEST_EXIT -ne 0 ]; then
-                    >&2 echo "⚠️  pytest failed for $project"
-                    log_issue "## Pytest Failed for $project\n\nTests failed. Please fix the following:\n\n\`\`\`\n${PYTEST_OUTPUT}\n\`\`\`"
-                fi
-                >&2 echo ""
-            fi
-        done
-    else
-        >&2 echo "No tests to run for changed files"
-    fi
-else
-    >&2 echo "No changed files detected, skipping local tests"
-fi
->&2 echo ""
-
-# --------------------------
-# Step 3: Check if there's a pushed commit and wait for CI
-# --------------------------
->&2 echo "=== Checking GitHub CI status ==="
-
-# Check if we're in a git repo with a GitHub remote
-GITHUB_REMOTE=$(git remote -v 2>/dev/null | grep -E "(github\.com.*push)" | head -1)
-if [ -z "$GITHUB_REMOTE" ]; then
-    >&2 echo "No GitHub remote found, skipping CI check"
-else
-    # Extract owner/repo from remote URL
-    # Handle both HTTPS and SSH formats
-    REPO_INFO=$(echo "$GITHUB_REMOTE" | sed -E 's|.*github\.com[:/]([^/]+)/([^/.]+)(\.git)?.*|\1/\2|')
-    
-    if [ -z "$REPO_INFO" ]; then
-        >&2 echo "Could not parse GitHub repository info"
-    else
-        >&2 echo "Repository: $REPO_INFO"
-        
-        # Get current branch
-        CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
-        >&2 echo "Current branch: $CURRENT_BRANCH"
-        
-        # Get the latest commit SHA
-        LOCAL_SHA=$(git rev-parse HEAD 2>/dev/null)
-        >&2 echo "Local commit: ${LOCAL_SHA:0:8}"
-        
-        # Check if this commit has been pushed
-        REMOTE_SHA=$(git ls-remote origin "$CURRENT_BRANCH" 2>/dev/null | awk '{print $1}')
-        
-        if [ -z "$REMOTE_SHA" ]; then
-            >&2 echo "Branch not pushed to remote, skipping CI check"
-        elif [ "$LOCAL_SHA" != "$REMOTE_SHA" ]; then
-            >&2 echo "Local commit differs from remote (remote: ${REMOTE_SHA:0:8}), skipping CI check"
-        else
-            >&2 echo "Commit has been pushed, checking CI status..."
-            
-            # Check if GITHUB_TOKEN is available
-            if [ -z "$GITHUB_TOKEN" ]; then
-                >&2 echo "GITHUB_TOKEN not set, cannot check CI status"
-            else
-                # Use gh CLI if available, otherwise fall back to API
-                if command -v gh &> /dev/null; then
-                    >&2 echo "Using gh CLI to check CI status..."
-                    
-                    # Get check runs for this commit
-                    CI_STATUS=$(gh api "repos/$REPO_INFO/commits/$LOCAL_SHA/check-runs" \
-                        --jq '.check_runs | map({name: .name, status: .status, conclusion: .conclusion})' 2>&1)
-                    
-                    if [ $? -ne 0 ]; then
-                        >&2 echo "Failed to get CI status: $CI_STATUS"
-                    else
-                        # Parse the status
-                        TOTAL_CHECKS=$(echo "$CI_STATUS" | jq 'length')
-                        
-                        if [ "$TOTAL_CHECKS" -eq 0 ]; then
-                            >&2 echo "No CI checks found for this commit"
-                        else
-                            >&2 echo "Found $TOTAL_CHECKS CI check(s)"
-                            
-                            # Check for in-progress runs
-                            IN_PROGRESS=$(echo "$CI_STATUS" | jq '[.[] | select(.status != "completed")] | length')
-                            FAILED=$(echo "$CI_STATUS" | jq '[.[] | select(.conclusion == "failure" or .conclusion == "timed_out" or .conclusion == "cancelled")] | length')
-                            
-                            if [ "$IN_PROGRESS" -gt 0 ]; then
-                                >&2 echo "⏳ $IN_PROGRESS check(s) still in progress"
-                                
-                                # Wait for CI to complete (with timeout)
-                                MAX_WAIT=300  # 5 minutes
-                                WAIT_INTERVAL=15
-                                TOTAL_WAITED=0
-                                
-                                while [ "$IN_PROGRESS" -gt 0 ] && [ "$TOTAL_WAITED" -lt "$MAX_WAIT" ]; do
-                                    >&2 echo "Waiting for CI... (${TOTAL_WAITED}s / ${MAX_WAIT}s max)"
-                                    sleep $WAIT_INTERVAL
-                                    TOTAL_WAITED=$((TOTAL_WAITED + WAIT_INTERVAL))
-                                    
-                                    CI_STATUS=$(gh api "repos/$REPO_INFO/commits/$LOCAL_SHA/check-runs" \
-                                        --jq '.check_runs | map({name: .name, status: .status, conclusion: .conclusion})' 2>&1)
-                                    IN_PROGRESS=$(echo "$CI_STATUS" | jq '[.[] | select(.status != "completed")] | length')
-                                done
-                                
-                                if [ "$IN_PROGRESS" -gt 0 ]; then
-                                    >&2 echo "⚠️  CI still running after ${MAX_WAIT}s timeout"
-                                    log_issue "## CI Still Running\n\nCI checks are still in progress after waiting ${MAX_WAIT} seconds. Please wait for CI to complete before finishing."
-                                fi
-                            fi
-                            
-                            # Re-check for failures after waiting
-                            FAILED=$(echo "$CI_STATUS" | jq '[.[] | select(.conclusion == "failure" or .conclusion == "timed_out" or .conclusion == "cancelled")] | length')
-                            
-                            if [ "$FAILED" -gt 0 ]; then
-                                >&2 echo "❌ $FAILED check(s) failed!"
-                                
-                                # Get details of failed checks
-                                FAILED_DETAILS=$(echo "$CI_STATUS" | jq -r '.[] | select(.conclusion == "failure" or .conclusion == "timed_out" or .conclusion == "cancelled") | "- \(.name): \(.conclusion)"')
-                                >&2 echo "$FAILED_DETAILS"
-                                
-                                # Try to get failure logs
-                                FAILED_NAMES=$(echo "$CI_STATUS" | jq -r '.[] | select(.conclusion == "failure") | .name')
-                                
-                                FAILURE_MSG="## CI Failed\n\nThe following CI checks failed:\n\n${FAILED_DETAILS}\n"
-                                
-                                # Try to get the workflow run logs for more context
-                                WORKFLOW_RUNS=$(gh api "repos/$REPO_INFO/actions/runs?head_sha=$LOCAL_SHA" \
-                                    --jq '.workflow_runs[] | select(.conclusion == "failure") | {id: .id, name: .name}' 2>/dev/null)
-                                
-                                if [ -n "$WORKFLOW_RUNS" ]; then
-                                    FAILURE_MSG="${FAILURE_MSG}\nYou can view the full logs at: https://github.com/$REPO_INFO/actions\n"
-                                    
-                                    # Try to get job logs
-                                    FIRST_RUN_ID=$(echo "$WORKFLOW_RUNS" | jq -r '.id' | head -1)
-                                    if [ -n "$FIRST_RUN_ID" ]; then
-                                        JOBS_OUTPUT=$(gh api "repos/$REPO_INFO/actions/runs/$FIRST_RUN_ID/jobs" \
-                                            --jq '.jobs[] | select(.conclusion == "failure") | "### \(.name)\nConclusion: \(.conclusion)\nSteps:\n" + (.steps | map("- \(.name): \(.conclusion)") | join("\n"))' 2>/dev/null | head -100)
-                                        if [ -n "$JOBS_OUTPUT" ]; then
-                                            FAILURE_MSG="${FAILURE_MSG}\n### Failed Job Details:\n\`\`\`\n${JOBS_OUTPUT}\n\`\`\`"
-                                        fi
-                                    fi
-                                fi
-                                
-                                log_issue "$FAILURE_MSG"
-                            else
-                                >&2 echo "✓ All CI checks passed!"
-                            fi
-                        fi
-                    fi
-                else
-                    # Fallback to curl
-                    >&2 echo "gh CLI not available, using API directly..."
-                    CI_RESPONSE=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
-                        -H "Accept: application/vnd.github.v3+json" \
-                        "https://api.github.com/repos/$REPO_INFO/commits/$LOCAL_SHA/check-runs" 2>&1)
-                    
-                    TOTAL_CHECKS=$(echo "$CI_RESPONSE" | jq '.total_count // 0')
-                    
-                    if [ "$TOTAL_CHECKS" -gt 0 ]; then
-                        IN_PROGRESS=$(echo "$CI_RESPONSE" | jq '[.check_runs[] | select(.status != "completed")] | length')
-                        FAILED=$(echo "$CI_RESPONSE" | jq '[.check_runs[] | select(.conclusion == "failure")] | length')
-                        
-                        if [ "$IN_PROGRESS" -gt 0 ]; then
-                            >&2 echo "⏳ CI checks still in progress"
-                            log_issue "## CI In Progress\n\nCI checks are still running. Please wait for CI to complete."
-                        elif [ "$FAILED" -gt 0 ]; then
-                            FAILED_NAMES=$(echo "$CI_RESPONSE" | jq -r '.check_runs[] | select(.conclusion == "failure") | .name')
-                            >&2 echo "❌ CI failed: $FAILED_NAMES"
-                            log_issue "## CI Failed\n\nThe following CI checks failed:\n${FAILED_NAMES}\n\nPlease fix the issues and try again."
-                        else
-                            >&2 echo "✓ All CI checks passed!"
-                        fi
-                    else
-                        >&2 echo "No CI checks found"
-                    fi
-                fi
-            fi
-        fi
-    fi
-fi
->&2 echo ""
-
-# --------------------------
-# Final decision
-# --------------------------
-if [ "$BLOCK_STOP" = true ]; then
-    >&2 echo "=== BLOCKING STOP: Issues found ==="
-    # Output JSON to provide feedback to the agent
-    # Escape the issues for JSON
-    ESCAPED_ISSUES=$(echo -e "$ISSUES" | jq -Rs .)
-    echo "{\"decision\": \"deny\", \"reason\": \"Checks failed\", \"additionalContext\": $ESCAPED_ISSUES}"
-    exit 2
-fi
-
->&2 echo "=== All checks passed, allowing stop ==="
-echo '{"decision": "allow"}'
-exit 0

.openhands/setup.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-
-if ! command -v uv &> /dev/null; then
-    echo "uv is not installed. Installing..."
-    curl -LsSf https://astral.sh/uv/install.sh | sh
-else
-    echo "uv is already installed."
-    uv self update  # always update to the latest version
-fi
-
-make build

.openhands_instructions

@@ -0,0 +1,28 @@
+OpenHands is an automated AI software engineer. It is a repo with a Python backend
+(in the `openhands` directory) and TypeScript frontend (in the `frontend` directory).
+
+General Setup:
+- To set up the entire repo, including frontend and backend, run `make build`
+- To run linting and type-checking before finishing the job, run `poetry run pre-commit run --all-files --config ./dev_config/python/.pre-commit-config.yaml`
+
+Backend:
+- Located in the `openhands` directory
+- Testing:
+  - All tests are in `tests/unit/test_*.py`
+  - To test new code, run `poetry run pytest tests/unit/test_xxx.py` where `xxx` is the appropriate file for the current functionality
+  - Write all tests with pytest
+
+Frontend:
+- Located in the `frontend` directory
+- Prerequisites: A recent version of NodeJS / NPM
+- Setup: Run `npm install` in the frontend directory
+- Testing:
+  - Run tests: `npm run test`
+  - To run specific tests: `npm run test -- -t "TestName"`
+- Building:
+  - Build for production: `npm run build`
+- Environment Variables:
+  - Set in `frontend/.env` or as environment variables
+  - Available variables: VITE_BACKEND_HOST, VITE_USE_TLS, VITE_INSECURE_SKIP_VERIFY, VITE_FRONTEND_PORT
+- Internationalization:
+  - Generate i18n declaration file: `npm run make-i18n`

.pre-commit-config.yaml

@@ -1,56 +0,0 @@
----
-repos:
-    - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
-      rev: 0.2.1 # or other specific tag
-      hooks:
-          - id: yamlfmt
-    - repo: local
-      hooks:
-          - id: ruff-format
-            name: Ruff format
-            entry: uv
-            args: [run, ruff, format]
-            language: system
-            types: [python]
-            pass_filenames: true
-            always_run: false
-          - id: ruff-check
-            name: Ruff lint
-            entry: uv
-            args: [run, ruff, check, --fix, --exit-non-zero-on-fix]
-            language: system
-            types: [python]
-            pass_filenames: true
-            always_run: false
-          - id: pycodestyle
-            name: PEP8 style check (pycodestyle)
-            entry: uv
-            args: [run, pycodestyle, --max-line-length=88, '--ignore=E203,E501,W503,E704']
-            language: system
-            types: [python]
-            pass_filenames: true
-            always_run: false
-          - id: pyright
-            name: Type check with pyright
-            entry: uv
-            args: [run, pyright]
-            language: system
-            types: [python]
-            pass_filenames: true
-            always_run: false
-          - id: check-import-rules
-            name: Check import dependency rules
-            entry: uv
-            args: [run, python, scripts/check_import_rules.py]
-            language: system
-            types: [python]
-            pass_filenames: true
-            always_run: false
-          - id: check-tool-registration
-            name: Check Tool subclass registration
-            entry: uv
-            args: [run, python, scripts/check_tool_registration.py]
-            language: system
-            types: [python]
-            pass_filenames: true
-            always_run: false

.python-version

@@ -1 +0,0 @@
-3.13

AGENTS.md

@@ -1,328 +0,0 @@
-<ROLE>
-You are a collaborative software engineering partner with a strong focus on code quality and simplicity. Your approach is inspired by proven engineering principles from successful open-source projects, emphasizing pragmatic solutions and maintainable code.
-
-# Core Engineering Principles
-
-1. **Simplicity and Clarity**
-"The best solutions often come from looking at problems from a different angle, where special cases disappear and become normal cases."
-    • Prefer solutions that eliminate edge cases rather than adding conditional checks
-    • Good design patterns emerge from experience and careful consideration
-    • Simple, clear code is easier to maintain and debug
-
-2. **Backward Compatibility**
-"Stability is a feature, not a constraint."
-    • Changes should not break existing functionality
-    • Consider the impact on users and existing integrations
-    • Compatibility enables trust and adoption
-
-3. **Pragmatic Problem-Solving**
-"Focus on solving real problems with practical solutions."
-    • Address actual user needs rather than theoretical edge cases
-    • Prefer proven, straightforward approaches over complex abstractions
-    • Code should serve real-world requirements
-
-4. **Maintainable Architecture**
-"Keep functions focused and code readable."
-    • Functions should be short and have a single responsibility
-    • Avoid deep nesting - consider refactoring when indentation gets complex
-    • Clear naming and structure reduce cognitive load
-
-# Collaborative Approach
-
-## Communication Style
-    • **Constructive**: Focus on helping improve code and solutions
-    • **Collaborative**: Work together as partners toward better outcomes
-    • **Clear**: Provide specific, actionable feedback
-    • **Respectful**: Maintain a supportive tone while being technically rigorous
-
-## Problem Analysis Process
-
-### 1. Understanding Requirements
-When reviewing a requirement, confirm understanding by restating it clearly:
-> "Based on your description, I understand you need: [clear restatement of the requirement]. Is this correct?"
-
-### 2. Collaborative Problem Decomposition
-
-#### Data Structure Analysis
-"Well-designed data structures often lead to simpler code."
-    • What are the core data elements and their relationships?
-    • How does data flow through the system?
-    • Are there opportunities to simplify data handling?
-
-#### Complexity Assessment
-"Let's look for ways to simplify this."
-    • What's the essential functionality we need to implement?
-    • Which parts of the current approach add unnecessary complexity?
-    • How can we make this more straightforward?
-
-#### Compatibility Review
-"Let's make sure this doesn't break existing functionality."
-    • What existing features might be affected?
-    • How can we implement this change safely?
-    • What migration path do users need?
-
-#### Practical Validation
-"Let's focus on the real-world use case."
-    • Does this solve an actual problem users face?
-    • Is the complexity justified by the benefit?
-    • What's the simplest approach that meets the need?
-
-## 3. Constructive Feedback Format
-
-After analysis, provide feedback in this format:
-
-**Assessment**: [Clear evaluation of the approach]
-
-**Key Observations**:
-- Data Structure: [insights about data organization]
-- Complexity: [areas where we can simplify]
-- Compatibility: [potential impact on existing code]
-
-**Suggested Approach**:
-If the solution looks good:
-1. Start with the simplest data structure that works
-2. Eliminate special cases where possible
-3. Implement clearly and directly
-4. Ensure backward compatibility
-
-If there are concerns:
-"I think we might be able to simplify this. The core issue seems to be [specific problem]. What if we tried [alternative approach]?"
-
-## 4. Code Review Approach
-When reviewing code, provide constructive feedback:
-
-**Overall Assessment**: [Helpful evaluation]
-
-**Specific Suggestions**:
-- [Concrete improvements with explanations]
-- [Alternative approaches to consider]
-- [Ways to reduce complexity]
-
-**Next Steps**: [Clear action items]
-</ROLE>
-
-## Package-specific guidance
-When reviewing or modifying code, read the closest AGENTS file for the
-package(s) containing the changed files. If a PR spans multiple packages,
-consult each relevant package-level AGENTS.md.
-
-- SDK: [openhands-sdk/openhands/sdk/AGENTS.md](openhands-sdk/openhands/sdk/AGENTS.md)
-- Subagents: [openhands-sdk/openhands/sdk/subagent/AGENTS.md](openhands-sdk/openhands/sdk/subagent/AGENTS.md)
-- Tools: [openhands-tools/openhands/tools/AGENTS.md](openhands-tools/openhands/tools/AGENTS.md)
-- Workspace: [openhands-workspace/openhands/workspace/AGENTS.md](openhands-workspace/openhands/workspace/AGENTS.md)
-- Agent server: [openhands-agent-server/AGENTS.md](openhands-agent-server/AGENTS.md)
-- Eval config: [.github/run-eval/AGENTS.md](.github/run-eval/AGENTS.md)
-
-## API compatibility pointers
-
-- For SDK Python API deprecation/removal policy, read
-  [openhands-sdk/openhands/sdk/AGENTS.md](openhands-sdk/openhands/sdk/AGENTS.md).
-  Public API removals require deprecation before removal, and breaking SDK API
-  changes require at least a **MINOR** SemVer bump.
-- The SDK API breakage checker should treat metadata-only changes to
-  Pydantic `Field(...)` declarations as non-breaking, including adding,
-  removing, or editing `description`, `title`, `examples`,
-  `json_schema_extra`, and `deprecated` kwargs.
-- For public REST APIs, read
-  [openhands-agent-server/AGENTS.md](openhands-agent-server/AGENTS.md).
-  REST contract breaks need a deprecation notice and a runway of
-  **5 minor releases** before removing the old contract or making an
-  incompatible replacement mandatory.
-
-<DEV_SETUP>
-- Make sure you `make build` to configure the dependencies first
-- We use pre-commit hooks `.pre-commit-config.yaml` that includes:
-  - type check through pyright
-  - linting and formatter with `uv ruff`
-- NEVER USE `mypy`!
-- Do NOT commit ALL the file, just commit the relevant file you've changed!
-- In every commit message, you should add "Co-authored-by: openhands <openhands@all-hands.dev>"
-- You can run pytest with `uv run pytest`
-
-# Instruction for fixing "E501 Line too long"
-
-- If it is just code, you can modify it so it spans multiple lines.
-- If it is a single-line string, you can break it into a multi-line string by doing "ABC" -> ("A"\n"B"\n"C")
-- If it is a long multi-line string (e.g., docstring), you should just add type ignore AFTER the ending """. You should NEVER ADD IT INSIDE the docstring.
-
-
-</DEV_SETUP>
-
-<PR_ARTIFACTS>
-# PR-Specific Documents
-
-When working on a PR that requires design documents, scripts meant for development-only, or other temporary artifacts that should NOT be merged to main, store them in a `.pr/` directory at the repository root.
-
-## Usage
-
-```bash
-# Create the directory if it doesn't exist
-mkdir -p .pr
-
-# Add your PR-specific documents
-.pr/
-├── design.md       # Design decisions and architecture notes
-├── analysis.md     # Investigation or debugging notes
-└── notes.md        # Any other PR-specific content
-```
-
-## How It Works
-
-1. **Notification**: When `.pr/` exists, a single comment is posted to the PR conversation alerting reviewers
-2. **Auto-cleanup**: When the PR is approved, the `.pr/` directory is automatically removed via commit
-3. **Fork PRs**: Auto-cleanup cannot push to forks, so manual removal is required before merging
-
-## Important Notes
-
-- Do NOT put anything in `.pr/` that needs to be preserved
-- The `.pr/` check passes (green ✅) during development - it only posts a notification, not a blocking error
-- For fork PRs: You must manually remove `.pr/` before the PR can be merged
-
-## When to Use
-
-- Complex refactoring that benefits from written design rationale
-- Debugging sessions where you want to document your investigation
-- Feature implementations that need temporary planning docs
-- Temporary script that are intended to show reviewers that the feature works
-- Any analysis that helps reviewers understand the PR but isn't needed long-term
-</PR_ARTIFACTS>
-
-<REVIEW_HANDLING>
-- Critically evaluate each review comment before acting on it. Not all feedback is worth implementing:
-  - Does it fix a real bug or improve clarity significantly?
-  - Does it align with the project's engineering principles (simplicity, maintainability)?
-  - Is the suggested change proportional to the benefit, or does it add unnecessary complexity?
-- It's acceptable to respectfully decline suggestions that add verbosity without clear benefit, over-engineer for hypothetical edge cases, or contradict the project's pragmatic approach.
-- After addressing (or deciding not to address) inline review comments, mark the corresponding review threads as resolved.
-- Before resolving a thread, leave a reply comment that either explains the reason for dismissing the feedback or references the specific commit (e.g., commit SHA) that addressed the issue.
-- Prefer resolving threads only once fixes are pushed or a clear decision is documented.
-- Use the GitHub GraphQL API to reply to and resolve review threads (see below).
-
-## Resolving Review Threads via GraphQL
-
-The CI check `Review Thread Gate/unresolved-review-threads` will fail if there are unresolved review threads. To resolve threads programmatically:
-
-1. Get the thread IDs (replace `<OWNER>`, `<REPO>`, `<PR_NUMBER>`):
-```bash
-gh api graphql -f query='
-{
-  repository(owner: "<OWNER>", name: "<REPO>") {
-    pullRequest(number: <PR_NUMBER>) {
-      reviewThreads(first: 20) {
-        nodes {
-          id
-          isResolved
-          comments(first: 1) {
-            nodes { body }
-          }
-        }
-      }
-    }
-  }
-}'
-```
-
-2. Reply to the thread explaining how the feedback was addressed:
-```bash
-gh api graphql -f query='
-mutation {
-  addPullRequestReviewThreadReply(input: {
-    pullRequestReviewThreadId: "<THREAD_ID>"
-    body: "Fixed in <COMMIT_SHA>"
-  }) {
-    comment { id }
-  }
-}'
-```
-
-3. Resolve the thread:
-```bash
-gh api graphql -f query='
-mutation {
-  resolveReviewThread(input: {threadId: "<THREAD_ID>"}) {
-    thread { isResolved }
-  }
-}'
-```
-
-4. Get the failed workflow run ID and rerun it:
-```bash
-# Find the run ID from the failed check URL, or use:
-gh run list --repo <OWNER>/<REPO> --branch <BRANCH> --limit 5
-
-# Rerun failed jobs
-gh run rerun <RUN_ID> --repo <OWNER>/<REPO> --failed
-```
-</REVIEW_HANDLING>
-
-
-<CODE>
-- Avoid hacky trick like `sys.path.insert` when resolving package dependency
-- Use existing packages/libraries instead of implementing yourselves whenever possible.
-- Avoid using # type: ignore. Treat it only as a last resort. In most cases, issues should be resolved by improving type annotations, adding assertions, or adjusting code/tests—rather than silencing the type checker.
-  - Please AVOID using # type: ignore[attr-defined] unless absolutely necessary. If the issue can be addressed by adding a few extra assert statements to verify types, prefer that approach instead!
-  - For issue like # type: ignore[call-arg]: if you discover that the argument doesn’t actually exist, do not try to mock it again in tests. Instead, simply remove it.
-- Avoid doing in-line imports unless absolutely necessary (e.g., circular dependency).
-- Avoid getattr/hasattr guards and instead enforce type correctness by relying on explicit type assertions and proper object usage, ensuring functions only receive the expected Pydantic models or typed inputs. Prefer type hints and validated models over runtime shape checks.
-- Prefer accessing typed attributes directly. If necessary, convert inputs up front into a canonical shape; avoid purely hypothetical fallbacks.
-- Use real newlines in commit messages; do not write literal "\n".
-
-</CODE>
-
-<TESTING>
-- AFTER you edit ONE file, you should run pre-commit hook on that file via `uv run pre-commit run --files [filepath]` to make sure you didn't break it.
-- Don't write TOO MUCH test, you should write just enough to cover edge cases.
-- Check how we perform tests in .github/workflows/tests.yml
-- Put unit tests under the corresponding domain folder in `tests/` (e.g., `tests/sdk`, `tests/tools`, `tests/workspace`). For example, changes to `openhands-sdk/openhands/sdk/tool/tool.py` should be covered in `tests/sdk/tool/test_tool.py`.
-- DON'T write TEST CLASSES unless absolutely necessary!
-- If you find yourself duplicating logics in preparing mocks, loading data etc, these logic should be fixtures in conftest.py!
-- Please test only the logic implemented in the current codebase. Do not test functionality (e.g., BaseModel.model_dumps()) that is not implemented in this repository.
-- For changes to prompt templates, tool descriptions, or agent decision logic, add the `integration-test` label to trigger integration tests and verify no unexpected impact on benchmark performance.
-
-# Behavior Tests
-
-Behavior tests (prefix `b##_*`) in `tests/integration/tests/` are designed to verify that agents exhibit desired behaviors in realistic scenarios. These tests are distinct from functional tests (prefix `t##_*`) and have specific requirements.
-
-Before adding or modifying behavior tests, review `tests/integration/BEHAVIOR_TESTS.md` for the latest workflow, expectations, and examples.
-</TESTING>
-
-<AGENT_TMP_DIRECTORY>
-# Agent Temporary Directory Convention
-
-When tools need to store observation files (e.g., browser session recordings, task tracker data), use `.agent_tmp` as the directory name for consistency.
-
-The browser session recording tool saves recordings to `.agent_tmp/observations/recording-{timestamp}/`.
-
-This convention ensures tool-generated observation files are stored in a predictable location that can be easily:
-- Added to `.gitignore`
-- Cleaned up after agent sessions
-- Identified as agent-generated artifacts
-
-Note: This is separate from `persistence_dir` which is used for conversation state persistence.
-</AGENT_TMP_DIRECTORY>
-
-<REPO>
-<PROJECT_STRUCTURE>
-- This is a `uv`-managed Python monorepo (single `uv.lock` at repo root) with multiple distributable packages: `openhands-sdk/` (SDK), `openhands-tools/` (built-in tools), `openhands-workspace/` (workspace impls), and `openhands-agent-server/` (server runtime).
-- `examples/` contains runnable patterns; `tests/` is split by domain (`tests/sdk`, `tests/tools`, `tests/workspace`, `tests/agent_server`, etc.).
-- Python namespace is `openhands.*` across packages; keep new modules within the matching package and mirror test paths under `tests/`.
-</PROJECT_STRUCTURE>
-
-<QUICK_COMMANDS>
-- Set up the dev environment: `make build` (runs `uv sync --dev` and installs pre-commit; requires uv >= 0.8.13)
-- Lint/format: `make lint`, `make format`
-- Run tests: `uv run pytest`
-- Build agent-server: `make build-server` (output: `dist/agent-server/`)
-- Clean caches: `make clean`
-- Run SDK examples: see [openhands-sdk/openhands/sdk/AGENTS.md](openhands-sdk/openhands/sdk/AGENTS.md).
-- The example workflow runs `uv run pytest tests/examples/test_examples.py --run-examples`; each successful example must print an `EXAMPLE_COST: ...` line to stdout (use `EXAMPLE_COST: 0` for non-LLM examples).
-- Conversation plugins passed via `plugins=[...]` are lazy-loaded on the first `send_message()` or `run()`, so example code should inspect plugin-added skills or `resolved_plugins` only after that first interaction.
-</QUICK_COMMANDS>
-
-<REPO_CONFIG_NOTES>
-- Ruff: `line-length = 88`, `target-version = "py312"` (see `pyproject.toml`).
-- Ruff ignores `ARG` (unused arguments) under `tests/**/*.py` to allow pytest fixtures.
-- Repository guidance lives in the project root AGENTS.md (loaded as a third-party skill file).
-</REPO_CONFIG_NOTES>
-
-</REPO>

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+contact@all-hands.dev
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -1,70 +1,94 @@
 # Contributing
 
-Thank you for helping improve the OpenHands Software Agent SDK.
+Thanks for your interest in contributing to OpenHands! We welcome and appreciate contributions.
 
-This repo is a foundation. We want the SDK to stay stable and extensible so that many
-applications can build on it safely.
+## Understanding OpenHands's CodeBase
 
-Downstream applications we actively keep in mind:
-- [OpenHands-CLI](https://github.com/OpenHands/OpenHands-CLI) (client)
-- [OpenHands app-server](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md) (client)
-- [OpenHands Enterprise](https://github.com/OpenHands/OpenHands/blob/main/enterprise/README.md) (client)
+To understand the codebase, please refer to the README in each module:
+- [frontend](./frontend/README.md)
+- [evaluation](./evaluation/README.md)
+- [openhands](./openhands/README.md)
+   - [agenthub](./openhands/agenthub/README.md)
+   - [server](./openhands/server/README.md)
 
-The SDK itself has a Python interface. In addition, the
-[agent-server](https://docs.openhands.dev/sdk/guides/agent-server/overview) is the
-REST/WebSocket server component that exposes the SDK for remote execution and integrations.
-Changes should keep both interfaces stable and consistent.
+## Setting up your development environment
 
-## A lesson we learned (why we care about architecture)
+We have a separate doc [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md) that tells you how to set up a development workflow.
 
-In earlier iterations, we repeatedly ran into a failure mode: needs from downstream applications
-(or assumptions) would leak into core logic.
+## How can I contribute?
 
-That kind of coupling can feel convenient in the moment, but it tends to create subtle
-breakage elsewhere: different environments, different workspaces, different execution modes,
-and different evaluation setups.
+There are many ways that you can contribute:
 
-The architecture of OpenHands V0 was too monolithic to support multiple applications built into it,
-as CLI, evaluation scripts, web server were, and built on it, as OpenHands Cloud was.
+1. **Download and use** OpenHands, and send [issues](https://github.com/All-Hands-AI/OpenHands/issues) when you encounter something that isn't working or a feature that you'd like to see.
+2. **Send feedback** after each session by [clicking the thumbs-up thumbs-down buttons](https://docs.all-hands.dev/modules/usage/feedback), so we can see where things are working and failing, and also build an open dataset for training code agents.
+3. **Improve the Codebase** by sending PRs (see details below). In particular, we have some [good first issues](https://github.com/All-Hands-AI/OpenHands/labels/good%20first%20issue) that may be ones to start on.
 
-If you’re interested in the deeper background and lessons learned, see our write-up:
-[OpenHands: An Open Platform for AI Software Developers as Generalist Agents](https://arxiv.org/abs/2511.03690)
+## What can I build?
+Here are a few ways you can help improve the codebase.
 
-This SDK exists (as a separate, rebuilt foundation) to avoid that failure mode.
+#### UI/UX
+We're always looking to improve the look and feel of the application. If you've got a small fix
+for something that's bugging you, feel free to open up a PR that changes the `./frontend` directory.
 
-## Principles we review PRs with
+If you're looking to make a bigger change, add a new UI element, or significantly alter the style
+of the application, please open an issue first, or better, join the #frontend channel in our Slack
+to gather consensus from our design team first.
 
-We welcome all contributions, big or small, to improve or extend the software agent SDK.
+#### Improving the agent
+Our main agent is the CodeAct agent. You can [see its prompts here](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/agenthub/codeact_agent)
 
-You may find that occasionally we are opinionated about several things:
+Changes to these prompts, and to the underlying behavior in Python, can have a huge impact on user experience.
+You can try modifying the prompts to see how they change the behavior of the agent as you use the app
+locally, but we will need to do an end-to-end evaluation of any changes here to ensure that the agent
+is getting better over time.
 
-- **OpenHands SDK is its own thing**: its downstream are client applications.
-- **Prefer interfaces over special cases**: if a client needs something, add or improve a
-  clean, reusable interface/extension point instead of adding a shortcut.
-- **Extensibility over one-off patches**: design features so multiple clients can adopt them
-  without rewriting core logic.
-- **Avoid hidden assumptions**: don’t rely on particular env vars, workspace layouts, request
-  contexts, or runtime quirks that only exist in one app.
-  - Workspaces *do* encode environment specifics (local/Docker/remote), but keep those assumptions
-    explicit (params + validation) and contained to the `workspace` layer.
-- **No client-specific code paths**: avoid logic that only makes sense for one
-  downstream app.
-  - It’s fine to have multiple workspace implementations; it’s not fine for SDK core behavior to
-    branch on whether the caller is CLI/app-server/SaaS. Prefer capabilities/config over app-identity.
-- **Keep the agent loop stable**: treat stability as a feature; be cautious with control-flow
-  changes and "small" behavior tweaks.
-- **Compatibility is part of the API**: if something could break downstream clients, call it
-  out explicitly and consider a migration path. We have a deprecation mechanism you may want to use.
+We use the [SWE-bench](https://www.swebench.com/) benchmark to test our agent. You can join the #evaluation
+channel in Slack to learn more.
 
-If you’re not sure whether a change crosses these lines, please ask early. We’re happy to help think
-through the shape of a clean interface.
+#### Adding a new agent
+You may want to experiment with building new types of agents. You can add an agent to `openhands/agenthub`
+to help expand the capabilities of OpenHands.
 
-## Practical pointers
+#### Adding a new runtime
+The agent needs a place to run code and commands. When you run OpenHands on your laptop, it uses a Docker container
+to do this by default. But there are other ways of creating a sandbox for the agent.
 
-This file is mostly about principles. For the mechanics, please see:
-- [AGENTS.md](AGENTS.md) for AI agents
-- [DEVELOPMENT.md](DEVELOPMENT.md) for humans
+If you work for a company that provides a cloud-based runtime, you could help us add support for that runtime
+by implementing the [interface specified here](https://github.com/All-Hands-AI/OpenHands/blob/main/openhands/runtime/runtime.py).
 
-## Questions / discussion
+#### Testing
+When you write code, it is also good to write tests. Please navigate to the `tests` folder to see existing test suites.
+At the moment, we have two kinds of tests: `unit` and `integration`. Please refer to the README for each test suite. These tests also run on GitHub's continuous integration to ensure quality of the project.
 
-Join us on Slack: https://openhands.dev/joinslack
+## Sending Pull Requests to OpenHands
+
+You'll need to fork our repository to send us a Pull Request. You can learn more
+about how to fork a GitHub repo and open a PR with your changes in [this article](https://medium.com/swlh/forks-and-pull-requests-how-to-contribute-to-github-repos-8843fac34ce8)
+
+### Pull Request title
+As described [here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json), a valid PR title should begin with one of the following prefixes:
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white space, formatting, missing semicolons, etc.)
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `perf`: A code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- `chore`: Other changes that don't modify src or test files
+- `revert`: Reverts a previous commit
+
+For example, a PR title could be:
+- `refactor: modify package path`
+- `feat(frontend): xxxx`, where `(frontend)` means that this PR mainly focuses on the frontend component.
+
+You may also check out previous PRs in the [PR list](https://github.com/All-Hands-AI/OpenHands/pulls).
+
+### Pull Request description
+- If your PR is small (such as a typo fix), you can go brief.
+- If it contains a lot of changes, it's better to write more details.
+
+If your changes are user-facing (e.g. a new feature in the UI, a change in behavior, or a bugfix)
+please include a short message that we can add to our changelog.

CREDITS.md

@@ -0,0 +1,312 @@
+# Credits
+
+## Contributors
+
+We would like to thank all the [contributors](https://github.com/All-Hands-AI/OpenHands/graphs/contributors) who have helped make OpenHands possible. We greatly appreciate your dedication and hard work.
+
+## Open Source Projects
+
+OpenHands includes and adapts the following open source projects. We are grateful for their contributions to the open source community:
+
+#### [SWE Agent](https://github.com/princeton-nlp/swe-agent)
+   - License: MIT License
+   - Description: Adapted for use in OpenHands's agent hub
+
+#### [Aider](https://github.com/paul-gauthier/aider)
+   - License: Apache License 2.0
+   - Description: AI pair programming tool. OpenHands has adapted and integrated its linter module for code-related tasks in [`agentskills utilities`](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/runtime/plugins/agent_skills/utils/aider)
+
+#### [BrowserGym](https://github.com/ServiceNow/BrowserGym)
+   - License: Apache License 2.0
+   - Description: Adapted in implementing the browsing agent
+
+
+### Reference Implementations for Evaluation Benchmarks
+OpenHands integrates code of the reference implementations for the following agent evaluation benchmarks:
+
+#### [HumanEval](https://github.com/openai/human-eval)
+   - License: MIT License
+
+#### [DSP](https://github.com/microsoft/DataScienceProblems)
+   - License: MIT License
+
+#### [HumanEvalPack](https://github.com/bigcode-project/bigcode-evaluation-harness)
+   - License: Apache License 2.0
+
+#### [AgentBench](https://github.com/THUDM/AgentBench)
+   - License: Apache License 2.0
+
+#### [SWE-Bench](https://github.com/princeton-nlp/SWE-bench)
+   - License: MIT License
+
+#### [BIRD](https://bird-bench.github.io/)
+   - License: MIT License
+   - Dataset: CC-BY-SA 4.0
+
+#### [Gorilla APIBench](https://github.com/ShishirPatil/gorilla)
+   - License: Apache License 2.0
+
+#### [GPQA](https://github.com/idavidrein/gpqa)
+   - License: MIT License
+
+#### [ProntoQA](https://github.com/asaparov/prontoqa)
+   - License: Apache License 2.0
+
+
+## Open Source licenses
+
+### MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+### BSD 3-Clause License
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+### Apache License 2.0
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+
+
+### Non-Open Source Reference Implementations:
+
+#### [MultiPL-E](https://github.com/nuprl/MultiPL-E)
+   - License: BSD 3-Clause License with Machine Learning Restriction
+
+BSD 3-Clause License with Machine Learning Restriction
+
+Copyright (c) 2022, Northeastern University, Oberlin College, Roblox Inc,
+Stevens Institute of Technology, University of Massachusetts Amherst, and
+Wellesley College.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+4.  The contents of this repository may not be used as training data for any
+    machine learning model, including but not limited to neural networks.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

DEVELOPMENT.md

@@ -1,48 +0,0 @@
-# Development Guide
-
-## Setup
-
-```bash
-git clone https://github.com/OpenHands/agent-sdk.git
-cd agent-sdk
-make build
-```
-
-## Code Quality
-
-```bash
-make format                              # Format code
-make lint                                # Lint code
-uv run pre-commit run --all-files        # Run all checks
-```
-
-Pre-commit hooks run automatically on commit with type checking and linting.
-
-## Testing
-
-```bash
-uv run pytest                            # All tests
-uv run pytest tests/sdk/                 # SDK tests only
-uv run pytest tests/tools/               # Tools tests only
-```
-
-## Project Structure
-
-```
-agent-sdk/
-├── openhands-sdk/          # Core SDK package
-├── openhands-tools/        # Built-in tools
-├── openhands-workspace/    # Workspace management
-├── openhands-agent-server/ # Agent server
-├── examples/               # Usage examples
-└── tests/                  # Test suites
-```
-
-## Contributing
-
-1. Create a new branch
-2. Make your changes
-3. Run tests and checks
-4. Push and create a pull request
-
-For questions, join our [Slack community](https://openhands.dev/joinslack).

Development.md

@@ -0,0 +1,128 @@
+# Development Guide
+This guide is for people working on OpenHands and editing the source code.
+If you wish to contribute your changes, check out the [CONTRIBUTING.md](https://github.com/All-Hands-AI/OpenHands/blob/main/CONTRIBUTING.md) on how to clone and setup the project initially before moving on.
+Otherwise, you can clone the OpenHands project directly.
+
+## Start the server for development
+### 1. Requirements
+* Linux, Mac OS, or [WSL on Windows](https://learn.microsoft.com/en-us/windows/wsl/install)  [Ubuntu <= 22.04]
+* [Docker](https://docs.docker.com/engine/install/) (For those on MacOS, make sure to allow the default Docker socket to be used from advanced settings!)
+* [Python](https://www.python.org/downloads/) = 3.12
+* [NodeJS](https://nodejs.org/en/download/package-manager) >= 18.17.1
+* [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer) >= 1.8
+* OS-specific dependencies:
+  - Ubuntu: build-essential => `sudo apt-get install build-essential`
+  - WSL: netcat => `sudo apt-get install netcat`
+
+Make sure you have all these dependencies installed before moving on to `make build`.
+
+#### Develop without sudo access
+If you want to develop without system admin/sudo access to upgrade/install `Python` and/or `NodeJs`, you can use `conda` or `mamba` to manage the packages for you:
+
+```bash
+# Download and install Mamba (a faster version of conda)
+curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+bash Miniforge3-$(uname)-$(uname -m).sh
+
+# Install Python 3.12, nodejs, and poetry
+mamba install python=3.12
+mamba install conda-forge::nodejs
+mamba install conda-forge::poetry
+```
+
+### 2. Build and Setup The Environment
+Begin by building the project which includes setting up the environment and installing dependencies. This step ensures that OpenHands is ready to run on your system:
+
+```bash
+make build
+```
+
+### 3. Configuring the Language Model
+OpenHands supports a diverse array of Language Models (LMs) through the powerful [litellm](https://docs.litellm.ai) library. By default, we've chosen the mighty GPT-4 from OpenAI as our go-to model, but the world is your oyster! You can unleash the potential of Anthropic's suave Claude, the enigmatic Llama, or any other LM that piques your interest.
+
+To configure the LM of your choice, run:
+
+   ```bash
+   make setup-config
+   ```
+
+   This command will prompt you to enter the LLM API key, model name, and other variables ensuring that OpenHands is tailored to your specific needs. Note that the model name will apply only when you run headless. If you use the UI, please set the model in the UI.
+
+   Note: If you have previously run OpenHands using the docker command, you may have already set some environmental variables in your terminal. The final configurations are set from highest to lowest priority:
+   Environment variables > config.toml variables > default variables
+
+**Note on Alternative Models:**
+Some alternative models may prove more challenging to tame than others. Fear not, brave adventurer! We shall soon unveil LLM-specific documentation to guide you on your quest.
+And if you've already mastered the art of wielding a model other than OpenAI's GPT, we encourage you to share your setup instructions with us by creating instructions and adding it [to our documentation](https://github.com/All-Hands-AI/OpenHands/tree/main/docs/modules/usage/llms).
+
+For a full list of the LM providers and models available, please consult the [litellm documentation](https://docs.litellm.ai/docs/providers).
+
+### 4. Running the application
+#### Option A: Run the Full Application
+Once the setup is complete, launching OpenHands is as simple as running a single command. This command starts both the backend and frontend servers seamlessly, allowing you to interact with OpenHands:
+```bash
+make run
+```
+
+#### Option B: Individual Server Startup
+- **Start the Backend Server:** If you prefer, you can start the backend server independently to focus on backend-related tasks or configurations.
+    ```bash
+    make start-backend
+    ```
+
+- **Start the Frontend Server:** Similarly, you can start the frontend server on its own to work on frontend-related components or interface enhancements.
+    ```bash
+    make start-frontend
+    ```
+
+### 6. LLM Debugging
+If you encounter any issues with the Language Model (LM) or you're simply curious, you can inspect the actual LLM prompts and responses. To do so, export DEBUG=1 in the environment and restart the backend.
+OpenHands will then log the prompts and responses in the logs/llm/CURRENT_DATE directory, allowing you to identify the causes.
+
+### 7. Help
+Need assistance or information on available targets and commands? The help command provides all the necessary guidance to ensure a smooth experience with OpenHands.
+```bash
+make help
+ ```
+
+### 8. Testing
+To run tests, refer to the following:
+#### Unit tests
+
+```bash
+poetry run pytest ./tests/unit/test_*.py
+```
+
+### 9. Add or update dependency
+1. Add your dependency in `pyproject.toml` or use `poetry add xxx`
+2. Update the poetry.lock file via `poetry lock --no-update`
+
+### 9. Use existing Docker image
+To reduce build time (e.g., if no changes were made to the client-runtime component), you can use an existing Docker container image. Follow these steps:
+1. Set the SANDBOX_RUNTIME_CONTAINER_IMAGE environment variable to the desired Docker image.
+2. Example: export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.13-nikolaik
+
+## Develop inside Docker container
+
+TL;DR
+
+```bash
+make docker-dev
+```
+
+See more details [here](./containers/dev/README.md)
+
+If you are just interested in running `OpenHands` without installing all the required tools on your host.
+
+```bash
+make docker-run
+```
+
+If you do not have `make` on your host, run:
+
+```bash
+cd ./containers/dev
+./dev.sh
+```
+
+You do need [Docker](https://docs.docker.com/engine/install/) installed on your host though.

ISSUE_TRIAGE.md

@@ -0,0 +1,25 @@
+# Issue Triage
+These are the procedures and guidelines on how issues are triaged in this repo by the maintainers.
+
+## General
+* Most issues must be tagged with **enhancement** or **bug**
+* Issues may be tagged with what it relates to (**backend**, **frontend**, **agent quality**, etc.)
+
+## Severity
+* **Low**: Minor issues, single user report
+* **Medium**: Affecting multiple users
+* **Critical**: Affecting all users or potential security issues
+
+## Effort
+* Issues may be estimated with effort required (**small effort**, **medium effort**, **large effort**)
+
+## Difficulty
+* Issues with low implementation difficulty may be tagged with **good first issue**
+
+## Not Enough Information
+* User is asked to provide more information (logs, how to reproduce, etc.) when the issue is not clear
+* If an issue is unclear and the author does not provide more information or respond to a request, the issue may be closed as **not planned** (Usually after a week)
+
+## Multiple Requests/Fixes in One Issue
+* These issues will be narrowed down to one request/fix so the issue is more easily tracked and fixed
+* Issues may be broken down into multiple issues if required

LICENSE

@@ -1,21 +1,25 @@
-MIT License
+The MIT License (MIT)
+=====================
 
-Copyright (c) 2026 OpenHands contributors
+Copyright © 2023
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

MAINTAINERS

@@ -1,11 +0,0 @@
-# Repository Maintainers
-#
-# Format: Each maintainer on a new line starting with "- @username"
-# This file is read by .github/workflows/assign-reviews.yml for automated triage
-#
-
-The following people are maintainers of this repository and are responsible for triage and review:
-
-- @xingyaoww
-- @neubig
-- @enyst

MANIFEST.in

@@ -1,48 +1,5 @@
-# This MANIFEST.in file tells setuptools which files to include 
-# in the sdist package distribution used for building docker image
+# Exclude all Python bytecode files
+global-exclude *.pyc
 
-# ==============================================================================
-# Root-level workspace files
-# ==============================================================================
-include pyproject.toml
-include uv.lock
-
-# ==============================================================================
-# openhands-sdk
-# ==============================================================================
-include openhands-sdk/pyproject.toml
-recursive-include openhands-sdk *.py
-recursive-include openhands-sdk *.j2
-recursive-include openhands-sdk py.typed
-
-# ==============================================================================
-# openhands-tools
-# ==============================================================================
-include openhands-tools/pyproject.toml
-recursive-include openhands-tools *.py
-recursive-include openhands-tools *.j2
-recursive-include openhands-tools py.typed
-
-# ==============================================================================
-# openhands-workspace
-# ==============================================================================
-include openhands-workspace/pyproject.toml
-recursive-include openhands-workspace *.py
-recursive-include openhands-workspace py.typed
-
-# ==============================================================================
-# openhands-agent-server
-# ==============================================================================
-include openhands-agent-server/pyproject.toml
-recursive-include openhands-agent-server *.py
-recursive-include openhands-agent-server py.typed
-
-# Docker build files
-include openhands-agent-server/openhands/agent_server/docker/Dockerfile
-include openhands-agent-server/openhands/agent_server/docker/wallpaper.svg
-
-# PyInstaller spec
-include openhands-agent-server/openhands/agent_server/agent-server.spec
-
-# VSCode extensions
-recursive-include openhands-agent-server/openhands/agent_server/vscode_extensions *
+# Exclude Python cache directories
+global-exclude __pycache__

Makefile

@@ -1,109 +1,332 @@
-SHELL := /usr/bin/env bash
-.SHELLFLAGS := -eu -o pipefail -c
+SHELL=/bin/bash
+# Makefile for OpenHands project
 
-# Colors for output
-ECHO := printf '%b\n'
-GREEN := \033[32m
-YELLOW := \033[33m
-RED := \033[31m
-CYAN := \033[36m
-RESET := \033[0m
-UNDERLINE := \033[4m
+# Variables
+BACKEND_HOST ?= "127.0.0.1"
+BACKEND_PORT = 3000
+BACKEND_HOST_PORT = "$(BACKEND_HOST):$(BACKEND_PORT)"
+FRONTEND_PORT = 3001
+DEFAULT_WORKSPACE_DIR = "./workspace"
+DEFAULT_MODEL = "gpt-4o"
+CONFIG_FILE = config.toml
+PRE_COMMIT_CONFIG_PATH = "./dev_config/python/.pre-commit-config.yaml"
+PYTHON_VERSION = 3.12
 
-# Required uv version
-REQUIRED_UV_VERSION := 0.8.13
-PKGS ?= openhands-sdk openhands-tools openhands-workspace openhands-agent-server
+# ANSI color codes
+GREEN=$(shell tput -Txterm setaf 2)
+YELLOW=$(shell tput -Txterm setaf 3)
+RED=$(shell tput -Txterm setaf 1)
+BLUE=$(shell tput -Txterm setaf 6)
+RESET=$(shell tput -Txterm sgr0)
 
-.PHONY: build format lint clean help check-uv-version
+# Build
+build:
+	@echo "$(GREEN)Building project...$(RESET)"
+	@$(MAKE) -s check-dependencies
+	@$(MAKE) -s install-python-dependencies
+	@$(MAKE) -s install-frontend-dependencies
+	@$(MAKE) -s install-pre-commit-hooks
+	@$(MAKE) -s build-frontend
+	@echo "$(GREEN)Build completed successfully.$(RESET)"
 
-# Default target
-.DEFAULT_GOAL := help
+check-dependencies:
+	@echo "$(YELLOW)Checking dependencies...$(RESET)"
+	@$(MAKE) -s check-system
+	@$(MAKE) -s check-python
+	@$(MAKE) -s check-npm
+	@$(MAKE) -s check-nodejs
+ifeq ($(INSTALL_DOCKER),)
+	@$(MAKE) -s check-docker
+endif
+	@$(MAKE) -s check-poetry
+	@echo "$(GREEN)Dependencies checked successfully.$(RESET)"
 
-
-check-uv-version:
-	@$(ECHO) "$(YELLOW)Checking uv version...$(RESET)"
-	@UV_VERSION=$$(uv --version | cut -d' ' -f2); \
-	REQUIRED_VERSION=$(REQUIRED_UV_VERSION); \
-	if [ "$$(printf '%s\n' "$$REQUIRED_VERSION" "$$UV_VERSION" | sort -V | head -n1)" != "$$REQUIRED_VERSION" ]; then \
-		$(ECHO) "$(RED)Error: uv version $$UV_VERSION is less than required $$REQUIRED_VERSION$(RESET)"; \
-		$(ECHO) "$(YELLOW)Please update uv with: uv self update$(RESET)"; \
-		exit 1; \
-	fi; \
-	$(ECHO) "$(GREEN)uv version $$UV_VERSION meets requirements$(RESET)"
-
-build: check-uv-version
-	@$(ECHO) "$(CYAN)Setting up OpenHands V1 development environment...$(RESET)"
-	@$(ECHO) "$(YELLOW)Installing dependencies with uv sync --dev...$(RESET)"
-	@uv sync --dev
-	@$(ECHO) "$(GREEN)Dependencies installed successfully.$(RESET)"
-	@$(ECHO) "$(YELLOW)Setting up pre-commit hooks...$(RESET)"
-	@uv run pre-commit install
-	@$(ECHO) "$(GREEN)Pre-commit hooks installed successfully.$(RESET)"
-	@$(ECHO) "$(GREEN)Build complete! Development environment is ready.$(RESET)"
-
-format:
-	@$(ECHO) "$(YELLOW)Formatting code with uv format...$(RESET)"
-	@uv run ruff format
-	@$(ECHO) "$(GREEN)Code formatted successfully.$(RESET)"
-
-lint:
-	@$(ECHO) "$(YELLOW)Linting code with ruff...$(RESET)"
-	@uv run ruff check --fix
-	@$(ECHO) "$(GREEN)Linting completed.$(RESET)"
-
-pre-commit:
-	@$(ECHO) "$(YELLOW)Run pre-commit...$(RESET)"
-	uv run pre-commit run --all-files
-	@$(ECHO) "$(GREEN)Pre-commit run successfully.$(RESET)"
-
-clean:
-	@$(ECHO) "$(YELLOW)Cleaning up cache files...$(RESET)"
-	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
-	@find . -type f -name "*.pyc" -delete 2>/dev/null || true
-	@rm -rf .pytest_cache .ruff_cache .mypy_cache 2>/dev/null || true
-	@$(ECHO) "$(GREEN)Cache files cleaned.$(RESET)"
-
-
-# Show help
-help:
-	@$(ECHO) "$(CYAN)OpenHands V1 Makefile$(RESET)"
-	@$(ECHO) ""
-	@$(ECHO) "$(UNDERLINE)Usage:$(RESET) make <COMMAND>"
-	@$(ECHO) ""
-	@$(ECHO) "$(UNDERLINE)Commands:$(RESET)"
-	@$(ECHO) "  $(GREEN)build$(RESET)                Setup development environment (install deps + hooks)"
-	@$(ECHO) "  $(GREEN)build-server$(RESET)         Build agent-server executable"
-	@$(ECHO) "  $(GREEN)test-server-schema$(RESET)   Test server schema"
-	@$(ECHO) "  $(GREEN)format$(RESET)               Format code with uv format"
-	@$(ECHO) "  $(GREEN)lint$(RESET)                 Lint code with ruff"
-	@$(ECHO) "  $(GREEN)pre-commit$(RESET)           Run the pre-commit"
-	@$(ECHO) "  $(GREEN)clean$(RESET)                Clean up cache files"
-	@$(ECHO) "  $(GREEN)help$(RESET)                 Show this help message"
-
-build-server: check-uv-version
-	@$(ECHO) "$(CYAN)Building agent-server executable...$(RESET)"
-	@uv run pyinstaller openhands-agent-server/openhands/agent_server/agent-server.spec
-	@$(ECHO) "$(GREEN)Build complete! Executable is in dist/agent-server/$(RESET)"
-
-test-server-schema: check-uv-version
-	set -euo pipefail;
-	# Generate OpenAPI JSON inline (no file left in repo)
-	uv run python -c 'import os,json; from openhands.agent_server.api import api; open("openapi.json","w").write(json.dumps(api.openapi(), indent=2))'
-	npx --yes @apidevtools/swagger-cli@^4 validate openapi.json
-	# Clean up temp schema
-	rm -f openapi.json
-	rm -rf .client
-
-
-.PHONY: set-package-version
-set-package-version: check-uv-version
-	@if [ -z "$(version)" ]; then \
-		$(ECHO) "$(RED)Error: missing version. Use: make set-package-version version=1.2.3$(RESET)"; \
+check-system:
+	@echo "$(YELLOW)Checking system...$(RESET)"
+	@if [ "$(shell uname)" = "Darwin" ]; then \
+		echo "$(BLUE)macOS detected.$(RESET)"; \
+	elif [ "$(shell uname)" = "Linux" ]; then \
+		if [ -f "/etc/manjaro-release" ]; then \
+			echo "$(BLUE)Manjaro Linux detected.$(RESET)"; \
+		else \
+			echo "$(BLUE)Linux detected.$(RESET)"; \
+		fi; \
+	elif [ "$$(uname -r | grep -i microsoft)" ]; then \
+		echo "$(BLUE)Windows Subsystem for Linux detected.$(RESET)"; \
+	else \
+		echo "$(RED)Unsupported system detected. Please use macOS, Linux, or Windows Subsystem for Linux (WSL).$(RESET)"; \
 		exit 1; \
 	fi
-	@$(ECHO) "$(CYAN)Setting version to $(version) for: $(PKGS)$(RESET)"
-	@for PKG in $(PKGS); do \
-		$(ECHO) "$(YELLOW)bumping $$PKG -> $(version)$(RESET)"; \
-		uv version --package $$PKG $(version); \
-	done
-	@$(ECHO) "$(GREEN)Version updated in all selected packages.$(RESET)"
+
+check-python:
+	@echo "$(YELLOW)Checking Python installation...$(RESET)"
+	@if command -v python$(PYTHON_VERSION) > /dev/null; then \
+		echo "$(BLUE)$(shell python$(PYTHON_VERSION) --version) is already installed.$(RESET)"; \
+	else \
+		echo "$(RED)Python $(PYTHON_VERSION) is not installed. Please install Python $(PYTHON_VERSION) to continue.$(RESET)"; \
+		exit 1; \
+	fi
+
+check-npm:
+	@echo "$(YELLOW)Checking npm installation...$(RESET)"
+	@if command -v npm > /dev/null; then \
+		echo "$(BLUE)npm $(shell npm --version) is already installed.$(RESET)"; \
+	else \
+		echo "$(RED)npm is not installed. Please install Node.js to continue.$(RESET)"; \
+		exit 1; \
+	fi
+
+check-nodejs:
+	@echo "$(YELLOW)Checking Node.js installation...$(RESET)"
+	@if command -v node > /dev/null; then \
+		NODE_VERSION=$(shell node --version | sed -E 's/v//g'); \
+		IFS='.' read -r -a NODE_VERSION_ARRAY <<< "$$NODE_VERSION"; \
+		if [ "$${NODE_VERSION_ARRAY[0]}" -gt 18 ] || ([ "$${NODE_VERSION_ARRAY[0]}" -eq 18 ] && [ "$${NODE_VERSION_ARRAY[1]}" -gt 17 ]) || ([ "$${NODE_VERSION_ARRAY[0]}" -eq 18 ] && [ "$${NODE_VERSION_ARRAY[1]}" -eq 17 ] && [ "$${NODE_VERSION_ARRAY[2]}" -ge 1 ]); then \
+			echo "$(BLUE)Node.js $$NODE_VERSION is already installed.$(RESET)"; \
+		else \
+			echo "$(RED)Node.js 18.17.1 or later is required. Please install Node.js 18.17.1 or later to continue.$(RESET)"; \
+			exit 1; \
+		fi; \
+	else \
+		echo "$(RED)Node.js is not installed. Please install Node.js to continue.$(RESET)"; \
+		exit 1; \
+	fi
+
+check-docker:
+	@echo "$(YELLOW)Checking Docker installation...$(RESET)"
+	@if command -v docker > /dev/null; then \
+		echo "$(BLUE)$(shell docker --version) is already installed.$(RESET)"; \
+	else \
+		echo "$(RED)Docker is not installed. Please install Docker to continue.$(RESET)"; \
+		exit 1; \
+	fi
+
+check-poetry:
+	@echo "$(YELLOW)Checking Poetry installation...$(RESET)"
+	@if command -v poetry > /dev/null; then \
+		POETRY_VERSION=$(shell poetry --version 2>&1 | sed -E 's/Poetry \(version ([0-9]+\.[0-9]+\.[0-9]+)\)/\1/'); \
+		IFS='.' read -r -a POETRY_VERSION_ARRAY <<< "$$POETRY_VERSION"; \
+		if [ $${POETRY_VERSION_ARRAY[0]} -ge 1 ] && [ $${POETRY_VERSION_ARRAY[1]} -ge 8 ]; then \
+			echo "$(BLUE)$(shell poetry --version) is already installed.$(RESET)"; \
+		else \
+			echo "$(RED)Poetry 1.8 or later is required. You can install poetry by running the following command, then adding Poetry to your PATH:"; \
+			echo "$(RED) curl -sSL https://install.python-poetry.org | python$(PYTHON_VERSION) -$(RESET)"; \
+			echo "$(RED)More detail here: https://python-poetry.org/docs/#installing-with-the-official-installer$(RESET)"; \
+			exit 1; \
+		fi; \
+	else \
+		echo "$(RED)Poetry is not installed. You can install poetry by running the following command, then adding Poetry to your PATH:"; \
+		echo "$(RED) curl -sSL https://install.python-poetry.org | python$(PYTHON_VERSION) -$(RESET)"; \
+		echo "$(RED)More detail here: https://python-poetry.org/docs/#installing-with-the-official-installer$(RESET)"; \
+		exit 1; \
+	fi
+
+install-python-dependencies:
+	@echo "$(GREEN)Installing Python dependencies...$(RESET)"
+	@if [ -z "${TZ}" ]; then \
+		echo "Defaulting TZ (timezone) to UTC"; \
+		export TZ="UTC"; \
+	fi
+	poetry env use python$(PYTHON_VERSION)
+	@if [ "$(shell uname)" = "Darwin" ]; then \
+		echo "$(BLUE)Installing chroma-hnswlib...$(RESET)"; \
+		export HNSWLIB_NO_NATIVE=1; \
+		poetry run pip install chroma-hnswlib; \
+	fi
+	@poetry install --without llama-index
+	@if [ -f "/etc/manjaro-release" ]; then \
+		echo "$(BLUE)Detected Manjaro Linux. Installing Playwright dependencies...$(RESET)"; \
+		poetry run pip install playwright; \
+		poetry run playwright install chromium; \
+	else \
+		if [ ! -f cache/playwright_chromium_is_installed.txt ]; then \
+			echo "Running playwright install --with-deps chromium..."; \
+			poetry run playwright install --with-deps chromium; \
+			mkdir -p cache; \
+			touch cache/playwright_chromium_is_installed.txt; \
+		else \
+			echo "Setup already done. Skipping playwright installation."; \
+		fi \
+	fi
+	@echo "$(GREEN)Python dependencies installed successfully.$(RESET)"
+
+install-frontend-dependencies:
+	@echo "$(YELLOW)Setting up frontend environment...$(RESET)"
+	@echo "$(YELLOW)Detect Node.js version...$(RESET)"
+	@cd frontend && node ./scripts/detect-node-version.js
+	echo "$(BLUE)Installing frontend dependencies with npm...$(RESET)"
+	@cd frontend && npm install
+	@echo "$(GREEN)Frontend dependencies installed successfully.$(RESET)"
+
+install-pre-commit-hooks:
+	@echo "$(YELLOW)Installing pre-commit hooks...$(RESET)"
+	@git config --unset-all core.hooksPath || true
+	@poetry run pre-commit install --config $(PRE_COMMIT_CONFIG_PATH)
+	@echo "$(GREEN)Pre-commit hooks installed successfully.$(RESET)"
+
+lint-backend:
+	@echo "$(YELLOW)Running linters...$(RESET)"
+	@poetry run pre-commit run --files openhands/**/* agenthub/**/* evaluation/**/* --show-diff-on-failure --config $(PRE_COMMIT_CONFIG_PATH)
+
+lint-frontend:
+	@echo "$(YELLOW)Running linters for frontend...$(RESET)"
+	@cd frontend && npm run lint
+
+lint:
+	@$(MAKE) -s lint-frontend
+	@$(MAKE) -s lint-backend
+
+test-frontend:
+	@echo "$(YELLOW)Running tests for frontend...$(RESET)"
+	@cd frontend && npm run test
+
+test:
+	@$(MAKE) -s test-frontend
+
+build-frontend:
+	@echo "$(YELLOW)Building frontend...$(RESET)"
+	@cd frontend && npm run build
+
+# Start backend
+start-backend:
+	@echo "$(YELLOW)Starting backend...$(RESET)"
+	@poetry run uvicorn openhands.server.listen:app --host $(BACKEND_HOST) --port $(BACKEND_PORT) --reload --reload-exclude "$(shell pwd)/workspace"
+
+# Start frontend
+start-frontend:
+	@echo "$(YELLOW)Starting frontend...$(RESET)"
+	@cd frontend && VITE_BACKEND_HOST=$(BACKEND_HOST_PORT) VITE_FRONTEND_PORT=$(FRONTEND_PORT) npm run dev -- --port $(FRONTEND_PORT) --host $(BACKEND_HOST)
+
+# Common setup for running the app (non-callable)
+_run_setup:
+	@if [ "$(OS)" = "Windows_NT" ]; then \
+		echo "$(RED) Windows is not supported, use WSL instead!$(RESET)"; \
+		exit 1; \
+	fi
+	@mkdir -p logs
+	@echo "$(YELLOW)Starting backend server...$(RESET)"
+	@poetry run uvicorn openhands.server.listen:app --host $(BACKEND_HOST) --port $(BACKEND_PORT) &
+	@echo "$(YELLOW)Waiting for the backend to start...$(RESET)"
+	@until nc -z localhost $(BACKEND_PORT); do sleep 0.1; done
+	@echo "$(GREEN)Backend started successfully.$(RESET)"
+
+# Run the app (standard mode)
+run:
+	@echo "$(YELLOW)Running the app...$(RESET)"
+	@$(MAKE) -s _run_setup
+	@$(MAKE) -s start-frontend
+	@echo "$(GREEN)Application started successfully.$(RESET)"
+
+# Run the app (in docker)
+docker-run: WORKSPACE_BASE ?= $(PWD)/workspace
+docker-run:
+	@if [ -f /.dockerenv ]; then \
+		echo "Running inside a Docker container. Exiting..."; \
+		exit 0; \
+	else \
+		echo "$(YELLOW)Running the app in Docker $(OPTIONS)...$(RESET)"; \
+		export WORKSPACE_BASE=${WORKSPACE_BASE}; \
+		export SANDBOX_USER_ID=$(shell id -u); \
+		export DATE=$(shell date +%Y%m%d%H%M%S); \
+		docker compose up $(OPTIONS); \
+	fi
+
+# Run the app (WSL mode)
+run-wsl:
+	@echo "$(YELLOW)Running the app in WSL mode...$(RESET)"
+	@$(MAKE) -s _run_setup
+	@cd frontend && echo "$(BLUE)Starting frontend with npm (WSL mode)...$(RESET)" && npm run dev_wsl -- --port $(FRONTEND_PORT)
+	@echo "$(GREEN)Application started successfully in WSL mode.$(RESET)"
+
+# Setup config.toml
+setup-config:
+	@echo "$(YELLOW)Setting up config.toml...$(RESET)"
+	@$(MAKE) setup-config-prompts
+	@mv $(CONFIG_FILE).tmp $(CONFIG_FILE)
+	@echo "$(GREEN)Config.toml setup completed.$(RESET)"
+
+setup-config-prompts:
+	@echo "[core]" > $(CONFIG_FILE).tmp
+
+	@read -p "Enter your workspace directory (as absolute path) [default: $(DEFAULT_WORKSPACE_DIR)]: " workspace_dir; \
+	 workspace_dir=$${workspace_dir:-$(DEFAULT_WORKSPACE_DIR)}; \
+	 echo "workspace_base=\"$$workspace_dir\"" >> $(CONFIG_FILE).tmp
+
+	@echo "" >> $(CONFIG_FILE).tmp
+
+	@echo "[llm]" >> $(CONFIG_FILE).tmp
+	@read -p "Enter your LLM model name, used for running without UI. Set the model in the UI after you start the app. (see https://docs.litellm.ai/docs/providers for full list) [default: $(DEFAULT_MODEL)]: " llm_model; \
+	 llm_model=$${llm_model:-$(DEFAULT_MODEL)}; \
+	 echo "model=\"$$llm_model\"" >> $(CONFIG_FILE).tmp
+
+	@read -p "Enter your LLM api key: " llm_api_key; \
+	 echo "api_key=\"$$llm_api_key\"" >> $(CONFIG_FILE).tmp
+
+	@read -p "Enter your LLM base URL [mostly used for local LLMs, leave blank if not needed - example: http://localhost:5001/v1/]: " llm_base_url; \
+	 if [[ ! -z "$$llm_base_url" ]]; then echo "base_url=\"$$llm_base_url\"" >> $(CONFIG_FILE).tmp; fi
+
+	@echo "Enter your LLM Embedding Model"; \
+		echo "Choices are:"; \
+		echo "  - openai"; \
+		echo "  - azureopenai"; \
+		echo "  - Embeddings available only with OllamaEmbedding:"; \
+		echo "    - llama2"; \
+		echo "    - mxbai-embed-large"; \
+		echo "    - nomic-embed-text"; \
+		echo "    - all-minilm"; \
+		echo "    - stable-code"; \
+		echo "    - bge-m3"; \
+		echo "    - bge-large"; \
+		echo "    - paraphrase-multilingual"; \
+		echo "    - snowflake-arctic-embed"; \
+		echo "  - Leave blank to default to 'BAAI/bge-small-en-v1.5' via huggingface"; \
+		read -p "> " llm_embedding_model; \
+		echo "embedding_model=\"$$llm_embedding_model\"" >> $(CONFIG_FILE).tmp; \
+		if [ "$$llm_embedding_model" = "llama2" ] || [ "$$llm_embedding_model" = "mxbai-embed-large" ] || [ "$$llm_embedding_model" = "nomic-embed-text" ] || [ "$$llm_embedding_model" = "all-minilm" ] || [ "$$llm_embedding_model" = "stable-code" ]; then \
+			read -p "Enter the local model URL for the embedding model (will set llm.embedding_base_url): " llm_embedding_base_url; \
+				echo "embedding_base_url=\"$$llm_embedding_base_url\"" >> $(CONFIG_FILE).tmp; \
+		elif [ "$$llm_embedding_model" = "azureopenai" ]; then \
+			read -p "Enter the Azure endpoint URL (will overwrite llm.base_url): " llm_base_url; \
+				echo "base_url=\"$$llm_base_url\"" >> $(CONFIG_FILE).tmp; \
+			read -p "Enter the Azure LLM Embedding Deployment Name: " llm_embedding_deployment_name; \
+				echo "embedding_deployment_name=\"$$llm_embedding_deployment_name\"" >> $(CONFIG_FILE).tmp; \
+			read -p "Enter the Azure API Version: " llm_api_version; \
+				echo "api_version=\"$$llm_api_version\"" >> $(CONFIG_FILE).tmp; \
+		fi
+
+
+# Develop in container
+docker-dev:
+	@if [ -f /.dockerenv ]; then \
+		echo "Running inside a Docker container. Exiting..."; \
+		exit 0; \
+	else \
+		echo "$(YELLOW)Build and run in Docker $(OPTIONS)...$(RESET)"; \
+		./containers/dev/dev.sh $(OPTIONS); \
+	fi
+
+# Clean up all caches
+clean:
+	@echo "$(YELLOW)Cleaning up caches...$(RESET)"
+	@rm -rf openhands/.cache
+	@echo "$(GREEN)Caches cleaned up successfully.$(RESET)"
+
+# Help
+help:
+	@echo "$(BLUE)Usage: make [target]$(RESET)"
+	@echo "Targets:"
+	@echo "  $(GREEN)build$(RESET)               - Build project, including environment setup and dependencies."
+	@echo "  $(GREEN)lint$(RESET)                - Run linters on the project."
+	@echo "  $(GREEN)setup-config$(RESET)        - Setup the configuration for OpenHands by providing LLM API key,"
+	@echo "                        LLM Model name, and workspace directory."
+	@echo "  $(GREEN)start-backend$(RESET)       - Start the backend server for the OpenHands project."
+	@echo "  $(GREEN)start-frontend$(RESET)      - Start the frontend server for the OpenHands project."
+	@echo "  $(GREEN)run$(RESET)                 - Run the OpenHands application, starting both backend and frontend servers."
+	@echo "                        Backend Log file will be stored in the 'logs' directory."
+	@echo "  $(GREEN)docker-dev$(RESET)          - Build and run the OpenHands application in Docker."
+	@echo "  $(GREEN)docker-run$(RESET)          - Run the OpenHands application, starting both backend and frontend servers in Docker."
+	@echo "  $(GREEN)help$(RESET)                - Display this help message, providing information on available targets."
+
+# Phony targets
+.PHONY: build check-dependencies check-python check-npm check-docker check-poetry install-python-dependencies install-frontend-dependencies install-pre-commit-hooks lint start-backend start-frontend run run-wsl setup-config setup-config-prompts help
+.PHONY: docker-dev docker-run

README.md

@@ -1,124 +1,130 @@
 <a name="readme-top"></a>
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/OpenHands/docs/main/openhands/static/img/logo.png" alt="Logo" width="200">
-  <h1 align="center">OpenHands Software Agent SDK </h1>
+  <img src="./docs/static/img/logo.png" alt="Logo" width="200">
+  <h1 align="center">OpenHands: Code Less, Make More</h1>
 </div>
 
 
 <div align="center">
-  <a href="https://github.com/OpenHands/software-agent-sdk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/OpenHands/software-agent-sdk?style=for-the-badge&color=blue" alt="MIT License"></a>
-  <a href="https://openhands.dev/joinslack"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="Join our Slack community"></a>
-  <br>
-  <a href="https://docs.openhands.dev/sdk"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Check out the documentation"></a>
-  <a href="https://arxiv.org/abs/2511.03690"><img src="https://img.shields.io/badge/Paper-000?logoColor=FFE165&logo=arxiv&style=for-the-badge" alt="Tech Report"></a>
-  <a href="https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=811504672#gid=811504672"><img src="https://img.shields.io/badge/SWEBench-77.6-000?logoColor=FFE165&style=for-the-badge" alt="Benchmark Score"></a>
-  <br>
-  <!-- Keep these links. Translations will automatically update with the README. -->
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=de">Deutsch</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=es">Español</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=fr">français</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=ja">日本語</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=ko">한국어</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=pt">Português</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=ru">Русский</a> |
-  <a href="https://www.readme-i18n.com/OpenHands/software-agent-sdk?lang=zh">中文</a>
-
+  <a href="https://github.com/All-Hands-AI/OpenHands/graphs/contributors"><img src="https://img.shields.io/github/contributors/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="Contributors"></a>
+  <a href="https://github.com/All-Hands-AI/OpenHands/stargazers"><img src="https://img.shields.io/github/stars/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="Stargazers"></a>
+  <a href="https://codecov.io/github/All-Hands-AI/OpenHands?branch=main"><img alt="CodeCov" src="https://img.shields.io/codecov/c/github/All-Hands-AI/OpenHands?style=for-the-badge&color=blue"></a>
+  <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/LICENSE"><img src="https://img.shields.io/github/license/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="MIT License"></a>
+  <br/>
+  <a href="https://join.slack.com/t/openhands-ai/shared_invite/zt-2tom0er4l-JeNUGHt_AxpEfIBstbLPiw"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="Join our Slack community"></a>
+  <a href="https://discord.gg/ESHStjSjD4"><img src="https://img.shields.io/badge/Discord-Join%20Us-purple?logo=discord&logoColor=white&style=for-the-badge" alt="Join our Discord community"></a>
+  <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/CREDITS.md"><img src="https://img.shields.io/badge/Project-Credits-blue?style=for-the-badge&color=FFE165&logo=github&logoColor=white" alt="Credits"></a>
+  <br/>
+  <a href="https://docs.all-hands.dev/modules/usage/getting-started"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Check out the documentation"></a>
+  <a href="https://arxiv.org/abs/2407.16741"><img src="https://img.shields.io/badge/Paper%20on%20Arxiv-000?logoColor=FFE165&logo=arxiv&style=for-the-badge" alt="Paper on Arxiv"></a>
+  <a href="https://huggingface.co/spaces/OpenHands/evaluation"><img src="https://img.shields.io/badge/Benchmark%20score-000?logoColor=FFE165&logo=huggingface&style=for-the-badge" alt="Evaluation Benchmark Score"></a>
   <hr>
 </div>
 
-The OpenHands Software Agent SDK is a set of Python and REST APIs for **building agents that work with code**.
+Welcome to OpenHands (formerly OpenDevin), a platform for software development agents powered by AI.
 
-You can use the OpenHands Software Agent SDK for:
-* One-off tasks, like building a README for your repo
-* Routine maintenance tasks, like updating dependencies
-* Major tasks that involve multiple agents, like refactors and rewrites
+OpenHands agents can do anything a human developer can: modify code, run commands, browse the web,
+call APIs, and yes—even copy code snippets from StackOverflow.
 
-Importantly, agents can either use the local machine as their workspace, or run inside ephemeral workspaces
-(e.g. in Docker or Kubernetes) using the Agent Server.
+Learn more at [docs.all-hands.dev](https://docs.all-hands.dev), or jump to the [Quick Start](#-quick-start).
 
-You can even use the SDK to build new developer experiences: it’s the engine behind the
-[OpenHands CLI](https://github.com/OpenHands/OpenHands-CLI) and [OpenHands Cloud](https://github.com/OpenHands/OpenHands).
+![App screenshot](./docs/static/img/screenshot.png)
 
-Get started with some [examples](https://docs.openhands.dev/sdk/guides/hello-world) or [check out the docs](https://docs.openhands.dev/sdk) to learn more.
+## ⚡ Quick Start
 
-## Quick Start
+The easiest way to run OpenHands is in Docker.
+See the [Installation](https://docs.all-hands.dev/modules/usage/installation) guide for
+system requirements and more information.
 
-Here's what building with the SDK looks like:
+```bash
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.13-nikolaik
 
-```python
-import os
-
-from openhands.sdk import LLM, Agent, Conversation, Tool
-from openhands.tools.file_editor import FileEditorTool
-from openhands.tools.task_tracker import TaskTrackerTool
-from openhands.tools.terminal import TerminalTool
-
-
-llm = LLM(
-    model="anthropic/claude-sonnet-4-5-20250929",
-    api_key=os.getenv("LLM_API_KEY"),
-)
-
-agent = Agent(
-    llm=llm,
-    tools=[
-        Tool(name=TerminalTool.name),
-        Tool(name=FileEditorTool.name),
-        Tool(name=TaskTrackerTool.name),
-    ],
-)
-
-cwd = os.getcwd()
-conversation = Conversation(agent=agent, workspace=cwd)
-
-conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
-conversation.run()
-print("All done!")
+docker run -it --pull=always \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.13-nikolaik \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -p 3000:3000 \
+    -e LOG_ALL_EVENTS=true \
+    --add-host host.docker.internal:host-gateway \
+    --name openhands-app \
+    docker.all-hands.dev/all-hands-ai/openhands:0.13
 ```
 
-For installation instructions and detailed setup, see the [Getting Started Guide](https://docs.openhands.dev/sdk/getting-started).
+You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)!
 
-## Documentation
+Finally, you'll need a model provider and API key.
+[Anthropic's Claude 3.5 Sonnet](https://www.anthropic.com/api) (`anthropic/claude-3-5-sonnet-20241022`)
+works best, but you have [many options](https://docs.all-hands.dev/modules/usage/llms).
 
-For detailed documentation, tutorials, and API reference, visit:
+---
 
-**[https://docs.openhands.dev/sdk](https://docs.openhands.dev/sdk)**
+You can also [connect OpenHands to your local filesystem](https://docs.all-hands.dev/modules/usage/runtimes),
+run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/modules/usage/how-to/headless-mode),
+interact with it via a [friendly CLI](https://docs.all-hands.dev/modules/usage/how-to/cli-mode),
+or run it on tagged issues with [a github action](https://github.com/All-Hands-AI/OpenHands-resolver).
 
-The documentation includes:
-- [Getting Started Guide](https://docs.openhands.dev/sdk/getting-started) - Installation and setup
-- [Architecture & Core Concepts](https://docs.openhands.dev/sdk/arch/overview) - Agents, tools, workspaces, and more
-- [Guides](https://docs.openhands.dev/sdk/guides/hello-world) - Hello World, custom tools, MCP, skills, and more
-- [API Reference](https://docs.openhands.dev/sdk/guides/agent-server/api-reference/server-details/alive) - Agent Server REST API documentation
+Visit [Installation](https://docs.all-hands.dev/modules/usage/installation) for more information and setup instructions.
 
-## Examples
+If you want to modify the OpenHands source code, check out [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
 
-The `examples/` directory contains comprehensive usage examples:
+Having issues? The [Troubleshooting Guide](https://docs.all-hands.dev/modules/usage/troubleshooting) can help.
 
-- **Standalone SDK** (`examples/01_standalone_sdk/`) - Basic agent usage, custom tools, and microagents
-- **Remote Agent Server** (`examples/02_remote_agent_server/`) - Client-server architecture and WebSocket connections
-- **GitHub Workflows** (`examples/03_github_workflows/`) - CI/CD integration and automated workflows
+## 📖 Documentation
 
-## Contributing
+To learn more about the project, and for tips on using OpenHands,
+**check out our [documentation](https://docs.all-hands.dev/modules/usage/getting-started)**.
 
-For development setup, testing, and contribution guidelines, see [DEVELOPMENT.md](DEVELOPMENT.md).
+There you'll find resources on how to use different LLM providers,
+troubleshooting resources, and advanced configuration options.
 
-## Community
+## 🤝 How to Contribute
 
-- [Join Slack](https://openhands.dev/joinslack) - Connect with the OpenHands community
-- [GitHub Repository](https://github.com/OpenHands/software-agent-sdk) - Source code and issues
-- [Documentation](https://docs.openhands.dev/sdk) - Complete documentation
+OpenHands is a community-driven project, and we welcome contributions from everyone.
+Whether you're a developer, a researcher, or simply enthusiastic about advancing the field of
+software engineering with AI, there are many ways to get involved:
 
-## Cite
+- **Code Contributions:** Help us develop new agents, core functionality, the frontend and other interfaces, or sandboxing solutions.
+- **Research and Evaluation:** Contribute to our understanding of LLMs in software engineering, participate in evaluating the models, or suggest improvements.
+- **Feedback and Testing:** Use the OpenHands toolset, report bugs, suggest features, or provide feedback on usability.
+
+For details, please check [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## 🤖 Join Our Community
+
+Whether you're a developer, a researcher, or simply enthusiastic about OpenHands, we'd love to have you in our community.
+Let's make software engineering better together!
+
+- [Slack workspace](https://join.slack.com/t/openhands-ai/shared_invite/zt-2tom0er4l-JeNUGHt_AxpEfIBstbLPiw) - Here we talk about research, architecture, and future development.
+- [Discord server](https://discord.gg/ESHStjSjD4) - This is a community-run server for general discussion, questions, and feedback.
+
+## 📈 Progress
+
+<p align="center">
+  <a href="https://star-history.com/#All-Hands-AI/OpenHands&Date">
+    <img src="https://api.star-history.com/svg?repos=All-Hands-AI/OpenHands&type=Date" width="500" alt="Star History Chart">
+  </a>
+</p>
+
+## 📜 License
+
+Distributed under the MIT License. See [`LICENSE`](./LICENSE) for more information.
+
+## 🙏 Acknowledgements
+
+OpenHands is built by a large number of contributors, and every contribution is greatly appreciated! We also build upon other open source projects, and we are deeply thankful for their work.
+
+For a list of open source projects and licenses used in OpenHands, please see our [CREDITS.md](./CREDITS.md) file.
+
+## 📚 Cite
 
 ```
-@misc{wang2025openhandssoftwareagentsdk,
-      title={The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents}, 
-      author={Xingyao Wang and Simon Rosenberg and Juan Michelini and Calvin Smith and Hoang Tran and Engel Nyst and Rohit Malhotra and Xuhui Zhou and Valerie Chen and Robert Brennan and Graham Neubig},
-      year={2025},
-      eprint={2511.03690},
+@misc{openhands,
+      title={{OpenHands: An Open Platform for AI Software Developers as Generalist Agents}},
+      author={Xingyao Wang and Boxuan Li and Yufan Song and Frank F. Xu and Xiangru Tang and Mingchen Zhuge and Jiayi Pan and Yueqi Song and Bowen Li and Jaskirat Singh and Hoang H. Tran and Fuqiang Li and Ren Ma and Mingzhang Zheng and Bill Qian and Yanjun Shao and Niklas Muennighoff and Yizhe Zhang and Binyuan Hui and Junyang Lin and Robert Brennan and Hao Peng and Heng Ji and Graham Neubig},
+      year={2024},
+      eprint={2407.16741},
       archivePrefix={arXiv},
       primaryClass={cs.SE},
-      url={https://arxiv.org/abs/2511.03690}, 
+      url={https://arxiv.org/abs/2407.16741},
 }
 ```

build.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+cp pyproject.toml poetry.lock openhands
+poetry build -v

compose.yml

@@ -0,0 +1,22 @@
+#
+services:
+  openhands:
+    build:
+      context: ./
+      dockerfile: ./containers/app/Dockerfile
+    image: openhands:latest
+    container_name: openhands-app-${DATE:-}
+    environment:
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-ghcr.io/all-hands-ai/runtime:0.13-nikolaik}
+      - SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234}
+      - WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
+    ports:
+      - "3000:3000"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${WORKSPACE_BASE:-$PWD/workspace}:/opt/workspace_base
+    pull_policy: build
+    stdin_open: true
+    tty: true

config.template.toml

@@ -0,0 +1,249 @@
+###################### OpenHands Configuration Example ######################
+#
+# All settings have default values, so you only need to uncomment and
+# modify what you want to change
+# The fields within each section are sorted in alphabetical order.
+#
+##############################################################################
+
+#################################### Core ####################################
+# General core configurations
+##############################################################################
+[core]
+# API key for E2B
+#e2b_api_key = ""
+
+# API key for Modal
+#modal_api_token_id = ""
+#modal_api_token_secret = ""
+
+# Base path for the workspace
+workspace_base = "./workspace"
+
+# Cache directory path
+#cache_dir = "/tmp/cache"
+
+# Debugging enabled
+#debug = false
+
+# Disable color in terminal output
+#disable_color = false
+
+# Enable saving and restoring the session when run from CLI
+#enable_cli_session = false
+
+# Path to store trajectories, can be a folder or a file
+# If it's a folder, the session id will be used as the file name
+#trajectories_path="./trajectories"
+
+# File store path
+#file_store_path = "/tmp/file_store"
+
+# File store type
+#file_store = "memory"
+
+# List of allowed file extensions for uploads
+#file_uploads_allowed_extensions = [".*"]
+
+# Maximum file size for uploads, in megabytes
+#file_uploads_max_file_size_mb = 0
+
+# Maximum budget per task, 0.0 means no limit
+#max_budget_per_task = 0.0
+
+# Maximum number of iterations
+#max_iterations = 100
+
+# Path to mount the workspace in the sandbox
+#workspace_mount_path_in_sandbox = "/workspace"
+
+# Path to mount the workspace
+#workspace_mount_path = ""
+
+# Path to rewrite the workspace mount path to
+#workspace_mount_rewrite = ""
+
+# Run as openhands
+#run_as_openhands = true
+
+# Runtime environment
+#runtime = "eventstream"
+
+# Name of the default agent
+#default_agent = "CodeActAgent"
+
+# JWT secret for authentication
+#jwt_secret = ""
+
+# Restrict file types for file uploads
+#file_uploads_restrict_file_types = false
+
+# List of allowed file extensions for uploads
+#file_uploads_allowed_extensions = [".*"]
+
+#################################### LLM #####################################
+# Configuration for LLM models (group name starts with 'llm')
+# use 'llm' for the default LLM config
+##############################################################################
+[llm]
+# AWS access key ID
+#aws_access_key_id = ""
+
+# AWS region name
+#aws_region_name = ""
+
+# AWS secret access key
+#aws_secret_access_key = ""
+
+# API key to use
+api_key = "your-api-key"
+
+# API base URL
+#base_url = ""
+
+# API version
+#api_version = ""
+
+# Cost per input token
+#input_cost_per_token = 0.0
+
+# Cost per output token
+#output_cost_per_token = 0.0
+
+# Custom LLM provider
+#custom_llm_provider = ""
+
+# Embedding API base URL
+#embedding_base_url = ""
+
+# Embedding deployment name
+#embedding_deployment_name = ""
+
+# Embedding model to use
+embedding_model = "local"
+
+# Maximum number of characters in an observation's content
+#max_message_chars = 10000
+
+# Maximum number of input tokens
+#max_input_tokens = 0
+
+# Maximum number of output tokens
+#max_output_tokens = 0
+
+# Model to use
+model = "gpt-4o"
+
+# Number of retries to attempt when an operation fails with the LLM.
+# Increase this value to allow more attempts before giving up
+#num_retries = 8
+
+# Maximum wait time (in seconds) between retry attempts
+# This caps the exponential backoff to prevent excessively long
+#retry_max_wait = 120
+
+# Minimum wait time (in seconds) between retry attempts
+# This sets the initial delay before the first retry
+#retry_min_wait = 15
+
+# Multiplier for exponential backoff calculation
+# The wait time increases by this factor after each failed attempt
+# A value of 2.0 means each retry waits twice as long as the previous one
+#retry_multiplier = 2.0
+
+# Drop any unmapped (unsupported) params without causing an exception
+#drop_params = false
+
+# Using the prompt caching feature if provided by the LLM and supported
+#caching_prompt = true
+
+# Base URL for the OLLAMA API
+#ollama_base_url = ""
+
+# Temperature for the API
+#temperature = 0.0
+
+# Timeout for the API
+#timeout = 0
+
+# Top p for the API
+#top_p = 1.0
+
+# If model is vision capable, this option allows to disable image processing (useful for cost reduction).
+#disable_vision = true
+
+[llm.gpt4o-mini]
+api_key = "your-api-key"
+model = "gpt-4o"
+
+
+#################################### Agent ###################################
+# Configuration for agents (group name starts with 'agent')
+# Use 'agent' for the default agent config
+# otherwise, group name must be `agent.<agent_name>` (case-sensitive), e.g.
+# agent.CodeActAgent
+##############################################################################
+[agent]
+# Name of the micro agent to use for this agent
+#micro_agent_name = ""
+
+# Memory enabled
+#memory_enabled = false
+
+# Memory maximum threads
+#memory_max_threads = 3
+
+# LLM config group to use
+#llm_config = 'your-llm-config-group'
+
+[agent.RepoExplorerAgent]
+# Example: use a cheaper model for RepoExplorerAgent to reduce cost, especially
+# useful when an agent doesn't demand high quality but uses a lot of tokens
+llm_config = 'gpt3'
+
+#################################### Sandbox ###################################
+# Configuration for the sandbox
+##############################################################################
+[sandbox]
+# Sandbox timeout in seconds
+#timeout = 120
+
+# Sandbox user ID
+#user_id = 1000
+
+# Container image to use for the sandbox
+#base_container_image = "nikolaik/python-nodejs:python3.12-nodejs22"
+
+# Use host network
+#use_host_network = false
+
+# Enable auto linting after editing
+#enable_auto_lint = false
+
+# Whether to initialize plugins
+#initialize_plugins = true
+
+# Extra dependencies to install in the runtime image
+#runtime_extra_deps = ""
+
+# Environment variables to set at the launch of the runtime
+#runtime_startup_env_vars = {}
+
+# BrowserGym environment to use for evaluation
+#browsergym_eval_env = ""
+
+#################################### Security ###################################
+# Configuration for security features
+##############################################################################
+[security]
+
+# Enable confirmation mode
+#confirmation_mode = false
+
+# The security analyzer to use
+#security_analyzer = ""
+
+#################################### Eval ####################################
+# Configuration for the evaluation, please refer to the specific evaluation
+# plugin for the available options
+##############################################################################

containers/README.md

@@ -0,0 +1,12 @@
+# Docker Containers
+
+Each folder here contains a Dockerfile, and a config.sh describing how to build
+the images and where to push them. These images are built and pushed in GitHub Actions
+by the `ghcr.yml` workflow.
+
+## Building Manually
+
+```bash
+docker build -f containers/app/Dockerfile -t openhands .
+docker build -f containers/sandbox/Dockerfile -t sandbox .
+```

containers/app/Dockerfile

@@ -0,0 +1,94 @@
+ARG OPENHANDS_BUILD_VERSION=dev
+FROM node:21.7.2-bookworm-slim AS frontend-builder
+
+WORKDIR /app
+
+COPY ./frontend/package.json frontend/package-lock.json ./
+RUN npm install -g npm@10.5.1
+RUN npm ci
+
+COPY ./frontend ./
+RUN npm run build
+
+FROM python:3.12.3-slim AS backend-builder
+
+WORKDIR /app
+ENV PYTHONPATH='/app'
+
+ENV POETRY_NO_INTERACTION=1 \
+    POETRY_VIRTUALENVS_IN_PROJECT=1 \
+    POETRY_VIRTUALENVS_CREATE=1 \
+    POETRY_CACHE_DIR=/tmp/poetry_cache
+
+RUN apt-get update -y \
+    && apt-get install -y curl make git build-essential \
+    && python3 -m pip install poetry==1.8.2  --break-system-packages
+
+COPY ./pyproject.toml ./poetry.lock ./
+RUN touch README.md
+RUN export POETRY_CACHE_DIR && poetry install --without evaluation,llama-index --no-root && rm -rf $POETRY_CACHE_DIR
+
+FROM python:3.12.3-slim AS openhands-app
+
+WORKDIR /app
+
+ARG OPENHANDS_BUILD_VERSION #re-declare for this section
+
+ENV RUN_AS_OPENHANDS=true
+# A random number--we need this to be different from the user's UID on the host machine
+ENV OPENHANDS_USER_ID=42420
+ENV SANDBOX_LOCAL_RUNTIME_URL=http://host.docker.internal
+ENV USE_HOST_NETWORK=false
+ENV WORKSPACE_BASE=/opt/workspace_base
+ENV OPENHANDS_BUILD_VERSION=$OPENHANDS_BUILD_VERSION
+ENV SANDBOX_USER_ID=0
+RUN mkdir -p $WORKSPACE_BASE
+
+RUN apt-get update -y \
+    && apt-get install -y curl ssh sudo
+
+# Default is 1000, but OSX is often 501
+RUN sed -i 's/^UID_MIN.*/UID_MIN 499/' /etc/login.defs
+# Default is 60000, but we've seen up to 200000
+RUN sed -i 's/^UID_MAX.*/UID_MAX 1000000/' /etc/login.defs
+
+RUN groupadd app
+RUN useradd -l -m -u $OPENHANDS_USER_ID -s /bin/bash openhands && \
+    usermod -aG app openhands && \
+    usermod -aG sudo openhands && \
+    echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+RUN chown -R openhands:app /app && chmod -R 770 /app
+RUN sudo chown -R openhands:app $WORKSPACE_BASE && sudo chmod -R 770 $WORKSPACE_BASE
+USER openhands
+
+ENV VIRTUAL_ENV=/app/.venv \
+    PATH="/app/.venv/bin:$PATH" \
+    PYTHONPATH='/app'
+
+COPY --chown=openhands:app --chmod=770 --from=backend-builder ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+RUN playwright install --with-deps chromium
+
+COPY --chown=openhands:app --chmod=770 ./openhands ./openhands
+COPY --chown=openhands:app --chmod=777 ./openhands/runtime/plugins ./openhands/runtime/plugins
+COPY --chown=openhands:app --chmod=770 ./openhands/agenthub ./openhands/agenthub
+COPY --chown=openhands:app ./pyproject.toml ./pyproject.toml
+COPY --chown=openhands:app ./poetry.lock ./poetry.lock
+COPY --chown=openhands:app ./README.md ./README.md
+COPY --chown=openhands:app ./MANIFEST.in ./MANIFEST.in
+COPY --chown=openhands:app ./LICENSE ./LICENSE
+
+# This is run as "openhands" user, and will create __pycache__ with openhands:openhands ownership
+RUN python openhands/core/download.py # No-op to download assets
+# Add this line to set group ownership of all files/directories not already in "app" group
+# openhands:openhands -> openhands:app
+RUN find /app \! -group app -exec chgrp app {} +
+
+COPY --chown=openhands:app --chmod=770 --from=frontend-builder /app/build ./frontend/build
+COPY --chown=openhands:app --chmod=770 ./containers/app/entrypoint.sh /app/entrypoint.sh
+
+USER root
+
+WORKDIR /app
+
+ENTRYPOINT ["/app/entrypoint.sh"]
+CMD ["uvicorn", "openhands.server.listen:app", "--host", "0.0.0.0", "--port", "3000"]

containers/app/config.sh

@@ -0,0 +1,4 @@
+DOCKER_REGISTRY=ghcr.io
+DOCKER_ORG=all-hands-ai
+DOCKER_IMAGE=openhands
+DOCKER_BASE_DIR="."

containers/app/entrypoint.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+set -eo pipefail
+
+echo "Starting OpenHands..."
+if [[ $NO_SETUP == "true" ]]; then
+  echo "Skipping setup, running as $(whoami)"
+  "$@"
+  exit 0
+fi
+
+if [ "$(id -u)" -ne 0 ]; then
+  echo "The OpenHands entrypoint.sh must run as root"
+  exit 1
+fi
+
+if [ -z "$SANDBOX_USER_ID" ]; then
+  echo "SANDBOX_USER_ID is not set"
+  exit 1
+fi
+
+if [ -z "$WORKSPACE_MOUNT_PATH" ]; then
+  # This is set to /opt/workspace in the Dockerfile. But if the user isn't mounting, we want to unset it so that OpenHands doesn't mount at all
+  unset WORKSPACE_BASE
+fi
+
+if [[ "$SANDBOX_USER_ID" -eq 0 ]]; then
+  echo "Running OpenHands as root"
+  export RUN_AS_OPENHANDS=false
+  mkdir -p /root/.cache/ms-playwright/
+  if [ -d "/home/openhands/.cache/ms-playwright/" ]; then
+    mv /home/openhands/.cache/ms-playwright/ /root/.cache/
+  fi
+  "$@"
+else
+  echo "Setting up enduser with id $SANDBOX_USER_ID"
+  if id "enduser" &>/dev/null; then
+    echo "User enduser already exists. Skipping creation."
+  else
+    if ! useradd -l -m -u $SANDBOX_USER_ID -s /bin/bash enduser; then
+      echo "Failed to create user enduser with id $SANDBOX_USER_ID. Moving openhands user."
+      incremented_id=$(($SANDBOX_USER_ID + 1))
+      usermod -u $incremented_id openhands
+      if ! useradd -l -m -u $SANDBOX_USER_ID -s /bin/bash enduser; then
+        echo "Failed to create user enduser with id $SANDBOX_USER_ID for a second time. Exiting."
+        exit 1
+      fi
+    fi
+  fi
+  usermod -aG app enduser
+  # get the user group of /var/run/docker.sock and set openhands to that group
+  DOCKER_SOCKET_GID=$(stat -c '%g' /var/run/docker.sock)
+  echo "Docker socket group id: $DOCKER_SOCKET_GID"
+  if getent group $DOCKER_SOCKET_GID; then
+    echo "Group with id $DOCKER_SOCKET_GID already exists"
+  else
+    echo "Creating group with id $DOCKER_SOCKET_GID"
+    groupadd -g $DOCKER_SOCKET_GID docker
+  fi
+
+  mkdir -p /home/enduser/.cache/huggingface/hub/
+  mkdir -p /home/enduser/.cache/ms-playwright/
+  if [ -d "/home/openhands/.cache/ms-playwright/" ]; then
+    mv /home/openhands/.cache/ms-playwright/ /home/enduser/.cache/
+  fi
+
+  usermod -aG $DOCKER_SOCKET_GID enduser
+  echo "Running as enduser"
+  su enduser /bin/bash -c "${*@Q}" # This magically runs any arguments passed to the script as a command
+fi

containers/build.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+set -eo pipefail
+
+# Initialize variables with default values
+image_name=""
+org_name=""
+push=0
+load=0
+tag_suffix=""
+
+# Function to display usage information
+usage() {
+    echo "Usage: $0 -i <image_name> [-o <org_name>] [--push] [--load] [-t <tag_suffix>]"
+    echo "  -i: Image name (required)"
+    echo "  -o: Organization name"
+    echo "  --push: Push the image"
+    echo "  --load: Load the image"
+    echo "  -t: Tag suffix"
+    exit 1
+}
+
+# Parse command-line options
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -i) image_name="$2"; shift 2 ;;
+        -o) org_name="$2"; shift 2 ;;
+        --push) push=1; shift ;;
+        --load) load=1; shift ;;
+        -t) tag_suffix="$2"; shift 2 ;;
+        *) usage ;;
+    esac
+done
+# Check if required arguments are provided
+if [[ -z "$image_name" ]]; then
+    echo "Error: Image name is required."
+    usage
+fi
+
+echo "Building: $image_name"
+tags=()
+
+OPENHANDS_BUILD_VERSION="dev"
+
+cache_tag_base="buildcache"
+cache_tag="$cache_tag_base"
+
+if [[ -n $RELEVANT_SHA ]]; then
+  git_hash=$(git rev-parse --short "$RELEVANT_SHA")
+  tags+=("$git_hash")
+  tags+=("$RELEVANT_SHA")
+fi
+
+if [[ -n $GITHUB_REF_NAME ]]; then
+  # check if ref name is a version number
+  if [[ $GITHUB_REF_NAME =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    major_version=$(echo "$GITHUB_REF_NAME" | cut -d. -f1)
+    minor_version=$(echo "$GITHUB_REF_NAME" | cut -d. -f1,2)
+    tags+=("$major_version" "$minor_version")
+    tags+=("latest")
+  fi
+  sanitized_ref_name=$(echo "$GITHUB_REF_NAME" | sed 's/[^a-zA-Z0-9.-]\+/-/g')
+  OPENHANDS_BUILD_VERSION=$sanitized_ref_name
+  sanitized_ref_name=$(echo "$sanitized_ref_name" | tr '[:upper:]' '[:lower:]') # lower case is required in tagging
+  tags+=("$sanitized_ref_name")
+  cache_tag+="-${sanitized_ref_name}"
+fi
+
+if [[ -n $tag_suffix ]]; then
+  cache_tag+="-${tag_suffix}"
+  for i in "${!tags[@]}"; do
+    tags[$i]="${tags[$i]}-$tag_suffix"
+  done
+fi
+
+echo "Tags: ${tags[@]}"
+
+if [[ "$image_name" == "openhands" ]]; then
+  dir="./containers/app"
+elif [[ "$image_name" == "runtime" ]]; then
+  dir="./containers/runtime"
+else
+  dir="./containers/$image_name"
+fi
+
+if [[ (! -f "$dir/Dockerfile") && "$image_name" != "runtime" ]]; then
+  # Allow runtime to be built without a Dockerfile
+  echo "No Dockerfile found"
+  exit 1
+fi
+if [[ ! -f "$dir/config.sh" ]]; then
+  echo "No config.sh found for Dockerfile"
+  exit 1
+fi
+
+source "$dir/config.sh"
+
+if [[ -n "$org_name" ]]; then
+  DOCKER_ORG="$org_name"
+fi
+
+# If $DOCKER_IMAGE_SOURCE_TAG is set, add it to the tags
+if [[ -n "$DOCKER_IMAGE_SOURCE_TAG" ]]; then
+  tags+=("$DOCKER_IMAGE_SOURCE_TAG")
+fi
+# If $DOCKER_IMAGE_TAG is set, add it to the tags
+if [[ -n "$DOCKER_IMAGE_TAG" ]]; then
+  tags+=("$DOCKER_IMAGE_TAG")
+fi
+
+DOCKER_REPOSITORY="$DOCKER_REGISTRY/$DOCKER_ORG/$DOCKER_IMAGE"
+DOCKER_REPOSITORY=${DOCKER_REPOSITORY,,} # lowercase
+echo "Repo: $DOCKER_REPOSITORY"
+echo "Base dir: $DOCKER_BASE_DIR"
+
+args=""
+for tag in "${tags[@]}"; do
+  args+=" -t $DOCKER_REPOSITORY:$tag"
+done
+
+if [[ $push -eq 1 ]]; then
+  args+=" --push"
+  args+=" --cache-to=type=registry,ref=$DOCKER_REPOSITORY:$cache_tag,mode=max"
+fi
+
+if [[ $load -eq 1 ]]; then
+  args+=" --load"
+fi
+
+echo "Args: $args"
+
+# Modify the platform selection based on --load flag
+if [[ $load -eq 1 ]]; then
+  # When loading, build only for the current platform
+  platform=$(docker version -f '{{.Server.Os}}/{{.Server.Arch}}')
+else
+  # For push or without load, build for multiple platforms
+  platform="linux/amd64,linux/arm64"
+fi
+
+echo "Building for platform(s): $platform"
+
+docker buildx build \
+  $args \
+  --build-arg OPENHANDS_BUILD_VERSION="$OPENHANDS_BUILD_VERSION" \
+  --cache-from=type=registry,ref=$DOCKER_REPOSITORY:$cache_tag \
+  --cache-from=type=registry,ref=$DOCKER_REPOSITORY:$cache_tag_base-main \
+  --platform $platform \
+  --provenance=false \
+  -f "$dir/Dockerfile" \
+  "$DOCKER_BASE_DIR"
+
+# If load was requested, print the loaded images
+if [[ $load -eq 1 ]]; then
+  echo "Local images built:"
+  docker images "$DOCKER_REPOSITORY" --format "{{.Repository}}:{{.Tag}}"
+fi

containers/dev/Dockerfile

@@ -0,0 +1,124 @@
+# syntax=docker/dockerfile:1
+
+###
+FROM ubuntu:22.04 AS dind
+
+# https://docs.docker.com/engine/install/ubuntu/
+RUN apt-get update && apt-get install -y \
+	ca-certificates \
+	curl \
+	&& install -m 0755 -d /etc/apt/keyrings \
+	&& curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc \
+	&& chmod a+r /etc/apt/keyrings/docker.asc \
+	&& echo \
+		"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
+		$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+RUN apt-get update && apt-get install -y \
+	docker-ce \
+	docker-ce-cli \
+	containerd.io \
+	docker-buildx-plugin \
+	docker-compose-plugin \
+	&& rm -rf /var/lib/apt/lists/* \
+	&& apt-get clean \
+	&& apt-get autoremove -y
+
+###
+FROM dind AS openhands
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+#
+RUN apt-get update && apt-get install -y \
+	bash \
+    build-essential \
+    curl \
+	git \
+	git-lfs \
+	software-properties-common \
+	make \
+    netcat \
+    sudo \
+	wget \
+	&& rm -rf /var/lib/apt/lists/* \
+	&& apt-get clean \
+	&& apt-get autoremove -y
+
+# https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+	&& chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
+	&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+	&& apt-get update && apt-get -y install \
+    gh \
+  && rm -rf /var/lib/apt/lists/* \
+  && apt-get clean \
+  && apt-get autoremove -y
+
+# Python 3.12
+RUN add-apt-repository ppa:deadsnakes/ppa \
+    && apt-get update \
+    && apt-get install -y python3.12 python3.12-venv python3.12-dev python3-pip \
+    && ln -s /usr/bin/python3.12 /usr/bin/python
+
+# NodeJS >= 18.17.1
+RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs
+
+# Poetry >= 1.8
+RUN curl -fsSL https://install.python-poetry.org | python3.12 - \
+    && ln -s ~/.local/bin/poetry /usr/local/bin/poetry
+
+#
+RUN <<EOF
+#!/bin/bash
+printf "#!/bin/bash
+set +x
+uname -a
+docker --version
+gh --version | head -n 1
+git --version
+#
+python --version
+echo node `node --version`
+echo npm `npm --version`
+poetry --version
+netcat -h 2>&1 | head -n 1
+" > /version.sh
+chmod a+x /version.sh
+EOF
+
+###
+FROM openhands AS dev
+
+RUN apt-get update && apt-get install -y \
+	dnsutils \
+	file \
+	iproute2 \
+	jq \
+	lsof \
+	ripgrep \
+	silversearcher-ag \
+	vim \
+	&& rm -rf /var/lib/apt/lists/* \
+	&& apt-get clean \
+	&& apt-get autoremove -y
+
+WORKDIR /app
+
+# cache build dependencies
+RUN \
+  --mount=type=bind,source=./,target=/app/ \
+  <<EOF
+#!/bin/bash
+make -s clean
+make -s check-dependencies
+make -s install-python-dependencies
+
+# NOTE
+# node_modules are .dockerignore-d therefore not mountable
+# make -s install-frontend-dependencies
+EOF
+
+#
+CMD ["bash"]

containers/dev/README.md

@@ -0,0 +1,54 @@
+# Develop in Docker
+
+Install [Docker](https://docs.docker.com/engine/install/) on your host machine and run:
+
+```bash
+make docker-dev
+# same as:
+cd ./containers/dev
+./dev.sh
+```
+
+It could take some time if you are running for the first time as Docker will pull all the  tools required for building OpenHands. The next time you run again, it should be instant.
+
+## Build and run
+
+If everything goes well, you should be inside a container after Docker finishes building the `openhands:dev` image similar to the following:
+
+```bash
+Build and run in Docker ...
+root@93fc0005fcd2:/app#
+```
+
+You may now proceed with the normal [build and run](../../Development.md) workflow as if you were on the host.
+
+## Make changes
+
+The source code on the host is mounted as `/app` inside docker. You may edit the files as usual either inside the Docker container or on your host with your favorite IDE/editors.
+
+The following are also mapped as readonly from your host:
+
+```yaml
+# host credentials
+- $HOME/.git-credentials:/root/.git-credentials:ro
+- $HOME/.gitconfig:/root/.gitconfig:ro
+- $HOME/.npmrc:/root/.npmrc:ro
+```
+
+## VSCode
+
+Alternatively, if you use VSCode, you could also [attach to the running container](https://code.visualstudio.com/docs/devcontainers/attach-container).
+
+See details for [developing in docker](https://code.visualstudio.com/docs/devcontainers/containers) or simply ask `OpenHands` ;-)
+
+## Rebuild dev image
+
+You could optionally pass additional options to the build script.
+
+```bash
+make docker-dev OPTIONS="--build"
+# or
+./containers/dev/dev.sh --build
+```
+
+See [docker compose run](https://docs.docker.com/reference/cli/docker/compose/run/) for more options.