# Wax Agent Integrations

This is the machine-oriented entry point for coding agents working with Wax projects and Wax execution recordings. It is plain Markdown by design.

## Choose the resource

- To read or write Wax source, load the [Wax Agent Language Reference](https://waxlang.dev/agent-reference).
- To investigate a completed `.wxs` recording, load the [Wax recording investigation prompt](https://waxlang.dev/waxdbg-agent-prompt.md).
- To orient a human collaborator to the installed tools, use the [Wax command-line documentation](https://waxlang.dev/docs/tools/).

## Tool discovery

Do not assume that a remembered command surface matches the installed toolchain.

```sh
wax help
wax --version
waxdbg capabilities --json
```

Use `wax help <command>` for version-matched command help. During debugger work,
discover supported CLI spellings in the `command` fields returned by
`waxdbg capabilities --json`, then read `waxdbg help <command> --json` for the
selected command's contract.

Commands with a result document return JSON by default. Use the installed
catalog to check command availability and help to discover the result contract.
Report a missing capability and use an available operation only when it can
answer the same question.

## Working rules

1. Inspect the relevant sources and, when present, the project manifest before proposing commands or edits.
2. Prefer `wax check` from inside the project for source validation when no artifact is needed.
3. Prefer structured output when the installed command advertises it.
4. Treat `.wxs` recordings as read-only evidence. Keep generated queries and debugger session state separate from the recording.
5. Separate facts returned by tools from interpretation, and preserve the commands that support important conclusions.

## Integration surfaces

- `wax` is the public umbrella command for builds, packages, debugging, editor setup, and version discovery.
- `waxc` and `waxdbg` are focused engines that may be invoked directly.
- `waxdbg` provides its machine-readable capability catalog at runtime; clients should discover it instead of maintaining a second command list.
- Agent integrations that host an LSP client may start `wax lsp` for diagnostics and source navigation.

## Local MCP server

Wax ships one MCP server for completed-recording work and the browser debugger
workbench. It is built into `waxdbg`, requires no Node.js installation, and
launches no helper process.

### Add Wax to an agent host

In the custom MCP server settings for any stdio-capable agent host, add:

```json
{
  "command": "waxdbg",
  "args": ["agent", "serve", "--agent-name", "My local agent", "--grant", "readSession", "--grant", "readSource", "--grant", "readHeap", "--grant", "writeSession", "--grant", "writeFiles", "--grant", "controlExecution", "--grant", "readRecording", "--grant", "compileCode", "--grant", "unboundedCost", "--grant", "presentUi", "--grant-ttl-seconds", "3600"]
}
```

Adding this configuration opts into the full local debugger access set:
reading recordings, source, and heap state; compiling and running investigations;
editing session state and files; controlling execution; and presenting evidence.
The agent host controls approval of the configuration and tool calls. Browser
work still requires pairing with the intended Inspector tab.

Configured grants last one hour after server startup. Reload the server to
renew them if an operation returns `forbidden` after that interval. For a custom
restricted configuration, list only the effects you intend to grant.

The Inspector's top-bar **Agent** control copies an adaptive setup and
connection request. When the receiving local agent has terminal and host
configuration access, that request first discovers an existing Wax installation
and MCP server. If either is missing, the agent explains the required local
changes and asks before downloading Wax, installing it, or changing MCP
configuration. The request uses the inspectable installers documented on
[`/get-wax`](https://waxlang.dev/get-wax); it does not pipe a remote script into
a shell.

Prefer the installed executable's absolute path in MCP configuration. The
standard per-user locations are `$HOME/.wax/bin/waxdbg` on macOS and Linux and
`$HOME\.wax\bin\waxdbg.exe` on Windows. This avoids depending on whether the
agent host inherited a shell PATH updated after it started.

MCP hosts do not share a configuration or live-reload standard. A host that can
load the new server immediately can finish the connection in the same
conversation. When a host requires a restart or MCP reload, the agent names
that action; perform it, then paste the same request again while the Inspector
tab is still waiting. The Agent view retains the manual server configuration
for hosts that cannot configure themselves.

### Investigate a local recording

For completed-recording work, no browser pairing is needed. Give the agent an
absolute recording path. The configuration above supports both metadata reads
and native investigations. Start with `wax_recording_info` and
`{ "path": "/absolute/path/run.wxs" }`.

The [HealthGame walkthrough](https://waxlang.dev/docs/tools/waxdbg/queries-and-investigations)
provides a complete recording and investigation fixture. With those files saved,
call `wax_investigation_list` using the recording's absolute `path` and
`files: ["/absolute/path/HealthGame/Queries/Health.wax"]`. Then call
`wax_investigation_run` with the same `path` and `files`,
`name: "Game.HealthReview"`, `member: "Review"`, and
`arguments: "{\"frame\":4,\"from\":0,\"span\":8}"`.
The `arguments` field is a JSON string, as advertised by the tool schema.
The result reports health `50` at frame `4` and `8` observed frames.

Use explicit paths for this sessionless workflow. Omitting `path` selects the
paired browser recording and requires a connection to the Inspector.

### Pair with the browser Inspector

Use the top-bar **Agent** shortcut, or open the **Agent** view and choose
**Connect agent**, then copy the setup and connection request. Paste that one
request into the agent conversation.
It tells the agent to call `wax_pair_start` with the browser-created rendezvous
ticket and the access needed for an investigation. The tab is already waiting:
when the MCP server starts the named loopback bridge, the Inspector connects
automatically. There is no pairing result to copy back, no JSON field to extract,
and no second browser confirmation.

The ticket carries a random session ID and page token, is bound to the exact
Inspector origin, and is useful only to a bridge on numeric loopback. Its browser
grants last until that `waxdbg agent serve` process exits or a different pairing
replaces it, so an active local workflow does not expire halfway through. Copy a
fresh request after an MCP server restart or an explicit disconnect.

After pairing, omit `path` from `wax_recording_info`,
`wax_investigation_list`, and `wax_investigation_run` to target the recording
already open in the workbench. Results flow through the existing Investigations
view. Ask the agent to present its strongest evidence so source locations and
frames become navigable in the shared Inspector.

`wax_recording_info` preserves the recording format's inclusive `lastFrame` and
also returns `seekableStartFrame` and `seekableLastFrame` for replay navigation.
Those seekable fields are `null` when the recording has no navigable frame. The
bundled Doom target supplies its `DoomWax.SignalBattery` investigation to both
the Inspector and a paired agent without requiring a source path.

Read `wax_ui_snapshot` before presentation actions and pass its exact `revision`
and `targetGeneration` to `wax_ui_activate_view`, `wax_ui_ping`,
`wax_ui_reveal_source`, or `wax_ui_present_evidence`. `wax_ui_ping` accepts a
`viewId` from the snapshot's `availableViews` and a message of at most 280
characters. It activates that
view and places one dismissible note over it; a later ping replaces the prior
note. Continue to use canonical commands such as
`investigation.run` and `replay.seekFrame` for semantic work. The `ui.*` surface
only asks existing workbench controllers to present results; it exposes no DOM,
selectors, arbitrary JavaScript, Playwright/CDP, or synthetic browser input.

`wax_ui_present_evidence` optionally accepts `{ "protocol":
"wxdbg.evidence.v1", "summary": "…", "frames": [42], "locations": [{
"path": "Src/App.wax", "line": 87, "column": 5 }], "data": {} }`. Ordinary
typed investigation results remain valid and are adopted into the existing
Investigations view without this convention.

The Agent view shows the current state and one next action. Connection details
and recent typed commands remain available under its details disclosure.
Disconnecting, a stale workbench revision, or a stale target generation fails
closed. Start a fresh pairing if the bridge cannot reconnect after its MCP server
restarts.

## Status

Tool, protocol, and language surfaces may change. Prefer the installed binaries and the resources linked above over cached copies.