[earakely-scale]

What

Snapshots reach envs deployed without a gateway, and a computer env's files can be snapshotted and loaded back into it. This is built on environment artifacts of several files (#424).

• snapshot_env without a gateway. It reaches an env through the card its deployment recorded, and snapshots the environments that card lists as children, or the env itself when it lists none. Before, any record without a gateway was refused.
• A file tree is kept file by file. An environment whose card declares that data/get returns a file tree (urn:agentenv:intake/v1, format file-tree, as a computer's does) is kept in its environment artifact, each file by its path, under an upload grant sized for a file tree. Every other environment is still kept as one file, exactly as before.
• snapshot_computer_env, a new step in task_steps/computer/, is snapshot_env with the computer's file_paths passed as data/get's paths. By default those are the folders the computer's card declares (Desktop, Documents, Downloads). It writes the same environment universe snapshot_env does.
• A computer env loads its snapshot back. load_environment_artifact writes the files at their paths under the session user's home through the driver's data/add, so load_artifact of a computer's snapshot restores it.
• An env that can't reach the store under the upload grant is asked again without the grant, and returns its export inline.

Issue: FD-4382 (M1.8). Design: Environment Artifacts With Several Files, section "After it lands".

How

• No gateway. execute takes a record with a recorded card in place of a gateway URL. snapshot_env_state then lists the card's environments (_card_environments) instead of the env's MCP servers, and the existing helpers resolve each environment's address from the stored card.

• File trees. For an environment whose card declares a file tree, _export_environment_to_file asks data/get under a grant of FILE_TREE_LIMITS (100,000 objects, 50 GiB in all) and returns its answer. export_one then writes the files (_file_tree_files), 8 at a time:

  • a file uploaded under the grant is registered where it was put, with no download;
  • any other file is written from its inline bytes;
  • each file's id is derive_path_id(<snapshot>-<environment>, path).

  The files go into the environment's artifact by path. A part naming no path, or no files at all, fails that environment with a clear message.

• data_get_params. snapshot_env_state takes data_get_params for every environment's data/get, which is how snapshot_computer_env passes paths.

• snapshot_computer_env.

  • Its fields: env_id, env_instance_id, env_step_id, snapshot_id, file_paths, export_timeout_seconds.
  • Refused before a run: an env that isn't a computer env, and file_paths that aren't normalized paths relative to the home.
  • It picks the deployment and names the snapshot as snapshot_env does, and records under env_snapshotted_universes.

• ComputerEnv.

  • load_environment_artifact takes the computer's own environment artifact and writes its files at their paths through inside.add_artifacts, the path load_file_artifact_universe already uses. It uses read grants when the store's grants reach the computer and its network allows it, and inline bytes otherwise. Files already there that aren't in the artifact stay.
  • load_environment_universe_artifact loads the universe's environment named after the computer, and leaves any other out with a warning.

• The retry (snapshot_env.get_data): a data/get that fails under the grant, as a computer whose network is closed does, is asked once more without it. A failure without a grant is reported as before.

Not in this PR

• A computer's apps (M1.4, FD-4369): their exports in the computer's snapshot, and loading a universe's app environments into them. Today those are left out with a warning.
• An environment that returns several parts without declaring a file tree is still kept as its first part, as before.
• prompt_agent's periodic env snapshots still skip an env without a gateway (env_has_no_gateway_url).

Testing

Unit: 12,337 passed, none failed, on macOS. New and extended tests:

• snapshot_env without a gateway:
  • each child on a recorded card is reached and kept as one file;
  • the env itself is reached when the card has no children;
  • a file tree is kept file by file by its paths, under a 100,000-object grant;
  • an env failing under the grant is asked again without it, and one failing with no grant is asked once;
  • execute end to end.
• snapshot_computer_env:
  • its fields round-trip and it's registered;
  • non-relative file_paths and an env that isn't a computer are refused before a run;
  • inline files are kept by their paths, with file_paths sent as paths or nothing;
  • uploaded files are kept where the computer put them;
  • the retry without the grant;
  • a run on an env that isn't a computer, or with no files, is refused.
• ComputerEnv: a snapshot of its files loads back at their paths, leaving out another environment with a warning. An environment or universe not named after the computer is refused before anything is sent.
• load_artifact: a computer env now passes the save-time check for loading an environment universe; service_db is the type that's refused.

Integration, laptop (local Docker, localhost:5000), on the shipped desktop computer:

• A computer with no network. It's given a file in Downloads and one written to Desktop, then snapshotted with file_paths = ["Desktop", "Downloads/note.txt"].
  • Its upload under the grant fails, it's asked again, and exactly those two files come back inline.
  • After a reset removes them, load_artifact of the snapshot writes Desktop/left.txt back.
• An open computer with files in Documents/reports and Downloads, snapshotted with its card's folders. Each file is uploaded under the grant and kept at its object URL, with the bytes intact.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no blocking issue was established.

Summary

The PR adds snapshots for deployments without a gateway and preserves computer files by path.

• Environment snapshots can follow a deployment card without a gateway.
• Computer files can be saved and restored as separate files at their original paths.
• Computer environments can combine apps in their listed order.
• OpenEnv servers can require a bearer token for requests and WebSocket connections.
• verl can train on OpenEnv tasks through an agent loop and generated datasets.
• Protocol version and timing-related test edits leave product behavior unchanged.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Deployed environment] --> B{Gateway available?}
  B -->|Yes| C[List environment services]
  B -->|No| D[Read recorded card]
  C --> E[Request current data]
  D --> E
  E --> F{File tree?}
  F -->|Yes| G[Save each file by path]
  F -->|No| H[Save one environment file]
  G --> I[Create environment universe]
  H --> I
  I --> J[Load into matching environment]

Loading

_{Reviews (3) · Last reviewed commit: "Merge the earlier branch head into the r..." · Reviewed by Greptile}