# Agent Protocol

WinBridge AI uses a simple Mac-hosted HTTP polling protocol.

## Pairing

1. The control computer starts `winbridge start` (or `server.mjs` in a checkout).
2. WinBridge prints a six-digit pairing code and LAN pairing URL.
3. Windows opens the URL and copies the generated agent command.
4. Windows agent posts registration data to `/api/agent/register`.
5. WinBridge stores the agent in `<data-dir>/state/state.json`.

## Authentication

Authentication is enabled by default for LAN use. The browser-facing pairing
flow accepts a six-digit code, rate-limits failures, then exchanges a valid code
for an HttpOnly session cookie containing the strong internal token.
The six-digit code alone never authorizes API, file, or agent callback routes.

When token mode is enabled, requests are authorized when one of these values
matches the pairing token:

- `X-WinBridge-Token: <token>`
- `Authorization: Bearer <token>`
- `?token=<token>`

The internal token remains available to the generated one-line Windows commands
so scripts can be downloaded without manual credential input.
`WINBRIDGE_PAIRING_CODE`, `WINBRIDGE_AUTH_REQUIRED=1`, `WINBRIDGE_AUTH=token`,
and `WINBRIDGE_PAIRING_TOKEN` remain supported for explicit configuration. Use
`WINBRIDGE_AUTH_DISABLED=1` or `winbridge start --auth none` only on an isolated,
trusted network.

## Job Lifecycle

1. Mac queues a command through `/api/agent/*`.
2. Windows polls `/api/agent/next?agentId=<id>`.
3. Windows runs the PowerShell script in a hidden child process.
4. Windows posts progress snapshots to `/api/agent/progress`.
5. Windows posts final exit code and logs to `/api/agent/result`.
6. Mac updates the job state.

Job states:

- `queued`
- `running`
- `cancelling`
- `cancelled`
- `success`
- `failed`

## Current API Surface

- `GET /api/status`
- `POST /api/agent/register`
- `GET /api/agent/next`
- `POST /api/agent/progress`
- `POST /api/agent/result`
- `POST /api/agent/cancel`
- `POST /api/agent/test`
- `POST /api/agent/preflight`
- `POST /api/agent/install-env`
- `POST /api/agent/install-artifact`
- `POST /api/agent/capture-screenshot`
- `POST /api/agent/run-powershell`
- `POST /api/agent/screenshot-upload`
- `POST /api/agent/artifact-upload`
- `GET /artifacts/:filename`
- `GET /screenshots/:filename`

## MCP Direction

The next product layer should expose the same control plane through MCP tools:

- `list_windows_agents`
- `run_windows_powershell`
- `capture_windows_screenshot`
- `upload_windows_artifact`
- `install_windows_artifact`
- `get_windows_job`
- `cancel_windows_job`
- `read_windows_logs`
