feat(load_artifact): allow urls entries to set the saved filename

[polakamtejas]

What and why

load_artifact names each URL download after the last segment of the URL path. When that segment is an opaque object key, as it often is for object-storage and signed URLs, the file lands with no real name and no extension. The prompt meanwhile refers to the file by its real name, and the agent has no way to match the two.

A urls entry may now be {"url": ..., "filename": ...} as well as a bare URL string:

{"id": "load-inputs", "type": "load_artifact", "agent_name": "agent", "destination_path": "/tmp/data",
 "urls": [
   {"url": "https://files.example/objects/obj-4f9c2a", "filename": "report.txt"},
   "https://a.example/data.csv"
 ]}

This saves /tmp/data/report.txt and /tmp/data/data.csv, and loaded_urls[].files records both names.

• A bare string is named exactly as before: the last path segment, percent-decoded, downloaded when empty, and repeats suffixed -1, -2, ….
• An object entry takes a non-empty url and filename and no other key. The filename must be a plain file name: relative, no .., no path separators.
  • Nested paths are left out on purpose: ./a vs a would get past the duplicate check, and a vs a/b would put a file inside a directory instead of failing.
  • Allowing them later is backward compatible.
• An explicit filename is never renamed. The same filename twice, or a bare URL whose name would match an explicit one, raises an error instead of being suffixed.
• Entries are validated at construction, so __init__ and from_dict reject a bad stored entry. A per-run urls override is validated in _resolve_inputs, before anything in the step is loaded.
• to_dict and from_dict pass entries through unchanged.

Compatibility: existing steps are unchanged. A step that uses the object form needs a version with this change to run. An older version accepts the step but fails at run time when it names the downloads.

How it was tested

• make unit-test: 6544 passed, 13 skipped.
• 13 new test cases in tst/unit/task_step/test_load_artifact_{container_sandbox,overrides,url_filenames,vm_target}.py:
  • bare-URL naming: suffix, fallback name and percent-decoding. No test covered it before, and the code moved.
  • a mixed list run end to end: where each file is written, and loaded_urls.
  • a named URL on the VM-host path.
  • a named entry in a per-run override.
  • an invalid override failing before anything is loaded.
  • the round-trip.
  • five invalid entries: missing filename, an unknown key, .., an absolute path, a nested path.
  • a duplicate filename.
  • a bare URL colliding with an explicit filename.
• Disabling each rule in turn (explicit name ignored, duplicate check, collision check, plain-name check, construction-time validation, override validation) makes at least one of these tests fail.
• .github/scripts/check_plugin_api.py: no break to the plugin surface.
• Downloads go through mocked sandboxes only. No integration test covers urls.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge.

What we checked:

• Chosen filenames overwrite each other: The step rejects duplicate chosen names and rejects a bare URL when its generated name matches a chosen name, before downloads start.

Summary

load_artifact URL lists can now mix bare URLs with entries that choose a filename. Chosen names are used for downloads and recorded in loaded_urls[].files.

• URL downloads can now keep the filenames task authors give them.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["urls entry"] --> B{"Entry type"}
  B -->|Bare URL| C["Name from URL path"]
  B -->|Object| D["Check chosen filename"]
  C --> E["Check against chosen names"]
  D --> E
  E --> F["Download to target"]
  F --> G["Record loaded_urls"]

Loading

_{Reviews (1) · Last reviewed commit: "feat(load_artifact): allow urls entries ..." · Reviewed by Greptile}

[earakely-scale]

Does what it says. It merges cleanly with current main, and the unit tier passes on the merge.

One suggestion, inline: names derived from bare URLs skip the rules explicit names now get.

Heads-up for consumers: anything that pre-validates urls as strings, such as a URL scheme check, needs to read entry["url"] from object entries too, or those entries skip it.