antithesis-debug

What this skill does

# Antithesis Multiverse Debugger

Use the `agent-browser` skill to interact with the Antithesis multiverse
debugger.

Every debugging session should use:

- a fresh, unique `SESSION` value such as `antithesis-debug-$(date +%s)-$$`

Use `--session-name antithesis` so `agent-browser` manages shared
authentication state automatically, while `--session "$SESSION"` keeps each
debugging run isolated from other concurrent agents. Close the unique live
session when debugging is complete.

## When to use this skill

Use this when:

- the user gives an Antithesis debugging-session URL
- the user makes a request to inspect container filesystem, runtime state, or events inside Antithesis
- the triage skill has launched an MVD session when investigating the results of a run

For auth and report navigation, use the `antithesis-agent-browser` skill. It
owns the `agent-browser` session and authentication flow. This skill handles
the debugger itself.

## Gathering user input

Before starting, collect the following from the user:

1. **Debugger URL** (required) — A debugging-session URL like `https://TENANT.antithesis.com/debugging-session/...`.
2. **What to investigate** — Are we checking filesystem contents? Runtime state? Specific artifacts?
3. **Container name** (if known) — The name of the container to target. If not provided, the log view or container dropdown will show available containers.

## Simplified vs. advanced mode

The debugger has two modes. **Prefer simplified mode** — it is sufficient for
most tasks.

| Mode           | Best for                                                                                         | How it works                                                            |
| -------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| **Simplified** | Running shell commands, reading files, listing directories, extracting artifacts                 | Click log lines to set moment/container, type bash commands, press Send |
| **Advanced**   | Programmatic inspection, branching, event sets, custom JavaScript, multi-step notebook workflows | Monaco editor with JavaScript cells, action authorization, runtime API  |

### Detecting which mode is active

Different tenants may open the debugger in either mode by default. After
injecting the runtime (see `references/setup-session.md`), check which mode is
active:

```bash
agent-browser --session "$SESSION" eval \
  "window.__antithesisDebug.getMode()"
```

Returns `"simplified"` or `"advanced"`. To switch:

```bash
agent-browser --session "$SESSION" eval \
  'window.__antithesisDebug.switchMode("simplified")'
```

### When to escalate to advanced mode

Switch to advanced mode only when you need:

- **A target container that had crashed (or otherwise wasn't running) at the MVD recreate moment.** The simplified container dropdown only lists containers running at that point. To inspect a container while it was alive, you must time-travel back via `moment.rewind_to(...)` and target it by name via `bash...run({container: "<name>"})`. This is the one container-targeting case where advanced is strictly required.
- Branching (`moment.branch()`) and advancing time (`branch.wait`, `branch.wait_until`)
- Exploring multiple random histories from the same moment (`branch.send_input`)
- Event set queries (`environment.events.up_to(moment)`, `.contains({source})`)
- Fault injector state inspection or control (`environment.fault_injector.pause/unpause`)
- Background processes and process-exit awaiting (`run_in_background`, `p.exits`)
- Complex multi-cell notebook workflows with grouped authorization
- The full JavaScript notebook API
- As an escape hatch when something in simplified mode isn't working

To switch programmatically, call `window.__antithesisDebug.switchMode("advanced")`.
This is what `getMode()` reports. **Note:** there is a separate "Simple
mode" / "Advanced mode" tab strip in the right pane (`.display_area__tabs`)
that `switchMode()` does NOT click; the two can disagree. The right-pane
tab strip controls the help / pop-out panel content. To read the on-page
advanced-mode help (a canonical ~5KB reference for the notebook API), click
the "Advanced mode" tab in that strip and read
`document.querySelector(".display_area__layout").innerText`. See
`references/advanced-debugger.md`.

## Reference files

Each reference file covers a specific interaction mode or task. Read the
relevant file before performing that task.

### Simplified mode (default — start here)

| Page                                | When to read                                                        |
| ----------------------------------- | ------------------------------------------------------------------- |
| `references/setup-session.md`       | Always — read first to set up the browser session                   |
| `references/simplified-debugger.md` | Running commands, extracting files, reading logs in simplified mode |

### Advanced mode (using a notebook)

| Page                                | When to read                                                                              |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| `references/setup-session.md`       | Always — read first to set up the browser session                                          |
| `references/advanced-debugger.md`   | **Read this BEFORE other advanced refs** — mental model, mode-switching, authorization, branches, time advancement, fault injector, host commands, common errors |
| `references/notebook.md`            | Reading or writing notebook source, injecting cells                                       |
| `references/actions.md`             | Authorizing shell actions, reading action output                                          |
| `references/common-inspections.md`  | Ready-to-use debug cell snippets for common tasks                                         |

## Recommended workflows

### Simplified: Run a command in a container

1. Read `references/setup-session.md` — open the debugger URL
2. Read `references/simplified-debugger.md` — click a log line to set the
   moment and container, enter a bash command, press Send, read the output
3. Report findings with concrete evidence

### Simplified: Extract a file

1. Read `references/setup-session.md` — open the debugger URL
2. Read `references/simplified-debugger.md` — click a log line, toggle
   "Extract file", enter the file path, press Send
3. Read the download link from the output

### Advanced: Programmatic investigation

1. Read `references/setup-session.md` — open the debugger URL and inject runtime
2. Switch to advanced mode: `window.__antithesisDebug.switchMode("advanced")`,
   then `notebook.waitForReady()`
3. Read `references/advanced-debugger.md` — internalize moments, branches,
   reactive-vs-effectful, action grouping, and common errors
4. Read `references/notebook.md` — mechanics of writing cells
5. Read `references/common-inspections.md` — ready-to-use snippets
6. Read `references/actions.md` — authorizing and reading action results
7. Report findings with evidence chain

### Download the events log for offline analysis

1. Read `references/setup-session.md` — launch / open the debugger URL
2. Read `references/download-log.md` — run `assets/download-mvd-log.sh`
   to capture and (for JSON) annotate the events log. The annotation step
   delegates to the triage skill's `process-logs.py`; no debug-skill-local
   copy.
3. Analyze the local file with `jq` (event shape matches the triage
   skill's logs reference)

## Runtime injection

The JS runtime is required for **both** simplified and advanced modes. It
provides the `window.__antithesisDebug` API with three namespaces:
`simplified`, `notebook`, and `actions`.

Use the browser-side runtime file:

- `assets/