amap-ml/longhorizon-harness/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

1. Copy the agent into mm_agents/ with a clear, non-conflicting name.
2. 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

1. 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

1. Add a small shell entrypoint under scripts/bash/.

• use uv run

1. 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.