/migrate-osworld-agent

name: migrate-osworld-agent
description: "Migrate an agent from upstream OSWorld into this OSWorld-V2 repository, add matching evaluation entrypoints, and verify the integration."

Migrate OSWorld Agent

Use this when adding an upstream OSWorld agent to this repo.

Workflow

1. Read the upstream agent. 2. Read local patterns before editing:

• use `scripts/python/run_multienv_claude.py` as the main runner reference
• use `scripts/bash/run_multienv_claude.sh` as the shell entrypoint reference
• if a similar local agent exists, use it only for interface shape
• if none exists, derive the interface from the runner and `DesktopEnv`

3. Copy the agent into `mm_agents/` with a clear, non-conflicting name. 4. Adapt only the repo-facing interfaces:

• `predict()` return shape
• action dict fields consumed by `DesktopEnv.step()`
• `ASK_USER` turns and follow-up user responses
• done/fail markers
• task current date
• platform, screen, provider, and password settings

5. Add a matching multi-env Python runner under `scripts/python/run_multienv_<agent>.py`.

• start from the closest retained runner structure
• keep task loading, env recreation, checkpoint args, logs, and cleanup behavior
• remove provider/model checks that only apply to the source runner

6. Add a small shell entrypoint under `scripts/bash/`.

• use `uv run`

7. Keep unrelated agents, scripts, results, and local dirty files out of the change.

Verify

Run fast checks first.

• Compile the new Python files.
• Check shell syntax.
• Check staged diff for whitespace.
• Run local fake tests for:
• action parsing
• `ASK_USER`
• user response returning to the agent
• checkpoint argument parsing if touched

Then run one small real smoke test.

• Use the intended provider.
• Use a tiny step limit.
• Prefer public IP for cloud providers when the local machine cannot reach private IPs.
• Confirm the model call happens.
• Confirm at least one environment action executes.
• Confirm result files and trajectory are written.
• Confirm cloud resources are cleaned up.

Before opening a PR, stage only the migration files and re-run the fast checks.