feat(provider-utils): add readFile and writeFile plus convenience wrappers to Experimental_Sandbox abstraction

[felixarntz]

Background

Experimental_Sandbox (previous: #14949, #15253, #15301) only exposed description and runCommand, so tools that needed file I/O had to wrap every read/write in a shell command (cat, tee, echo > …). That is fragile for binary content and impossible to type properly.

Summary

• Adds six file methods to Experimental_Sandbox: streaming readFile/writeFile as the foundation, plus readBinaryFile/readTextFile and writeBinaryFile/writeTextFile as convenience wrappers.
  • All methods take a single options object so additional fields can be added without breaking the signature.
  • Using a stream for the foundation is the most low-level and future-proof primitive, plus it handles large files better.
  • In a follow up PR, we'll add another reduced abstraction surface, because technically a sandbox provider shouldn't have to implement the convenience wrappers readTextFile, writeTextFile, etc. This can take inspiration from (or continue with) provider sandbox #15311.
• Updates the three example sandbox implementations (LocalSandbox, JustBashSandbox, both VercelSandbox copies) to implement the new methods, using streaming readFile/writeFile as the foundation that the binary and text variants delegate to.

Checklist

• All commits are signed (PRs with unsigned commits cannot be merged)
• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• I have reviewed this pull request (self-review)

Future Work

See above: We'll need to add that reduced abstraction surface so that only essential methods have to be implemented by the provider. We can provide a helper function to fill in the convenience wrappers automatically.

[lgrammel]

what do we consider a linebreak? presumably \n but we may want an optional linebreak field that allows setting \r or \n or \r\n

[felixarntz]

Good point, though I think an option feels a bit too low-level. I implemented a helper in provider-utils instead for extracting lines which detects the line break format used in a file and maintains it.

If this shows to be problematic, we can still considering adding an option.

[lgrammel]

wonder if it's worth moving to provider-utils so providers can use this for testing

[felixarntz]

Unsure about this. Do we have other test-only helpers in provider-utils? Either way, we could add this later if there's value.