Tool Calls

When you call bluebag.enhance, Bluebag injects sandbox tool handlers into your AI SDK config. They are merged with any tools you already provide, and show up under stable names prefixed with bluebag_.

The tools are bluebag_bash, bluebag_code_execution, bluebag_computer_use, bluebag_text_editor and bluebag_file_download_url.

Shared output shape

Most tools return a ToolExecutionResult payload with:

• result: Tool-specific payload.
• exitCode: Exit status for command execution tools.
• artifacts: null or metadata about files created during execution. Each artifact includes fileId, filename, path, size, and expiryAt.

The bluebag_text_editor tool returns a command-specific payload, and bluebag_file_download_url returns result with a signed URL.

Tools exposed by bluebag.enhance

bluebag_bash

Execute bash commands & simple code execution (e.g., node your-script.js or python your-script.py) when working with Skills in the Bluebag sandbox. If files are created during execution, the tool result includes metadata (including fileId) about the created file(s) in the artifacts array.

Input

• command (string, required): Shell command to execute inside the sandbox.

Output

• result (string): Standard output from the command.
• exitCode (number): Exit status.
• artifacts (array | null): Created file metadata (fileId, filename, path, size, expiryAt).

bluebag_code_execution

Analyze data, create visualizations, and perform complex calculations when working with Skills in the Bluebag sandbox using Python, JavaScript, or TypeScript. If files are created during execution, the tool result includes metadata (including fileId) about the created file(s) in the artifacts array.

Input

• language ("python" | "javascript" | "typescript", required): Programming language to execute the code in.
• code (string, required): Source code that will be executed.
• files (array, optional): Files to mount into the sandbox before execution.
  • fileId (string, required): File identifier.
  • path (string, required): Target path inside the sandbox.

Output

• result (string): Standard output from the code execution.
• exitCode (number): Exit status.
• artifacts (array | object | null): When files are created, this is an array of file metadata (fileId, filename, path, size, expiryAt). Otherwise it may include execution artifacts like stdout or charts.

bluebag_computer_use

Control the sandbox desktop environment for browser automation and GUI interactions.

Input

• action ("screenshot" | "click" | "type" | "key", required): Action to perform.
• coordinate ([x, y], optional): Screen coordinates for click actions.
• text (string, optional): Text to type or key to press.

Output

• result: Action-specific payload (screenshot data, confirmation, etc.).

bluebag_text_editor

View, create, and edit files in the sandbox via text manipulation.

Input

• command ("view" | "create" | "str_replace", required)
• path (string, required)
• file_text (string, optional): Required for create.
• old_str (string, optional): Required for str_replace.
• new_str (string, optional): Required for str_replace.
• start_line (number, optional): Start line for view.
• end_line (number, optional): End line for view.

Output

• view: file_type, content, numLines, startLine, path, totalLines, isTemp.
• create: path, is_file_update, fileId, size, isTemp, expiryAt.
• str_replace: path, fileId, size, isTemp, expiryAt.

fileId and expiryAt are present when the file path is eligible for persistence.

bluebag_file_download_url

Mint a short-lived download URL for a file by its fileId.

Input

• fileId (string, required)
• ttlSeconds (number, optional): Optional TTL override in seconds (capped server-side).

Output

• result: fileId, downloadUrl, expiresAt.