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.