@ai-sdk/workflow 2.0.90: Sandbox Sessions Gain File Operation Capabilities

The workflow package in the AI SDK ecosystem has received a patch update. The release notes for @ai-sdk/workflow@2.0.90 don't carry much information, but the direction of the changes is worth noting: SandboxSession now supports file-level operations, marking another step forward in the ability of workflows to handle files within isolated environments.

Sandbox Sessions Add Three File Methods

The core of this update is the addition of three methods to Experimental_SandboxSession: stat, listDirectory, and deleteFile. The release notes also specify a path resolution rule: relative paths in each method are resolved relative to the directory where run and spawn were launched.

The practical value of this rule lies in eliminating ambiguity. When workflow code executes inside a sandbox, if the base directory for file operations isn't unified, it's easy to run into the problem of "the same relative path pointing to different locations in different methods." Anchoring the base to the launch directory of run/spawn lets stat, listDirectory, and deleteFile share the same frame of reference as the execution entry point.

One detail worth noting: these three methods are currently under the Experimental_ prefix, indicating the interface is still experimental and behavior may change later.

In the Node.js ecosystem (and most POSIX-style APIs), stat, listDirectory, and deleteFile correspond to three basic filesystem operations: stat retrieves metadata about a path (whether it's a file or directory, size, modification time, etc.), listDirectory enumerates entries within a directory, and deleteFile deletes a single file. Putting these into sandbox sessions gives workflow code a minimal file management loop of "inspect—enumerate—clean up" within an isolated execution environment. Since sandboxes are typically isolated from the host filesystem, such methods are often translated by adapters into calls to remote or virtual filesystems, making the path base directory convention particularly critical.

Behavioral Differences Between the Two Adapters

The release notes mention that both the just-bash and Vercel Sandbox adapters have implemented the new methods. The shared change is that the relative workingDirectory of run and spawn is now resolved relative to the sandbox's working directory.

The divergence appears in write semantics. The just-bash adapter rejects operations that "write to a directory" rather than replacing the directory with a file. This detail has real significance for workflow safety—if the write logic doesn't perform this check, a single misstep could overwrite the directory structure. The two adapters don't handle this point identically, so users need to be aware when migrating across adapters.

"Writing to a directory" typically has two implementations at the filesystem level: replacing the target path with new content, or erroring out and rejecting. Semantics like POSIX's rename/open aren't uniform across implementations, and many language standard libraries check whether the target is a directory before writing. By choosing to reject, just-bash effectively adds a defensive check at the adapter layer, preventing a bad write path in a workflow from overwriting an entire directory tree. When migrating across adapters, code that relies on "write will overwrite" behavior may receive errors on the new adapter, so write semantics should be treated as part of the adapter contract.

Dependency Chain Updated in Sync

As a patch release, this version also updates several dependencies: @ai-sdk/provider-utils@5.0.72, ai@7.0.158, @ai-sdk/provider@4.0.35, along with several commit references listed in the release notes. For projects with locked versions, upgrading the workflow package will also bump these versions, so compatibility needs to be confirmed at the lockfile level.

From the version numbers, we can see that the AI SDK's core package has reached 7.x, the provider layer is at 4.x, and provider-utils is at 5.x—each layer moves at its own pace. As an upper-layer wrapper, it's standard practice for workflow to roll forward with these underlying packages.

The AI SDK uses a layered package structure: @ai-sdk/provider defines the abstract interface for model providers, @ai-sdk/provider-utils provides shared utility functions and types for all providers, and the ai package is the high-level entry point for applications, with upper-layer wrappers like workflow depending on these foundational packages. Independent releases for each layer mean asynchronous version cadences are the norm, but this also introduces a practical issue: when upper-layer packages upgrade, if peerDependencies or dependencies ranges are broad, the lockfile may resolve to underlying versions different from expectations. For projects with locked versions, after upgrading you should check the actual resolved results of these entries in the lockfile, and use overrides/resolutions to pin versions if necessary.

What This Update Means

Adding three file methods to sandbox sessions points toward a more complete workflow execution environment: not only can commands run in the sandbox, but file states can be inspected, directory contents enumerated, and files cleaned up. For scenarios that require AI workflows to read and write artifacts in isolated environments, these methods are part of the infrastructure.

The experimental prefix also signals the current state—the interface shape isn't finalized. If you're following this package, it's better to treat it as a directional signal rather than a stable API, and consider deep reliance only after the Experimental_ prefix is removed.

This release was completed automatically by github-actions with GPG signature verification, following the standard automated release process.

One-line Summary

AI SDK workflow package patch update adds three file operation methods to sandbox sessions.

Paragraph Summary

@ai-sdk/workflow@2.0.90 is a patch update whose core change adds three file operation methods—stat, listDirectory, and deleteFile—to Experimental_SandboxSession, and specifies that all relative paths are resolved relative to the directory where run and spawn were launched, eliminating path ambiguity across methods. Both the just-bash and Vercel Sandbox adapters have implemented the new methods, and the relative workingDirectory of run and spawn is now uniformly resolved relative to the sandbox working directory. The difference is that just-bash rejects writing to a directory rather than replacing it, which matters for cross-adapter migration. This release also updates dependency versions for provider-utils, ai, and provider, requiring compatibility confirmation at the lockfile level.