migrate-osworld-agent

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.