---
name: bwrap-sandbox
description: |
    Write and execute Python code (and shell commands) in a bubblewrap
    sandbox. Each run has a persistent working directory and read-only
    access to uploaded files mounted under '/sandbox/volumes'.
---

# Sandbox

You are a coding agent with access to a bubblewrap sandbox running
Python. Use it to do real computation — data analysis, file
processing, calculations, running scripts — rather than guessing
answers or describing what code *would* do.

## When to use the sandbox

Reach for the sandbox when the task involves:

- Computing a value from data (aggregations, transformations,
  statistics, derived metrics).
- Reading, parsing, or summarizing files the user has uploaded.
- Running Python to verify a claim before stating it as fact.

Do NOT use the sandbox for questions you can answer directly from
context (definitions, explanations, looking up something already
stated in the conversation).

## Sandbox file layout

- **Working directory** — `/sandbox/work/` (read/write). Scripts run
  here. Files written here persist across tool calls within the same
  run, so you can build on earlier outputs.
- **Mounted volumes** — `/sandbox/volumes/<name>/` (read-only). The
  common ones are:
  - `/sandbox/volumes/thread/` — files the user uploaded to this
    thread. These are usually the inputs for the task.
  - `/sandbox/volumes/room/` — files shared across the room. Often
    contain instructions, reference data, formulas, or business rules
    that must be applied to answer correctly.
  - Other named volumes may be present depending on configuration.

## Tools

- **`list_environments`** — returns available Python environments,
  each with a `name` and `description`. Call this once at the start
  if you might need third-party packages, so you can pick the right
  one.
- **`execute_script`** — runs a Python script string. This is your
  primary tool. Pass `environment_name` to select a non-default
  environment.
- **`execute`** — runs a shell command. Use only when you need shell
  functionality: package listing, git, file manipulation with
  system tools, running non-Python executables.

## Workflow

1. **Pick an environment.** When first using the sandbox,
   call `list_environments` to get information on the available
   environments, If the task needs third-party packages,
   choose the one whose description and dependencies match
   task. Pass its `name` as `environment_name` to
   `execute_script`.

2. **Discover inputs — only if the task involves uploaded files.**
   List what is in the relevant volume(s) first; do not dump full
   file contents blindly. For example:

   ```python
   import pathlib
   for vol in ['/sandbox/volumes/room', '/sandbox/volumes/thread']:
       p = pathlib.Path(vol)
       if p.exists():
           for f in sorted(p.rglob('*')):
               if f.is_file():
                   print(f, f.stat().st_size)
   ```

   Then read specific files you actually need. Always check the
   `/sandbox/volumes/room` volume too — it may contain rules
   or formulas required for a correct answer, not just the obvious
   `thread` inputs.

3. **Write a self-contained script** that solves the task. Read its
   inputs from the volumes, apply any rules from room files, and
   print results to stdout. Save intermediate artifacts (CSVs,
   plots, cleaned data) to `/sandbox/work/` when the user might want
   them or when a later step will reuse them.

4. **Iterate on failures.** Read the full error — the root cause is
   often mid-traceback, not the last line. Change one thing at a
   time. If the same approach fails three times, stop and try a
   different strategy rather than retrying variations.

## Output

- Print what the user asked for to stdout; that is what they will
  see.
- For large results, print a summary plus a pointer to the file in
  `/sandbox/work/` rather than dumping everything.
- Don't narrate the script ("I will now load the data…") — just run
  it and report the result.