feat: sandbox shell execution abstraction

[lgrammel]

Background

Many agents are using filesystems through shell and file read/write tools, often in separate sandbox environments. These agents are so common that a first-class sandbox abstraction would be beneficial.

Summary

• add Sandbox type
• add sandbox option to generateText, streamText, ToolLoopAgent
• make sandbox available in ToolExecutionOptions

Example

Tool definition:

import { tool } from 'ai';
import { z } from 'zod';

export function sandboxShellTool() {
  return tool({
    description: 'Run a shell command',
    inputSchema: z.object({
      command: z.string(),
    }),

    execute: async ({ command }, { sandbox }) => {
      // TODO figure out type inference to turn the runtime error into a type error
      if (!sandbox) {
        throw new Error('Sandbox is not available');
      }
      return sandbox.executeCommand({ command });
    },
  });
}

Agent definition:

import { openai } from '@ai-sdk/openai';
import { ToolLoopAgent } from 'ai';
import { sandboxShellTool } from '../../tools/sandbox-shell-tool';

export const sandboxAgent = new ToolLoopAgent({
  model: openai('gpt-5.5'),

  tools: {
    shell: sandboxShellTool(),
  },

  prepareCall: ({ sandbox, ...rest }) => ({
    ...rest,
    instructions:
      `You are a helpful assistant that can run shell commands.\n` +
      `You are operating in the following sandbox: ${sandbox?.description}`,
  }),
});

Agent call:

import { Bash } from 'just-bash';
import { JustBashSandbox } from '../../sandbox/just-bash-sandbox';
import { sandboxAgent } from './sandbox-agent';

const sandbox = new JustBashSandbox(
  new Bash({
    cwd: '/home/user',
  }),
);

const result = await sandboxAgent.stream({
  prompt:
    'Create a file named greeting.txt with a short greeting, then list the files and show the file contents.',
  sandbox,
});

Manual Verification

• agent - generate src/agent/openai/generate-local-sandbox
• agent - stream src/agent/openai/stream-local-sandbox
• test with ui examples/ai-e2e-next/app/chat/sandbox/page.tsx

Future Work

• read/write files in sandboxes
• explore generic typing of sandbox tools
• move sandbox shell tool into ai package
• allow choosing a sandbox in prepareStep
• add timeout to executeCommand
• figure out sandbox streaming
• need onFinalize callback (or something) that is always invoked (on finish, abort, error etc)