# Barrel Brain Playground: guide for AI agents

You are on the **Barrel Brain Playground**, a petroleum engineering workbench that runs in the browser. It has:

- a **workspace** of files, shown in the explorer;
- **editor tabs** (Monaco);
- the **catalog** of Barrel Brain's engineering scripts (PVT, decline curves, well tests, material balance, ...);
- **runs**: a C# `.script` runs on an isolated server worker against the workspace files it names, and its results show
  in the results panel.

**Drive the page with its JavaScript API, `window.barrelbrain`. Don't click through it.**

- Every call is `async` and returns plain JSON.
- A call that cannot be done rejects with an `Error` whose message says why.
- Everything you do through the API shows on the page, so the person you work for can watch: files appear in the
  explorer, tabs open, the catalog pane searches, and results fill the panel.

## Start here

Run this JavaScript in the page, with a JavaScript tool, the console, or Playwright's `page.evaluate`:

```js
await barrelbrain.ready;          // the workbench has started and a workspace is open
await barrelbrain.status();       // { version, workspace, tabs, activeFile, run, webmcp, ... }
await barrelbrain.files.list();   // what is in the workspace
```

## The API (`window.barrelbrain`, version 1.0)

| Call | Does | Returns |
|---|---|---|
| `ready` | A promise: resolves once the workbench can take calls | `true` |
| `status()` | The workbench now | `{ version, ready, workspace: { name, kind, key, files }, tabs: [{ path, dirty }], activeFile, pane, run: { state, path, sends, outcome, message }, webmcp, tools }` |
| `workspace.list()` | The browser-private workspaces | `{ open, browser: [names] }` |
| `workspace.open(name)` | Opens (or creates) a browser-private workspace. **The page reloads** | `{ navigating: true, workspace, url }` |
| `workspace.openDemo()` | Opens the demo workspace. **The page reloads** | `{ navigating: true, workspace: 'demo', url }` |
| `workspace.resetDemo()` | In the open demo, puts every shipped file back and removes the files that are not part of it. Refused outside the demo and while a tab has unsaved edits. Cannot be undone | `{ restored: [paths], removed: [paths], files }` |
| `files.list(path?)` | Files and folders, all or under one folder | `[{ path, folder, size }]` |
| `files.read(path)` | A file's saved text | a string |
| `files.write(path, text)` | Creates or replaces a text file; folders are made as needed | `{ path, created, bytes }` |
| `files.delete(path)` | Deletes a file, or a folder and everything in it | `{ path, deleted, folder }` |
| `editor.open(path)` | Opens a file in a tab and makes it the active one | `{ path }` |
| `editor.active()` | The active tab, with its unsaved edits | `{ path, dirty, binary, text }` or `null` |
| `run(path, { files?, wholeWorkspace?, wait?, timeout? })` | Runs a `.script` on a server worker (see below) | the run's result |
| `stop()` | Stops the run in progress | `{ stopped }` |
| `catalog.search(query)` | Searches the catalog and shows the hits in the catalog pane | `[{ slug, title, hub, description }]`, best first |
| `catalog.get(slug)` | One example in full, previewed in the pane | `{ slug, title, hub, description, useCases, workspacePath, source }` |
| `catalog.open(slug)` | Copies the example to `examples/<slug>.script` and opens it. An existing file there is opened as it is, never overwritten | `{ path, created }` |
| `tools` | The WebMCP tool names registered | an array, empty without WebMCP |

After `workspace.open` or `workspace.openDemo` the page reloads. In the new page, `await barrelbrain.ready` again before
the next call.

## A typical session

```js
await barrelbrain.ready;
await barrelbrain.workspace.openDemo();
// ...the page reloads; then, in a new evaluate:
await barrelbrain.ready;
const files = await barrelbrain.files.list();                 // data/wells.csv, data/monthly-rates.csv, scripts/*.script
const csv = await barrelbrain.files.read('data/wells.csv');
const r = await barrelbrain.run('scripts/well-summary.script'); // the demo, unchanged: no sign-in needed
if (!r.ok) return r.summary;                                   // e.g. "sign-in-required", or the compile errors
return { summary: r.summary, table: r.blocks.find(b => b.kind === 'table') };
```

## Runs

- **What a run sends.** The script's source, plus each workspace file whose path appears in the script as a string
  literal (`"data/wells.csv"`), plus any you list in `files`, or every file when `wholeWorkspace` is true.
  `status().run.sends` and the result's `sends` say how much, such as `2 files, 340 KB`.
- **Where it runs.** On the server: a fresh isolated worker runs it against an in-memory workspace of exactly those
  files, with no network. Nothing is kept on the server afterwards.
- **Limits.** Up to 200 files and 10 MB per run, a script up to 100,000 characters, and the worker's time and memory
  limits. Runs are rate-limited per visitor.
- **Who may run what.**
  - A catalog example or a demo script, unchanged, runs for anyone, signed in or not.
  - An edited or new script, or a run that sends an edited demo file, needs a sign-in. Without one, the result's
    `outcome` is `sign-in-required` and its `message` says so. You cannot sign in for the person: tell them.
- **The result.** `{ ok, outcome, path, sends, summary, blocks, errors, warnings, timing }`.
  - `outcome` is `success`, `compileFailed`, `runtimeError`, `timeout`, `securityRejected`, `sign-in-required`,
    `quota-exceeded` and the like.
  - `summary` is one line, such as `success in 812 ms: table "Wells" (5 rows)`.
  - `blocks` are the result tabs the page shows: `{ kind: 'table', columns, rows }`, `{ kind: 'chart', ... }`,
    `{ kind: 'object', value }` and `{ kind: 'text', markdown }`.
- **Waiting.** `run` waits up to `timeout` milliseconds (default 120000). With `wait: false`, or past the timeout, it
  returns `{ state: 'pending' }` and the run goes on. Poll `status().run.state` until it is `done`.
- **One at a time.** A second `run` while one is pending is refused. Wait for it, or `stop()` it.

A script is C# with `Team76.Engineering` in scope. A script that reads files implements `IDataScript` and reads them
through `ctx.Workspace`. `scripts/well-summary.script` in the demo is a worked example; `catalog.search` finds more.

## Be careful with the person's workspace

The workspace belongs to the person using this browser, and it persists between visits.

- **Your work goes in new files**, such as `scripts/agent-test.script`, rather than edits to theirs, unless they asked.
- **Calls stay inside the open workspace.** A path is relative, `/`-separated, with no `.` or `..` segment, so nothing
  reaches outside it.
- **Unsaved edits are safe.** Writing over a file whose tab has unsaved edits is refused, and so is deleting it or a
  folder that holds it. Opening another workspace is refused while any tab has unsaved edits.
- **A local folder asks the person.** When the workspace is a real folder on their computer (`status().workspace.kind`
  is `folder`), every write and delete waits until the person allows it in the page's ask bar. If they cancel, the call
  rejects with "The user did not allow it."
- **Ask before deleting.** `files.delete` cannot be undone, and neither can `workspace.resetDemo`, which removes every
  file in the demo that is not part of it, yours and the person's alike.

## If you click instead

The page carries the state to wait on, and hooks for the controls:

- **`<body>`** has `data-workbench-ready` once calls go through, `data-run-state` (`idle`, `pending`, `done`),
  `data-active-file` (the active tab's path) and `data-webmcp` (`on` or `off`).
- **Controls** have a `data-testid` and an accessible name. Among them: `run`, `stop`, `save`, `new-file`,
  `new-folder`, `rename`, `delete`, `pane-explorer`, `pane-catalog`, `catalog-search`, `catalog-item`,
  `open-in-workspace`, `results`, `run-output`, `result-tab`, and the explorer's rows, `node` with `data-path`.

## WebMCP

In a browser with WebMCP (`document.modelContext`, in the origin trial in Chrome 149 and Edge 150), the same calls are
registered as tools. Each has a JSON schema with described properties.

| Tool | Call |
|---|---|
| `workbench_status_get` | `status()` |
| `workspace_list` | `workspace.list()` |
| `workspace_open` | `workspace.open(name)` |
| `workspace_demo_open` | `workspace.openDemo()` |
| `workspace_demo_reset` | `workspace.resetDemo()` |
| `workspace_file_list` | `files.list(path?)` |
| `workspace_file_read` | `files.read(path)` |
| `workspace_file_write` | `files.write(path, text)` |
| `workspace_file_delete` | `files.delete(path)` |
| `editor_file_open` | `editor.open(path)` |
| `editor_file_get` | `editor.active()` |
| `script_run` | `run(path, options)` |
| `script_stop` | `stop()` |
| `catalog_example_search` | `catalog.search(query)` |
| `catalog_example_get` | `catalog.get(slug)` |
| `catalog_example_open` | `catalog.open(slug)` |

## More

- **[llms.txt](/llms.txt):** the short summary of this site.
- **[Catalog](/catalog):** every example script as a static page.
- Outside the browser, Barrel Brain's MCP server offers the catalog and calc-tier script runs as MCP tools.
