feat(run_code): run a script on a deploy_sandbox sandbox via sandbox_name

[psinghal20]

Stacked on #68. The base is that PR's branch, so this diff is run_code only; it retargets to main once #68 merges.

Summary

run_code could target only an env's VM host (env_id) or an agent container (agent_name). A task that provisions a bare machine with deploy_sandbox, stages files onto it with load_artifact(sandbox_name=...) and collects them with collect_artifacts(sandbox_name=...) had no way to run a script there in between.

• New sandbox_name target, resolved from context.deployed_sandboxes through the sandbox's own provider type (the lookup load_artifact and collect_artifacts use), deciding from the mode deploy_sandbox recorded:
  • VM-mode sandbox: runs on its host (the existing _HostTarget; staging, run, output read and timeout unchanged);
  • container-mode sandbox: runs in its container via _AgentTarget, the path container-mode agents already use: directly on a container provider, and with a docker exec -u 0 <container> prefix on a VM-backed one, where a plain exec lands on the host.
• env_id, sandbox_name and agent_name are mutually exclusive: more than one fails at construction (previously env_id silently won over agent_name). A blank value, as a form submits it, is unset.
  • Behaviour change: a host target (env_id or sandbox_name) no longer defaults agent_name, so it serializes agent_name: null. An agent step with no agent_name still runs in DEFAULT_AGENT_NAME.
  • Compatibility: steps stored before this change carry DEFAULT_AGENT_NAME beside env_id; from_dict drops it so they keep loading. A stored step with a non-default agent_name beside env_id is rejected.

Use case

Building a deliverable on a throwaway machine with no env or agent deployed: deploy_sandbox → load_artifact (inputs) → run_code (build) → collect_artifacts (output).

Tests

• tst/unit/task_step/test_run_code.py: the named sandbox on a VM (host, never docker), its provider type, an unknown name, a container-mode sandbox on a container provider (no prefix) and on a VM-backed one (docker exec -u 0), round trip; exclusivity (every pair and all three, the default agent name beside sandbox_name, blank values unset, host targets store no agent name, no target uses the default agent, legacy stored steps load, a stored non-default agent beside env_id is rejected).
• tst/integration/task_step/test_run_code_named_sandbox_local.py (new), the chain deploy_sandbox → load_artifact → run_code (zips the inputs, 0600) → collect_artifacts → load_artifact(artifact_from_step_id=...) → run_code (reads the zip back):
  • on a local VM-mode sandbox (no Docker): passes on Linux;
  • on a local container-mode sandbox (Docker + a throwaway registry:2, a non-root image user, paths under /work in the container): passes. Cleanup removes only the containers of sandboxes in the test's own sandbox root.
• tst/unit + protocol suite with fix(task_steps): reach the container of a container-mode deploy_sandbox sandbox #68 in a python:3.12 slim image: 6084 passed; the same 3 environment failures as on main in that image.
• check_plugin_api.py: no break to the plugin surface.

Notes for reviewers:

• On macOS the local VM-mode paths of run_code and collect_artifacts need GNU timeout and stat -c; CI runs Linux.
• Seen while testing, not changed: collect_artifacts given an absolute artifact_paths entry names the collected member by that absolute path, which load_artifact(artifact_from_step_id=...) then rejects as non-relative. The test collects with base_path and a relative name.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the previous findings are addressed and no new issue was established.

What we checked:

• Conflicting saved targets: No. The loader can discard an old agent_name, but the constructor rejects two remaining targets.

Summary

Tasks can now use run_code on a sandbox deployed by name, running on its host or inside its container based on the sandbox mode. The step also enforces one execution target at a time while keeping saved host steps loadable.

• Scripts can now run on a sandbox deployed by name.
• Run-code steps choose one target and keep saved host steps loadable.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["run_code target"] --> B{"Selected target"}
    B -- env_id --> C["Environment host"]
    B -- sandbox_name --> D{"Deployed sandbox mode"}
    B -- agent_name or default --> E["Agent container"]
    D -- VM --> F["Sandbox host"]
    D -- container --> G["Sandbox container"]

Loading

_{Reviews (4) · Last reviewed commit: "test(run_code): scope image cleanup to t..."}